From 5ef3f93a7cc2128d46ea5dafb430ffe5378fdea1 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Tue, 10 Nov 2026 20:04:10 -0800 Subject: [PATCH 1/5] feat(mcp,claude-agent-sdk): capture typed tool media through the shared 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 --- .../workflows/mcp-agent-attachments-tests.yml | 50 ++++++++ .../traceai_claude_agent_sdk/README.md | 30 +++++ .../src/__tests__/package.test.ts | 4 +- .../src/__tests__/wrapper.test.ts | 5 +- .../src/attachments.ts | 70 +++++++++++ .../src/instrumentation.ts | 14 ++- .../src/queryWrapper.ts | 7 +- .../traceai_claude_agent_sdk/src/spans.ts | 18 ++- .../test/attachments.test.cjs | 94 +++++++++++++++ .../test/real-sdk.test.cjs | 66 +++++++++++ typescript/packages/traceai_mcp/README.md | 39 +++++- .../packages/traceai_mcp/src/attachments.ts | 87 ++++++++++++++ typescript/packages/traceai_mcp/src/client.ts | 68 +++++++++++ typescript/packages/traceai_mcp/src/index.ts | 5 +- .../traceai_mcp/test/attachment-harness.cjs | 46 +++++++ .../traceai_mcp/test/attachments.test.cjs | 112 ++++++++++++++++++ .../traceai_mcp/test/real-sdk.test.cjs | 60 ++++++++++ .../traceai_mcp/test/run-attachments.cjs | 15 +++ .../traceai_mcp/test/run-sdk-matrix.cjs | 30 +++++ .../traceai_mcp/test/sdk-versions.json | 4 + 20 files changed, 811 insertions(+), 13 deletions(-) create mode 100644 .github/workflows/mcp-agent-attachments-tests.yml create mode 100644 typescript/packages/traceai_claude_agent_sdk/src/attachments.ts create mode 100644 typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs create mode 100644 typescript/packages/traceai_claude_agent_sdk/test/real-sdk.test.cjs create mode 100644 typescript/packages/traceai_mcp/src/attachments.ts create mode 100644 typescript/packages/traceai_mcp/src/client.ts create mode 100644 typescript/packages/traceai_mcp/test/attachment-harness.cjs create mode 100644 typescript/packages/traceai_mcp/test/attachments.test.cjs create mode 100644 typescript/packages/traceai_mcp/test/real-sdk.test.cjs create mode 100644 typescript/packages/traceai_mcp/test/run-attachments.cjs create mode 100644 typescript/packages/traceai_mcp/test/run-sdk-matrix.cjs create mode 100644 typescript/packages/traceai_mcp/test/sdk-versions.json diff --git a/.github/workflows/mcp-agent-attachments-tests.yml b/.github/workflows/mcp-agent-attachments-tests.yml new file mode 100644 index 000000000..60d655ca2 --- /dev/null +++ b/.github/workflows/mcp-agent-attachments-tests.yml @@ -0,0 +1,50 @@ +name: MCP and Agent SDK attachments +on: + pull_request: + paths: + - 'typescript/packages/traceai_mcp/**' + - 'typescript/packages/traceai_claude_agent_sdk/**' + - 'typescript/packages/fi-core/**' + - '.github/workflows/mcp-agent-attachments-tests.yml' + workflow_dispatch: +permissions: + contents: read +jobs: + attachments: + runs-on: ubuntu-24.04 + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + node: ['18', '24'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + - uses: pnpm/action-setup@v4 + with: + version: 10.30.1 + - name: Build adapters and shared core + working-directory: typescript + run: | + pnpm --filter @traceai/mcp... --filter @traceai/claude-agent-sdk... install --frozen-lockfile --ignore-scripts + for package in fi-semantic-conventions fi-core mcp claude-agent-sdk; do + pnpm --filter "@traceai/$package" run build + done + - name: Existing and attachment boundary suites + working-directory: typescript + run: | + pnpm --filter @traceai/mcp test --runInBand + pnpm --filter @traceai/claude-agent-sdk test --runInBand + node packages/traceai_mcp/test/run-attachments.cjs + - name: Real SDK floor and latest-qualified loopback flows + if: matrix.node == '24' + working-directory: typescript + run: node packages/traceai_mcp/test/run-sdk-matrix.cjs "$RUNNER_TEMP/attachment-evidence" + - uses: actions/upload-artifact@v4 + if: always() && matrix.node == '24' + with: + name: mcp-agent-attachment-evidence + path: ${{ runner.temp }}/attachment-evidence + if-no-files-found: ignore diff --git a/typescript/packages/traceai_claude_agent_sdk/README.md b/typescript/packages/traceai_claude_agent_sdk/README.md index 05626f9ff..d664d7f9f 100644 --- a/typescript/packages/traceai_claude_agent_sdk/README.md +++ b/typescript/packages/traceai_claude_agent_sdk/README.md @@ -152,3 +152,33 @@ pnpm --filter @traceai/claude-agent-sdk test # jest: wrapper, parity, fi-cor ``` The shared-harness contract tests (`contract/test_harness_contract.py`) run the built package in Node against the Python OTLP `Receiver`, run the real SDK against a loopback Messages API mock, pack the tarball and check it holds no SDK file or native binary, and import the package as CJS and ESM. See the module docstring for the command. + + +## Original tool media + +The wrapper can send original typed image and PDF blocks to the provider's +shared attachment manager before tool output is truncated into span text. Tool +results attach to their exact tool span; direct user media attaches to the +conversation span. The wrapper does not turn screenshots into recordings. + +This requires an attachment-capable service and an attachment-enabled +`@traceai/fi-core` provider. Capture is off by default. The existing +`wrapQuery(query, { tracerProvider })` setup uses `tracerProvider.attachments`; +you may also supply `attachments` explicitly when using a custom provider. +`attachmentCapture` adds integration restrictions such as `captureContent: false`, +`recordInputs: false`, `recordOutputs: false`, `muted: true` or +`temporaryChat: true`. These restrictions cannot loosen the manager's policy. + +Only typed inline base64 image/PDF sources are observed, with at most 64 parts +and 256 KiB of decoded bytes per content list. URLs, file IDs, arbitrary tool +objects and local paths are not retrieved. Input hide rules apply to tool media +that is sent back to the model; output hide rules also apply to tool results. +Required PII redaction without a qualified media sanitizer denies raw capture. +Original media may contain embedded metadata. + +Parameters, hooks, message objects, iterator cancellation and control methods +remain owned by the application. The wrapper neither awaits uploads during +inference nor keeps spans open for uploads. Flush the provider before process +exit; if an explicitly supplied manager differs from the provider's manager, +flush that manager as well. Do not enable overlapping media capture at both the +agent and provider boundary: cross-adapter duplicate suppression is not provided. diff --git a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/package.test.ts b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/package.test.ts index 8ce59d955..48f5b9351 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/package.test.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/package.test.ts @@ -25,9 +25,7 @@ describe("package.json", () => { directory: "typescript/packages/traceai_claude_agent_sdk", }); expect(ours.bugs).toEqual(sibling.bugs); - expect(ours.homepage).toBe( - (sibling.homepage as string).replace("traceai_anthropic", "traceai_claude_agent_sdk"), - ); + expect(ours.homepage).toBe("https://docs.futureagi.com/docs/tracing"); expect(JSON.stringify([ours.repository, ours.bugs, ours.homepage])).not.toContain("github.com/futureagi/"); }); }); diff --git a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts index 42d75d8a0..786ba4038 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts @@ -502,7 +502,8 @@ describe("wrapQuery", () => { expect(tool.status.code).toBe(SpanStatusCode.ERROR); // Error text is tool output: hidden with hideOutputs. expect(tool.attributes["claude_agent.tool.error_message"]).toBeUndefined(); - expect(tool.status.message).toBe("tool error"); + // fi-core hides the status description with hidden error details. + expect(tool.status.message).toBeUndefined(); expect(conversation.status.code).toBe(SpanStatusCode.ERROR); expect(conversation.attributes["claude_agent.is_error"]).toBe(true); @@ -676,7 +677,7 @@ describe("wrapQuery", () => { expect(JSON.stringify({ a: conversation.attributes, e: conversation.events, s: conversation.status })).not.toContain( "SECRET_ERROR_TEXT_MARKER", ); - expect(conversation.status.message).toBe("TypeError"); + expect(conversation.status.message).toBeUndefined(); expect(conversation.attributes["claude_agent.error.type"]).toBe("TypeError"); expect(conversation.events.find((e) => e.name === "exception")?.attributes).toEqual({ "exception.type": "TypeError" }); }); diff --git a/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts new file mode 100644 index 000000000..72a548bb4 --- /dev/null +++ b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts @@ -0,0 +1,70 @@ +import type { Span } from "@opentelemetry/api"; +import type { TraceConfigOptions } from "@traceai/fi-core"; +import type { AttachmentCapturePolicy, AttachmentManager } from "@traceai/fi-core/attachments"; + +/** One observed message/tool result has a bounded synchronous decode budget. */ +const DECODE_BUDGET = 256 * 1024; + +export interface AgentAttachmentContext { + attachments?: AttachmentManager; + attachmentCapture?: AttachmentCapturePolicy; + attachmentTraceConfig?: TraceConfigOptions; +} + +/** + * Original Anthropic image/document base64 blocks only, before text truncation. + * No arbitrary object walk, URL/file-ID resolver, path opening or stream reads. + * Capturing an existing tool screenshot never starts a recorder. + */ +export function captureAgentMedia( + config: AgentAttachmentContext, + span: Span, + content: unknown, + options: { toolCallId?: string; messageIndex: number; isError?: boolean; toolResult: boolean }, +): void { + const manager = config.attachments; + if (!manager || !Array.isArray(content)) return; + let remaining = DECODE_BUDGET; + for (let partIndex = 0; partIndex < Math.min(content.length, 64); partIndex++) { + try { + const block = content[partIndex]; + if (!block || (block.type !== "image" && block.type !== "document")) continue; + const source = block.source; + if (!source || source.type !== "base64" || typeof source.media_type !== "string") continue; + const mimeType = source.media_type; + // Do not let a misleading MIME relabel an image to bypass hideInputImages. + if (block.type === "image" ? !mimeType.startsWith("image/") : mimeType !== "application/pdf") continue; + const f = config.attachmentTraceConfig ?? {}; + const c = config.attachmentCapture ?? {}; + const errorDetail = options.isError === true || c.errorDetail === true; + const hidden = f.hideInputs || f.hideInputMessages || f.hideInputText || + (block.type === "image" && f.hideInputImages) || + (options.toolResult && (f.hideOutputs || f.hideOutputMessages || f.hideOutputText)) || + (errorDetail && f.hideErrorDetails) || f.piiRedaction; + manager.attach(span, { + kind: "Bytes", + get data(): Uint8Array { + // Manager privacy, bootstrap, sampling and descriptor gates precede this getter. + const encoded = source.data; + if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(remaining / 3)) throw new Error("media unavailable"); + if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new Error("media unavailable"); + const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); + if (size > remaining) throw new Error("media unavailable"); + remaining -= size; + return Buffer.from(encoded, "base64"); + }, + }, { + mimeType, + direction: options.toolResult ? "output" : "input", + purpose: options.toolResult ? "tool_result" : "model_input", + role: options.toolResult ? "tool" : "user", + toolCallId: options.toolCallId, + messageIndex: options.messageIndex, + partIndex, + capture: { ...c, captureContent: hidden ? false : c.captureContent, modelInput: true, containsOutput: options.toolResult || c.containsOutput === true, errorDetail }, + }); + } catch { + // Untrusted properties / malformed blocks do not change the SDK iterator. + } + } +} diff --git a/typescript/packages/traceai_claude_agent_sdk/src/instrumentation.ts b/typescript/packages/traceai_claude_agent_sdk/src/instrumentation.ts index 01b96b5f0..a76364981 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/instrumentation.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/instrumentation.ts @@ -19,6 +19,7 @@ import { FI_HIDE_OUTPUT_TEXT, TraceConfigOptions, } from "@traceai/fi-core"; +import type { AttachmentCapturePolicy, AttachmentManager } from "@traceai/fi-core/attachments"; import { ContentPolicy } from "./spans"; import { QueryTracingContext, wrapQueryFunction } from "./queryWrapper"; import { QueryFunctionLike } from "./types"; @@ -27,6 +28,10 @@ import { VERSION } from "./version"; export const INSTRUMENTATION_NAME = "@traceai/claude-agent-sdk"; export interface ClaudeAgentSDKInstrumentationConfig { + /** Shared provider-owned manager. Defaults to tracerProvider.attachments when available. */ + attachments?: AttachmentManager; + /** Integration restrictions can only tighten manager policy. */ + attachmentCapture?: AttachmentCapturePolicy; /** Provider to create spans with. Defaults to the global provider at call time. */ tracerProvider?: TracerProvider; /** @@ -128,9 +133,13 @@ export function trackedProviderCount(): number { export class ClaudeAgentSDKInstrumentation { private tracerProvider?: TracerProvider; private readonly traceConfig?: TraceConfigOptions; + private readonly attachments?: AttachmentManager; + private readonly attachmentCapture?: AttachmentCapturePolicy; constructor(config: ClaudeAgentSDKInstrumentationConfig = {}) { this.traceConfig = config.traceConfig; + this.attachments = config.attachments; + this.attachmentCapture = config.attachmentCapture; if (config.tracerProvider) { this.setTracerProvider(config.tracerProvider); } @@ -153,6 +162,7 @@ export class ClaudeAgentSDKInstrumentation { /** Flush the provider's span processors. Does not shut the provider down. */ async forceFlush(): Promise { + await this.attachments?.flush(); await flushProvider(this.tracerProvider ?? trace.getTracerProvider()); } @@ -170,7 +180,9 @@ export class ClaudeAgentSDKInstrumentation { tracer: provider.getTracer(INSTRUMENTATION_NAME, VERSION), traceConfig: { ...(this.traceConfig ?? {}), ...resolveHideFlags(this.traceConfig) }, }); - return { tracer, policy }; + const owner = resolveDelegate(provider) as TracerProvider & { attachments?: AttachmentManager }; + return { tracer, policy, attachments: this.attachments ?? owner.attachments, + attachmentCapture: this.attachmentCapture, attachmentTraceConfig: this.traceConfig }; } } diff --git a/typescript/packages/traceai_claude_agent_sdk/src/queryWrapper.ts b/typescript/packages/traceai_claude_agent_sdk/src/queryWrapper.ts index bb689fad8..d96e21ab0 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/queryWrapper.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/queryWrapper.ts @@ -11,12 +11,13 @@ * idle right after a result), then forward. */ import { Tracer, context as otelContext, diag } from "@opentelemetry/api"; +import type { AgentAttachmentContext } from "./attachments"; import { ContentPolicy, QueryTracer, clockMs } from "./spans"; import { QueryFunctionLike, QueryParamsLike } from "./types"; const WRAPPED = Symbol.for("@traceai/claude-agent-sdk/wrapped"); -export interface QueryTracingContext { +export interface QueryTracingContext extends AgentAttachmentContext { tracer: Tracer; policy: ContentPolicy; } @@ -50,8 +51,8 @@ export function wrapQueryFunction( let queryTracer: QueryTracer | undefined; try { - const { tracer, policy } = getContext(); - queryTracer = new QueryTracer({ tracer, policy, params, parentContext, startTimeMs }); + const tracing = getContext(); + queryTracer = new QueryTracer({ ...tracing, params, parentContext, startTimeMs }); } catch (error) { diag.debug(`@traceai/claude-agent-sdk: tracing disabled for this query: ${error}`); } diff --git a/typescript/packages/traceai_claude_agent_sdk/src/spans.ts b/typescript/packages/traceai_claude_agent_sdk/src/spans.ts index 08721f34d..2b7892887 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/spans.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/spans.ts @@ -36,6 +36,7 @@ import { getToolSource, parseMcpToolName, } from "./attributes"; +import { AgentAttachmentContext, captureAgentMedia } from "./attachments"; import { ScrubContext, defaultScrubContext, scrubContent, scrubErrorText } from "./scrub"; import { AbortSignalLike, @@ -235,9 +236,11 @@ function flattenToolResult(content: unknown): string { return content .map((block: ContentBlockLike) => { if (block && typeof block.text === "string") return block.text; - if (block && block.type === "image") return "[image]"; + // Binary/source metadata never goes through JSON serialization or text truncation. + if (block && ["image", "document", "audio", "resource", "resource_link"].includes(block.type ?? "")) return ""; return safeJson(block); }) + .filter(Boolean) .join("\n"); } return safeJson(content); @@ -285,6 +288,8 @@ function errorParts(error: unknown): { type: string; message: string } { export class QueryTracer { private readonly tracer: Tracer; + private readonly media: AgentAttachmentContext; + private messageIndex = 0; private readonly policy: ContentPolicy; private readonly params: QueryParamsLike; private readonly options: OptionsLike | undefined; @@ -331,8 +336,9 @@ export class QueryTracer { params: QueryParamsLike; parentContext: Context; startTimeMs?: number; - }) { + } & AgentAttachmentContext) { this.tracer = args.tracer; + this.media = { attachments: args.attachments, attachmentCapture: args.attachmentCapture, attachmentTraceConfig: args.attachmentTraceConfig }; this.policy = args.policy; this.params = args.params ?? ({} as QueryParamsLike); this.options = this.params.options; @@ -396,6 +402,7 @@ export class QueryTracer { return; } try { + this.messageIndex = Math.min(this.messageIndex + 1, 65535); const type = (message as { type?: unknown }).type; this.trackIdleAfterResult(type, message as { parent_tool_use_id?: unknown; subtype?: unknown; state?: unknown }); if (type === "assistant") { @@ -597,6 +604,9 @@ export class QueryTracer { private onUser(message: UserMessageLike): void { const scope: Scope = message.parent_tool_use_id ?? null; const affectedTurns = new Set(); + captureAgentMedia({ ...this.media, attachmentCapture: { ...this.media.attachmentCapture, + recordInputs: this.policy.hideInputMessages ? false : this.media.attachmentCapture?.recordInputs } }, + this.conversation!, message.message?.content, { messageIndex: this.messageIndex, toolResult: false }); for (const block of contentBlocks(message.message?.content)) { if (block && block.type === "tool_result" && typeof block.tool_use_id === "string") { const turn = this.endTool(block.tool_use_id, block.content, block.is_error === true); @@ -890,6 +900,10 @@ export class QueryTracer { const endMs = clockMs(); span.setAttribute(A.TOOL_DURATION_MS, endMs - tool.startMs); span.setAttribute(A.TOOL_IS_ERROR, isError); + captureAgentMedia({ ...this.media, attachmentCapture: { ...this.media.attachmentCapture, + recordInputs: this.policy.hideInputMessages ? false : this.media.attachmentCapture?.recordInputs, + recordOutputs: this.policy.hideOutputMessages ? false : this.media.attachmentCapture?.recordOutputs } }, + span, content, { toolCallId: id, messageIndex: this.messageIndex, isError, toolResult: true }); const output = this.policy.hideOutputs ? "" : this.clean(flattenToolResult(content), CONTENT_MAX); if (!this.policy.hideOutputs) { const serialized = output; diff --git a/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs new file mode 100644 index 000000000..f0774e33e --- /dev/null +++ b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs @@ -0,0 +1,94 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { wrapQuery } = require('../dist/src'); +const { harness, PNG, PDF } = require('../../traceai_mcp/test/attachment-harness.cjs'); +const image = () => ({ type: 'image', source: { type: 'base64', media_type: 'image/png', data: PNG.toString('base64') } }); +function messages(content, isError = false) { + return [ + { type: 'assistant', message: { id: 'msg_1', content: [{ type: 'tool_use', id: 'tool_1', name: 'screenshot', input: {} }] } }, + { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 'tool_1', content, is_error: isError }] } }, + { type: 'result', subtype: 'success', result: 'done' }, + ]; +} +async function run(h, frames, config = {}) { + const params = { prompt: 'synthetic', options: {} }; + const original = function (actual) { assert.equal(actual, params); return (async function* () { yield* frames; })(); }; + const received = []; + for await (const frame of wrapQuery(original, { tracerProvider: h.provider, ...config })(params)) received.push(frame); + assert.equal(received.length, frames.length); + received.forEach((frame, i) => assert.equal(frame, frames[i])); + await h.manager.flush(); +} + +test('original nested image/PDF attach to tool before truncation; results remain identical', async () => { + const h = await harness(); + try { + const frames = messages([{ type: 'text', text: 'x'.repeat(6000) }, image(), { type: 'document', title: 'secret-filename', source: { type: 'base64', media_type: 'application/pdf', data: PDF.toString('base64') } }]); + await run(h, frames); + assert.equal(h.uploads.length, 2); + const tool = h.exporter.getFinishedSpans().find(s => s.name === 'tool.screenshot'); + assert.ok(tool); assert.equal(JSON.parse(tool.attributes['fi.attachment.refs']).length, 2); + for (const record of h.records) { assert.equal(record.association.parent.span_id, tool.spanContext().spanId); assert.equal(record.tool_call_id, 'tool_1'); } + const attributes = JSON.stringify(h.exporter.getFinishedSpans().map(s => s.attributes)); + assert.ok(!attributes.includes(PNG.toString('base64'))); assert.ok(!attributes.includes(PDF.toString('base64'))); assert.ok(!attributes.includes('secret-filename')); + } finally { await h.close(); } +}); + +for (const flag of ['hideInputs', 'hideOutputs', 'hideInputMessages', 'hideOutputMessages', 'hideInputText', 'hideOutputText', 'hideInputImages', 'piiRedaction']) { + test(`agent privacy ${flag}: original bytes never read/uploaded`, async () => { + const h = await harness({ manager: { traceConfig: { [flag]: true } } }); + try { + let reads = 0; + const part = { type: 'image', source: { type: 'base64', media_type: 'image/png', get data() { reads++; throw Error('secret'); } } }; + await run(h, messages([part])); + assert.equal(reads, 0); assert.equal(h.records.length, 0); assert.equal(h.uploads.length, 0); + for (const span of h.exporter.getFinishedSpans()) assert.equal(span.attributes['fi.attachment.refs'], undefined); + } finally { await h.close(); } + }); +} + +test('default disabled, integration hide flags, capture restrictions and error policy fail closed', async () => { + for (const setting of ['disabled', 'integration', 'muted', 'error']) { + const h = await harness({ manager: setting === 'disabled' ? { enabled: false } : setting === 'error' ? { traceConfig: { hideErrorDetails: true } } : {} }); + try { + const config = setting === 'integration' ? { traceConfig: { hideInputImages: true } } : setting === 'muted' ? { attachmentCapture: { muted: true } } : {}; + await run(h, messages([image()], setting === 'error'), config); + assert.equal(h.records.length, 0); assert.equal(h.uploads.length, 0); + } finally { await h.close(); } + } +}); + +test('input images use conversation identity; paths, URLs, file IDs and opaque streams are not read', async () => { + const h = await harness(); + try { + const frames = [{ type: 'user', message: { content: [image(), { type: 'image', source: { type: 'url', get url() { throw Error('source read'); } } }, { type: 'document', source: { type: 'file', get file_id() { throw Error('file read'); } } }] } }]; + await run(h, frames); + assert.equal(h.uploads.length, 1); + const conversation = h.exporter.getFinishedSpans().find(s => s.name === 'claude_agent.conversation'); + assert.equal(h.records[0].association.parent.span_id, conversation.spanContext().spanId); + assert.equal(h.records[0].direction, 'input'); + } finally { await h.close(); } +}); + +test('replayed tool_result cannot upload a second occurrence after the tool ended', async () => { + const h = await harness(); + try { + const frames = messages([image()]); frames.splice(2, 0, frames[1]); + await run(h, frames); assert.equal(h.uploads.length, 1); + } finally { await h.close(); } +}); + +test('iterator cancellation and control method receivers are unchanged', async () => { + const h = await harness(); + try { + const frames = messages([image()]); let closed = 0; + const original = (async function* () { yield* frames; })(); + original.close = function () { assert.equal(this, original); closed++; }; + const traced = wrapQuery(() => original, { tracerProvider: h.provider })({ prompt: 'synthetic' }); + assert.equal((await traced.next()).value, frames[0]); + traced.close(); + assert.equal((await traced.next()).value, frames[1]); + await traced.return(); await h.manager.flush(); + assert.equal(closed, 1); assert.equal(h.uploads.length, 0); + } finally { await h.close(); } +}); diff --git a/typescript/packages/traceai_claude_agent_sdk/test/real-sdk.test.cjs b/typescript/packages/traceai_claude_agent_sdk/test/real-sdk.test.cjs new file mode 100644 index 000000000..5d7b26db9 --- /dev/null +++ b/typescript/packages/traceai_claude_agent_sdk/test/real-sdk.test.cjs @@ -0,0 +1,66 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const http = require('node:http'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { pathToFileURL } = require('node:url'); +const { once } = require('node:events'); +const { wrapQuery } = require('../dist/src'); +const { harness, PNG } = require('../../traceai_mcp/test/attachment-harness.cjs'); + +function sse(res, id, blocks, reason) { + res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' }); + const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); + send('message_start', { type: 'message_start', message: { id, type: 'message', role: 'assistant', model: 'claude-opus-5-5', content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 10, output_tokens: 1 } } }); + blocks.forEach((block, index) => { + const isTool = block.type === 'tool_use'; + send('content_block_start', { type: 'content_block_start', index, content_block: isTool ? { ...block, input: {} } : { type: 'text', text: '' } }); + send('content_block_delta', { type: 'content_block_delta', index, delta: isTool ? { type: 'input_json_delta', partial_json: JSON.stringify(block.input) } : { type: 'text_delta', text: block.text } }); + send('content_block_stop', { type: 'content_block_stop', index }); + }); + send('message_delta', { type: 'message_delta', delta: { stop_reason: reason, stop_sequence: null }, usage: { output_tokens: 8 } }); + send('message_stop', { type: 'message_stop' }); res.end(); +} + +test('real Agent SDK bundled CLI Read-image tool maps original media to the exact tool span', { timeout: 180000 }, async () => { + const { query } = await import(pathToFileURL(path.join(process.env.AGENT_SDK_ROOT, 'sdk.mjs')).href); + const work = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-media-')); + const imagePath = path.join(work, 'synthetic.png'); fs.writeFileSync(imagePath, PNG); + let calls = 0, mediaRequests = 0; + const server = http.createServer(async (req, res) => { + const chunks = []; for await (const chunk of req) chunks.push(chunk); + let body = {}; try { body = JSON.parse(Buffer.concat(chunks).toString() || '{}'); } catch {} + if (req.method !== 'POST' || !req.url.startsWith('/v1/messages') || req.url.includes('count_tokens')) { res.writeHead(404); res.end('{}'); return; } + calls++; + const toolResult = (body.messages ?? []).some(message => Array.isArray(message.content) && message.content.some(block => block.type === 'tool_result')); + if (toolResult) mediaRequests++; + sse(res, `msg_${calls}`, toolResult ? [{ type: 'text', text: 'Synthetic image observed.' }] : [{ type: 'tool_use', id: `tool_${calls}`, name: 'Read', input: { file_path: imagePath } }], toolResult ? 'end_turn' : 'tool_use'); + }); + server.listen(0, '127.0.0.1'); await once(server, 'listening'); + try { + for (const mode of ['enabled', 'disabled', 'hidden', 'pii']) { + const h = await harness({ manager: mode === 'disabled' ? { enabled: false } : mode === 'hidden' ? { traceConfig: { hideInputs: true } } : mode === 'pii' ? { traceConfig: { piiRedaction: true } } : {} }); + const abortController = new AbortController(), timer = setTimeout(() => abortController.abort(), 35000); + try { + const observed = []; + const traced = wrapQuery(query, { tracerProvider: h.provider }); + const stream = traced({ prompt: 'Read the synthetic.png fixture.', options: { + cwd: work, model: 'claude-opus-5-5', maxTurns: 3, allowedTools: ['Read'], permissionMode: 'default', settingSources: [], persistSession: false, abortController, + canUseTool: async (name, input) => name === 'Read' && input.file_path === imagePath ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: 'fixture only' }, + env: { PATH: process.env.PATH, HOME: work, CLAUDE_CONFIG_DIR: path.join(work, '.claude'), ANTHROPIC_BASE_URL: `http://127.0.0.1:${server.address().port}`, ANTHROPIC_API_KEY: 'sk-ant-synthetic-not-a-key', CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1', DISABLE_TELEMETRY: '1', DISABLE_ERROR_REPORTING: '1', DISABLE_AUTOUPDATER: '1', HTTPS_PROXY: 'http://127.0.0.1:9', HTTP_PROXY: 'http://127.0.0.1:9', NO_PROXY: '127.0.0.1,localhost' }, + } }); + for await (const frame of stream) observed.push(frame); + await h.manager.flush(); + assert.ok(observed.some(m => m.type === 'result' && !m.is_error), `${mode}: SDK did not complete`); + if (mode === 'enabled') { + assert.equal(h.uploads.length, 1, 'real CLI must return original typed image, not only text'); + const tool = h.exporter.getFinishedSpans().find(s => s.name === 'tool.Read'); assert.ok(tool); + assert.equal(h.records[0].association.parent.span_id, tool.spanContext().spanId); + assert.ok(observed.some(m => m.type === 'user' && m.message?.content?.some(b => b.type === 'tool_result' && Array.isArray(b.content) && b.content.some(p => p.type === 'image')))); + } else { assert.equal(h.uploads.length, 0); assert.equal(h.records.length, 0); } + } finally { clearTimeout(timer); abortController.abort(); await h.close(); } + } + assert.ok(calls >= 8); assert.ok(mediaRequests >= 4); + } finally { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); fs.rmSync(work, { recursive: true, force: true }); } +}); diff --git a/typescript/packages/traceai_mcp/README.md b/typescript/packages/traceai_mcp/README.md index 93a9c4d73..65bf8c2f1 100644 --- a/typescript/packages/traceai_mcp/README.md +++ b/typescript/packages/traceai_mcp/README.md @@ -27,4 +27,41 @@ mcpInstrumentation.manuallyInstrument({ }); ``` -For more information on OpenTelemetry Node.js SDK, see the OpenTelemetry Node.js SDK documentation. \ No newline at end of file +For more information on OpenTelemetry Node.js SDK, see the OpenTelemetry Node.js SDK documentation. + +## Typed media capture API + +`wrapMCPClient(client, config)` observes `callTool()` image/audio/embedded-resource +blocks and `readResource()` blob contents. It creates a span for each operation +and uses the provider's shared attachment manager; the transport-only +`MCPInstrumentation` above propagates context but does not capture media. + +This API requires an attachment-enabled `@traceai/fi-core` provider and an +attachment-capable service. Attachments remain off unless explicitly enabled +on that provider. Pass the same `tracerProvider` to `wrapMCPClient`; do not create +an uploader per client. An explicitly supplied `attachments` manager is also +accepted for custom provider setups. + +| Configuration | Effect | +| --- | --- | +| `tracerProvider` | Provider that creates the operation span and owns `attachments` | +| `attachments` | Optional shared manager override | +| `traceConfig` | Additional hide/PII restrictions; cannot loosen manager policy | +| `attachmentCapture` | Additional `captureContent`, `recordInputs`, `recordOutputs`, `muted` and `temporaryChat` restrictions | + +Tool media is both tool output and potential model input. Input restrictions, +including `hideInputImages`, therefore apply even when a screenshot first +appears in a tool response. Required PII redaction without a qualified media +sanitizer denies raw media capture. Original media may contain embedded metadata. + +Capture inspects only typed inline base64, at most 64 parts and 256 KiB of decoded +bytes per response. Larger parts are not uploaded. Resource links, URLs, local +paths and arbitrary `structuredContent` are not fetched or scraped. Capture +never creates recordings or advances streams. The original SDK promise, +response, error and cancellation signal are preserved. + +Call the provider's `forceFlush()` or the shared manager's `flush()` before a +short process exits. Upload completion means transferred for validation, not +permission to play the content. Playback requires an authorized live occurrence +through the media gateway. Do not wrap the same underlying client multiple +times or enable overlapping media observers for the same operation. diff --git a/typescript/packages/traceai_mcp/src/attachments.ts b/typescript/packages/traceai_mcp/src/attachments.ts new file mode 100644 index 000000000..d23ced091 --- /dev/null +++ b/typescript/packages/traceai_mcp/src/attachments.ts @@ -0,0 +1,87 @@ +import type { TraceConfigOptions } from "@traceai/fi-core"; +import type { Span, SpanContext } from "@opentelemetry/api"; +import type { AttachmentCapturePolicy, AttachmentHandle, AttachmentManager } from "@traceai/fi-core/attachments"; + +/** Bounded synchronous decode budget, independent of the manager's owned queue. */ +export const MCP_MEDIA_DECODE_BUDGET = 256 * 1024; +const MAX_PARTS = 64; + +/** + * Observe only MCP CallToolResult.content / ReadResourceResult.contents. + * No structuredContent scraping, URI retrieval, path access or stream reads. + * Tool results are also model inputs: both directional policies apply. + * The manager reads the lazy Bytes source only AFTER its privacy/sampling gate. + */ +export function captureMCPResult( + manager: AttachmentManager, + span: Span | SpanContext, + result: unknown, + operation: "tools/call" | "resources/read" = "tools/call", + capture: AttachmentCapturePolicy = {}, + traceConfig: TraceConfigOptions = {}, +): AttachmentHandle[] { + const handles: AttachmentHandle[] = []; + let remaining = MCP_MEDIA_DECODE_BUDGET; + try { + if (!result || typeof result !== "object") return handles; + const envelope = result as Record; + const parts = operation === "tools/call" ? envelope.content : envelope.contents; + if (!Array.isArray(parts)) return handles; + for (let index = 0; index < Math.min(parts.length, MAX_PARTS); index++) { + try { + const part = parts[index]; + if (!part || typeof part !== "object") continue; + let media: Record; + let field: "data" | "blob"; + if (operation === "resources/read") { + media = part; + field = "blob"; + } else if (part.type === "image" || part.type === "audio") { + media = part; + field = "data"; + } else if (part.type === "resource" && part.resource && typeof part.resource === "object") { + media = part.resource; + field = "blob"; + } else { + continue; + } + const mimeType = media.mimeType; + if (typeof mimeType !== "string") continue; + if (operation === "tools/call" && (part.type === "image" || part.type === "audio") && !mimeType.startsWith(`${part.type}/`)) continue; + const errorDetail = capture.errorDetail === true || envelope.isError === true; + const hidden = traceConfig.hideInputs || traceConfig.hideInputMessages || traceConfig.hideInputText || + traceConfig.hideOutputs || traceConfig.hideOutputMessages || traceConfig.hideOutputText || + (mimeType.startsWith("image/") && traceConfig.hideInputImages) || + (errorDetail && traceConfig.hideErrorDetails) || traceConfig.piiRedaction; + const handle = manager.attach(span, { + kind: "Bytes", + get data(): Uint8Array { + // No data getter, length scan or decode before manager admission. + const encoded = media[field]; + if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(remaining / 3)) { + throw new Error("media unavailable"); + } + if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new Error("media unavailable"); + const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); + if (size > remaining) throw new Error("media unavailable"); + remaining -= size; + return Buffer.from(encoded, "base64"); + }, + }, { + mimeType, + direction: "output", + purpose: "tool_result", + role: "tool", + partIndex: index, + capture: { ...capture, captureContent: hidden ? false : capture.captureContent, modelInput: true, containsOutput: true, errorDetail }, + }); + handles.push(handle); + } catch { + // Malformed/untrusted media must not change the tool response or diagnostics. + } + } + } catch { + // Content-free failure; never stringify a provider response or exception. + } + return handles; +} diff --git a/typescript/packages/traceai_mcp/src/client.ts b/typescript/packages/traceai_mcp/src/client.ts new file mode 100644 index 000000000..78935842d --- /dev/null +++ b/typescript/packages/traceai_mcp/src/client.ts @@ -0,0 +1,68 @@ +import { context, Span, SpanKind, SpanStatusCode, trace, TracerProvider } from "@opentelemetry/api"; +import { FITracer, TraceConfigOptions } from "@traceai/fi-core"; +import type { AttachmentCapturePolicy, AttachmentManager } from "@traceai/fi-core/attachments"; +import { captureMCPResult } from "./attachments"; +import { VERSION } from "./version"; + +export interface MCPClientTracingConfig { + tracerProvider?: TracerProvider; + /** The SAME manager as the provider/auto runtime; never creates another uploader. */ + attachments?: AttachmentManager; + traceConfig?: TraceConfigOptions; + attachmentCapture?: AttachmentCapturePolicy; +} + +const WRAPPED = new WeakSet(); + +/** + * Trace the actual client callTool/readResource boundaries (not transport refs). + * The proxy preserves SDK receiver, argument/result/error identity and cancellation. + * Only successfully returned typed bytes are observed. Network work is never awaited. + */ +export function wrapMCPClient(client: C, config: MCPClientTracingConfig = {}): C { + if (WRAPPED.has(client)) return client; + const methods = new Map(); + const proxy = new Proxy(client, { + get(target, key) { + if (methods.has(key)) return methods.get(key); + const value = Reflect.get(target, key, target); + if (typeof value !== "function") return value; + if (key !== "callTool" && key !== "readResource") return value.bind(target); + const operation = key === "callTool" ? "tools/call" : "resources/read"; + const wrapped = (...args: unknown[]) => { + let span: Span | undefined; + let attachments: AttachmentManager | undefined; + try { + const provider = config.tracerProvider ?? trace.getTracerProvider(); + const owner = provider as TracerProvider & { attachments?: AttachmentManager; getDelegate?: () => TracerProvider & { attachments?: AttachmentManager } }; + attachments = config.attachments ?? owner.attachments ?? owner.getDelegate?.().attachments; + const tracer = new FITracer({ tracer: provider.getTracer("@traceai/mcp", VERSION), traceConfig: config.traceConfig ?? {} }); + span = tracer.startSpan(`mcp.${operation}`, { kind: SpanKind.CLIENT, attributes: { "gen_ai.span.kind": "TOOL", "mcp.method.name": operation } }); + } catch { /* Tracing cannot prevent the SDK call. */ } + const finish = (failed: boolean, result?: unknown) => { + try { + if (!span) return; + if (!failed && attachments) captureMCPResult(attachments, span, result, operation, config.attachmentCapture, config.traceConfig); + const toolError = result && typeof result === "object" && (result as { isError?: unknown }).isError === true; + span.setStatus({ code: failed || toolError ? SpanStatusCode.ERROR : SpanStatusCode.OK }); + } catch { /* Never log raw SDK exceptions. */ } + finally { try { span?.end(); } catch { /* Best effort. */ } } + }; + let result; + try { + result = span + ? context.with(trace.setSpan(context.active(), span), () => value.apply(target, args)) + : value.apply(target, args); + } catch (error) { finish(true); throw error; } + // Observe a side branch, but return the exact SDK promise to the caller. + try { result.then((response: unknown) => finish(false, response), () => finish(true)); } + catch { finish(true); } + return result; + }; + methods.set(key, wrapped); + return wrapped; + }, + }); + WRAPPED.add(proxy); + return proxy; +} diff --git a/typescript/packages/traceai_mcp/src/index.ts b/typescript/packages/traceai_mcp/src/index.ts index a986320c6..6a7219b8e 100644 --- a/typescript/packages/traceai_mcp/src/index.ts +++ b/typescript/packages/traceai_mcp/src/index.ts @@ -1 +1,4 @@ -export * from "./mcp"; \ No newline at end of file +export * from "./mcp"; +export { captureMCPResult, MCP_MEDIA_DECODE_BUDGET } from "./attachments"; +export { wrapMCPClient } from "./client"; +export type { MCPClientTracingConfig } from "./client"; diff --git a/typescript/packages/traceai_mcp/test/attachment-harness.cjs b/typescript/packages/traceai_mcp/test/attachment-harness.cjs new file mode 100644 index 000000000..c7f5234f6 --- /dev/null +++ b/typescript/packages/traceai_mcp/test/attachment-harness.cjs @@ -0,0 +1,46 @@ +const https = require('node:https'); +const fs = require('node:fs'); +const { randomUUID } = require('node:crypto'); +const { once } = require('node:events'); +const { createNodeAttachmentManager } = require('@traceai/fi-core/attachments/node'); +const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base'); +const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a5XcAAAAASUVORK5CYII=', 'base64'); +const WAV = Buffer.alloc(48); WAV.write('RIFF'); WAV.writeUInt32LE(40, 4); WAV.write('WAVEfmt ', 8); WAV.writeUInt32LE(16, 16); WAV.writeUInt16LE(1, 20); WAV.writeUInt16LE(1, 22); WAV.writeUInt32LE(8000, 24); WAV.writeUInt32LE(16000, 28); WAV.writeUInt16LE(2, 32); WAV.writeUInt16LE(16, 34); WAV.write('data', 36); WAV.writeUInt32LE(4, 40); +const PDF = Buffer.from('%PDF-1.7\nsynthetic fixture\n%%EOF'); +const identity = { traceId: '0123456789abcdef0123456789abcdef', spanId: '0123456789abcdef', traceFlags: 1 }; + +async function harness(options = {}) { + const requests = [], uploads = [], records = []; + const policy = { version: '1', enabled: true, allowed_sources: ['Bytes', 'Blob'], allowed_modalities: ['audio', 'image', 'video', 'document', 'file'], require_media_redaction: false, require_metadata_removal: false, allow_unredacted_media_with_text_pii: false, record_audio: false, record_video: false, ...options.serverPolicy }; + const scope = { organization_id: randomUUID(), workspace_id: randomUUID(), project_id: randomUUID() }; + const server = https.createServer({ key: fs.readFileSync(process.env.ATTACHMENT_TEST_KEY), cert: fs.readFileSync(process.env.NODE_EXTRA_CA_CERTS) }, async (req, res) => { + const chunks = []; + for await (const chunk of req) chunks.push(chunk); + const body = Buffer.concat(chunks); + requests.push({ path: req.url, headers: req.headers }); + res.setHeader('content-type', 'application/json'); + if (req.url === '/tracer/v1/attachment-sessions') { + const request = JSON.parse(body); + res.end(JSON.stringify({ schema_version: 1, scope, capture_session_id: request.capture_session_id, policy, limits: { max_upload_bytes: 1048576, segment_bytes: 8388608, segment_duration_ms: 30000, recording_bytes: 1073741824, recording_duration_ms: 7200000, active_transfers: 16, active_recordings: 4, reserved_bytes: 1073741824, validation_jobs: 1024, initializations_per_minute: 120, links_per_minute: 1000, upload_bytes_per_second: 1048576, playback_bytes_per_second: 1048576, transfer_timeout_seconds: 600, grant_ttl_seconds: 300, revocation_check_seconds: 5 }, expires_at: new Date(Date.now() + 600000).toISOString(), transfer_modes: ['authenticated_stream'] })); + } else if (req.url === `/tracer/v1/projects/${scope.project_id}/attachments/uploads`) { + const request = JSON.parse(body); records.push(request); + res.statusCode = 201; + res.end(JSON.stringify({ upload_id: randomUUID(), attachment_id: request.attachment_id, occurrence_id: request.occurrence_id, state: 'pending_upload', reserved_bytes: request.declared_bytes, expires_at: new Date(Date.now() + 600000).toISOString(), transfer_mode: 'authenticated_stream', write_capability: 'synthetic-write-capability' })); + } else if (req.url.endsWith('/content')) { + uploads.push(body); res.end(JSON.stringify({ upload_id: req.url.split('/').at(-2), state: 'pending_upload' })); + } else if (req.url.endsWith('/complete')) { + res.statusCode = 202; res.end(JSON.stringify({ upload_id: req.url.split('/').at(-2), state: 'validating', reason: 'binding_pending' })); + } else { res.statusCode = 404; res.end('{}'); } + }); + server.listen(0, '127.0.0.1'); await once(server, 'listening'); + const manager = createNodeAttachmentManager({ enabled: true, projectName: 'fixture', projectType: 'observe', endpoint: `https://127.0.0.1:${server.address().port}`, headers: { authorization: 'Bearer synthetic-bootstrap' }, ...options.manager }); + await manager.ready(); + const exporter = new InMemorySpanExporter(); + const processor = new SimpleSpanProcessor(exporter); + const provider = new BasicTracerProvider({ spanProcessors: [processor] }); + provider.attachments = manager; + return { manager, provider, exporter, requests, uploads, records, async close() { + await manager.shutdown(); await provider.shutdown(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); + } }; +} +module.exports = { harness, PNG, WAV, PDF, identity }; diff --git a/typescript/packages/traceai_mcp/test/attachments.test.cjs b/typescript/packages/traceai_mcp/test/attachments.test.cjs new file mode 100644 index 000000000..fdc228fb9 --- /dev/null +++ b/typescript/packages/traceai_mcp/test/attachments.test.cjs @@ -0,0 +1,112 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { captureMCPResult, wrapMCPClient, MCP_MEDIA_DECODE_BUDGET } = require('../dist/src'); +const { harness, PNG, WAV, PDF, identity } = require('./attachment-harness.cjs'); +const image = () => ({ type: 'image', data: PNG.toString('base64'), mimeType: 'image/png' }); + +test('typed image/audio/nested resource bytes use the shared TLS uploader and exact span', async () => { + const h = await harness(); + try { + const response = { content: [image(), { type: 'audio', data: WAV.toString('base64'), mimeType: 'audio/wav' }, { type: 'resource', resource: { uri: 'file:///untrusted/secret.pdf', mimeType: 'application/pdf', blob: PDF.toString('base64') } }] }; + const promise = Promise.resolve(response), args = [{ name: 'screenshot' }, undefined, { signal: new AbortController().signal }]; + const client = { callTool(...received) { assert.equal(this, client); assert.deepEqual(received, args); return promise; } }; + const wrapped = wrapMCPClient(client, { tracerProvider: h.provider }); + assert.equal(wrapMCPClient(wrapped), wrapped); + assert.equal(wrapped.callTool(...args), promise); + assert.equal(await promise, response); + await h.manager.flush(); + assert.equal(h.uploads.length, 3); + assert.deepEqual(h.uploads.map(b => b.toString('base64')).sort(), [PNG, WAV, PDF].map(b => b.toString('base64')).sort()); + const span = h.exporter.getFinishedSpans()[0]; + assert.equal(span.name, 'mcp.tools/call'); + for (const record of h.records) { + assert.equal(record.association.parent.span_id, span.spanContext().spanId); + assert.equal(record.direction, 'output'); + assert.equal(record.purpose, 'tool_result'); + } + assert.equal(JSON.parse(span.attributes['fi.attachment.refs']).length, 3); + assert.ok(!JSON.stringify(span.attributes).includes('untrusted')); + assert.ok(!JSON.stringify(h.records).includes('secret.pdf')); + for (const request of h.requests.filter(r => /\/(content|complete)$/.test(r.path))) assert.equal(request.headers.authorization, 'Bearer synthetic-write-capability'); + } finally { await h.close(); } +}); + +for (const [label, options, capture] of [ + ['disabled', { enabled: false }], + ...['hideInputs', 'hideOutputs', 'hideInputMessages', 'hideOutputMessages', 'hideInputText', 'hideOutputText', 'hideInputImages', 'piiRedaction'].map(flag => [flag, { traceConfig: { [flag]: true } }]), + ['captureContent', {}, { captureContent: false }], ['muted', {}, { muted: true }], ['temporaryChat', {}, { temporaryChat: true }], + ['recordInputs', {}, { recordInputs: false }], ['recordOutputs', {}, { recordOutputs: false }], +]) test(`privacy ${label}: no decoding, source getters, reference or network upload`, async () => { + const h = await harness({ manager: options }); + try { + let reads = 0; + const part = { type: 'image', mimeType: 'image/png', get data() { reads++; throw Error('secret'); } }; + const handles = captureMCPResult(h.manager, identity, { content: [part] }, 'tools/call', capture); + await h.manager.flush(); + assert.equal(reads, 0); assert.equal(h.uploads.length, 0); assert.equal(h.records.length, 0); + assert.notEqual(handles[0].admission, 'queued'); + if (label === 'disabled') assert.equal(h.requests.length, 0); + } finally { await h.close(); } +}); + +test('resource read bytes are captured; links, structuredContent and arbitrary paths are never dereferenced', async () => { + const h = await harness(); + try { + let uriReads = 0; + const resource = { mimeType: 'application/pdf', blob: PDF.toString('base64'), get uri() { uriReads++; throw Error('secret'); } }; + captureMCPResult(h.manager, identity, { contents: [resource] }, 'resources/read'); + captureMCPResult(h.manager, identity, { content: [{ type: 'resource_link', get uri() { throw Error('secret'); } }, { type: 'text', text: 'file:///x' }], structuredContent: { screenshot: image() } }); + await h.manager.flush(); + assert.equal(uriReads, 0); assert.equal(h.uploads.length, 1); assert.deepEqual(h.uploads[0], PDF); + } finally { await h.close(); } +}); + +test('malformed, MIME-mislabelled, oversized and excess parts cannot consume unbounded decode work', async () => { + const h = await harness(); + try { + const parts = [ + { type: 'image', mimeType: 'audio/wav', data: PNG.toString('base64') }, + { ...image(), data: '!!!!' }, { ...image(), data: 'a'.repeat(MCP_MEDIA_DECODE_BUDGET * 2) }, + ]; + captureMCPResult(h.manager, identity, { content: parts }); + await h.manager.flush(); assert.equal(h.uploads.length, 0); + captureMCPResult(h.manager, identity, { content: Array.from({ length: 100 }, image) }); + await h.manager.flush(); assert.equal(h.uploads.length, 64); + } finally { await h.close(); } +}); + +test('cancellation and synchronous failures retain original error and produce no media', async () => { + const h = await harness(); + try { + const controller = new AbortController(), error = new Error('synthetic abort'); + const rejected = Promise.reject(error); + const client = { callTool(_request, _schema, options) { assert.equal(options.signal, controller.signal); return rejected; }, readResource() { throw error; } }; + const wrapped = wrapMCPClient(client, { tracerProvider: h.provider }); + controller.abort(); + assert.equal(wrapped.callTool({}, undefined, { signal: controller.signal }), rejected); + await assert.rejects(rejected, e => e === error); + assert.throws(() => wrapped.readResource(), e => e === error); + await h.manager.flush(); assert.equal(h.uploads.length, 0); + assert.equal(h.exporter.getFinishedSpans().length, 2); + } finally { await h.close(); } +}); + +test('error media and stricter integration flags cannot bypass manager policy', async () => { + const h = await harness({ manager: { traceConfig: { hideErrorDetails: true } } }); + try { + let reads = 0; + const part = { type: 'image', mimeType: 'image/png', get data() { reads++; return PNG.toString('base64'); } }; + captureMCPResult(h.manager, identity, { content: [part], isError: true }); + const wrapped = wrapMCPClient({ callTool: () => Promise.resolve({ content: [part] }) }, { tracerProvider: h.provider, traceConfig: { hideInputImages: true } }); + await wrapped.callTool(); await h.manager.flush(); assert.equal(reads, 0); assert.equal(h.uploads.length, 0); + } finally { await h.close(); } +}); + +test('policy tightening after enqueue discards decoded bytes before upload', async () => { + const h = await harness(); + try { + const [handle] = captureMCPResult(h.manager, identity, { content: [image()] }); + h.manager.updatePolicy({ enabled: false }); + await h.manager.flush(); assert.equal(h.uploads.length, 0); assert.notEqual((await handle.completion).status, 'validating'); + } finally { await h.close(); } +}); diff --git a/typescript/packages/traceai_mcp/test/real-sdk.test.cjs b/typescript/packages/traceai_mcp/test/real-sdk.test.cjs new file mode 100644 index 000000000..cdf96529d --- /dev/null +++ b/typescript/packages/traceai_mcp/test/real-sdk.test.cjs @@ -0,0 +1,60 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const http = require('node:http'); +const path = require('node:path'); +const { once } = require('node:events'); +const { wrapMCPClient } = require('../dist/src'); +const { harness, PNG, WAV, PDF } = require('./attachment-harness.cjs'); +const sdk = name => require(path.join(process.env.MCP_SDK_ROOT, 'dist/cjs', name)); + +test('real MCP SDK SSE tool screenshot, audio, resource read and cancellation', async () => { + const { Client } = sdk('client/index.js'); + const { Server } = sdk('server/index.js'); + const { SSEClientTransport } = sdk('client/sse.js'); + const { SSEServerTransport } = sdk('server/sse.js'); + const { CallToolRequestSchema, ReadResourceRequestSchema } = sdk('types.js'); + const protocol = new Server({ name: 'synthetic-media', version: '1.0.0' }, { capabilities: { tools: {}, resources: {} } }); + const response = { content: [{ type: 'image', mimeType: 'image/png', data: PNG.toString('base64') }, { type: 'audio', mimeType: 'audio/wav', data: WAV.toString('base64') }, { type: 'resource', resource: { uri: 'file:///not-opened.pdf', mimeType: 'application/pdf', blob: PDF.toString('base64') } }] }; + protocol.setRequestHandler(CallToolRequestSchema, async request => { + if (request.params.name === 'wait') { await new Promise(resolve => setTimeout(resolve, 100)); } + return response; + }); + protocol.setRequestHandler(ReadResourceRequestSchema, async () => ({ contents: [{ uri: 'fixture:pdf', mimeType: 'application/pdf', blob: PDF.toString('base64') }] })); + let transport; + const server = http.createServer(async (req, res) => { + if (req.method === 'GET' && req.url === '/sse') { + transport = new SSEServerTransport('/messages', res); + await protocol.connect(transport); + } else if (req.method === 'POST' && req.url.startsWith('/messages')) { + const chunks = []; for await (const chunk of req) chunks.push(chunk); + await transport.handlePostMessage(req, res, JSON.parse(Buffer.concat(chunks))); + } else { res.writeHead(404); res.end(); } + }); + server.listen(0, '127.0.0.1'); await once(server, 'listening'); + const client = new Client({ name: 'fixture-client', version: '1.0.0' }); + await client.connect(new SSEClientTransport(new URL(`http://127.0.0.1:${server.address().port}/sse`))); + const h = await harness(); + try { + const traced = wrapMCPClient(client, { tracerProvider: h.provider }); + assert.deepEqual(await traced.callTool({ name: 'screenshot', arguments: {} }), response); + await traced.readResource({ uri: 'fixture:pdf' }); + await h.manager.flush(); + assert.equal(h.uploads.length, 4); + const spans = h.exporter.getFinishedSpans(); + assert.equal(spans.length, 2); + assert.equal(h.records.filter(r => r.association.parent.span_id === spans[0].spanContext().spanId).length, 3); + const abort = new AbortController(); + const pending = traced.callTool({ name: 'wait', arguments: {} }, undefined, { signal: abort.signal }); + abort.abort(); await assert.rejects(pending); + await h.manager.flush(); assert.equal(h.uploads.length, 4); + for (const policy of [{ enabled: false }, { enabled: true, traceConfig: { hideInputImages: true } }, { enabled: true, traceConfig: { hideInputs: true } }, { enabled: true, traceConfig: { piiRedaction: true } }]) { + h.manager.updatePolicy(policy); + await traced.callTool({ name: 'screenshot', arguments: {} }); await h.manager.flush(); + // hideInputImages leaves typed audio/PDF allowed; the other controls deny all. + const expected = policy.traceConfig?.hideInputImages ? 6 : policy.enabled === false ? 4 : 6; + assert.equal(h.uploads.length, expected); + } + } finally { + await client.close(); await protocol.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); await h.close(); + } +}); diff --git a/typescript/packages/traceai_mcp/test/run-attachments.cjs b/typescript/packages/traceai_mcp/test/run-attachments.cjs new file mode 100644 index 000000000..b7dae0471 --- /dev/null +++ b/typescript/packages/traceai_mcp/test/run-attachments.cjs @@ -0,0 +1,15 @@ +// Runs the maintained suites with a fresh, explicitly trusted loopback TLS certificate. +const { execFileSync, spawnSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'media-test-tls-')); +try { + const key = path.join(dir, 'key.pem'), cert = path.join(dir, 'cert.pem'); + execFileSync('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-keyout', key, '-out', cert, '-days', '1', '-subj', '/CN=localhost', '-addext', 'subjectAltName=IP:127.0.0.1,DNS:localhost'], { stdio: 'ignore' }); + const args = process.argv.slice(2); + const files = args.length ? args : [path.join(__dirname, 'attachments.test.cjs'), path.resolve(__dirname, '../../traceai_claude_agent_sdk/test/attachments.test.cjs')]; + const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit', timeout: 240000, env: { ...process.env, ATTACHMENT_TEST_KEY: key, NODE_EXTRA_CA_CERTS: cert } }); + if (result.error) throw result.error; + process.exitCode = result.status ?? 1; +} finally { fs.rmSync(dir, { recursive: true, force: true }); } diff --git a/typescript/packages/traceai_mcp/test/run-sdk-matrix.cjs b/typescript/packages/traceai_mcp/test/run-sdk-matrix.cjs new file mode 100644 index 000000000..29afc5143 --- /dev/null +++ b/typescript/packages/traceai_mcp/test/run-sdk-matrix.cjs @@ -0,0 +1,30 @@ +// Cloud/CI only. Installs exact real upstream SDKs into isolated temporary directories. +const { execFileSync, spawnSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const pins = require('./sdk-versions.json'); +const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'media-sdk-matrix-')); +const evidence = path.resolve(process.argv[2] || dir); +fs.mkdirSync(evidence, { recursive: true }); +try { + for (const [kind, name, versions, testFile, envKey] of [ + ['mcp', '@modelcontextprotocol/sdk', pins.mcp, path.join(__dirname, 'real-sdk.test.cjs'), 'MCP_SDK_ROOT'], + ['agent', '@anthropic-ai/claude-agent-sdk', pins.claudeAgent, path.resolve(__dirname, '../../traceai_claude_agent_sdk/test/real-sdk.test.cjs'), 'AGENT_SDK_ROOT'], + ]) { + for (const [tier, version] of Object.entries(versions)) { + const prefix = path.join(dir, `${kind}-${tier}`); fs.mkdirSync(prefix); + console.log(`STAGE ${kind} ${tier} ${version}`); + const install = execFileSync('npm', ['install', '--prefix', prefix, '--ignore-scripts', '--no-audit', '--no-fund', `${name}@${version}`], { encoding: 'utf8', timeout: 180000 }); + fs.writeFileSync(path.join(evidence, `${kind}-${tier}-install.log`), install); + const actual = JSON.parse(fs.readFileSync(path.join(prefix, 'node_modules', name, 'package.json'))).version; + if (actual !== version) throw Error('version mismatch'); + const result = spawnSync(process.execPath, [path.join(__dirname, 'run-attachments.cjs'), testFile], { encoding: 'utf8', timeout: 240000, env: { ...process.env, [envKey]: path.join(prefix, 'node_modules', name) } }); + const log = (result.stdout || '') + (result.stderr || ''); + fs.writeFileSync(path.join(evidence, `${kind}-${tier}.log`), log); console.log(log); + if (result.error) throw result.error; + if (result.status !== 0) throw Error(`${kind} ${version} qualification failed`); + } + } + fs.writeFileSync(path.join(evidence, 'sdk-versions.json'), JSON.stringify({ node: process.version, ...pins }, null, 2)); +} finally { fs.rmSync(dir, { recursive: true, force: true }); } diff --git a/typescript/packages/traceai_mcp/test/sdk-versions.json b/typescript/packages/traceai_mcp/test/sdk-versions.json new file mode 100644 index 000000000..b25e94e34 --- /dev/null +++ b/typescript/packages/traceai_mcp/test/sdk-versions.json @@ -0,0 +1,4 @@ +{ + "mcp": { "floor": "1.10.2", "latest": "1.32.2" }, + "claudeAgent": { "floor": "0.3.277", "latest": "0.3.322" } +} From 27a462fae7010262fc948db1a0a92e89bfb3cbb3 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Tue, 10 Nov 2026 20:05:53 -0800 Subject: [PATCH 2/5] fix(mcp,claude-agent-sdk): one proxy per client and per-query media dedup 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 --- .../src/attachments.ts | 4 ++++ .../traceai_claude_agent_sdk/src/spans.ts | 6 ++++-- .../test/attachments.test.cjs | 10 +++++++++ typescript/packages/traceai_mcp/src/client.ts | 21 +++++++++++++------ .../traceai_mcp/test/attachments.test.cjs | 14 +++++++++++++ 5 files changed, 47 insertions(+), 8 deletions(-) diff --git a/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts index 72a548bb4..3c9010ef0 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts @@ -21,6 +21,7 @@ export function captureAgentMedia( span: Span, content: unknown, options: { toolCallId?: string; messageIndex: number; isError?: boolean; toolResult: boolean }, + observed?: WeakSet, ): void { const manager = config.attachments; if (!manager || !Array.isArray(content)) return; @@ -34,6 +35,9 @@ export function captureAgentMedia( const mimeType = source.media_type; // Do not let a misleading MIME relabel an image to bypass hideInputImages. if (block.type === "image" ? !mimeType.startsWith("image/") : mimeType !== "application/pdf") continue; + // One occurrence per original block object per query: a replayed/re-yielded frame is not new media. + // Identity only; the encoded data is never read for deduplication. + if (observed) { if (observed.has(source)) continue; observed.add(source); } const f = config.attachmentTraceConfig ?? {}; const c = config.attachmentCapture ?? {}; const errorDetail = options.isError === true || c.errorDetail === true; diff --git a/typescript/packages/traceai_claude_agent_sdk/src/spans.ts b/typescript/packages/traceai_claude_agent_sdk/src/spans.ts index 2b7892887..107151d4a 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/spans.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/spans.ts @@ -290,6 +290,8 @@ export class QueryTracer { private readonly tracer: Tracer; private readonly media: AgentAttachmentContext; private messageIndex = 0; + /** Original media source objects already offered to the manager during this query. */ + private readonly observedMedia = new WeakSet(); private readonly policy: ContentPolicy; private readonly params: QueryParamsLike; private readonly options: OptionsLike | undefined; @@ -606,7 +608,7 @@ export class QueryTracer { const affectedTurns = new Set(); captureAgentMedia({ ...this.media, attachmentCapture: { ...this.media.attachmentCapture, recordInputs: this.policy.hideInputMessages ? false : this.media.attachmentCapture?.recordInputs } }, - this.conversation!, message.message?.content, { messageIndex: this.messageIndex, toolResult: false }); + this.conversation!, message.message?.content, { messageIndex: this.messageIndex, toolResult: false }, this.observedMedia); for (const block of contentBlocks(message.message?.content)) { if (block && block.type === "tool_result" && typeof block.tool_use_id === "string") { const turn = this.endTool(block.tool_use_id, block.content, block.is_error === true); @@ -903,7 +905,7 @@ export class QueryTracer { captureAgentMedia({ ...this.media, attachmentCapture: { ...this.media.attachmentCapture, recordInputs: this.policy.hideInputMessages ? false : this.media.attachmentCapture?.recordInputs, recordOutputs: this.policy.hideOutputMessages ? false : this.media.attachmentCapture?.recordOutputs } }, - span, content, { toolCallId: id, messageIndex: this.messageIndex, isError, toolResult: true }); + span, content, { toolCallId: id, messageIndex: this.messageIndex, isError, toolResult: true }, this.observedMedia); const output = this.policy.hideOutputs ? "" : this.clean(flattenToolResult(content), CONTENT_MAX); if (!this.policy.hideOutputs) { const serialized = output; diff --git a/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs index f0774e33e..246a991fd 100644 --- a/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs +++ b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs @@ -92,3 +92,13 @@ test('iterator cancellation and control method receivers are unchanged', async ( assert.equal(closed, 1); assert.equal(h.uploads.length, 0); } finally { await h.close(); } }); + +test('the same original block re-yielded in user frames is one occurrence per query', async () => { + const h = await harness(); + try { + const block = image(); + const frame = { type: 'user', message: { content: [block] } }; + await run(h, [frame, frame, { type: 'user', message: { content: [block] } }]); + assert.equal(h.uploads.length, 1); assert.equal(h.records.length, 1); + } finally { await h.close(); } +}); diff --git a/typescript/packages/traceai_mcp/src/client.ts b/typescript/packages/traceai_mcp/src/client.ts index 78935842d..93bdb3dde 100644 --- a/typescript/packages/traceai_mcp/src/client.ts +++ b/typescript/packages/traceai_mcp/src/client.ts @@ -12,7 +12,8 @@ export interface MCPClientTracingConfig { attachmentCapture?: AttachmentCapturePolicy; } -const WRAPPED = new WeakSet(); +const PROXIES = new WeakSet(); +const BY_CLIENT = new WeakMap(); /** * Trace the actual client callTool/readResource boundaries (not transport refs). @@ -20,7 +21,10 @@ const WRAPPED = new WeakSet(); * Only successfully returned typed bytes are observed. Network work is never awaited. */ export function wrapMCPClient(client: C, config: MCPClientTracingConfig = {}): C { - if (WRAPPED.has(client)) return client; + if (PROXIES.has(client)) return client; + // One proxy per raw client: wrapping twice must not create nested spans or duplicate capture. + const existing = BY_CLIENT.get(client); + if (existing) return existing as C; const methods = new Map(); const proxy = new Proxy(client, { get(target, key) { @@ -54,15 +58,20 @@ export function wrapMCPClient(client: C, config: MCPClientTrac ? context.with(trace.setSpan(context.active(), span), () => value.apply(target, args)) : value.apply(target, args); } catch (error) { finish(true); throw error; } - // Observe a side branch, but return the exact SDK promise to the caller. - try { result.then((response: unknown) => finish(false, response), () => finish(true)); } - catch { finish(true); } + // Observe a side branch, but return the exact SDK promise (or value) to the caller. + try { + const thenable = result !== null && (typeof result === "object" || typeof result === "function") && + typeof (result as { then?: unknown }).then === "function"; + if (thenable) (result as PromiseLike).then((response: unknown) => finish(false, response), () => finish(true)); + else finish(false, result); + } catch { finish(true); } return result; }; methods.set(key, wrapped); return wrapped; }, }); - WRAPPED.add(proxy); + PROXIES.add(proxy); + BY_CLIENT.set(client, proxy); return proxy; } diff --git a/typescript/packages/traceai_mcp/test/attachments.test.cjs b/typescript/packages/traceai_mcp/test/attachments.test.cjs index fdc228fb9..ffd02ec6e 100644 --- a/typescript/packages/traceai_mcp/test/attachments.test.cjs +++ b/typescript/packages/traceai_mcp/test/attachments.test.cjs @@ -12,6 +12,7 @@ test('typed image/audio/nested resource bytes use the shared TLS uploader and ex const client = { callTool(...received) { assert.equal(this, client); assert.deepEqual(received, args); return promise; } }; const wrapped = wrapMCPClient(client, { tracerProvider: h.provider }); assert.equal(wrapMCPClient(wrapped), wrapped); + assert.equal(wrapMCPClient(client, { tracerProvider: h.provider }), wrapped, 'one proxy per raw client'); assert.equal(wrapped.callTool(...args), promise); assert.equal(await promise, response); await h.manager.flush(); @@ -110,3 +111,16 @@ test('policy tightening after enqueue discards decoded bytes before upload', asy await h.manager.flush(); assert.equal(h.uploads.length, 0); assert.notEqual((await handle.completion).status, 'validating'); } finally { await h.close(); } }); + +test('synchronous non-thenable result is returned unchanged and recorded as success', async () => { + const h = await harness(); + try { + const response = { content: [image()] }; + const wrapped = wrapMCPClient({ callTool: () => response }, { tracerProvider: h.provider }); + assert.equal(wrapped.callTool({ name: 'sync' }), response); + await h.manager.flush(); + const [span] = h.exporter.getFinishedSpans(); + assert.equal(span.status.code, 1); + assert.equal(h.uploads.length, 1); + } finally { await h.close(); } +}); From 5780b83be4e64a0a3987977931a86242552e005a Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Tue, 10 Nov 2026 20:19:11 -0800 Subject: [PATCH 3/5] test(claude-agent-sdk): align stale suite expectations and document media 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 --- typescript/packages/traceai_claude_agent_sdk/README.md | 10 ++++++++-- .../src/__tests__/parity.test.ts | 3 ++- .../src/__tests__/wrapper.test.ts | 3 ++- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/typescript/packages/traceai_claude_agent_sdk/README.md b/typescript/packages/traceai_claude_agent_sdk/README.md index d664d7f9f..05a10bd12 100644 --- a/typescript/packages/traceai_claude_agent_sdk/README.md +++ b/typescript/packages/traceai_claude_agent_sdk/README.md @@ -180,5 +180,11 @@ Parameters, hooks, message objects, iterator cancellation and control methods remain owned by the application. The wrapper neither awaits uploads during inference nor keeps spans open for uploads. Flush the provider before process exit; if an explicitly supplied manager differs from the provider's manager, -flush that manager as well. Do not enable overlapping media capture at both the -agent and provider boundary: cross-adapter duplicate suppression is not provided. +flush that manager as well. + +Each original media block is offered to the manager at most once per query, +so a replayed or re-yielded frame does not create a second occurrence. The SDK +runs model calls inside the spawned Claude Code executable, so an in-process +Anthropic provider instrumentation does not see the same media. If you also +capture the same bytes yourself through another adapter, the manager does not +deduplicate across adapters. diff --git a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/parity.test.ts b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/parity.test.ts index 9b1fbb424..d9ff43bec 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/parity.test.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/parity.test.ts @@ -60,7 +60,8 @@ describe("Python parity", () => { const block = source.slice(source.indexOf("BUILTIN_TOOLS = frozenset([")); const list = block.slice(0, block.indexOf("])")); const python = [...list.matchAll(/"([A-Za-z]+)"/g)].map((m) => m[1]); - expect(python.length).toBe(13); + // Python now lists "Agent" too (the 0.3.x subagent tool name TS already had). + expect(python.length).toBe(14); for (const name of python) expect(BUILTIN_TOOLS.has(name)).toBe(true); }); diff --git a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts index 786ba4038..61a3b1300 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts @@ -510,7 +510,8 @@ describe("wrapQuery", () => { expect(conversation.attributes["claude_agent.error.type"]).toBe("error_max_turns"); // The result's error strings are raw error text: hidden with hideOutputs. expect(conversation.attributes["claude_agent.error.message"]).toBeUndefined(); - expect(conversation.status.message).toBe("error_max_turns"); + // fi-core hides the status description with hidden outputs/error details. + expect(conversation.status.message).toBeUndefined(); expect(conversation.attributes["gen_ai.cost.total"]).toBe(0.002); }); From 148b91bc74e07c8022aae69113060fc7bb787737 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Wed, 11 Nov 2026 03:37:46 -0800 Subject: [PATCH 4/5] fix(mcp,claude-agent-sdk): preflight every media part before reading 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 --- .../traceai_claude_agent_sdk/README.md | 6 +- .../src/attachments.ts | 60 +++++++++++----- .../test/attachments.test.cjs | 47 +++++++++++- typescript/packages/traceai_mcp/README.md | 10 ++- .../packages/traceai_mcp/src/attachments.ts | 66 +++++++++++------ .../traceai_mcp/test/attachment-harness.cjs | 7 +- .../traceai_mcp/test/attachments.test.cjs | 71 ++++++++++++++++++- 7 files changed, 219 insertions(+), 48 deletions(-) diff --git a/typescript/packages/traceai_claude_agent_sdk/README.md b/typescript/packages/traceai_claude_agent_sdk/README.md index 05a10bd12..2e60540d8 100644 --- a/typescript/packages/traceai_claude_agent_sdk/README.md +++ b/typescript/packages/traceai_claude_agent_sdk/README.md @@ -171,7 +171,11 @@ you may also supply `attachments` explicitly when using a custom provider. Only typed inline base64 image/PDF sources are observed, with at most 64 parts and 256 KiB of decoded bytes per content list. URLs, file IDs, arbitrary tool -objects and local paths are not retrieved. Input hide rules apply to tool media +objects and local paths are not retrieved. Each block is checked with the +manager's `preflight` (every privacy, sampling and budget rule) before its base64 +is read or decoded, so denied media is never touched. SDK messages arrive complete, +not as byte streams, so there is no streaming capture to configure. +Input hide rules apply to tool media that is sent back to the model; output hide rules also apply to tool results. Required PII redaction without a qualified media sanitizer denies raw capture. Original media may contain embedded metadata. diff --git a/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts index 3c9010ef0..5b57a5f6d 100644 --- a/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts +++ b/typescript/packages/traceai_claude_agent_sdk/src/attachments.ts @@ -5,6 +5,20 @@ import type { AttachmentCapturePolicy, AttachmentManager } from "@traceai/fi-cor /** One observed message/tool result has a bounded synchronous decode budget. */ const DECODE_BUDGET = 256 * 1024; +/** Decoded length of canonical padded base64 within `limit`, without decoding; 0 when invalid or too large. */ +function decodedSize(encoded: unknown, limit: number): number { + if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(limit / 3)) return 0; + if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) return 0; + const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); + return size > 0 && size <= limit ? size : 0; +} +function decodeBase64(encoded: unknown, limit: number): Uint8Array | undefined { + const size = decodedSize(encoded, limit); + if (!size) return undefined; + const bytes = Buffer.from(encoded as string, "base64"); + return bytes.byteLength === size ? bytes : undefined; +} + export interface AgentAttachmentContext { attachments?: AttachmentManager; attachmentCapture?: AttachmentCapturePolicy; @@ -15,6 +29,9 @@ export interface AgentAttachmentContext { * Original Anthropic image/document base64 blocks only, before text truncation. * No arbitrary object walk, URL/file-ID resolver, path opening or stream reads. * Capturing an existing tool screenshot never starts a recorder. + * Every block is preflighted (deny-wins, budget reserved) before its base64 value is read or decoded; an admitted + * block whose bytes turn out malformed or over budget is released. SDK frames are complete parsed messages, never + * consumed byte streams, so consumed-stream capture does not apply. */ export function captureAgentMedia( config: AgentAttachmentContext, @@ -24,9 +41,10 @@ export function captureAgentMedia( observed?: WeakSet, ): void { const manager = config.attachments; - if (!manager || !Array.isArray(content)) return; + // A manager without preflight (an older core) cannot gate before decode: capture nothing. + if (!manager || typeof manager.preflight !== "function" || !Array.isArray(content)) return; let remaining = DECODE_BUDGET; - for (let partIndex = 0; partIndex < Math.min(content.length, 64); partIndex++) { + for (let partIndex = 0; partIndex < Math.min(content.length, 64) && remaining > 0; partIndex++) { try { const block = content[partIndex]; if (!block || (block.type !== "image" && block.type !== "document")) continue; @@ -45,27 +63,33 @@ export function captureAgentMedia( (block.type === "image" && f.hideInputImages) || (options.toolResult && (f.hideOutputs || f.hideOutputMessages || f.hideOutputText)) || (errorDetail && f.hideErrorDetails) || f.piiRedaction; - manager.attach(span, { - kind: "Bytes", - get data(): Uint8Array { - // Manager privacy, bootstrap, sampling and descriptor gates precede this getter. - const encoded = source.data; - if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(remaining / 3)) throw new Error("media unavailable"); - if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new Error("media unavailable"); - const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); - if (size > remaining) throw new Error("media unavailable"); - remaining -= size; - return Buffer.from(encoded, "base64"); - }, - }, { + const request = { mimeType, - direction: options.toolResult ? "output" : "input", - purpose: options.toolResult ? "tool_result" : "model_input", + direction: (options.toolResult ? "output" : "input") as "output" | "input", + purpose: (options.toolResult ? "tool_result" : "model_input") as "tool_result" | "model_input", + capture: { ...c, captureContent: hidden ? false : c.captureContent, modelInput: true, containsOutput: options.toolResult || c.containsOutput === true, errorDetail }, + }; + // Preflight (deny-wins, budget reserved) BEFORE the base64 value is read or decoded (design section 1). + // The value is read at most once, and only after a preflight passed every privacy, correlation and sampling step. + let encoded: unknown, read = false; + const value = () => { if (!read) { read = true; encoded = source.data; } return encoded; }; + let ticket = manager.preflight(span, { ...request, maxBytes: remaining }); + // too_large (negotiated limit below the budget) and queue_full (owned budget nearly used) come after every + // privacy, correlation and sampling step, so sizing the block exactly and retrying once is safe. + if (ticket.reason === "too_large" || ticket.reason === "queue_full") { + const exact = decodedSize(value(), remaining); + if (exact > 0) ticket = manager.preflight(span, { ...request, maxBytes: exact }); + } + if (!ticket.admitted) continue; + const bytes = decodeBase64(value(), Math.min(ticket.maxBytes, remaining)); + // Admitted but malformed or over budget: the reservation is returned and nothing is captured. + if (!bytes) { ticket.release(); continue; } + remaining -= bytes.byteLength; + ticket.attach({ kind: "Bytes", data: bytes }, { role: options.toolResult ? "tool" : "user", toolCallId: options.toolCallId, messageIndex: options.messageIndex, partIndex, - capture: { ...c, captureContent: hidden ? false : c.captureContent, modelInput: true, containsOutput: options.toolResult || c.containsOutput === true, errorDetail }, }); } catch { // Untrusted properties / malformed blocks do not change the SDK iterator. diff --git a/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs index 246a991fd..e7289b216 100644 --- a/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs +++ b/typescript/packages/traceai_claude_agent_sdk/test/attachments.test.cjs @@ -1,7 +1,7 @@ const { test } = require('node:test'); const assert = require('node:assert/strict'); const { wrapQuery } = require('../dist/src'); -const { harness, PNG, PDF } = require('../../traceai_mcp/test/attachment-harness.cjs'); +const { harness, PNG, PDF, warnings } = require('../../traceai_mcp/test/attachment-harness.cjs'); const image = () => ({ type: 'image', source: { type: 'base64', media_type: 'image/png', data: PNG.toString('base64') } }); function messages(content, isError = false) { return [ @@ -102,3 +102,48 @@ test('the same original block re-yielded in user frames is one occurrence per qu assert.equal(h.uploads.length, 1); assert.equal(h.records.length, 1); } finally { await h.close(); } }); + +function spyPreflight(manager) { + const original = manager.preflight.bind(manager), state = { calls: 0, reasons: [] }; + manager.preflight = (target, options) => { const ticket = original(target, options); state.calls++; state.reasons.push(ticket.reason); return ticket; }; + return state; +} + +test('each original block is preflighted before its base64 is read, and read at most once', async () => { + const h = await harness(); + try { + const spy = spyPreflight(h.manager); const reads = []; + const tracked = (mime, bytes) => ({ type: mime === 'application/pdf' ? 'document' : 'image', + source: Object.defineProperty({ type: 'base64', media_type: mime }, 'data', { enumerable: true, get() { reads.push(spy.calls); return bytes.toString('base64'); } }) }); + await run(h, messages([tracked('image/png', PNG), tracked('application/pdf', PDF)])); + assert.deepEqual(reads, [1, 2]); + assert.deepEqual(spy.reasons, ['queued', 'queued']); + assert.equal(h.uploads.length, 2); + } finally { await h.close(); } +}); + +test('a nearly used owned-byte budget still admits a small tool screenshot at its exact size', async () => { + const h = await harness({ manager: { maxOwnedBytes: 200 * 1024 } }); + try { + const spy = spyPreflight(h.manager); + const pdf = { type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: Buffer.concat([PDF, Buffer.alloc(100 * 1024)]).toString('base64') } }; + await run(h, messages([pdf, image()])); + assert.deepEqual(spy.reasons, ['too_large', 'queued', 'queue_full', 'queued']); + assert.equal(h.uploads.length, 2); + } finally { await h.close(); } +}); + +test('an admitted block with malformed base64 returns its reservation and uploads nothing', async () => { + const h = await harness(); + try { + await run(h, messages([{ type: 'image', source: { type: 'base64', media_type: 'image/png', data: '!!!!' } }])); + const status = h.manager.status(); + assert.equal(status.openTickets, 0); assert.equal(status.ownedBytes, 0); + assert.equal(h.uploads.length, 0); assert.equal(h.records.length, 0); + } finally { await h.close(); } +}); + +test('the loopback service is accepted as a V1 F01 peer: no FI_ATTACHMENTS_* warning in this process', async () => { + await new Promise(resolve => setImmediate(resolve)); + assert.deepEqual(warnings, []); +}); diff --git a/typescript/packages/traceai_mcp/README.md b/typescript/packages/traceai_mcp/README.md index 65bf8c2f1..acb6c6f4c 100644 --- a/typescript/packages/traceai_mcp/README.md +++ b/typescript/packages/traceai_mcp/README.md @@ -55,7 +55,10 @@ appears in a tool response. Required PII redaction without a qualified media sanitizer denies raw media capture. Original media may contain embedded metadata. Capture inspects only typed inline base64, at most 64 parts and 256 KiB of decoded -bytes per response. Larger parts are not uploaded. Resource links, URLs, local +bytes per response. Larger parts are not uploaded. Each part is checked with the +manager's `preflight` (every privacy, sampling and budget rule) before its base64 +is read or decoded, so denied media is never touched. MCP results arrive as fully +parsed objects, not byte streams, so there is no streaming capture to configure. Resource links, URLs, local paths and arbitrary `structuredContent` are not fetched or scraped. Capture never creates recordings or advances streams. The original SDK promise, response, error and cancellation signal are preserved. @@ -63,5 +66,6 @@ response, error and cancellation signal are preserved. Call the provider's `forceFlush()` or the shared manager's `flush()` before a short process exits. Upload completion means transferred for validation, not permission to play the content. Playback requires an authorized live occurrence -through the media gateway. Do not wrap the same underlying client multiple -times or enable overlapping media observers for the same operation. +through the media gateway. Wrapping the same client again returns the same +traced client, so it never creates nested spans or uploads the same media twice. +Do not enable a second, separate media observer for the same operation. diff --git a/typescript/packages/traceai_mcp/src/attachments.ts b/typescript/packages/traceai_mcp/src/attachments.ts index d23ced091..ffb4fd794 100644 --- a/typescript/packages/traceai_mcp/src/attachments.ts +++ b/typescript/packages/traceai_mcp/src/attachments.ts @@ -5,12 +5,31 @@ import type { AttachmentCapturePolicy, AttachmentHandle, AttachmentManager } fro /** Bounded synchronous decode budget, independent of the manager's owned queue. */ export const MCP_MEDIA_DECODE_BUDGET = 256 * 1024; const MAX_PARTS = 64; +/** A denied ticket returns its denial handle without reading this. */ +const NO_SOURCE = Object.freeze({ kind: "Bytes" as const, data: new Uint8Array(0) }); + +/** Decoded length of canonical padded base64 within `limit`, without decoding; 0 when invalid or too large. */ +function decodedSize(encoded: unknown, limit: number): number { + if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(limit / 3)) return 0; + if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) return 0; + const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); + return size > 0 && size <= limit ? size : 0; +} +function decodeBase64(encoded: unknown, limit: number): Uint8Array | undefined { + const size = decodedSize(encoded, limit); + if (!size) return undefined; + const bytes = Buffer.from(encoded as string, "base64"); + return bytes.byteLength === size ? bytes : undefined; +} /** * Observe only MCP CallToolResult.content / ReadResourceResult.contents. * No structuredContent scraping, URI retrieval, path access or stream reads. * Tool results are also model inputs: both directional policies apply. - * The manager reads the lazy Bytes source only AFTER its privacy/sampling gate. + * Every media part is preflighted (deny-wins, budget reserved) before its encoded value is read or decoded. + * Returns one handle per media part that reached preflight: denied parts carry their denial reason; an admitted part + * whose bytes turn out malformed or over the decode budget is released and omitted. + * Results are fully parsed objects, never consumed byte streams, so consumed-stream capture does not apply. */ export function captureMCPResult( manager: AttachmentManager, @@ -23,11 +42,13 @@ export function captureMCPResult( const handles: AttachmentHandle[] = []; let remaining = MCP_MEDIA_DECODE_BUDGET; try { + // A manager without preflight (an older core) cannot gate before decode: capture nothing. + if (typeof manager?.preflight !== "function") return handles; if (!result || typeof result !== "object") return handles; const envelope = result as Record; const parts = operation === "tools/call" ? envelope.content : envelope.contents; if (!Array.isArray(parts)) return handles; - for (let index = 0; index < Math.min(parts.length, MAX_PARTS); index++) { + for (let index = 0; index < Math.min(parts.length, MAX_PARTS) && remaining > 0; index++) { try { const part = parts[index]; if (!part || typeof part !== "object") continue; @@ -53,28 +74,29 @@ export function captureMCPResult( traceConfig.hideOutputs || traceConfig.hideOutputMessages || traceConfig.hideOutputText || (mimeType.startsWith("image/") && traceConfig.hideInputImages) || (errorDetail && traceConfig.hideErrorDetails) || traceConfig.piiRedaction; - const handle = manager.attach(span, { - kind: "Bytes", - get data(): Uint8Array { - // No data getter, length scan or decode before manager admission. - const encoded = media[field]; - if (typeof encoded !== "string" || !encoded.length || encoded.length > 4 * Math.ceil(remaining / 3)) { - throw new Error("media unavailable"); - } - if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) throw new Error("media unavailable"); - const size = encoded.length / 4 * 3 - (encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0); - if (size > remaining) throw new Error("media unavailable"); - remaining -= size; - return Buffer.from(encoded, "base64"); - }, - }, { + const request = { mimeType, - direction: "output", - purpose: "tool_result", - role: "tool", - partIndex: index, + direction: "output" as const, + purpose: "tool_result" as const, capture: { ...capture, captureContent: hidden ? false : capture.captureContent, modelInput: true, containsOutput: true, errorDetail }, - }); + }; + // Preflight (deny-wins, budget reserved) BEFORE the encoded value is read or decoded (design section 1). + // The value is read at most once, and only after a preflight passed every privacy, correlation and sampling step. + let encoded: unknown, read = false; + const source = () => { if (!read) { read = true; encoded = media[field]; } return encoded; }; + let ticket = manager.preflight(span, { ...request, maxBytes: remaining }); + // too_large (negotiated limit below the budget) and queue_full (owned budget nearly used) come after every + // privacy, correlation and sampling step, so sizing the part exactly and retrying once is safe. + if (ticket.reason === "too_large" || ticket.reason === "queue_full") { + const exact = decodedSize(source(), remaining); + if (exact > 0) ticket = manager.preflight(span, { ...request, maxBytes: exact }); + } + if (!ticket.admitted) { handles.push(ticket.attach(NO_SOURCE)); continue; } + const bytes = decodeBase64(source(), Math.min(ticket.maxBytes, remaining)); + // Admitted but malformed or over budget: the reservation is returned and nothing is captured. + if (!bytes) { ticket.release(); continue; } + remaining -= bytes.byteLength; + const handle = ticket.attach({ kind: "Bytes", data: bytes }, { role: "tool", partIndex: index }); handles.push(handle); } catch { // Malformed/untrusted media must not change the tool response or diagnostics. diff --git a/typescript/packages/traceai_mcp/test/attachment-harness.cjs b/typescript/packages/traceai_mcp/test/attachment-harness.cjs index c7f5234f6..a033b18cf 100644 --- a/typescript/packages/traceai_mcp/test/attachment-harness.cjs +++ b/typescript/packages/traceai_mcp/test/attachment-harness.cjs @@ -7,6 +7,9 @@ const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } = requi const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a5XcAAAAASUVORK5CYII=', 'base64'); const WAV = Buffer.alloc(48); WAV.write('RIFF'); WAV.writeUInt32LE(40, 4); WAV.write('WAVEfmt ', 8); WAV.writeUInt32LE(16, 16); WAV.writeUInt16LE(1, 20); WAV.writeUInt16LE(1, 22); WAV.writeUInt32LE(8000, 24); WAV.writeUInt32LE(16000, 28); WAV.writeUInt16LE(2, 32); WAV.writeUInt16LE(16, 34); WAV.write('data', 36); WAV.writeUInt32LE(4, 40); const PDF = Buffer.from('%PDF-1.7\nsynthetic fixture\n%%EOF'); +// Every FI_ATTACHMENTS_* process warning (legacy transport, rejected wire shape) seen by this process. +const warnings = []; +process.on('warning', warning => { if (String(warning.code || '').startsWith('FI_ATTACHMENTS_')) warnings.push(warning.code); }); const identity = { traceId: '0123456789abcdef0123456789abcdef', spanId: '0123456789abcdef', traceFlags: 1 }; async function harness(options = {}) { @@ -21,7 +24,7 @@ async function harness(options = {}) { res.setHeader('content-type', 'application/json'); if (req.url === '/tracer/v1/attachment-sessions') { const request = JSON.parse(body); - res.end(JSON.stringify({ schema_version: 1, scope, capture_session_id: request.capture_session_id, policy, limits: { max_upload_bytes: 1048576, segment_bytes: 8388608, segment_duration_ms: 30000, recording_bytes: 1073741824, recording_duration_ms: 7200000, active_transfers: 16, active_recordings: 4, reserved_bytes: 1073741824, validation_jobs: 1024, initializations_per_minute: 120, links_per_minute: 1000, upload_bytes_per_second: 1048576, playback_bytes_per_second: 1048576, transfer_timeout_seconds: 600, grant_ttl_seconds: 300, revocation_check_seconds: 5 }, expires_at: new Date(Date.now() + 600000).toISOString(), transfer_modes: ['authenticated_stream'] })); + res.end(JSON.stringify({ schema_version: 1, scope, capture_session_id: request.capture_session_id, policy, limits: { max_upload_bytes: 1048576, segment_bytes: 8388608, segment_duration_ms: 30000, recording_bytes: 1073741824, recording_duration_ms: 7200000, active_transfers: 16, active_recordings: 4, reserved_bytes: 1073741824, validation_jobs: 1024, initializations_per_minute: 120, links_per_minute: 1000, upload_bytes_per_second: 1048576, playback_bytes_per_second: 1048576, transfer_timeout_seconds: 600, grant_ttl_seconds: 300, revocation_check_seconds: 5, ...options.limits }, expires_at: new Date(Date.now() + 3600000).toISOString(), transfer_modes: ['authenticated_stream'] })); } else if (req.url === `/tracer/v1/projects/${scope.project_id}/attachments/uploads`) { const request = JSON.parse(body); records.push(request); res.statusCode = 201; @@ -43,4 +46,4 @@ async function harness(options = {}) { await manager.shutdown(); await provider.shutdown(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); } }; } -module.exports = { harness, PNG, WAV, PDF, identity }; +module.exports = { harness, PNG, WAV, PDF, identity, warnings }; diff --git a/typescript/packages/traceai_mcp/test/attachments.test.cjs b/typescript/packages/traceai_mcp/test/attachments.test.cjs index ffd02ec6e..fed67bd79 100644 --- a/typescript/packages/traceai_mcp/test/attachments.test.cjs +++ b/typescript/packages/traceai_mcp/test/attachments.test.cjs @@ -1,7 +1,7 @@ const { test } = require('node:test'); const assert = require('node:assert/strict'); const { captureMCPResult, wrapMCPClient, MCP_MEDIA_DECODE_BUDGET } = require('../dist/src'); -const { harness, PNG, WAV, PDF, identity } = require('./attachment-harness.cjs'); +const { harness, PNG, WAV, PDF, identity, warnings } = require('./attachment-harness.cjs'); const image = () => ({ type: 'image', data: PNG.toString('base64'), mimeType: 'image/png' }); test('typed image/audio/nested resource bytes use the shared TLS uploader and exact span', async () => { @@ -124,3 +124,72 @@ test('synchronous non-thenable result is returned unchanged and recorded as succ assert.equal(h.uploads.length, 1); } finally { await h.close(); } }); + +// Counts preflights on the instance; a media read asserts a preflight for that part already ran (design section 1). +function spyPreflight(manager) { + const original = manager.preflight.bind(manager), state = { calls: 0, reasons: [] }; + manager.preflight = (target, options) => { const ticket = original(target, options); state.calls++; state.reasons.push(ticket.reason); return ticket; }; + return state; +} +const PDF100K = Buffer.concat([PDF, Buffer.alloc(100 * 1024)]); + +test('every media part is preflighted before its encoded value is read, and read at most once', async () => { + const h = await harness(); + try { + const spy = spyPreflight(h.manager); const reads = []; + const tracked = (value, owner, field) => Object.defineProperty(owner, field, { enumerable: true, get() { reads.push(spy.calls); return value; } }); + const parts = [ + tracked(PNG.toString('base64'), { type: 'image', mimeType: 'image/png' }, 'data'), + tracked(WAV.toString('base64'), { type: 'audio', mimeType: 'audio/wav' }, 'data'), + { type: 'resource', resource: tracked(PDF.toString('base64'), { uri: 'file:///x', mimeType: 'application/pdf' }, 'blob') }, + ]; + const handles = captureMCPResult(h.manager, identity, { content: parts }); + await h.manager.flush(); + assert.deepEqual(reads, [1, 2, 3], 'each value is read once, after its own preflight'); + assert.deepEqual(spy.reasons, ['queued', 'queued', 'queued']); + assert.deepEqual(handles.map(x => x.admission), ['queued', 'queued', 'queued']); + assert.equal(h.uploads.length, 3); + } finally { await h.close(); } +}); + +test('a negotiated upload limit below the decode budget still captures small media at its exact size', async () => { + const h = await harness({ limits: { max_upload_bytes: 100 * 1024 } }); + try { + const spy = spyPreflight(h.manager); + const big = { type: 'resource', resource: { mimeType: 'application/pdf', blob: Buffer.concat([PDF100K, Buffer.alloc(50 * 1024)]).toString('base64') } }; + const handles = captureMCPResult(h.manager, identity, { content: [image(), big] }); + await h.manager.flush(); + assert.deepEqual(spy.reasons, ['too_large', 'queued', 'too_large', 'too_large']); + assert.deepEqual(handles.map(x => x.admission), ['queued', 'too_large']); + assert.equal(h.uploads.length, 1); assert.deepEqual(h.uploads[0], PNG); + } finally { await h.close(); } +}); + +test('a nearly used owned-byte budget still admits small media at its exact size', async () => { + const h = await harness({ manager: { maxOwnedBytes: 200 * 1024 } }); + try { + const spy = spyPreflight(h.manager); + const pdf = { type: 'resource', resource: { mimeType: 'application/pdf', blob: PDF100K.toString('base64') } }; + const handles = captureMCPResult(h.manager, identity, { content: [pdf, image()] }); + assert.deepEqual(spy.reasons, ['too_large', 'queued', 'queue_full', 'queued']); + await h.manager.flush(); + assert.deepEqual(handles.map(x => x.admission), ['queued', 'queued']); + assert.equal(h.uploads.length, 2); + } finally { await h.close(); } +}); + +test('an admitted part with malformed bytes returns its reservation and uploads nothing', async () => { + const h = await harness(); + try { + const handles = captureMCPResult(h.manager, identity, { content: [{ ...image(), data: '!!!!' }, { ...image(), data: 'QUJD' + '=' }] }); + assert.equal(handles.length, 0); + const status = h.manager.status(); + assert.equal(status.openTickets, 0); assert.equal(status.ownedBytes, 0); + await h.manager.flush(); assert.equal(h.uploads.length, 0); assert.equal(h.records.length, 0); + } finally { await h.close(); } +}); + +test('the loopback service is accepted as a V1 F01 peer: no FI_ATTACHMENTS_* warning in this process', async () => { + await new Promise(resolve => setImmediate(resolve)); + assert.deepEqual(warnings, []); +}); From f088b62c67a4484b2ad822a5229831be5b1fc06c Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Wed, 11 Nov 2026 03:58:25 -0800 Subject: [PATCH 5/5] test(mcp,claude-agent-sdk): align the loopback attachment double with strict F01 and tighten-only policy On ts-core f0a56b37 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 --- .../traceai_mcp/test/attachment-harness.cjs | 2 +- .../traceai_mcp/test/attachments.test.cjs | 2 ++ .../traceai_mcp/test/real-sdk.test.cjs | 18 ++++++++++++------ 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/typescript/packages/traceai_mcp/test/attachment-harness.cjs b/typescript/packages/traceai_mcp/test/attachment-harness.cjs index a033b18cf..148e6c535 100644 --- a/typescript/packages/traceai_mcp/test/attachment-harness.cjs +++ b/typescript/packages/traceai_mcp/test/attachment-harness.cjs @@ -30,7 +30,7 @@ async function harness(options = {}) { res.statusCode = 201; res.end(JSON.stringify({ upload_id: randomUUID(), attachment_id: request.attachment_id, occurrence_id: request.occurrence_id, state: 'pending_upload', reserved_bytes: request.declared_bytes, expires_at: new Date(Date.now() + 600000).toISOString(), transfer_mode: 'authenticated_stream', write_capability: 'synthetic-write-capability' })); } else if (req.url.endsWith('/content')) { - uploads.push(body); res.end(JSON.stringify({ upload_id: req.url.split('/').at(-2), state: 'pending_upload' })); + uploads.push(body); res.end(JSON.stringify({ upload_id: req.url.split('/').at(-2), state: 'pending_upload', reason: 'queued' })); } else if (req.url.endsWith('/complete')) { res.statusCode = 202; res.end(JSON.stringify({ upload_id: req.url.split('/').at(-2), state: 'validating', reason: 'binding_pending' })); } else { res.statusCode = 404; res.end('{}'); } diff --git a/typescript/packages/traceai_mcp/test/attachments.test.cjs b/typescript/packages/traceai_mcp/test/attachments.test.cjs index fed67bd79..b443254b5 100644 --- a/typescript/packages/traceai_mcp/test/attachments.test.cjs +++ b/typescript/packages/traceai_mcp/test/attachments.test.cjs @@ -149,6 +149,8 @@ test('every media part is preflighted before its encoded value is read, and read assert.deepEqual(spy.reasons, ['queued', 'queued', 'queued']); assert.deepEqual(handles.map(x => x.admission), ['queued', 'queued', 'queued']); assert.equal(h.uploads.length, 3); + // Transferred for validation under strict F01 response checks (no unsupported_version). + for (const x of handles) assert.equal((await x.completion).status, 'validating'); } finally { await h.close(); } }); diff --git a/typescript/packages/traceai_mcp/test/real-sdk.test.cjs b/typescript/packages/traceai_mcp/test/real-sdk.test.cjs index cdf96529d..c62bd51f8 100644 --- a/typescript/packages/traceai_mcp/test/real-sdk.test.cjs +++ b/typescript/packages/traceai_mcp/test/real-sdk.test.cjs @@ -47,12 +47,18 @@ test('real MCP SDK SSE tool screenshot, audio, resource read and cancellation', const pending = traced.callTool({ name: 'wait', arguments: {} }, undefined, { signal: abort.signal }); abort.abort(); await assert.rejects(pending); await h.manager.flush(); assert.equal(h.uploads.length, 4); - for (const policy of [{ enabled: false }, { enabled: true, traceConfig: { hideInputImages: true } }, { enabled: true, traceConfig: { hideInputs: true } }, { enabled: true, traceConfig: { piiRedaction: true } }]) { - h.manager.updatePolicy(policy); - await traced.callTool({ name: 'screenshot', arguments: {} }); await h.manager.flush(); - // hideInputImages leaves typed audio/PDF allowed; the other controls deny all. - const expected = policy.traceConfig?.hideInputImages ? 6 : policy.enabled === false ? 4 : 6; - assert.equal(h.uploads.length, expected); + // The core's updatePolicy only tightens (deny-wins), so each control runs on its own fresh manager. A thin + // per-control delegate gets its own proxy; the tool result still comes from the real SDK client over SSE. + for (const [options, expected] of [[{ enabled: false }, 0], [{ traceConfig: { hideInputImages: true } }, 2], [{ traceConfig: { hideInputs: true } }, 0], [{ traceConfig: { piiRedaction: true } }, 0]]) { + const control = await harness({ manager: options }); + try { + const delegate = { callTool: (...args) => client.callTool(...args) }; + await wrapMCPClient(delegate, { tracerProvider: control.provider }).callTool({ name: 'screenshot', arguments: {} }); + await control.manager.flush(); + // hideInputImages leaves typed audio/PDF allowed; the other controls deny all. + assert.equal(control.uploads.length, expected, JSON.stringify(options)); + if (options.enabled === false) assert.equal(control.requests.length, 0); + } finally { await control.close(); } } } finally { await client.close(); await protocol.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); await h.close();