Skip to content

feat(mcp,claude-agent-sdk): capture typed MCP tool media and original Agent SDK media - #681

Draft
nik13 wants to merge 6 commits into
feat/attachments-ts-corefrom
feat/attachments-ts-mcp-agents
Draft

nik13 wants to merge 6 commits into
feat/attachments-ts-corefrom
feat/attachments-ts-mcp-agents

Conversation

@nik13

@nik13 nik13 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Part of TH-2379 (Linear).

Stacked on #677 (feat/attachments-ts-core). Design packages C02 (TypeScript MCP) and C04 (TypeScript Claude Agent SDK).

What this adds

  • @traceai/mcp: wrapMCPClient(client, config) traces the real callTool() / readResource() boundaries and offers typed inline media to the provider's shared AttachmentManager: tool image/audio blocks, embedded resource.blob, and readResource().contents[].blob. captureMCPResult(manager, span, result, operation, capture, traceConfig) is exported for custom wiring.
  • @traceai/claude-agent-sdk: new attachments and attachmentCapture options. Original base64 image and PDF document blocks attach before tool output is truncated into span text: tool results go to the exact tool span (with tool_call_id), direct user media goes to the conversation span.
  • Each original block object is offered at most once per query (identity only, no byte reads), and wrapping one MCP client twice returns the same proxy.

Privacy and failure behaviour

  • Off by default. Every media part goes through the core's preflight (the full deny-wins check plus a budget reservation) before its base64 is read or decoded, and the value is read at most once. A too_large or queue_full preflight is retried once at the part's exact decoded size; both reasons come after every privacy, correlation and sampling step, so this read is post-gate. An admitted part whose bytes are malformed or over budget releases its reservation. A manager without preflight captures nothing.
  • Deny wins: any hide flag on the manager or integration, piiRedaction, hideErrorDetails with error media, and captureContent / recordInputs / recordOutputs / muted / temporaryChat restrictions all deny. Integration flags only tighten.
  • Bounded work: at most 64 parts and 256 KiB of decoded bytes per result. Strict base64 checks. A MIME type that doesn't match the block type is skipped.
  • Nothing is fetched: resource links, URIs, URLs, file IDs, local paths and structuredContent are never read. No stream is advanced, and no recording is started.
  • The original SDK promise, value, error, cancellation signal, iterator and control-method receivers come back unchanged.

Not supported here

  • Consumed-stream capture (startAttachmentStream) does not apply: callTool/readResource return fully parsed content arrays, and the Agent SDK yields complete message frames, so there are no consumed byte chunks to forward.
  • Completed-recording imports and remote/provider retrieval: these adapters never start recordings and never fetch URLs, file IDs or paths.
  • Cross-adapter dedup against provider hooks. The Agent SDK's model calls run inside the bundled CLI subprocess, so in-process provider instrumentation does not see the same media (evidence below).
  • The transport-level MCPInstrumentation only propagates context and does not capture media. This PR does not describe it as byte capture.

Test changes to pre-existing tests

The @traceai/claude-agent-sdk jest suite has no CI on dev, and four of its expectations had drifted. On the unchanged base head (7145f783) it gives 4 failed / 113 passed:

  • J3 MCP tool error and failure semantics … hideOutputs: fi-core now drops the ERROR status description when outputs or error details are hidden, so these expect undefined.
  • Python parity › built-in tool list: the Python BUILTIN_TOOLS now includes Agent, which TS already had, so the count is 14. Every Python name is still asserted to be in the TS set.
  • package.json homepage: this expectation was already failing. The test now pins the current package.json value (https://docs.futureagi.com/docs/tracing) instead of a homepage derived from the Anthropic package's path.

With this PR the suite gives 117 / 117.

Resync onto ts-core f0a56b37 (this update)

  • a9fd5c03 merges the updated feat/attachments-ts-core (clean merge, no rebase).
  • 148b91bc adopts preflight in both adapters (above) and adds rows: read-after-preflight spies, exact-size retry on too_large (negotiated max_upload_bytes 100 KiB) and queue_full (maxOwnedBytes 200 KiB), reservation release on malformed bytes, and an assertion that no FI_ATTACHMENTS_* process warning fires. READMEs now describe preflight ordering and the one-proxy-per-client behaviour.
  • f088b62c aligns the loopback test double with core changes. Under strict F01 checks, its content PUT body lacked reason. As a result, uploads transferred their bytes but completed as unsupported_version with FI_ATTACHMENTS_WIRE_REJECTED. updatePolicy is now tighten-only, so the real-SDK policy controls each run on a fresh manager.

Qualification on a temporary private GCP VM (synthetic data, loopback services, network-isolated suites). Each tree was rebuilt from public refs plus patches, and the tree hashes matched:

Run Result
Control: lane adapters 5780b83b on core f0a56b37, old tests + fixed double 35/35, 0 warnings; real SDK matrix passes (MCP 1.10.2/1.32.2, Agent SDK 0.3.277/0.3.322)
Head f088b62c attachment suites, Node 24.11.1 / 18.20.8 44/44 / 44/44, 0 FI_ATTACHMENTS_* warnings
@traceai/mcp jest / @traceai/claude-agent-sdk jest, Node 24 and 18 1/1 and 117/117 on both
Head real SDK matrix all 4 versions pass
Head tests on the control build 38/44: exactly the 6 rows that need the lane change fail
Mutation: read before preflight / no release / no exact-size retry 25 / 2 / 3 rows fail

Before the double fix, the control's old suites passed 35/35 but logged FI_ATTACHMENTS_WIRE_REJECTED, and the real MCP SDK row failed (4 !== 6) on the tighten-only policy. That is a test-double defect, not lost capture: the bytes reached the double in every row.

GitHub CI on f088b62c: MCP and Agent SDK attachments (run 43016779634) passes on Node 18 and 24, including the real-SDK floor/latest step.

Earlier qualification (head 5780b83b, on core 7145f783)

Final head 5780b83b, on Node 24.11.1 and Node 18.20.8:

  • pnpm --filter @traceai/mcp... --filter @traceai/claude-agent-sdk... install --frozen-lockfile --ignore-scripts, then build fi-semantic-conventions, fi-core, mcp and claude-agent-sdk: all exit 0.
  • pnpm --filter @traceai/mcp test: 1 / 1. pnpm --filter @traceai/claude-agent-sdk test: 117 / 117. Both pass on both Node versions.
  • node packages/traceai_mcp/test/run-attachments.cjs (fresh loopback TLS cert, synthetic attachment service): 35 / 35 on both Node versions. It covers:
    • privacy negative controls with zero getter reads, references or uploads: disabled, the eight hide/PII flags, captureContent, muted, temporaryChat, recordInputs and recordOutputs;
    • policy tightened after enqueue;
    • hideErrorDetails with error media;
    • URI, resource-link and structuredContent non-dereference;
    • MIME mismatch, malformed and oversized parts, and the 64-part cap;
    • cancellation and sync-throw identity;
    • write-capability header scoping;
    • per-query replay dedup;
    • one proxy per client;
    • sync results.
  • node packages/traceai_mcp/test/run-sdk-matrix.cjs, with real upstream SDKs installed at exact versions:
    • @modelcontextprotocol/sdk 1.10.2 (floor) and 1.32.2 (latest per npm view) over real SSE: screenshot, audio and resource tool result, readResource, abort, and four policy controls. All pass.
    • @anthropic-ai/claude-agent-sdk 0.3.277 (floor) and 0.3.322 (latest per npm view): the bundled Claude Code executable runs a real Read tool on a synthetic PNG against a loopback Messages mock, with egress blackholed. The original image attaches to the exact tool.Read span. The disabled, hideInputs and piiRedaction runs make no attachment requests. All pass.
  • SDK boundary check: none of the installed Agent SDK modules (sdk.mjs, core*.mjs, bridge.mjs, …) contains messages.create, /v1/messages or new Anthropic(. Model calls run in the spawned executable.

GitHub CI on 5780b83b: MCP and Agent SDK attachments passes on Node 18 and 24, including the real-SDK floor/latest step.

🤖 Generated with Claude Code

nik13 and others added 6 commits November 10, 2026 20:04
…ed attachment manager

Adds opt-in MCP callTool/readResource media capture (wrapMCPClient,
captureMCPResult) and Claude Agent SDK original image/PDF block capture
before text truncation. Both use the provider-owned AttachmentManager,
read source bytes only after manager admission, and never fetch URLs,
paths, file IDs or structuredContent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…edup

wrapMCPClient now returns the same proxy when a raw client is wrapped
again, and records a synchronous non-thenable result as success. The
Agent SDK tracer offers each original media source object to the
manager at most once per query, by identity, without reading its data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…edia dedup

Two existing expectations drifted on dev and fail on the unchanged base
head too: fi-core now hides the conversation status description under
hidden outputs, and the Python BUILTIN_TOOLS list now includes Agent
(which TS already had). The README now states the per-query dedup and
the subprocess model-call boundary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-agents

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…its base64

Adopt the core preflight API (SDK design section 1) in place of the lazy
Bytes getter passed to attach(). Each MCP tool/resource part and each Agent
SDK image/PDF block is preflighted with the full deny-wins facts before its
encoded value is read; the value is read at most once. A too_large or
queue_full preflight (both evaluated after every privacy, correlation and
sampling step) is retried once at the part's exact decoded size, so a
negotiated upload limit or a nearly used owned-byte budget still admits small
media as attach() did. An admitted part whose bytes are malformed or over the
decode budget releases its reservation. A manager without preflight captures
nothing.

Harness: sessions are minted for one hour (core renewal triggers), negotiated
limits can be overridden, and FI_ATTACHMENTS_* process warnings are collected
and asserted absent. New rows: read-after-preflight, exact-size retry on
too_large and queue_full, reservation release on malformed bytes, and no
legacy/wire-rejected warnings. README: preflight ordering, no stream capture
for parsed results, and the one-proxy-per-client behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… strict F01 and tighten-only policy

On ts-core f0a56b3 every status body is checked against F01: the double's
content PUT response lacked `reason`, so each upload transferred its bytes
but completed as unsupported_version with FI_ATTACHMENTS_WIRE_REJECTED. It
now returns {upload_id, state: pending_upload, reason: queued}, and a row
asserts completion is validating.

updatePolicy is now tighten-only (enabled:false cannot be undone), so the
real-SDK policy controls each run on a fresh manager through a per-control
delegate of the same real SSE client instead of toggling one manager.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant