Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions .github/workflows/mcp-agent-attachments-tests.yml
Original file line number Diff line number Diff line change
@@ -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
40 changes: 40 additions & 0 deletions typescript/packages/traceai_claude_agent_sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,3 +152,43 @@ 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. 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.

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.

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.
Original file line number Diff line number Diff line change
Expand Up @@ -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/");
});
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);
});

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -502,14 +502,16 @@ 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);
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);
});

Expand Down Expand Up @@ -676,7 +678,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" });
});
Expand Down
98 changes: 98 additions & 0 deletions typescript/packages/traceai_claude_agent_sdk/src/attachments.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
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;

/** 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;
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.
* 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,
span: Span,
content: unknown,
options: { toolCallId?: string; messageIndex: number; isError?: boolean; toolResult: boolean },
observed?: WeakSet<object>,
): void {
const manager = config.attachments;
// 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) && remaining > 0; 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;
// 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;
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;
const request = {
mimeType,
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,
});
} catch {
// Untrusted properties / malformed blocks do not change the SDK iterator.
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -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;
/**
Expand Down Expand Up @@ -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);
}
Expand All @@ -153,6 +162,7 @@ export class ClaudeAgentSDKInstrumentation {

/** Flush the provider's span processors. Does not shut the provider down. */
async forceFlush(): Promise<void> {
await this.attachments?.flush();
await flushProvider(this.tracerProvider ?? trace.getTracerProvider());
}

Expand All @@ -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 };
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand Down Expand Up @@ -50,8 +51,8 @@ export function wrapQueryFunction<Q extends QueryFunctionLike>(

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}`);
}
Expand Down
Loading
Loading