@alexkroman1/aai 1.7.0 → 1.8.0

package/host/transports/pipeline-transport.ts

@@ -1,15 +1,11 @@
 // Copyright 2026 the AAI authors. MIT license.
 // Pipeline transport — STT → LLM → TTS orchestration behind the Transport interface.
-
+//
 // Pipeline mode executes tools inline via streamText's `tools.execute`.
 // `callbacks.onToolCall` is observability-only; runtime.ts routes it to
 // `client.toolCall` directly (bypassing SessionCore's tool-dispatch path,
 // which is S2S-only). `sendToolResult` is a no-op because results are
 // already handled by streamText.
-//
-// `conversationMessages` below is transport-local and currently uncapped —
-// SessionCore's `maxHistory` does not yet feed through. Long pipeline
-// sessions may accumulate unbounded context; revisit if it matters.
 
 import type { LanguageModel, ModelMessage } from "ai";
 import { stepCountIs, streamText } from "ai";
@@ -97,14 +93,8 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     });
 
   const { callbacks, sessionConfig } = opts;
-
-  // Derive the system prompt — pipeline mode always uses voice=true.
-  // In the refactored transport, we receive the final systemPrompt directly
-  // from sessionConfig (built by the caller). We use it as-is but also keep
-  // the hasTools logic available if the caller passes raw schemas.
   const systemPrompt = sessionConfig.systemPrompt;
 
-  // ---- State ----------------------------------------------------------------
   const sessionAbort = new AbortController();
   let audioReady = false;
   let terminated = false;
@@ -112,16 +102,13 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
   let ttsSession: TtsSession | null = null;
   let turnController: AbortController | null = null;
   let nextReplyId = 0;
-  // Conversation history — seeded from sessionConfig.history if provided.
-  // Pipeline transport manages its own history since SessionCore doesn't own
-  // the conversation in pipeline mode (history is needed to build the LLM
-  // messages array for each turn).
+  // Pipeline transport manages its own history; SessionCore does not own the
+  // conversation in pipeline mode (we need it to build LLM messages per turn).
   const conversationMessages: Message[] = sessionConfig.history ? [...sessionConfig.history] : [];
   let turnPromise: Promise<void> | null = null;
   const sttSubs: Unsubscribe[] = [];
   const ttsSubs: Unsubscribe[] = [];
 
-  // ---- History helpers ------------------------------------------------------
   function pushMessages(...msgs: Message[]): void {
     conversationMessages.push(...msgs);
     if (conversationMessages.length > DEFAULT_MAX_HISTORY) {
@@ -133,16 +120,11 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     turnPromise = (turnPromise ?? Promise.resolve()).then(() => p);
   }
 
-  // ---- Error helpers --------------------------------------------------------
   function emitError(code: SessionErrorCode, message: string): void {
     callbacks.onError(code, message);
   }
 
-  // ---- Termination ----------------------------------------------------------
-  /**
-   * Tear down after an unrecoverable provider error. Aborts the in-flight
-   * turn, cancels TTS, signals providers to close. Idempotent.
-   */
+  // Idempotent teardown after an unrecoverable provider error.
   function terminate(): void {
     if (terminated) return;
     terminated = true;
@@ -155,7 +137,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     sessionAbort.abort();
   }
 
-  // ---- STT event handlers ---------------------------------------------------
   function onSttPartial(_text: string): void {
     if (terminated) return;
     if (turnController === null) return;
@@ -170,7 +151,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     if (terminated) return;
     const trimmed = text.trim();
     if (trimmed.length === 0) return;
-    // Replace in-flight turn if one is running (duplicate/late STT final).
     if (turnController !== null) {
       log.info("Pipeline replacing in-flight turn", { sid: opts.sid });
       turnController.abort();
@@ -192,7 +172,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     terminate();
   }
 
-  // ---- TTS event handlers ---------------------------------------------------
   function onTtsError(err: TtsError): void {
     if (terminated) return;
     log.error("TTS error", { code: err.code, message: err.message, sid: opts.sid });
@@ -200,7 +179,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     terminate();
   }
 
-  // ---- LLM streaming --------------------------------------------------------
   async function consumeLlmStream(
     ctl: AbortController,
     messages: ModelMessage[],
@@ -274,8 +252,7 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
           pendingSeparator = true;
           return;
         case "tool-call": {
-          // Option A: fire callbacks.onToolCall for observability only.
-          // Actual execution happens inline via toVercelTools.
+          // Observability only — actual execution happens inline via toVercelTools.
           const input = (part.input ?? {}) as Record<string, unknown>;
           callbacks.onToolCall(part.toolCallId ?? "", part.toolName ?? "", input);
           return;
@@ -292,17 +269,11 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     };
   }
 
-  // ---- TTS flush ------------------------------------------------------------
-  /**
-   * Flush TTS and wait for drain. Resolves on:
-   *   - TTS emits `done`
-   *   - `signal` aborts (barge-in / provider error / session stop)
-   *   - PIPELINE_FLUSH_TIMEOUT_MS elapses
-   * Resolves immediately if no TTS session.
-   */
+  // Resolves on TTS `done`, signal abort, or PIPELINE_FLUSH_TIMEOUT_MS elapsed.
   function flushTtsAndWait(signal: AbortSignal): Promise<void> {
     const tts = ttsSession;
     if (!tts) return Promise.resolve();
+    if (signal.aborted) return Promise.resolve();
     return new Promise<void>((resolve) => {
       let off: Unsubscribe | null = null;
       let timer: ReturnType<typeof setTimeout> | null = null;
@@ -322,24 +293,16 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
         resolve();
       };
       const onAbort = () => finish();
-      if (signal.aborted) {
-        resolve();
-        return;
-      }
       signal.addEventListener("abort", onAbort, { once: true });
       off = tts.on("done", finish);
       timer = setTimeout(() => {
-        log.warn("TTS flush timeout", {
-          sid: opts.sid,
-          timeoutMs: PIPELINE_FLUSH_TIMEOUT_MS,
-        });
+        log.warn("TTS flush timeout", { sid: opts.sid, timeoutMs: PIPELINE_FLUSH_TIMEOUT_MS });
         finish();
       }, PIPELINE_FLUSH_TIMEOUT_MS);
       tts.flush();
     });
   }
 
-  // ---- Turn orchestration ---------------------------------------------------
   async function runTurn(userText: string): Promise<void> {
     const replyId = `pipeline-${++nextReplyId}`;
     callbacks.onReplyStarted(replyId);
@@ -366,7 +329,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
       return;
     }
 
-    // Emit the complete transcript once the LLM finishes streaming.
     if (accumulated.length > 0) {
       callbacks.onAgentTranscript(accumulated, false);
       pushMessages({ role: "assistant", content: accumulated });
@@ -404,14 +366,12 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
       return;
     }
 
-    // Do NOT call callbacks.onAudioDone() here — session-core's flushReply
-    // (triggered by onReplyDone) emits audioDone + replyDone together, matching
-    // the S2S transport contract. Calling it here would double-fire audio_done.
+    // See runTurn: onReplyDone triggers session-core's flushReply which emits
+    // audioDone + replyDone together; firing onAudioDone here would double-fire.
     callbacks.onReplyDone();
     if (turnController === ctl) turnController = null;
   }
 
-  // ---- Provider lifecycle ---------------------------------------------------
   function reportOpenRejection(which: "stt" | "tts", reason: unknown): void {
     const msg = errorMessage(reason);
     log.error(`${which === "stt" ? "STT" : "TTS"} open failed`, {
@@ -443,10 +403,8 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
         callbacks.onAudioChunk(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
       }),
     );
-    // Note: `done` is NOT subscribed here. flushTtsAndWait() attaches a
-    // one-shot listener per-turn so it knows when synthesis drains. Calling
-    // callbacks.onAudioDone() is done explicitly at the end of runTurn /
-    // runGreeting — not via a persistent subscription — to avoid double-firing.
+    // `done` is intentionally NOT subscribed persistently — flushTtsAndWait
+    // attaches a one-shot listener per-turn to avoid double-firing audio_done.
     ttsSubs.push(session.on("error", onTtsError));
   }
 
@@ -479,7 +437,6 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     if (!aborted && (sttFailed || ttsFailed)) terminate();
   }
 
-  // ---- Greeting on audio ready ----------------------------------------------
   function onAudioReady(): void {
     if (audioReady || terminated) return;
     audioReady = true;
@@ -492,13 +449,11 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
     chainTurn(turn);
   }
 
-  // ---- Transport interface --------------------------------------------------
   return {
     async start(): Promise<void> {
       await openProviders();
-      // In S2S mode, onSessionReady fires when the provider acknowledges the
-      // session. In pipeline mode, we fire it immediately after providers open
-      // (which is the equivalent "ready" signal), then trigger greeting.
+      // S2S fires onSessionReady when the provider acks; in pipeline mode the
+      // equivalent "ready" signal is providers having opened.
       callbacks.onSessionReady?.(opts.sid);
       onAudioReady();
     },
@@ -522,8 +477,7 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
 
     sendUserAudio(bytes: Uint8Array): void {
       if (terminated || !audioReady) return;
-      const offset = bytes.byteOffset;
-      const length = bytes.byteLength;
+      const { byteOffset: offset, byteLength: length } = bytes;
       let pcm: Int16Array;
       if (offset % 2 === 0 && length % 2 === 0) {
         pcm = new Int16Array(bytes.buffer, offset, length / 2);
@@ -535,8 +489,8 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
       sttSession?.sendAudio(pcm);
     },
 
-    // Option A: tool execution stays inside toVercelTools/streamText.
-    // sendToolResult is a no-op for pipeline mode.
+    // Tool execution stays inside toVercelTools/streamText; results aren't
+    // routed through the transport.
     // biome-ignore lint/suspicious/noEmptyBlockStatements: intentional no-op for pipeline mode
     sendToolResult(_callId: string, _result: string): void {},
 
@@ -545,11 +499,9 @@ export function createPipelineTransport(opts: PipelineTransportOptions): Transpo
       turnController?.abort();
       turnController = null;
       ttsSession?.cancel();
-      // Do NOT call callbacks.onCancelled() here. This method is invoked from
-      // session-core.onCancel (client-initiated cancel), which calls
-      // client.cancelled() itself — firing onCancelled here would double-cancel.
-      // Barge-in (STT partial) fires callbacks.onCancelled() directly in
-      // onSttPartial, where the cancel originates inside the transport.
+      // Do NOT call callbacks.onCancelled() here — session-core.onCancel
+      // (client-initiated) calls client.cancelled() itself. Barge-in fires
+      // onCancelled directly in onSttPartial where the cancel originates here.
     },
   };
 }

package/host/transports/s2s-transport-fixtures.test.ts

@@ -20,7 +20,11 @@ import { z } from "zod";
 import type { AgentDef } from "../../sdk/types.ts";
 import { createFixtureSession, flush } from "../_test-utils.ts";
 
-// ─── Test agents with deterministic tools ────────────────────────────────────
+type FixtureSession = ReturnType<typeof createFixtureSession>;
+
+function firstToolResult(ctx: FixtureSession): [string, string] {
+  return vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls[0] as [string, string];
+}
 
 const weatherAgent: AgentDef = {
   name: "weather-agent",
@@ -69,8 +73,6 @@ const statefulAgent: AgentDef<{ callCount: number }> = {
   },
 };
 
-// ─── Tests ───────────────────────────────────────────────────────────────────
-
 describe("fixture replay with real executor (transport layer)", () => {
   let cleanup: () => void;
 
@@ -78,23 +80,20 @@ describe("fixture replay with real executor (transport layer)", () => {
     cleanup?.();
   });
 
-  // ── Tool call: real Zod validation + real tool execution ───────────────
+  function makeCtx(agent: AgentDef): FixtureSession {
+    const ctx = createFixtureSession(agent);
+    cleanup = ctx.cleanup;
+    return ctx;
+  }
 
   test("tool call fixture: Zod validates args, real tool executes, result sent to S2S", async () => {
-    const ctx = createFixtureSession(weatherAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(weatherAgent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
-
-    // Wait for the async tool execution pipeline to complete
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
 
-    // Verify the real tool was called and produced correct output
-    const [callId, resultStr] = vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls[0] as [
-      string,
-      string,
-    ];
+    const [callId, resultStr] = firstToolResult(ctx);
     expect(callId).toBeTruthy();
     const result = JSON.parse(resultStr);
     expect(result.city).toBe("San Francisco");
@@ -103,8 +102,7 @@ describe("fixture replay with real executor (transport layer)", () => {
   });
 
   test("tool call fixture: client receives tool_call with validated args", async () => {
-    const ctx = createFixtureSession(weatherAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(weatherAgent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
@@ -117,36 +115,30 @@ describe("fixture replay with real executor (transport layer)", () => {
   });
 
   test("tool call fixture: conversation history accumulates user + assistant messages", async () => {
-    const ctx = createFixtureSession(weatherAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(weatherAgent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
     await flush();
 
-    // Client received user transcript
     expect(ctx.client.userTranscripts.length).toBeGreaterThan(0);
     const lastUserText = ctx.client.userTranscripts.at(-1) ?? "";
     expect(lastUserText.toLowerCase()).toContain("weather");
   });
 
-  // ── Simple question: no tools, just session lifecycle ──────────────────
-
   test("simple question fixture: greeting + agent response reach client", async () => {
-    const ctx = createFixtureSession(simpleAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(simpleAgent);
     await ctx.start();
 
     ctx.replay("simple-question-sequence.json");
     await flush();
 
-    expect(ctx.client.agentTranscripts.length).toBeGreaterThanOrEqual(2); // greeting + answer
+    expect(ctx.client.agentTranscripts.length).toBeGreaterThanOrEqual(2);
   });
 
   test("simple question fixture: user speech events forwarded to client", async () => {
-    const ctx = createFixtureSession(simpleAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(simpleAgent);
     await ctx.start();
 
     ctx.replay("simple-question-sequence.json");
@@ -157,29 +149,20 @@ describe("fixture replay with real executor (transport layer)", () => {
     expect(ctx.client.userTranscripts.length).toBeGreaterThan(0);
   });
 
-  // ── Stateful agent: session state persists across tool calls ───────────
-
   test("stateful agent: tool accesses and mutates session state", async () => {
-    const ctx = createFixtureSession(statefulAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(statefulAgent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
 
-    const [, resultStr] = vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls[0] as [
-      string,
-      string,
-    ];
+    const [, resultStr] = firstToolResult(ctx);
     const result = JSON.parse(resultStr);
-    expect(result.calls).toBe(1); // state.callCount was incremented
+    expect(result.calls).toBe(1);
   });
 
-  // ── Greeting only: session lifecycle without user audio ────────────────
-
   test("greeting fixture: session setup completes with reply_done", async () => {
-    const ctx = createFixtureSession(simpleAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(simpleAgent);
     await ctx.start();
 
     ctx.replay("greeting-session-sequence.json");
@@ -189,11 +172,8 @@ describe("fixture replay with real executor (transport layer)", () => {
     expect(ctx.client.replyDoneCount).toBeGreaterThan(0);
   });
 
-  // ── Tool schemas: real agent produces correct S2S tool schemas ─────────
-
   test("real executor builds correct tool schemas from AgentDef", () => {
-    const ctx = createFixtureSession(weatherAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(weatherAgent);
 
     const schema = ctx.executor.toolSchemas.find((s) => s.name === "get_weather");
     expect(schema).toBeDefined();
@@ -205,8 +185,6 @@ describe("fixture replay with real executor (transport layer)", () => {
     });
   });
 
-  // ── Tool errors are surfaced as tool results ───────────────────────────
-
   test("tool throw is surfaced as error result", async () => {
     const agent: AgentDef = {
       name: "error-agent",
@@ -224,23 +202,16 @@ describe("fixture replay with real executor (transport layer)", () => {
       },
     };
 
-    const ctx = createFixtureSession(agent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(agent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
 
-    // Tool result should contain the error
-    const [, resultStr] = vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls[0] as [
-      string,
-      string,
-    ];
+    const [, resultStr] = firstToolResult(ctx);
     expect(resultStr).toContain("API key expired");
   });
 
-  // ── Zod validation: bad args rejected ──────────────────────────────────
-
   test("Zod validation rejects malformed tool args", async () => {
     const agent: AgentDef = {
       name: "strict-agent",
@@ -259,26 +230,18 @@ describe("fixture replay with real executor (transport layer)", () => {
       },
     };
 
-    const ctx = createFixtureSession(agent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(agent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
 
-    // The result should contain a Zod validation error
-    const [, resultStr] = vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls[0] as [
-      string,
-      string,
-    ];
+    const [, resultStr] = firstToolResult(ctx);
     expect(resultStr).toContain("Invalid arguments");
     expect(resultStr).toContain("country");
   });
 
-  // ── Interrupted transcript NOT added to conversation history ────────────
-
   test("interrupted agent transcript is not pushed to conversation history", async () => {
-    // Use a tool that captures messages to inspect conversation history
     let capturedMessages: readonly { role: string; content: string }[] = [];
     const agent: AgentDef = {
       name: "interrupt-history-agent",
@@ -297,46 +260,36 @@ describe("fixture replay with real executor (transport layer)", () => {
       },
     };
 
-    const ctx = createFixtureSession(agent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(agent);
     await ctx.start();
 
     const cbs = ctx.mockCallbacks;
 
-    // Fire an interrupted transcript — should NOT go into conversation history
     cbs.onReplyStarted("r1");
     cbs.onAgentTranscript("This was interrupted", true);
     cbs.onCancelled();
     await flush();
 
-    // Client sees both agent_transcript and cancelled events
     expect(ctx.client.agentTranscripts).toContain("This was interrupted");
     expect(ctx.client.cancelledCount).toBeGreaterThan(0);
 
-    // Fire a non-interrupted transcript — SHOULD go into conversation history
     cbs.onReplyStarted("r2");
     cbs.onAgentTranscript("This was completed", false);
     cbs.onReplyDone();
     await flush();
 
-    // Trigger a tool call to inspect conversation history.
     cbs.onUserTranscript("check");
     await flush();
     cbs.onReplyStarted("r3");
     cbs.onToolCall("c1", "check_history", { q: "test" });
-    // Wait for tool to execute (captures messages)
     await vi.waitFor(() => expect(capturedMessages.length).toBeGreaterThan(0));
 
-    // Conversation history should contain the completed text but NOT the interrupted text
     const assistantMsgs = capturedMessages.filter((m) => m.role === "assistant");
     expect(assistantMsgs.some((m) => m.content === "This was completed")).toBe(true);
     expect(assistantMsgs.every((m) => m.content !== "This was interrupted")).toBe(true);
   });
 
-  // ── Conversation history correctness after full tool-call flow ──────────
-
   test("conversation history has user + assistant messages after tool-call flow", async () => {
-    // Use a tool that captures the messages it receives
     let capturedMessages: readonly { role: string; content: string }[] = [];
     const agent: AgentDef = {
       name: "history-agent",
@@ -355,28 +308,21 @@ describe("fixture replay with real executor (transport layer)", () => {
       },
     };
 
-    const ctx = createFixtureSession(agent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(agent);
     await ctx.start();
 
     ctx.replay("tool-call-sequence.json");
     await vi.waitFor(() => expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalled());
 
-    // The tool should have seen the user's weather question in messages
     const userMsgs = capturedMessages.filter((m) => m.role === "user");
     expect(userMsgs.some((m) => m.content.toLowerCase().includes("weather"))).toBe(true);
   });
 
-  // ── Audio chunks forwarded to client.audio ─────────────────────────────
-
   test("reply.audio events forwarded to client.audio", async () => {
-    const ctx = createFixtureSession(simpleAgent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(simpleAgent);
     await ctx.start();
 
-    // Fire audio events directly via callbacks (replay skips reply.audio)
-    const audioBytes = new Uint8Array([10, 20, 30, 40]);
-    ctx.mockCallbacks.onAudio(audioBytes);
+    ctx.mockCallbacks.onAudio(new Uint8Array([10, 20, 30, 40]));
     ctx.mockCallbacks.onAudio(new Uint8Array([50, 60]));
 
     expect(ctx.client.audioChunks.length).toBe(2);
@@ -384,8 +330,6 @@ describe("fixture replay with real executor (transport layer)", () => {
     expect(Array.from(ctx.client.audioChunks[1] ?? [])).toEqual([50, 60]);
   });
 
-  // ── Multiple tool calls in one reply: results buffered and sent together ─
-
   test("multiple tool calls in one reply: all results buffered and sent after replyDone", async () => {
     const agent: AgentDef = {
       name: "multi-tool-agent",
@@ -401,8 +345,7 @@ describe("fixture replay with real executor (transport layer)", () => {
       },
     };
 
-    const ctx = createFixtureSession(agent);
-    cleanup = ctx.cleanup;
+    const ctx = makeCtx(agent);
     await ctx.start();
 
     const cbs = ctx.mockCallbacks;
@@ -410,21 +353,17 @@ describe("fixture replay with real executor (transport layer)", () => {
     cbs.onToolCall("c1", "get_weather", { city: "NYC" });
     cbs.onToolCall("c2", "get_weather", { city: "LA" });
 
-    // Wait for both tool calls to be dispatched to the client
     await vi.waitFor(() => {
       expect(ctx.client.toolCallEvents.length).toBe(2);
     });
 
-    // Results NOT sent yet — reply.done hasn't fired
     expect(ctx.fakeHandle.sendToolResult).not.toHaveBeenCalled();
 
-    // Fire reply.done — should flush both results
     cbs.onReplyDone();
     await vi.waitFor(() => {
       expect(ctx.fakeHandle.sendToolResult).toHaveBeenCalledTimes(2);
     });
 
-    // Verify both results are correct
     const calls = vi.mocked(ctx.fakeHandle.sendToolResult).mock.calls as [string, string][];
     const results = calls.map(([, r]) => JSON.parse(r));
     expect(results.some((r) => r.city === "NYC")).toBe(true);