Skip to content

Commit 14e3adf

Browse files
committed
fix(claude-agent-sdk): end spans when a Query is closed or disposed
The Query proxy only intercepted next/return/throw/asyncIterator. Query.close() (sdk.d.ts:3236-3243, the SDK's abort path) and Symbol.asyncDispose (`await using`) went straight to the original, so a query stopped mid-run never finished its spans and the trace was never exported. Both are now intercepted: the open spans are ended as cancelled (ERROR, claude_agent.cancelled=true), then the call is forwarded. After a completed stream the call changes nothing. Tests: jest close()/asyncDispose cases on the fake Query, and a real-SDK contract scenario (run_real_sdk.mjs SCENARIO=close) that stops two real CLI queries mid-tool. That scenario exported 0 spans before the fix. The real-SDK contract test now also asserts the x-secret-key header. The fake Query gains close/asyncDispose/backgroundTasks and a per-message delay. approved: Nikhil 2026-10-03 blanket Refs: TH-8235
1 parent 5d0efff commit 14e3adf

6 files changed

Lines changed: 251 additions & 58 deletions

File tree

‎typescript/packages/traceai_claude_agent_sdk/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ await shutdown(); // flush before a short script exits
5252
### What the wrapper does and does not do
5353

5454
- Calls the original `query()` with the same params object. Options (`resume`, `forkSession`, `sessionId`, `hooks`, `mcpServers`, `agents`, `abortController`, `allowedTools`, `permissionMode`, `maxTurns`, `env`, ...) are passed through untouched. The wrapper never sets `ANTHROPIC_BASE_URL`.
55-
- Yields the same message objects, in order. Control methods on the returned `Query` (`interrupt()`, `setModel()`, ...) go to the original.
55+
- Yields the same message objects, in order. Control methods on the returned `Query` (`interrupt()`, `setModel()`, ...) go to the original. `close()` and `Symbol.asyncDispose` first end the query's open spans as cancelled, then go to the original.
5656
- A tracing error never fails the agent. An exporter or collector failure is logged and does not reject the iterator.
5757
- `startup()` is not wrapped in 0.1.0.
5858

@@ -115,7 +115,7 @@ With 0.3.289 the CLI then calls `POST {ANTHROPIC_BASE_URL}/v1/messages?beta=true
115115
- **No traces.** `register()` needs `projectName` or `FI_PROJECT_NAME`.
116116
- **Zero spans from a short script.** `await shutdown()` before exit.
117117
- **Duplicate model spans.** Do not also run a provider instrumentor on the same calls.
118-
- **A span left open after abort.** Every span for the query is ended with status ERROR and `claude_agent.cancelled=true` when its `AbortController` aborts. Anything else is a bug here.
118+
- **A span left open after abort.** Every span for the query is ended with status ERROR and `claude_agent.cancelled=true` when its `AbortController` aborts, when you call `close()` on the returned `Query` (the SDK's abort path), or when `await using` disposes it (`Symbol.asyncDispose`). Calling `close()` after the stream has completed changes nothing. Anything else is a bug here.
119119

120120
## Tests
121121

‎typescript/packages/traceai_claude_agent_sdk/contract/run_real_sdk.mjs‎

Lines changed: 77 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,17 @@
55
// loopback port, and HOME / CLAUDE_CONFIG_DIR are a fresh temp dir.
66
//
77
// The mock answers the first /v1/messages call with a Read tool_use for a temp
8-
// file and the second with text, so the CLI runs one real tool.
8+
// file and the second with text, so the CLI runs one real tool ("tool" and
9+
// "close" scenarios). Other scenarios get a text reply to every call.
910
//
1011
// Env: FI_BASE_URL, FI_API_KEY, FI_SECRET_KEY, FI_PROJECT_NAME (fi-core).
1112
// CLAUDE_AGENT_SDK_ENTRY (optional): absolute path to another SDK build's
1213
// sdk.mjs, to run the same contract against an older 0.3.x.
13-
// Prints {"requests": [...], "messages": [...]} on stdout.
14+
// SCENARIO (optional, default "tool"):
15+
// tool one query() that runs the Read tool.
16+
// close two query() calls stopped mid-tool: one with close(), one
17+
// with Symbol.asyncDispose.
18+
// Prints {"requests": [...], "messages": [...], "queries": [[...], ...]} on stdout.
1419
import http from "node:http";
1520
import fs from "node:fs";
1621
import os from "node:os";
@@ -24,6 +29,8 @@ const { query } = process.env.CLAUDE_AGENT_SDK_ENTRY
2429

2530
const MOCK_MODEL = "claude-sonnet-4-5";
2631
const PROMPT = "Read README.md and summarize it. SECRET_PROMPT_MARKER";
32+
const SCENARIO = process.env.SCENARIO || "tool";
33+
const TOOL_FLOW = SCENARIO === "tool" || SCENARIO === "close";
2734

2835
const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "th8235-real-sdk-"));
2936
const readmePath = path.join(workdir, "README.md");
@@ -73,7 +80,7 @@ const server = http.createServer((req, res) => {
7380
});
7481
if (req.method === "POST" && req.url.startsWith("/v1/messages") && !req.url.includes("count_tokens")) {
7582
const model = parsed.model || MOCK_MODEL;
76-
if (!hasToolResult) {
83+
if (TOOL_FLOW && !hasToolResult) {
7784
return sendSse(res, model, [
7885
{ type: "text", text: "Reading it. SECRET_ASSISTANT_TEXT_MARKER" },
7986
{ type: "tool_use", id: "toolu_mock_read", name: "Read", input: { file_path: readmePath } },
@@ -93,39 +100,74 @@ const tracedQuery = wrapQuery(query, { tracerProvider: provider });
93100

94101
const abortController = new AbortController();
95102
const timer = setTimeout(() => abortController.abort(), 90_000);
96-
const messages = [];
97-
try {
98-
const stream = tracedQuery({
99-
prompt: PROMPT,
100-
options: {
101-
model: MOCK_MODEL,
102-
cwd: workdir,
103-
maxTurns: 3,
104-
allowedTools: ["Read"],
105-
permissionMode: "default",
106-
settingSources: [],
107-
persistSession: false,
108-
abortController,
109-
// Options.env REPLACES the subprocess environment: pass everything the CLI needs.
110-
env: {
111-
PATH: process.env.PATH,
112-
HOME: workdir,
113-
CLAUDE_CONFIG_DIR: path.join(workdir, ".claude"),
114-
ANTHROPIC_BASE_URL: mockOrigin,
115-
ANTHROPIC_API_KEY: "sk-ant-PLACEHOLDER-not-a-key",
116-
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
117-
DISABLE_TELEMETRY: "1",
118-
DISABLE_ERROR_REPORTING: "1",
119-
DISABLE_AUTOUPDATER: "1",
120-
HTTPS_PROXY: "http://127.0.0.1:9",
121-
HTTP_PROXY: "http://127.0.0.1:9",
122-
NO_PROXY: "127.0.0.1,localhost",
123-
},
103+
104+
function options(extra = {}) {
105+
return {
106+
model: MOCK_MODEL,
107+
cwd: workdir,
108+
maxTurns: 3,
109+
allowedTools: ["Read"],
110+
permissionMode: "default",
111+
settingSources: [],
112+
persistSession: false,
113+
abortController,
114+
// Options.env REPLACES the subprocess environment: pass everything the CLI needs.
115+
env: {
116+
PATH: process.env.PATH,
117+
HOME: workdir,
118+
CLAUDE_CONFIG_DIR: path.join(workdir, ".claude"),
119+
ANTHROPIC_BASE_URL: mockOrigin,
120+
ANTHROPIC_API_KEY: "sk-ant-PLACEHOLDER-not-a-key",
121+
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
122+
DISABLE_TELEMETRY: "1",
123+
DISABLE_ERROR_REPORTING: "1",
124+
DISABLE_AUTOUPDATER: "1",
125+
HTTPS_PROXY: "http://127.0.0.1:9",
126+
HTTP_PROXY: "http://127.0.0.1:9",
127+
NO_PROXY: "127.0.0.1,localhost",
124128
},
125-
});
126-
for await (const message of stream) {
127-
messages.push(message);
129+
...extra,
130+
};
131+
}
132+
133+
async function drain(stream) {
134+
const out = [];
135+
for await (const message of stream) out.push(message);
136+
return out;
137+
}
138+
139+
/** Read until the assistant asks for the Read tool (conversation, turn and tool spans open). */
140+
async function readUntilToolUse(stream) {
141+
const out = [];
142+
for (;;) {
143+
const { value, done } = await stream.next();
144+
if (done) return out;
145+
out.push(value);
146+
const content = value.type === "assistant" ? value.message?.content ?? [] : [];
147+
if (content.some((block) => block.type === "tool_use")) return out;
128148
}
149+
}
150+
151+
const SCENARIOS = {
152+
async tool() {
153+
return [await drain(tracedQuery({ prompt: PROMPT, options: options() }))];
154+
},
155+
async close() {
156+
const closed = tracedQuery({ prompt: PROMPT, options: options() });
157+
const first = await readUntilToolUse(closed);
158+
closed.close();
159+
const disposed = tracedQuery({ prompt: PROMPT, options: options() });
160+
const second = await readUntilToolUse(disposed);
161+
await disposed[Symbol.asyncDispose]();
162+
return [first, second];
163+
},
164+
};
165+
166+
const queries = [];
167+
try {
168+
const scenario = SCENARIOS[SCENARIO];
169+
if (!scenario) throw new Error(`unknown SCENARIO ${SCENARIO}`);
170+
queries.push(...(await scenario()));
129171
} finally {
130172
clearTimeout(timer);
131173
await shutdown(provider);
@@ -134,4 +176,4 @@ try {
134176
fs.rmSync(workdir, { recursive: true, force: true });
135177
}
136178

137-
process.stdout.write(JSON.stringify({ mockOrigin, requests, messages }));
179+
process.stdout.write(JSON.stringify({ mockOrigin, requests, messages: queries.flat(), queries }));

‎typescript/packages/traceai_claude_agent_sdk/contract/test_harness_contract.py‎

Lines changed: 61 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -253,32 +253,83 @@ def _sdk_platform_binary_installed() -> bool:
253253
return bool(store and list(store.glob("claude-agent-sdk-*")))
254254

255255

256-
@pytest.mark.skipif(not _sdk_platform_binary_installed(), reason="claude-agent-sdk platform binary not installed")
257-
def test_real_sdk_query_through_anthropic_base_url_mock(built_package: Path) -> None:
258-
"""The real SDK query() and bundled CLI, wrapped, against a loopback Messages API mock.
256+
requires_real_sdk = pytest.mark.skipif(
257+
not _sdk_platform_binary_installed(), reason="claude-agent-sdk platform binary not installed"
258+
)
259259

260-
Mechanism from the ADR: Options.env.ANTHROPIC_BASE_URL. No Anthropic call: placeholder
261-
key, dead-port HTTPS_PROXY, temp HOME. Spans go through fi-core to the shared Receiver.
260+
261+
def _run_real_sdk(scenario: str, project: str, extra_env: Dict[str, str] | None = None):
262+
"""Run contract/run_real_sdk.mjs with SCENARIO against a fresh Receiver.
263+
264+
Returns (stdout JSON, received spans, export request records).
262265
"""
263266
env = _base_env()
264267
env.update(
265268
{
266-
"FI_BASE_URL": "", # replaced below once the Receiver is up
267269
"FI_API_KEY": PLACEHOLDER_API_KEY,
268270
"FI_SECRET_KEY": PLACEHOLDER_SECRET_KEY,
269-
"FI_PROJECT_NAME": "th8235-real-sdk-contract",
271+
"FI_PROJECT_NAME": project,
272+
"SCENARIO": scenario,
270273
}
271274
)
272275
if os.environ.get("CLAUDE_AGENT_SDK_ENTRY"):
273276
# Run the same contract against another installed SDK build (older 0.3.x matrix).
274277
env["CLAUDE_AGENT_SDK_ENTRY"] = os.environ["CLAUDE_AGENT_SDK_ENTRY"]
278+
env.update(extra_env or {})
275279
with Receiver() as receiver:
276280
env["FI_BASE_URL"] = receiver.origin
277281
result = run([NODE, str(PKG_DIR / "contract" / "run_real_sdk.mjs")], env=env, stdin=None, timeout=180)
278-
_check(result, "node run_real_sdk.mjs")
282+
_check(result, f"node run_real_sdk.mjs ({scenario})")
279283
spans = receiver.spans()
280284
exported = receiver.requests()
281-
output = json.loads(result.stdout.decode("utf-8"))
285+
return json.loads(result.stdout.decode("utf-8")), spans, exported
286+
287+
288+
def _assert_exported_with_both_keys(exported: List[Dict[str, Any]], project: str) -> None:
289+
assert exported, "exporter sent nothing"
290+
for request in exported:
291+
assert request["path"] == "/tracer/v1/traces"
292+
assert request["headers"]["x-api-key"] == PLACEHOLDER_API_KEY
293+
assert request["headers"]["x-secret-key"] == PLACEHOLDER_SECRET_KEY
294+
assert request["resource_attributes"]
295+
for resource in request["resource_attributes"]:
296+
assert (resource["project_name"], resource["project_type"]) == (project, "observe")
297+
298+
299+
@requires_real_sdk
300+
def test_real_sdk_close_and_async_dispose_end_every_span_cancelled(built_package: Path) -> None:
301+
"""R3: Query.close() (the SDK abort path) and Symbol.asyncDispose bypass next/return/throw.
302+
303+
Each query is stopped right after the CLI streamed the Read tool_use, so the
304+
conversation, turn and tool spans are open. All of them must still be exported,
305+
ended ERROR with claude_agent.cancelled=true.
306+
"""
307+
output, spans, exported = _run_real_sdk("close", "th8235-real-sdk-close")
308+
closed, disposed = output["queries"]
309+
for messages in (closed, disposed):
310+
assert not [m for m in messages if m["type"] == "result"], "query finished before it was stopped"
311+
312+
traces: Dict[str, List[Dict[str, Any]]] = {}
313+
for span in spans:
314+
traces.setdefault(span["traceId"], []).append(span)
315+
assert len(traces) == 2, sorted(span["name"] for span in spans)
316+
for trace_spans in traces.values():
317+
names = sorted(span["name"] for span in trace_spans)
318+
assert names == sorted(["claude_agent.conversation", "claude_agent.assistant_turn", "tool.Read"]), names
319+
for span in trace_spans:
320+
assert _status_code(span) == 2, span["name"]
321+
assert _attrs(span)["claude_agent.cancelled"] is True, span["name"]
322+
_assert_exported_with_both_keys(exported, "th8235-real-sdk-close")
323+
324+
325+
@requires_real_sdk
326+
def test_real_sdk_query_through_anthropic_base_url_mock(built_package: Path) -> None:
327+
"""The real SDK query() and bundled CLI, wrapped, against a loopback Messages API mock.
328+
329+
Mechanism from the ADR: Options.env.ANTHROPIC_BASE_URL. No Anthropic call: placeholder
330+
key, dead-port HTTPS_PROXY, temp HOME. Spans go through fi-core to the shared Receiver.
331+
"""
332+
output, spans, exported = _run_real_sdk("tool", "th8235-real-sdk-contract")
282333

283334
# The CLI called the mock (host root + /v1/messages), streaming, with the placeholder key.
284335
mock_requests = output["requests"]
@@ -321,13 +372,7 @@ def test_real_sdk_query_through_anthropic_base_url_mock(built_package: Path) ->
321372
for marker in ("SECRET_PROMPT_MARKER", "SECRET_TOOL_OUTPUT_MARKER", "SECRET_ASSISTANT_TEXT_MARKER"):
322373
assert marker not in blob
323374
assert PLACEHOLDER_API_KEY not in blob and "PLACEHOLDER-not-a-key" not in blob
324-
assert exported, "exporter sent nothing"
325-
for request in exported:
326-
assert request["path"] == "/tracer/v1/traces"
327-
assert request["headers"]["x-api-key"] == PLACEHOLDER_API_KEY
328-
assert request["resource_attributes"]
329-
for resource in request["resource_attributes"]:
330-
assert (resource["project_name"], resource["project_type"]) == ("th8235-real-sdk-contract", "observe")
375+
_assert_exported_with_both_keys(exported, "th8235-real-sdk-contract")
331376

332377

333378
def _read_member(tar: tarfile.TarFile, member: Any) -> bytes:

‎typescript/packages/traceai_claude_agent_sdk/src/__tests__/fixtures/fakeQuery.ts‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ export interface FakeQueryControl {
88
/** Every params object the fake received, by reference. */
99
calls: { prompt: unknown; options?: Options }[];
1010
interruptCalls: number;
11+
closeCalls: number;
12+
disposeCalls: number;
13+
backgroundTasksCalls: (string | undefined)[];
1114
}
1215

1316
export interface FakeQueryBehavior {
@@ -16,6 +19,10 @@ export interface FakeQueryBehavior {
1619
error?: unknown;
1720
/** Before yielding message `waitForAbortAt`, block until options.abortController aborts. */
1821
waitForAbortAt?: number;
22+
/** Wait this long before yielding each message, so span times are ordered. */
23+
delayMs?: number;
24+
/** What `backgroundTasks()` resolves to (or rejects with, when an Error). */
25+
backgroundTasksResult?: boolean | Error;
1926
}
2027

2128
export class FakeAbortError extends Error {
@@ -29,14 +36,23 @@ export function makeFakeQuery(
2936
messages: SDKMessage[],
3037
behavior: FakeQueryBehavior = {},
3138
): { query: typeof query; control: FakeQueryControl } {
32-
const control: FakeQueryControl = { calls: [], interruptCalls: 0 };
39+
const control: FakeQueryControl = {
40+
calls: [],
41+
interruptCalls: 0,
42+
closeCalls: 0,
43+
disposeCalls: 0,
44+
backgroundTasksCalls: [],
45+
};
3346

3447
const fake = (params: { prompt: string | AsyncIterable<unknown>; options?: Options }): Query => {
3548
control.calls.push(params);
3649
const signal = params.options?.abortController?.signal;
3750

3851
async function* generate(): AsyncGenerator<SDKMessage, void> {
3952
for (let index = 0; index < messages.length; index += 1) {
53+
if (behavior.delayMs) {
54+
await new Promise((resolve) => setTimeout(resolve, behavior.delayMs));
55+
}
4056
if (behavior.throwAt === index) {
4157
throw behavior.error ?? new Error("fake query failed");
4258
}
@@ -58,14 +74,29 @@ export function makeFakeQuery(
5874
}
5975

6076
const generator = generate();
77+
const asyncDispose = (Symbol as unknown as { asyncDispose?: symbol }).asyncDispose ?? Symbol.for("Symbol.asyncDispose");
6178
const controlMethods = {
6279
interrupt: async () => {
6380
control.interruptCalls += 1;
6481
return undefined;
6582
},
6683
setPermissionMode: async () => undefined,
6784
setModel: async () => undefined,
68-
close: () => undefined,
85+
backgroundTasks: async (toolUseId?: string) => {
86+
control.backgroundTasksCalls.push(toolUseId);
87+
const result = behavior.backgroundTasksResult ?? true;
88+
if (result instanceof Error) throw result;
89+
return result;
90+
},
91+
// Like the SDK: close() and asyncDispose stop the stream; no further messages.
92+
close: () => {
93+
control.closeCalls += 1;
94+
void generator.return(undefined);
95+
},
96+
[asyncDispose]: async () => {
97+
control.disposeCalls += 1;
98+
await generator.return(undefined);
99+
},
69100
};
70101
return Object.assign(generator, controlMethods) as unknown as Query;
71102
};

0 commit comments

Comments
 (0)