Skip to content

Commit 4cf737f

Browse files
committed
fix(claude-agent-sdk): verify-r4: notifications, stream events and session state drive the idle-after-result state
R4-1: a background task_notification is queued as a main-thread command that runs its own turn (sdk.d.ts:5440, 4603), so close() after one is a cancellation again (supersedes 005a70f's expectation). R4-2: a main-loop stream_event (includePartialMessages) after a result also starts a turn. system/session_state_changed is authoritative when sent (sdk.d.ts:5858): 'idle' after a result ends OK, 'running' cancelled. README updated. Test first: 3 new jest cases failed on 005a70f. approved: Nikhil 2026-10-03 blanket Refs: TH-8235
1 parent 005a70f commit 4cf737f

3 files changed

Lines changed: 88 additions & 21 deletions

File tree

‎typescript/packages/traceai_claude_agent_sdk/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ With 0.3.289 the CLI then calls `POST {ANTHROPIC_BASE_URL}/v1/messages?beta=true
132132
- **No traces.** `register()` needs `projectName` or `FI_PROJECT_NAME`.
133133
- **Zero spans from a short script.** `await shutdown()` before exit.
134134
- **Duplicate model spans.** Do not also run a provider instrumentor on the same calls.
135-
- **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. Right after a result, before any further main-loop assistant or user message and with no background subagent still running, `close()`, `Symbol.asyncDispose` and an abort end the conversation OK instead, because nothing was cancelled. One gap remains: an abort after the app sends a new streaming-input prompt but before the SDK yields any message for it is recorded as OK. Anything else is a bug here.
135+
- **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. Right after a result, before the main loop starts another turn (a main-loop assistant, user or `stream_event` frame, or a background `task_notification`, which the CLI runs as its own turn) and with no background subagent still running, `close()`, `Symbol.asyncDispose` and an abort end the conversation OK instead, because nothing was cancelled. A `system/session_state_changed` frame, when the CLI sends one, decides it: `idle` after a result ends OK, `running` ends cancelled. One gap remains: an abort after the app sends a new streaming-input prompt but before the SDK yields any message for it is recorded as OK. Anything else is a bug here.
136136

137137
## Tests
138138

‎typescript/packages/traceai_claude_agent_sdk/src/__tests__/wrapper.test.ts‎

Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -716,29 +716,80 @@ describe("wrapQuery", () => {
716716
},
717717
);
718718

719-
it("M1: close() after a background subagent finishes post-result (its messages arrive after the result) ends OK", async () => {
720-
const { provider, exporter } = memoryProvider();
719+
/** Background subagent journey reordered: the main loop's result comes before the subagent's tail. */
720+
function resultBeforeBackgroundTail(): SDKMessage[] {
721721
const base = backgroundedSubagentJourney();
722722
const result = base[base.length - 1];
723723
const idx = base.findIndex((m) => m.type === "assistant" && m.message.id === "msg_13");
724-
// Main loop answers and yields its result; the background subagent's tool_result,
725-
// final turn and task_notification arrive afterwards.
726-
const journey = [...base.slice(0, idx + 1), result, ...base.slice(idx + 1, base.length - 1)];
727-
const fake = makeFakeQuery(journey);
728-
const q = wrapQuery(fake.query, { tracerProvider: provider })({ prompt: PROMPT });
724+
return [...base.slice(0, idx + 1), result, ...base.slice(idx + 1, base.length - 1)];
725+
}
726+
727+
async function readThrough(q: AsyncGenerator<SDKMessage, void>, stop: (m: SDKMessage) => boolean): Promise<void> {
729728
for (;;) {
730729
const step = await q.next();
731730
if (step.done) throw new Error("stream ended early");
732-
if (step.value.type === "system" && step.value.subtype === "task_notification") break;
731+
if (stop(step.value)) return;
733732
}
733+
}
734+
735+
const isTaskNotification = (m: SDKMessage) => m.type === "system" && m.subtype === "task_notification";
736+
737+
it("R4-1: close() after a post-result task_notification stays cancelled (the notification starts a main-loop turn)", async () => {
738+
const { provider, exporter } = memoryProvider();
739+
const fake = makeFakeQuery(resultBeforeBackgroundTail());
740+
const q = wrapQuery(fake.query, { tracerProvider: provider })({ prompt: PROMPT });
741+
await readThrough(q, isTaskNotification);
734742
q.close();
735743
const spans = exporter.getFinishedSpans();
736744
const conversation = one(spans, "claude_agent.conversation");
737-
expect(conversation.status.code).toBe(SpanStatusCode.OK);
738-
expect(conversation.attributes["claude_agent.cancelled"]).toBeUndefined();
745+
expect(conversation.status.code).toBe(SpanStatusCode.ERROR);
746+
expect(conversation.attributes["claude_agent.cancelled"]).toBe(true);
747+
// The subagent itself finished at its notification.
739748
expect(one(spans, "claude_agent.subagent.code-reviewer").status.code).toBe(SpanStatusCode.OK);
740749
});
741750

751+
it.each([
752+
["idle", SpanStatusCode.OK],
753+
["running", SpanStatusCode.ERROR],
754+
] as const)(
755+
"R4-1: session_state_changed %s is authoritative for close() after a result",
756+
async (state, expected) => {
757+
const { provider, exporter } = memoryProvider();
758+
const stateMessage = {
759+
type: "system",
760+
subtype: "session_state_changed",
761+
state,
762+
uuid: "00000000-0000-4000-8000-0000000000aa",
763+
session_id: SESSION_ID,
764+
} as unknown as SDKMessage;
765+
const fake = makeFakeQuery([...resultBeforeBackgroundTail(), stateMessage]);
766+
const q = wrapQuery(fake.query, { tracerProvider: provider })({ prompt: PROMPT });
767+
await readThrough(q, (m) => m.type === "system" && (m as { subtype?: string }).subtype === "session_state_changed");
768+
q.close();
769+
const conversation = one(exporter.getFinishedSpans(), "claude_agent.conversation");
770+
expect(conversation.status.code).toBe(expected);
771+
},
772+
);
773+
774+
it("R4-2: a main-loop stream_event after a result starts a new turn, so close() stays cancelled", async () => {
775+
const { provider, exporter } = memoryProvider();
776+
const partial = {
777+
type: "stream_event",
778+
event: { type: "message_start", message: { id: "msg_p2" } },
779+
parent_tool_use_id: null,
780+
uuid: "00000000-0000-4000-8000-0000000000bb",
781+
session_id: SESSION_ID,
782+
} as unknown as SDKMessage;
783+
const journey = [init(), assistant("msg_s1", [text("First answer.")]), resultSuccess("First answer.", { num_turns: 1 }), partial];
784+
const fake = makeFakeQuery(journey);
785+
const q = wrapQuery(fake.query, { tracerProvider: provider })({ prompt: PROMPT });
786+
await readThrough(q, (m) => m.type === "stream_event");
787+
q.close();
788+
const conversation = one(exporter.getFinishedSpans(), "claude_agent.conversation");
789+
expect(conversation.status.code).toBe(SpanStatusCode.ERROR);
790+
expect(conversation.attributes["claude_agent.cancelled"]).toBe(true);
791+
});
792+
742793
it("N1: close() after a result while a background subagent still runs stays cancelled", async () => {
743794
const { provider, exporter } = memoryProvider();
744795
// The result arrives before the background subagent's task_notification.

‎typescript/packages/traceai_claude_agent_sdk/src/spans.ts‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,7 @@ export class QueryTracer {
287287
private conversationContext?: Context;
288288
private conversationIsError = false;
289289
private resultSeen = false;
290-
/** A result arrived and no main-loop assistant/user message has followed it yet. */
290+
/** A result arrived and the main loop has not started another turn since (see trackIdleAfterResult). */
291291
private idleAfterResult = false;
292292
private sessionId?: string;
293293
private finished = false;
@@ -380,15 +380,7 @@ export class QueryTracer {
380380
}
381381
try {
382382
const type = (message as { type?: unknown }).type;
383-
if (
384-
(type === "assistant" || type === "user") &&
385-
((message as { parent_tool_use_id?: unknown }).parent_tool_use_id ?? null) === null
386-
) {
387-
// Main-loop activity after a result starts a new turn. Background
388-
// subagent messages (parent_tool_use_id set) do not: nothingInFlight()
389-
// already covers subagents that are still open.
390-
this.idleAfterResult = false;
391-
}
383+
this.trackIdleAfterResult(type, message as { parent_tool_use_id?: unknown; subtype?: unknown; state?: unknown });
392384
if (type === "assistant") {
393385
this.onAssistant(message as AssistantMessageLike);
394386
} else if (type === "user") {
@@ -487,6 +479,30 @@ export class QueryTracer {
487479
}
488480
}
489481

482+
/**
483+
* Keep idleAfterResult in step with the main loop. Main-loop assistant, user
484+
* and stream_event frames after a result start a new turn, and so does a
485+
* task_notification: the CLI queues it as a main-thread command that runs
486+
* its own turn (sdk.d.ts:5440, 4603). Background subagent frames
487+
* (parent_tool_use_id set) do not; nothingInFlight() covers subagents still
488+
* open. system/session_state_changed is authoritative when the CLI sends it
489+
* (sdk.d.ts:5858): 'idle' after a result means the turn is over.
490+
*/
491+
private trackIdleAfterResult(
492+
type: unknown,
493+
message: { parent_tool_use_id?: unknown; subtype?: unknown; state?: unknown },
494+
): void {
495+
if (type === "assistant" || type === "user" || type === "stream_event") {
496+
if ((message.parent_tool_use_id ?? null) === null) this.idleAfterResult = false;
497+
} else if (type === "system") {
498+
if (message.subtype === "task_notification") {
499+
this.idleAfterResult = false;
500+
} else if (message.subtype === "session_state_changed") {
501+
this.idleAfterResult = message.state === "idle" && this.resultSeen;
502+
}
503+
}
504+
}
505+
490506
/** True when no turn, tool or subagent span of this query is still open. */
491507
private nothingInFlight(): boolean {
492508
if (this.tools.size > 0) return false;

0 commit comments

Comments
 (0)