@kuralle-syrinx/realtime 2.1.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/realtime",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -8,8 +8,8 @@
   "types": "./src/index.ts",
   "dependencies": {
     "@google/genai": "^2.8.0",
-    "@kuralle-syrinx/core": "2.1.0",
-    "@kuralle-syrinx/ws": "2.1.0"
+    "@kuralle-syrinx/core": "3.0.0",
+    "@kuralle-syrinx/ws": "3.0.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/from-gemini-live.test.ts

@@ -10,6 +10,7 @@ import { fromGeminiLive } from "./from-gemini-live.js";
 
 const sendRealtimeInput = vi.fn();
 const sendToolResponse = vi.fn();
+const sendClientContent = vi.fn();
 const closeSession = vi.fn();
 
 let onopen: (() => void) | null = null;
@@ -27,6 +28,7 @@ const liveConnect = vi.fn().mockImplementation(async ({ callbacks }: {
   return {
     sendRealtimeInput,
     sendToolResponse,
+    sendClientContent,
     close: closeSession,
   };
 });
@@ -41,6 +43,7 @@ vi.mock("@google/genai", () => ({
 afterEach(() => {
   sendRealtimeInput.mockClear();
   sendToolResponse.mockClear();
+  sendClientContent.mockClear();
   closeSession.mockClear();
   liveConnect.mockClear();
   onopen = null;
@@ -126,6 +129,17 @@ describe("fromGeminiLive", () => {
     expect(sendRealtimeInput).toHaveBeenCalledTimes(1);
   });
 
+  it("sends a typed user turn via sendClientContent with turnComplete", async () => {
+    const adapter = fromGeminiLive({ apiKey: "test-key" });
+    await adapter.open(new AbortController().signal);
+
+    adapter.sendText!("when is the late-add deadline?");
+    expect(sendClientContent).toHaveBeenCalledWith({
+      turns: [{ role: "user", parts: [{ text: "when is the late-add deadline?" }] }],
+      turnComplete: true,
+    });
+  });
+
   it("normalizes provider server messages into RealtimeEvent", async () => {
     const adapter = fromGeminiLive({ apiKey: "test-key" });
     const eventsTask = collectEvents(adapter.events, 7);

package/src/from-gemini-live.ts

@@ -3,6 +3,7 @@
 import type { Session, LiveServerMessage } from "@google/genai";
 
 import { bytesToBase64, base64ToBytes } from "./base64.js";
+import { RealtimeEventStream } from "./realtime-event-stream.js";
 import type { RealtimeAdapter, RealtimeEvent, RealtimeToolDef } from "./realtime-adapter.js";
 
 const DEFAULT_MODEL = "gemini-3.1-flash-live-preview";
@@ -16,48 +17,6 @@ export interface GeminiLiveOptions {
   readonly tools?: readonly RealtimeToolDef[];
 }
 
-class RealtimeEventStream implements AsyncIterable<RealtimeEvent> {
-  private readonly queue: RealtimeEvent[] = [];
-  private readonly waiters: Array<(result: IteratorResult<RealtimeEvent>) => void> = [];
-  private closed = false;
-
-  push(event: RealtimeEvent): void {
-    if (this.closed) return;
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter({ value: event, done: false });
-      return;
-    }
-    this.queue.push(event);
-  }
-
-  close(): void {
-    if (this.closed) return;
-    this.closed = true;
-    while (this.waiters.length > 0) {
-      const waiter = this.waiters.shift();
-      waiter?.({ value: undefined, done: true });
-    }
-  }
-
-  [Symbol.asyncIterator](): AsyncIterator<RealtimeEvent> {
-    return {
-      next: () =>
-        new Promise<IteratorResult<RealtimeEvent>>((resolve) => {
-          if (this.queue.length > 0) {
-            resolve({ value: this.queue.shift()!, done: false });
-            return;
-          }
-          if (this.closed) {
-            resolve({ value: undefined, done: true });
-            return;
-          }
-          this.waiters.push(resolve);
-        }),
-    };
-  }
-}
-
 class GeminiLiveAdapter implements RealtimeAdapter {
   readonly caps = {
     inputSampleRateHz: INPUT_SAMPLE_RATE_HZ,
@@ -145,6 +104,13 @@ class GeminiLiveAdapter implements RealtimeAdapter {
     });
   }
 
+  sendText(text: string): void {
+    this.requireSession().sendClientContent({
+      turns: [{ role: "user", parts: [{ text }] }],
+      turnComplete: true,
+    });
+  }
+
   cancelResponse(_audioEndMs: number): void {
     // Gemini handles interruption server-side via `interrupted`; no truncate API.
   }

package/src/from-openai-realtime.test.ts

@@ -155,6 +155,31 @@ describe("fromOpenAIRealtime", () => {
     expect(JSON.parse(mock.sent[5]!)).toEqual({ type: "response.create" });
   });
 
+  it("sends a typed user turn as conversation.item.create(input_text) + response.create", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromOpenAIRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=gpt-realtime-2",
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length > 0);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    adapter.sendText!("when is the late-add deadline?");
+    expect(JSON.parse(mock.sent[1]!)).toEqual({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "when is the late-add deadline?" }],
+      },
+    });
+    expect(JSON.parse(mock.sent[2]!)).toEqual({ type: "response.create" });
+  });
+
   it("normalizes provider server events into RealtimeEvent", async () => {
     const mock = createMockSocketHarness();
     const adapter = fromOpenAIRealtime({

package/src/index.ts

@@ -14,4 +14,4 @@ export {
   type GeminiTranslateSession,
   type GeminiTranslateSessionOptions,
 } from "./gemini-translate.js";
-export { RealtimeBridge } from "./realtime-bridge.js";
+export { RealtimeBridge, type RealtimeBridgeOptions } from "./realtime-bridge.js";

package/src/openai-compatible-realtime.ts

@@ -4,6 +4,7 @@ import type { SocketFactory } from "@kuralle-syrinx/ws";
 import { RealtimeSocket } from "@kuralle-syrinx/ws/realtime";
 
 import { base64ToBytes, bytesToBase64 } from "./base64.js";
+import { RealtimeEventStream } from "./realtime-event-stream.js";
 import type { RealtimeAdapter, RealtimeEvent } from "./realtime-adapter.js";
 
 export interface OpenAiCompatibleRealtimeConfig {
@@ -30,48 +31,6 @@ export interface OpenAiCompatibleRealtimeConfig {
   ) => boolean;
 }
 
-class RealtimeEventStream implements AsyncIterable<RealtimeEvent> {
-  private readonly queue: RealtimeEvent[] = [];
-  private readonly waiters: Array<(result: IteratorResult<RealtimeEvent>) => void> = [];
-  private closed = false;
-
-  push(event: RealtimeEvent): void {
-    if (this.closed) return;
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter({ value: event, done: false });
-      return;
-    }
-    this.queue.push(event);
-  }
-
-  close(): void {
-    if (this.closed) return;
-    this.closed = true;
-    while (this.waiters.length > 0) {
-      const waiter = this.waiters.shift();
-      waiter?.({ value: undefined, done: true });
-    }
-  }
-
-  [Symbol.asyncIterator](): AsyncIterator<RealtimeEvent> {
-    return {
-      next: () =>
-        new Promise<IteratorResult<RealtimeEvent>>((resolve) => {
-          if (this.queue.length > 0) {
-            resolve({ value: this.queue.shift()!, done: false });
-            return;
-          }
-          if (this.closed) {
-            resolve({ value: undefined, done: true });
-            return;
-          }
-          this.waiters.push(resolve);
-        }),
-    };
-  }
-}
-
 class OpenAiCompatibleRealtimeAdapter implements RealtimeAdapter {
   readonly caps: RealtimeAdapter["caps"];
   readonly events: AsyncIterable<RealtimeEvent>;
@@ -143,6 +102,19 @@ class OpenAiCompatibleRealtimeAdapter implements RealtimeAdapter {
     });
   }
 
+  sendText(text: string): void {
+    const socket = this.requireSocket();
+    socket.send({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text }],
+      },
+    });
+    this.requestResponseCreate();
+  }
+
   cancelResponse(audioEndMs: number): void {
     if (!this.activeResponse) return;
     const socket = this.requireSocket();

package/src/realtime-adapter.ts

@@ -11,6 +11,11 @@ export interface RealtimeAdapter {
 
   open(signal: AbortSignal): Promise<void>;
   sendAudio(pcm16: Uint8Array): void;
+  /**
+   * Send a typed user turn to the front model and request a response. Optional: adapters whose
+   * provider cannot accept text input omit it, and the bridge silently ignores typed turns for them.
+   */
+  sendText?(text: string): void;
   cancelResponse(audioEndMs: number): void;
   injectToolResult(toolId: string, text: string): void;
   /** Close the provider socket and end the event stream. */

package/src/realtime-bridge.test.ts

@@ -8,6 +8,8 @@ import {
   VoiceAgentSession,
   type EndOfSpeechPacket,
   type InterruptTtsPacket,
+  type LlmDeltaPacket,
+  type LlmResponseDonePacket,
   type LlmErrorPacket,
   type LlmToolResultPacket,
   type Reasoner,
@@ -64,6 +66,12 @@ class FakeRealtimeAdapter implements RealtimeAdapter {
     this.sentAudio.push(pcm16);
   }
 
+  readonly sentText: string[] = [];
+
+  sendText(text: string): void {
+    this.sentText.push(text);
+  }
+
   readonly cancelCalls: number[] = [];
 
   cancelResponse(audioEndMs: number): void {
@@ -175,6 +183,36 @@ describe("RealtimeBridge", () => {
     await started;
   });
 
+  it("forwards a user.text_received turn to adapter.sendText (typed input), ignoring blank text", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const bridge = new RealtimeBridge(adapter);
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    bus.push(Route.Main, {
+      kind: "user.text_received",
+      contextId: "transport-turn",
+      timestampMs: Date.now(),
+      text: "when is the late-add deadline?",
+    });
+    bus.push(Route.Main, {
+      kind: "user.text_received",
+      contextId: "transport-turn",
+      timestampMs: Date.now(),
+      text: "   ",
+    });
+
+    await waitForCondition(() => adapter.sentText.length > 0);
+    expect(adapter.sentText).toEqual(["when is the late-add deadline?"]);
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
   it("mints a fresh contextId for each response_started (R1)", async () => {
     const adapter = new FakeRealtimeAdapter();
     const bridge = new RealtimeBridge(adapter);
@@ -426,6 +464,45 @@ describe("RealtimeBridge", () => {
     await started;
   });
 
+  it("R-08: delegate tool_call missing the query argument emits recoverable error, never calls reasoner", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    let reasonerCalled = false;
+    const reasoner: Reasoner = {
+      stream: () => {
+        reasonerCalled = true;
+        return (async function* () {
+          yield { type: "finish", reason: "stop", text: "should not run" };
+        })();
+      },
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner, "consult_knowledge");
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    const errors: LlmErrorPacket[] = [];
+    bus.on("llm.error", (pkt) => { errors.push(pkt as LlmErrorPacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({
+      type: "tool_call",
+      toolId: "call_noarg",
+      toolName: "consult_knowledge",
+      args: { question: "wrong arg name" },
+    });
+
+    await waitForCondition(() => errors.length === 1);
+    expect(errors[0]!.isRecoverable).toBe(true);
+    expect(errors[0]!.cause.message).toContain("query");
+    expect(reasonerCalled).toBe(false);
+    expect(adapter.injectedToolResults).toHaveLength(0);
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
   it("R-09: contextProvider messages are passed to reasoner.stream", async () => {
     const adapter = new FakeRealtimeAdapter();
     const prior: ReasonerMessage[] = [
@@ -466,6 +543,158 @@ describe("RealtimeBridge", () => {
     await started;
   });
 
+  it("R-10: routes a non-delegate tool call to onFrontToolCall and injects its result (no error)", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "finish", reason: "stop", text: "delegate not called" };
+      })(),
+    };
+    const frontCalls: Array<{ toolName: string; args: Record<string, unknown> }> = [];
+    const bridge = new RealtimeBridge(adapter, reasoner, "consult_knowledge", {
+      onFrontToolCall: (c) => {
+        frontCalls.push({ toolName: c.toolName, args: c.args });
+        return "acknowledged";
+      },
+    });
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    const errors: LlmErrorPacket[] = [];
+    bus.on("llm.error", (pkt) => { errors.push(pkt as LlmErrorPacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({ type: "tool_call", toolId: "call_front", toolName: "wait_for_user", args: { reason: "hold music" } });
+
+    await waitForCondition(() => adapter.injectedToolResults.length === 1);
+    expect(frontCalls).toEqual([{ toolName: "wait_for_user", args: { reason: "hold music" } }]);
+    expect(adapter.injectedToolResults[0]).toEqual({ toolId: "call_front", text: "acknowledged" });
+    expect(errors).toEqual([]); // front tools must NOT abort the turn
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("R-11: forwards the full tool-call args to the Reasoner, not just the query", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    let receivedArgs: Record<string, unknown> | undefined;
+    const reasoner: Reasoner = {
+      stream: (turn) => {
+        receivedArgs = turn.toolArgs;
+        return (async function* () {
+          yield { type: "finish", reason: "stop", text: "ok" };
+        })();
+      },
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner, "consult_knowledge");
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({
+      type: "tool_call",
+      toolId: "call_args",
+      toolName: "consult_knowledge",
+      args: { query: "What's the deadline?", reply_language: "si" },
+    });
+
+    await waitForCondition(() => adapter.injectedToolResults.length === 1);
+    expect(receivedArgs).toEqual({ query: "What's the deadline?", reply_language: "si" });
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("R-13: surfaces the assistant transcript as llm.delta/llm.done (client captions data)", async () => {
+    // Regression guard for #6: a realtime turn's assistant words must reach the bus as
+    // llm.delta/llm.done — VoiceAgentSession turns those into agent_text_delta/agent_finished,
+    // which the edge protocol forwards to the client as agent_chunk/agent_end.
+    const adapter = new FakeRealtimeAdapter();
+    const bridge = new RealtimeBridge(adapter);
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    const deltas: LlmDeltaPacket[] = [];
+    const dones: LlmResponseDonePacket[] = [];
+    bus.on("llm.delta", (pkt) => { deltas.push(pkt as LlmDeltaPacket); });
+    bus.on("llm.done", (pkt) => { dones.push(pkt as LlmResponseDonePacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({ type: "transcript", role: "assistant", text: "The deadline is March 31.", final: true });
+    adapter.emit({ type: "response_done" });
+
+    await waitForCondition(() => dones.length === 1);
+    expect(deltas.map((d) => d.text).join("")).toContain("The deadline is March 31.");
+    expect(dones[0]!.text).toContain("The deadline is March 31.");
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("surfaces a delta-only assistant transcript (Gemini Live: no final transcript event)", async () => {
+    // Gemini Live streams the assistant transcript as non-final fragments and never emits a
+    // final transcript. The bridge must still surface the concatenated words as llm.delta/llm.done
+    // so client captions work — without double-counting providers (OpenAI) that DO send a final.
+    const adapter = new FakeRealtimeAdapter();
+    const bridge = new RealtimeBridge(adapter);
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    const dones: LlmResponseDonePacket[] = [];
+    bus.on("llm.done", (pkt) => { dones.push(pkt as LlmResponseDonePacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({ type: "transcript", role: "assistant", text: "The capital", final: false });
+    adapter.emit({ type: "transcript", role: "assistant", text: " of France", final: false });
+    adapter.emit({ type: "transcript", role: "assistant", text: " is", final: false });
+    adapter.emit({ type: "transcript", role: "assistant", text: " Paris.", final: false });
+    adapter.emit({ type: "response_done" });
+
+    await waitForCondition(() => dones.length === 1);
+    expect(dones[0]!.text).toBe("The capital of France is Paris.");
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("prefers the final transcript over deltas (OpenAI: deltas + final, no double-count)", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const bridge = new RealtimeBridge(adapter);
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    const dones: LlmResponseDonePacket[] = [];
+    bus.on("llm.done", (pkt) => { dones.push(pkt as LlmResponseDonePacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({ type: "transcript", role: "assistant", text: "Let me ", final: false });
+    adapter.emit({ type: "transcript", role: "assistant", text: "check that.", final: false });
+    adapter.emit({ type: "transcript", role: "assistant", text: "Let me check that.", final: true });
+    adapter.emit({ type: "response_done" });
+
+    await waitForCondition(() => dones.length === 1);
+    expect(dones[0]!.text).toBe("Let me check that.");
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
   it("R-12: coalesces tiny audio deltas and never emits odd-length tts.audio", async () => {
     const adapter = new FakeRealtimeAdapter();
     const bridge = new RealtimeBridge(adapter);

package/src/realtime-bridge.ts

@@ -16,6 +16,7 @@ import {
   type Reasoner,
   type ReasonerMessage,
   type UserAudioReceivedPacket,
+  type UserTextReceivedPacket,
   type SttResultPacket,
   type TextToSpeechAudioPacket,
   type TextToSpeechEndPacket,
@@ -38,13 +39,32 @@ export interface RealtimeBridgeOptions {
    * stateless — each tool call receives only the query extracted from the front-model tool args.
    */
   readonly contextProvider?: () => readonly ReasonerMessage[];
+  /**
+   * Name of the front-model tool argument that carries the user's query for the delegate Reasoner.
+   * Must match the argument name in the registered delegate tool's schema. Defaults to "query".
+   */
+  readonly delegateQueryArg?: string;
+  /**
+   * Handle a front-model tool call whose name is NOT the delegate tool — front-level tools like
+   * `wait_for_user`, `escalate_to_human`, or `finish_session` that must not hit the reasoner.
+   * Return the string to inject back to the front model as the tool result (default `""`). When
+   * omitted, a non-delegate tool call remains a recoverable error (the prior behavior).
+   */
+  readonly onFrontToolCall?: (call: {
+    readonly toolId: string;
+    readonly toolName: string;
+    readonly args: Record<string, unknown>;
+  }) => string | undefined | Promise<string | undefined>;
 }
 
 export class RealtimeBridge implements VoicePlugin {
   private bus: PipelineBus | null = null;
   private contextId = "";
   private turnUserText = "";
+  /** Authoritative full assistant transcript(s) — providers that emit a final transcript (OpenAI). */
   private turnAssistantText = "";
+  /** Concatenated streamed transcript fragments — providers that emit deltas only, no final (Gemini Live). */
+  private turnAssistantDeltas = "";
   private sessionAbort: AbortController | null = null;
   private inflight: AbortController | undefined;
   private playedMs = 0;
@@ -71,6 +91,9 @@ export class RealtimeBridge implements VoicePlugin {
         );
         this.adapter.sendAudio(resampled);
       }),
+      bus.on<UserTextReceivedPacket>("user.text_received", (pkt) => {
+        if (pkt.text.trim().length > 0) this.adapter.sendText?.(pkt.text);
+      }),
       bus.on<TextToSpeechPlayoutProgressPacket>("tts.playout_progress", (pkt) => {
         if (pkt.contextId === this.contextId) this.playedMs = pkt.playedOutMs;
       }),
@@ -120,25 +143,19 @@ export class RealtimeBridge implements VoicePlugin {
         this.onAudio(bus, ev.pcm16, ev.sampleRateHz);
         break;
       case "transcript":
-        if (ev.final && ev.role === "user") this.onFinalTranscript(bus, ev.text);
-        else if (ev.final && ev.role === "assistant" && ev.text.trim()) {
+        if (ev.role === "user") {
+          if (ev.final) this.onFinalTranscript(bus, ev.text);
+        } else if (ev.final && ev.text.trim()) {
           this.turnAssistantText = this.turnAssistantText
             ? `${this.turnAssistantText} ${ev.text.trim()}`
             : ev.text.trim();
+        } else if (!ev.final && ev.text) {
+          // Streamed fragments already carry their own leading spaces — concatenate verbatim.
+          this.turnAssistantDeltas += ev.text;
         }
         break;
       case "tool_call":
-        if (this.reasoner) {
-          if (ev.toolName !== this.delegateToolName) {
-            const cause = new Error(
-              `Unexpected tool call "${ev.toolName}" (expected "${this.delegateToolName}")`,
-            );
-            if (this.opts.debug) console.error("[realtime-bridge]", cause.message);
-            this.onError(bus, cause, true);
-            break;
-          }
-          await this.runDelegate(bus, ev);
-        }
+        await this.handleToolCall(bus, ev);
         break;
       case "response_done":
         this.onResponseDone(bus);
@@ -154,6 +171,42 @@ export class RealtimeBridge implements VoicePlugin {
     }
   }
 
+  private async handleToolCall(
+    bus: PipelineBus,
+    ev: { toolId: string; toolName: string; args: Record<string, unknown> },
+  ): Promise<void> {
+    if (ev.toolName === this.delegateToolName) {
+      if (this.reasoner) await this.runDelegate(bus, ev);
+      return;
+    }
+    if (this.opts.onFrontToolCall) {
+      await this.handleFrontTool(bus, ev);
+      return;
+    }
+    // No front-tool handler: with a reasoner, an unexpected tool is a recoverable error
+    // (without one, tool calls are ignored, as before).
+    if (this.reasoner) {
+      const cause = new Error(`Unexpected tool call "${ev.toolName}" (expected "${this.delegateToolName}")`);
+      if (this.opts.debug) console.error("[realtime-bridge]", cause.message);
+      this.onError(bus, cause, true);
+    }
+  }
+
+  private async handleFrontTool(
+    bus: PipelineBus,
+    ev: { toolId: string; toolName: string; args: Record<string, unknown> },
+  ): Promise<void> {
+    if (!this.opts.onFrontToolCall) return;
+    let result: string;
+    try {
+      result = (await this.opts.onFrontToolCall({ toolId: ev.toolId, toolName: ev.toolName, args: ev.args })) ?? "";
+    } catch (err) {
+      this.onError(bus, err instanceof Error ? err : new Error(String(err)), true);
+      return;
+    }
+    this.adapter.injectToolResult(ev.toolId, result);
+  }
+
   private async runDelegate(
     bus: PipelineBus,
     ev: { toolId: string; toolName: string; args: Record<string, unknown> },
@@ -170,13 +223,26 @@ export class RealtimeBridge implements VoicePlugin {
     };
     bus.push(Route.Main, toolCall);
 
+    const queryArg = this.opts.delegateQueryArg ?? "query";
+    const rawQuery = ev.args[queryArg];
+    const userText = typeof rawQuery === "string" ? rawQuery : "";
+    if (userText.trim().length === 0) {
+      this.onError(
+        bus,
+        new Error(`delegate tool "${ev.toolName}" called without a string "${queryArg}" argument`),
+        true,
+      );
+      return;
+    }
+
     this.inflight = new AbortController();
     let answer = "";
 
     try {
       const messages = this.opts.contextProvider?.() ?? [];
       for await (const part of this.reasoner!.stream({
-        userText: String(ev.args["query"] ?? ""),
+        userText,
+        toolArgs: ev.args,
         messages,
         signal: this.inflight.signal,
       })) {
@@ -244,6 +310,7 @@ export class RealtimeBridge implements VoicePlugin {
     this.contextId = crypto.randomUUID();
     this.turnUserText = "";
     this.turnAssistantText = "";
+    this.turnAssistantDeltas = "";
     this.playedMs = 0;
     this.audioRemainder = new Uint8Array(0);
     const packet: TurnChangePacket = {
@@ -305,18 +372,21 @@ export class RealtimeBridge implements VoicePlugin {
     };
     // Surface the assistant's spoken transcript as agent text so UIs (e.g. the studio) render it.
     // The realtime adapter already produced the audio directly; these packets are display-only.
-    if (this.turnAssistantText.trim()) {
+    // Prefer the authoritative final transcript (OpenAI); fall back to the streamed fragments for
+    // providers that only emit non-final deltas (Gemini Live).
+    const assistantText = this.turnAssistantText.trim() || this.turnAssistantDeltas.trim();
+    if (assistantText) {
       const delta: LlmDeltaPacket = {
         kind: "llm.delta",
         contextId: this.contextId,
         timestampMs,
-        text: this.turnAssistantText,
+        text: assistantText,
       };
       const done: LlmResponseDonePacket = {
         kind: "llm.done",
         contextId: this.contextId,
         timestampMs,
-        text: this.turnAssistantText,
+        text: assistantText,
       };
       bus.push(Route.Main, delta, done);
     }

package/src/realtime-event-stream.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+
+import type { RealtimeEvent } from "./realtime-adapter.js";
+
+/**
+ * Single-consumer async-iterable queue of realtime provider events. Producers call
+ * `push()` / `close()`; the consumer drains it with `for await`. Events queue until
+ * consumed (no backpressure). Shared by every realtime adapter so the iteration and
+ * close semantics cannot drift between providers.
+ */
+export class RealtimeEventStream implements AsyncIterable<RealtimeEvent> {
+  private readonly queue: RealtimeEvent[] = [];
+  private readonly waiters: Array<(result: IteratorResult<RealtimeEvent>) => void> = [];
+  private closed = false;
+
+  push(event: RealtimeEvent): void {
+    if (this.closed) return;
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value: event, done: false });
+      return;
+    }
+    this.queue.push(event);
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift();
+      waiter?.({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<RealtimeEvent> {
+    return {
+      next: () =>
+        new Promise<IteratorResult<RealtimeEvent>>((resolve) => {
+          if (this.queue.length > 0) {
+            resolve({ value: this.queue.shift()!, done: false });
+            return;
+          }
+          if (this.closed) {
+            resolve({ value: undefined, done: true });
+            return;
+          }
+          this.waiters.push(resolve);
+        }),
+    };
+  }
+}