feat(foundry): validate generic file and artifact lifecycle parity

[sozercan]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Prove full session file and artifact lifecycle parity for AgentKit-built images.

Current behavior:
AgentKit has validated Foundry Toolbox code execution through a remote MCP tool, but it has not proven the full file lifecycle expected by native Foundry hosted-agent samples. The current Foundry sample gallery includes responses/06-files, which combines local file-oriented tools with a Foundry Toolbox MCP endpoint. AgentKit currently models tools as MCP servers and does not have a generic session artifact/file ABI. The parity work only proved code-interpreter arithmetic, not upload/read/search/generated artifact lifecycle.

Desired behavior:
AgentKit should support or explicitly scope the file/artifact parity story generically. Prefer representing file and code services as remote MCP tools first. Only add a generic session artifact ABI if remote MCP cannot cover required scenarios.

The validation should prove parity across:

• standalone AgentKit image
• Foundry hosted /invocations, if applicable
• Foundry hosted /responses

The test should exercise real file lifecycle behavior, not just code execution.

Key interfaces:

• Generic remote MCP tool config: type: mcp, transport: streamable-http, urlEnv, auth, and non-secret headers.
• Generic env declarations for file/tool endpoints and session paths.
• Potential future generic session artifact shape, if MCP is insufficient.
• Protocol adapter response extraction for generated artifacts/files, if artifacts are returned through protocol metadata rather than final text.

Investigation notes:

• Code interpreter through Foundry Toolbox already passed standalone and hosted with CODE_SMOKE_OK and correct arithmetic.
• Full file upload/read/search/artifact retrieval was not validated.
• Native responses/06-files uses file-list/read behavior and a Toolbox MCP endpoint; this needs an AgentKit equivalent rather than a one-off native MAF sample run.
• This should not be solved with foundry.files or Foundry-specific schema in AgentKit core.

Acceptance criteria:

• Determine whether the native file sample requirements can be represented entirely as remote MCP tools.
• If yes, add an AgentKit fixture using only generic remote MCP/env/auth config.
• If no, propose and test the smallest provider-neutral session artifact/file ABI.
• Standalone AgentKit image can read or use a runtime-supplied file.
• Foundry hosted AgentKit image can use the equivalent file/artifact input through supported hosted-agent protocol/tooling.
• Generated artifacts or file outputs are retrievable or verifiably surfaced in a provider-neutral way.
• Validation distinguishes code-interpreter execution from file/artifact lifecycle behavior.
• Documentation clearly states what file features are supported, remote-MCP-only, or intentionally unsupported.

Out of scope:

• Unsafe local code execution by default.
• Foundry-specific file schema in AgentKit core.
• Revalidating generic remote MCP auth/header behavior already covered by existing tests except where needed for file tools.