@kuralle-syrinx/realtime 3.1.0 → 4.0.0

package/README.md

@@ -105,6 +105,41 @@ Cartesia, …) all dial through `createWorkersSocket` so auth headers ride on th
 Regression lock: `edge-safety.test.ts` runs the adapter + bridge with `Buffer` and `process` removed from
 `globalThis`.
 
+## The Responder-Thinker primitive (the delegate seam)
+
+The bi-model shape has a name: **Responder-Thinker** — a fast realtime **responder** on the audio
+loop, an async reasoning/RAG **thinker** behind it, delegated to via one tool. `RealtimeBridge` +
+`Reasoner` *is* this architecture, and the delegate seam ships with four built-in behaviors
+(RFC `docs/rfc-bimodel-delegate-seam.md`) so a consumer never hand-rolls them:
+
+- **G1 — structured result envelope (default).** The thinker's answer reaches the responder as
+  authoritative JSON — `{ response_text, require_repeat_verbatim: true, render? }`
+  (`DelegateResultEnvelope`, OpenAI's documented *Tool Output Formatting* shape) — so the front
+  voices it faithfully instead of paraphrasing or inventing. Options:
+  `toolResultFormat: "envelope" | "string"` (default `"envelope"`), `renderDirective` (e.g.
+  `"translate_faithfully"`). Applied synchronously to the already-buffered delegate answer —
+  latency-neutral; bus packets keep the raw answer.
+- **G2 — delegate observability.** The bridge emits `delegate.query` / `delegate.result`
+  (Background route) around every `reasoner.stream(...)`: query, answer, `durationMs`,
+  `grounded` (the stream surfaced a `tool-result` part). Subscribe on the bus — or via
+  `VoiceAgentSession`'s `delegate_query` / `delegate_result` events — instead of wrapping the
+  `Reasoner` to log.
+- **G3 — typed preamble/filler lifecycle.** `VoiceAgentSession` turns each delegate tool call into
+  a `tool_call_cue` lifecycle — `started` (before the thinker runs) / `delayed` (time-triggered
+  "still working" after `delayCueAfterMs`) / `complete` / `failed` (error, barge-in, supersede) —
+  and the WS transports surface it as `tool_call_*` wire messages the standard clients parse.
+  Decoupled from any blocking-tool contract: it wraps the thinker-latency window itself.
+- **G4 — durable session + resume.** `caps.supportsNativeResume` splits providers: Gemini Live
+  resumes server-side (`sessionResumptionHandle` option in + `resumption_handle` events out —
+  never replay on top of it); OpenAI-compatible fronts replay via `resumeHistory: () => [...]`
+  (sent as `conversation.item.create` after every (re)connect's `session.update`, never a
+  `response.create` — a resumed session cannot double-answer). The thinker side re-seeds from a
+  `ReasonerSessionStore` (`@kuralle-syrinx/core`), DO-SQLite-backed in `@kuralle-syrinx/cf-agents`.
+
+On Cloudflare, `withVoice(Agent)` (`@kuralle-syrinx/cf-agents`) wires all four up turnkey — a new
+consumer supplies a front + a `Reasoner` and gets envelope + observability + cues + durable resume
+for free.
+
 ## Capability model
 
 `RealtimeAdapter.caps` lets the bridge adapt per provider:
@@ -145,7 +180,9 @@ Syrinx with the provider region to minimize the added leg.
 | Delegate → `Reasoner` (bi-model), `function_call_output` injection | ✅ live-verified (university turn) |
 | Barge-in: `speech_started`→interrupt, `cancel`+`truncate`, abort delegate, cancel-when-idle guard | ✅ logic unit-verified + detection live-confirmed; live "resume-after-barge" smoke is flaky (orchestration) |
 | First-audio direct-vs-bridged latency delta harness | ⏳ open (WBS-5) |
-| `fromGeminiLive` / `fromMoshi` adapters | ⏳ future |
+| `fromGeminiLive` adapter (incl. native session resume) | ✅ shipped |
+| Responder-Thinker delegate seam: envelope + observability + cues + durable resume | ✅ shipped (RFC bimodel-delegate-seam) |
+| `fromMoshi` adapter | ⏳ future |
 
 Tests: `pnpm --filter @kuralle-syrinx/realtime test`. Live gates (need `OPENAI_API_KEY`):
 `smoke:realtime-frame` / `:realtime-oneturn` / `:realtime-university` / `:realtime-bargein` in

package/package.json

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

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

@@ -129,6 +129,35 @@ describe("fromGeminiLive", () => {
     expect(sendRealtimeInput).toHaveBeenCalledTimes(1);
   });
 
+  it("G4/WBS-4: native resume — always enables sessionResumption, passes a prior handle through, surfaces new handles", async () => {
+    const adapter = fromGeminiLive({ apiKey: "test-key", sessionResumptionHandle: "handle-prev" });
+    expect(adapter.caps.supportsNativeResume).toBe(true);
+
+    const eventsTask = collectEvents(adapter.events, 1);
+    await adapter.open(new AbortController().signal);
+
+    const connectArg = liveConnect.mock.calls[0]![0] as { config: Record<string, unknown> };
+    // Handle passthrough — the server restores the conversation; nothing is replayed
+    // client-side (sendClientContent untouched — R6: no double-apply).
+    expect(connectArg.config["sessionResumption"]).toEqual({ handle: "handle-prev" });
+    expect(sendClientContent).not.toHaveBeenCalled();
+
+    inject({ sessionResumptionUpdate: { newHandle: "handle-next", resumable: true } });
+    // Non-resumable updates carry no usable handle and must be ignored.
+    inject({ sessionResumptionUpdate: { newHandle: "", resumable: false } });
+
+    expect(await eventsTask).toEqual([{ type: "resumption_handle", handle: "handle-next" }]);
+    await adapter.close();
+  });
+
+  it("G4/WBS-4: enables handle issuance even without a prior handle", async () => {
+    const adapter = fromGeminiLive({ apiKey: "test-key" });
+    await adapter.open(new AbortController().signal);
+    const connectArg = liveConnect.mock.calls[0]![0] as { config: Record<string, unknown> };
+    expect(connectArg.config["sessionResumption"]).toEqual({});
+    await adapter.close();
+  });
+
   it("sends a typed user turn via sendClientContent with turnComplete", async () => {
     const adapter = fromGeminiLive({ apiKey: "test-key" });
     await adapter.open(new AbortController().signal);
@@ -203,6 +232,7 @@ describe("fromGeminiLive", () => {
     expect(adapter.caps).toEqual({
       inputSampleRateHz: 16_000,
       outputSampleRateHz: 24_000,
+      supportsNativeResume: true,
       supportsConcurrentToolAudio: false,
       supportsTruncate: false,
       emitsServerSpeechStarted: true,

package/src/from-gemini-live.ts

@@ -15,6 +15,14 @@ export interface GeminiLiveOptions {
   readonly model?: string;
   readonly systemInstruction?: string;
   readonly tools?: readonly RealtimeToolDef[];
+  /**
+   * G4 native resume: a `sessionResumption` handle from a prior session's
+   * `resumption_handle` events. Gemini restores the conversation server-side —
+   * do NOT also replay the transcript (that would double-apply history, R6).
+   * Session resumption is always enabled so handles are issued; this passes a
+   * prior handle back on reconnect.
+   */
+  readonly sessionResumptionHandle?: string;
 }
 
 class GeminiLiveAdapter implements RealtimeAdapter {
@@ -24,6 +32,7 @@ class GeminiLiveAdapter implements RealtimeAdapter {
     supportsConcurrentToolAudio: false,
     supportsTruncate: false,
     emitsServerSpeechStarted: true,
+    supportsNativeResume: true,
   } as const;
 
   readonly events: AsyncIterable<RealtimeEvent>;
@@ -56,6 +65,11 @@ class GeminiLiveAdapter implements RealtimeAdapter {
       responseModalities: [Modality.AUDIO],
       inputAudioTranscription: {},
       outputAudioTranscription: {},
+      // G4: always on so the server issues resumption handles; a prior handle
+      // resumes the conversation server-side (native resume — no replay).
+      sessionResumption: this.opts.sessionResumptionHandle
+        ? { handle: this.opts.sessionResumptionHandle }
+        : {},
     };
     if (this.opts.systemInstruction) {
       config["systemInstruction"] = this.opts.systemInstruction;
@@ -161,6 +175,12 @@ class GeminiLiveAdapter implements RealtimeAdapter {
   }
 
   private handleMessage(msg: LiveServerMessage): void {
+    // G4: surface fresh resumption handles so a durable host can persist the latest.
+    const resumption = msg.sessionResumptionUpdate;
+    if (resumption?.resumable && resumption.newHandle) {
+      this.stream.push({ type: "resumption_handle", handle: resumption.newHandle });
+    }
+
     if (msg.setupComplete) {
       if (!this.activeResponse) {
         this.activeResponse = true;

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

@@ -44,6 +44,80 @@ function createMockSocketHarness(): MockSocketHarness {
   };
 }
 
+interface ReconnectableHarness {
+  readonly factory: SocketFactory;
+  readonly sent: string[];
+  readonly connectCount: () => number;
+  /** Fire the current socket's onClose with a reconnectable code → triggers auto-reconnect. */
+  drop(): void;
+  inject(msg: Record<string, unknown>): void;
+}
+
+/**
+ * Mock harness that models the connection lifecycle so a reconnect can be simulated: each
+ * factory call mints a fresh socket that auto-fires onOpen, and `drop()` closes the current
+ * socket which drives WebSocketConnection to reconnect (calling the factory again).
+ */
+function createReconnectableHarness(): ReconnectableHarness {
+  const sent: string[] = [];
+  let connectCount = 0;
+  let current: {
+    open: boolean;
+    closeHandler?: (code: number, reason: string) => void;
+    messageHandler?: (data: SocketData, isBinary: boolean) => void;
+  } | null = null;
+
+  const factory: SocketFactory = () => {
+    connectCount += 1;
+    const state: {
+      open: boolean;
+      closeHandler?: (code: number, reason: string) => void;
+      messageHandler?: (data: SocketData, isBinary: boolean) => void;
+    } = { open: false };
+    current = state;
+    const socket: ManagedSocket = {
+      get isOpen() {
+        return state.open;
+      },
+      send: (data: SocketData) => {
+        sent.push(typeof data === "string" ? data : "");
+      },
+      keepAlivePing: () => {},
+      verify: async () => true,
+      dispose: () => {
+        state.open = false;
+      },
+      onOpen: (handler) => {
+        queueMicrotask(() => {
+          state.open = true;
+          handler();
+        });
+      },
+      onMessage: (handler) => {
+        state.messageHandler = handler;
+      },
+      onClose: (handler) => {
+        state.closeHandler = handler;
+      },
+      onError: () => {},
+    };
+    return socket;
+  };
+
+  return {
+    factory,
+    sent,
+    connectCount: () => connectCount,
+    drop: () => {
+      const state = current;
+      if (!state) return;
+      state.open = false;
+      state.closeHandler?.(1006, "dropped");
+    },
+    inject: (msg) => current?.messageHandler?.(JSON.stringify(msg), false),
+  };
+}
+
 async function collectEvents(
   events: AsyncIterable<RealtimeEvent>,
   max = 8,
@@ -155,6 +229,82 @@ describe("fromOpenAIRealtime", () => {
     expect(JSON.parse(mock.sent[5]!)).toEqual({ type: "response.create" });
   });
 
+  it("G4/WBS-4: replays resumeHistory as conversation items after session.update, without response.create", async () => {
+    const mock = createMockSocketHarness();
+    const adapter = fromOpenAIRealtime({
+      apiKey: "test-key",
+      socketFactory: mock.factory,
+      url: () => "wss://example.test/realtime?model=gpt-realtime-2",
+      resumeHistory: () => [
+        { role: "user", content: "First question" },
+        { role: "assistant", content: "First answer" },
+      ],
+    });
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => mock.sent.length >= 3);
+    mock.inject({ type: "session.updated" });
+    await openTask;
+
+    expect(JSON.parse(mock.sent[0]!)).toMatchObject({ type: "session.update" });
+    expect(JSON.parse(mock.sent[1]!)).toEqual({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: "First question" }],
+      },
+    });
+    expect(JSON.parse(mock.sent[2]!)).toEqual({
+      type: "conversation.item.create",
+      item: {
+        type: "message",
+        role: "assistant",
+        content: [{ type: "text", text: "First answer" }],
+      },
+    });
+    // Replay must never make the model speak (R6: no double-answer).
+    expect(mock.sent.map((frame) => (JSON.parse(frame) as { type: string }).type)).not.toContain(
+      "response.create",
+    );
+    expect(adapter.caps.supportsNativeResume).toBeUndefined();
+  });
+
+  it("G4/WBS-4: replays the CURRENT resumeHistory again on reconnect (no amnesia error)", async () => {
+    const harness = createReconnectableHarness();
+    const history: Array<{ role: "user" | "assistant"; content: string }> = [
+      { role: "user", content: "Q1" },
+    ];
+    const adapter = fromOpenAIRealtime({
+      apiKey: "test-key",
+      socketFactory: harness.factory,
+      url: () => "wss://example.test/realtime?model=gpt-realtime-2",
+      resumeHistory: () => history,
+    });
+    const events: RealtimeEvent[] = [];
+    void (async () => {
+      for await (const event of adapter.events) events.push(event);
+    })();
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => harness.sent.length >= 2);
+    harness.inject({ type: "session.updated" });
+    await openTask;
+
+    history.push({ role: "assistant", content: "A1" });
+    harness.sent.length = 0;
+    harness.drop();
+    await waitFor(() => harness.connectCount() === 2 && harness.sent.length >= 3);
+
+    const types = harness.sent.map((frame) => (JSON.parse(frame) as { type: string }).type);
+    expect(types[0]).toBe("session.update");
+    expect(types.filter((type) => type === "conversation.item.create")).toHaveLength(2);
+    // With replay wired, the reconnect no longer surfaces the history-lost error.
+    expect(events.some((event) => event.type === "error" && event.cause.message.includes("history was lost"))).toBe(false);
+
+    await adapter.close();
+  });
+
   it("sends a typed user turn as conversation.item.create(input_text) + response.create", async () => {
     const mock = createMockSocketHarness();
     const adapter = fromOpenAIRealtime({
@@ -469,4 +619,57 @@ describe("fromOpenAIRealtime", () => {
       .filter((msg) => msg["type"] === "conversation.item.truncate");
     expect(truncateMessages).toHaveLength(0);
   });
+
+  it("BUG2: re-sends session.update (config + tools) on reconnect and surfaces history loss", async () => {
+    const harness = createReconnectableHarness();
+    const adapter = fromOpenAIRealtime({
+      apiKey: "test-key",
+      socketFactory: harness.factory,
+      url: () => "wss://example.test/realtime?model=gpt-realtime-2",
+      tools: [
+        {
+          name: "consult_knowledge",
+          description: "Answer knowledge questions.",
+          parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+        },
+      ],
+    });
+
+    const errors: RealtimeEvent[] = [];
+    const drainTask = (async () => {
+      for await (const ev of adapter.events) {
+        if (ev.type === "error") errors.push(ev);
+      }
+    })();
+
+    const openTask = adapter.open(new AbortController().signal);
+    await waitFor(() => harness.sent.some((s) => (JSON.parse(s) as { type?: string }).type === "session.update"));
+    harness.inject({ type: "session.updated" });
+    await openTask;
+
+    const countSessionUpdate = (): string[] =>
+      harness.sent.filter((s) => (JSON.parse(s) as { type?: string }).type === "session.update");
+    expect(countSessionUpdate()).toHaveLength(1);
+    expect(harness.connectCount()).toBe(1);
+
+    // Mid-call socket drop → WebSocketConnection auto-reconnects.
+    harness.drop();
+    await waitFor(() => countSessionUpdate().length >= 2);
+    expect(harness.connectCount()).toBeGreaterThanOrEqual(2);
+
+    // The reconnected session got a fresh session.update carrying the tools + config.
+    const secondUpdate = JSON.parse(countSessionUpdate()[1]!) as {
+      session: { tools: Array<{ name: string }> };
+    };
+    expect(secondUpdate.session.tools).toHaveLength(1);
+    expect(secondUpdate.session.tools[0]!.name).toBe("consult_knowledge");
+
+    // History loss is surfaced as a recoverable error, not silence.
+    await waitFor(() =>
+      errors.some((e) => e.type === "error" && e.recoverable && /history/i.test(e.cause.message)),
+    );
+
+    await adapter.close();
+    await drainTask;
+  });
 });

package/src/from-openai-realtime.ts

@@ -4,7 +4,7 @@ import type { SocketFactory } from "@kuralle-syrinx/ws";
 
 import { base64ToBytes, bytesToBase64 } from "./base64.js";
 import { createOpenAiCompatibleRealtimeAdapter } from "./openai-compatible-realtime.js";
-import type { RealtimeAdapter, RealtimeToolDef } from "./realtime-adapter.js";
+import type { RealtimeAdapter, RealtimeResumeMessage, RealtimeToolDef } from "./realtime-adapter.js";
 
 const DEFAULT_MODEL = "gpt-realtime-2";
 const DEFAULT_VOICE = "marin";
@@ -33,6 +33,12 @@ export interface OpenAIRealtimeOptions {
   readonly toolChoice?: string | Record<string, unknown>;
   readonly inputRateHz?: number;
   readonly outputRateHz?: number;
+  /**
+   * G4 resume-by-replay: returns the prior conversation to replay as
+   * `conversation.item.create` items on every (re)connect — OpenAI Realtime has no
+   * native session resume. Replay never triggers a response (no double-answer).
+   */
+  readonly resumeHistory?: () => readonly RealtimeResumeMessage[];
 }
 
 export function fromOpenAIRealtime(opts: OpenAIRealtimeOptions): RealtimeAdapter {
@@ -98,6 +104,7 @@ export function fromOpenAIRealtime(opts: OpenAIRealtimeOptions): RealtimeAdapter
     supportsTruncate: true,
     requiresResponseCreateAfterToolOutput: opts.requiresResponseCreateAfterToolOutput,
     defaultErrorMessage: "OpenAI Realtime error",
+    ...(opts.resumeHistory ? { buildResumeItems: opts.resumeHistory } : {}),
   });
 }
 

package/src/index.ts

@@ -1,6 +1,11 @@
 // SPDX-License-Identifier: MIT
 
-export type { RealtimeAdapter, RealtimeEvent, RealtimeToolDef } from "./realtime-adapter.js";
+export type {
+  RealtimeAdapter,
+  RealtimeEvent,
+  RealtimeResumeMessage,
+  RealtimeToolDef,
+} from "./realtime-adapter.js";
 export { bytesToBase64, base64ToBytes } from "./base64.js";
 export {
   createOpenAiCompatibleRealtimeAdapter,
@@ -14,4 +19,8 @@ export {
   type GeminiTranslateSession,
   type GeminiTranslateSessionOptions,
 } from "./gemini-translate.js";
-export { RealtimeBridge, type RealtimeBridgeOptions } from "./realtime-bridge.js";
+export {
+  RealtimeBridge,
+  type DelegateResultEnvelope,
+  type RealtimeBridgeOptions,
+} from "./realtime-bridge.js";

package/src/openai-compatible-realtime.ts

@@ -5,7 +5,7 @@ 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";
+import type { RealtimeAdapter, RealtimeEvent, RealtimeResumeMessage } from "./realtime-adapter.js";
 
 export interface OpenAiCompatibleRealtimeConfig {
   readonly apiKey: string;
@@ -18,6 +18,15 @@ export interface OpenAiCompatibleRealtimeConfig {
   readonly buildUrl?: (model: string) => string;
   readonly caps: RealtimeAdapter["caps"];
   readonly buildSessionUpdate: () => Record<string, unknown>;
+  /**
+   * G4 resume-by-replay: returns the prior conversation to re-create as
+   * `conversation.item.create` items after each (re)connect's `session.update` —
+   * these providers have no native resume, so the transcript is replayed. Item
+   * creation never triggers a response (no `response.create`), so a resumed
+   * session cannot double-answer (R6). Called on the initial connect AND every
+   * reconnect, so return the *current* durable history, not a snapshot.
+   */
+  readonly buildResumeItems?: () => readonly RealtimeResumeMessage[];
   readonly supportsTruncate: boolean;
   readonly requiresResponseCreateAfterToolOutput?: boolean;
   readonly defaultErrorMessage: string;
@@ -44,6 +53,7 @@ class OpenAiCompatibleRealtimeAdapter implements RealtimeAdapter {
   private assistantTranscript = "";
   private activeResponse = false;
   private pendingResponseCreate = false;
+  private opened = false;
 
   constructor(private readonly config: OpenAiCompatibleRealtimeConfig) {
     this.events = this.stream;
@@ -65,6 +75,12 @@ class OpenAiCompatibleRealtimeAdapter implements RealtimeAdapter {
       },
       socketFactory: this.config.socketFactory,
       onMessage: (json) => this.handleServerMessage(json),
+      // Re-applied on EVERY (re)connection. WebSocketConnection auto-reconnects after a mid-call
+      // drop; without re-sending session.update the fresh provider session comes back with no
+      // tools and default instructions — the front model silently loses its persona and the
+      // delegate tool (delegation permanently dead). onReady fires after the socket is verified
+      // and before replay frames flush, so config lands ahead of any buffered audio.
+      onReady: () => this.applySessionConfig(),
       onConnectionLost: (err) => {
         this.stream.push({ type: "error", cause: err, recoverable: true });
         this.rejectOpen(err);
@@ -86,13 +102,53 @@ class OpenAiCompatibleRealtimeAdapter implements RealtimeAdapter {
     };
     signal.addEventListener("abort", this.abortHandler, { once: true });
 
+    // connect() invokes onReady synchronously once the socket is open, which sends the first
+    // session.update; every subsequent reconnect re-invokes onReady and re-applies it.
     await this.socket.connect();
-    this.socket.send({
+    await openPromise;
+  }
+
+  /**
+   * (Re)configure the provider session — model, audio formats, turn detection, tools,
+   * instructions. Fired on the initial connect and on every reconnect. On a reconnect the provider
+   * session is brand new: config + tools are restored here, but the prior conversation history is
+   * gone, so surface that as a recoverable error rather than silently continuing amnesiac.
+   */
+  private applySessionConfig(): void {
+    const reconnected = this.opened;
+    this.opened = true;
+    this.socket?.send({
       type: "session.update",
       session: this.config.buildSessionUpdate(),
     });
-
-    await openPromise;
+    // G4 resume-by-replay: re-create the prior conversation as items. Providers
+    // without native resume start every (re)connection amnesiac; replaying the
+    // transcript here restores context. No response.create — replay must never
+    // make the model speak (R6).
+    const resumeItems = this.config.buildResumeItems?.() ?? [];
+    for (const message of resumeItems) {
+      this.socket?.send({
+        type: "conversation.item.create",
+        item: {
+          type: "message",
+          role: message.role,
+          content: [
+            message.role === "user"
+              ? { type: "input_text", text: message.content }
+              : { type: "text", text: message.content },
+          ],
+        },
+      });
+    }
+    if (reconnected && !this.config.buildResumeItems) {
+      this.stream.push({
+        type: "error",
+        cause: new Error(
+          "Realtime session reconnected: model config and tools restored, but prior conversation history was lost",
+        ),
+        recoverable: true,
+      });
+    }
   }
 
   sendAudio(pcm16: Uint8Array): void {

package/src/realtime-adapter.ts

@@ -7,6 +7,13 @@ export interface RealtimeAdapter {
     readonly supportsConcurrentToolAudio: boolean;
     readonly supportsTruncate: boolean;
     readonly emitsServerSpeechStarted: boolean;
+    /**
+     * G4: the provider resumes a prior session server-side from a handle (Gemini Live
+     * `sessionResumption`). Absent/false → resuming requires the host to replay the
+     * transcript (e.g. OpenAI `resumeHistory`). A native-resume provider must NOT also
+     * be replayed — that would double-apply history (RFC bimodel-delegate-seam R6).
+     */
+    readonly supportsNativeResume?: boolean;
   };
 
   open(signal: AbortSignal): Promise<void>;
@@ -34,6 +41,12 @@ export interface RealtimeToolDef {
   readonly parameters: Record<string, unknown>;
 }
 
+/** A prior-conversation message replayed into a front model on resume (G4). */
+export interface RealtimeResumeMessage {
+  readonly role: "user" | "assistant";
+  readonly content: string;
+}
+
 export type RealtimeEvent =
   | { type: "audio"; pcm16: Uint8Array; sampleRateHz: number }
   | { type: "speech_started" }
@@ -41,4 +54,7 @@ export type RealtimeEvent =
   | { type: "tool_call"; toolId: string; toolName: string; args: Record<string, unknown> }
   | { type: "response_started" }
   | { type: "response_done" }
+  // G4: a native-resume provider issued a fresh resumption handle — persist the
+  // latest one and pass it back on reconnect (Gemini `sessionResumption`).
+  | { type: "resumption_handle"; handle: string }
   | { type: "error"; cause: Error; recoverable: boolean };

package/src/realtime-bridge.test.ts

@@ -6,8 +6,11 @@ import {
   PipelineBusImpl,
   Route,
   VoiceAgentSession,
+  type DelegateQueryPacket,
+  type DelegateResultPacket,
   type EndOfSpeechPacket,
   type InterruptTtsPacket,
+  type InterruptionDetectedPacket,
   type LlmDeltaPacket,
   type LlmResponseDonePacket,
   type LlmErrorPacket,
@@ -288,9 +291,14 @@ describe("RealtimeBridge", () => {
 
     await waitForCondition(() => adapter.injectedToolResults.length === 1);
 
+    // The bus packet keeps the raw answer; the front model receives the G1 envelope (default).
     expect(toolResults).toHaveLength(1);
     expect(toolResults[0]!.result).toBe(answerText);
-    expect(adapter.injectedToolResults[0]).toEqual({ toolId: "call_delegate_1", text: answerText });
+    expect(adapter.injectedToolResults[0]!.toolId).toBe("call_delegate_1");
+    expect(JSON.parse(adapter.injectedToolResults[0]!.text)).toEqual({
+      response_text: answerText,
+      require_repeat_verbatim: true,
+    });
 
     await bridge.close();
     bus.stop();
@@ -321,7 +329,203 @@ describe("RealtimeBridge", () => {
     });
 
     await waitForCondition(() => adapter.injectedToolResults.length === 1);
-    expect(adapter.injectedToolResults[0]!.text).toBe("Partial ");
+    expect(JSON.parse(adapter.injectedToolResults[0]!.text)).toMatchObject({ response_text: "Partial " });
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("G1/WBS-2: envelope carries the render directive when configured", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "finish", reason: "stop", text: "The fee is 5000 rupees." };
+      })(),
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner, "consult_knowledge", {
+      renderDirective: "translate_faithfully",
+    });
+    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_env_1",
+      toolName: "consult_knowledge",
+      args: { query: "fees" },
+    });
+
+    await waitForCondition(() => adapter.injectedToolResults.length === 1);
+    expect(JSON.parse(adapter.injectedToolResults[0]!.text)).toEqual({
+      response_text: "The fee is 5000 rupees.",
+      require_repeat_verbatim: true,
+      render: "translate_faithfully",
+    });
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it('G1/WBS-2: toolResultFormat "string" opts out to the raw answer (pre-RFC behavior)', async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "finish", reason: "stop", text: "raw answer" };
+      })(),
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner, "consult_knowledge", {
+      toolResultFormat: "string",
+    });
+    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_env_2",
+      toolName: "consult_knowledge",
+      args: { query: "q" },
+    });
+
+    await waitForCondition(() => adapter.injectedToolResults.length === 1);
+    expect(adapter.injectedToolResults[0]!.text).toBe("raw answer");
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("G2/WBS-1: delegate turn emits delegate.query then delegate.result on the Background route", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "tool-call", toolId: "rag-1", toolName: "retrieve", args: { q: "deadline" } };
+        yield { type: "tool-result", toolId: "rag-1", toolName: "retrieve", result: "chunk" };
+        yield { type: "text-delta", text: "The deadline is March 31." };
+        yield { type: "finish", reason: "stop", text: "The deadline is March 31." };
+      })(),
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner);
+    const background: Array<{ route: Route; packet: VoicePacket }> = [];
+    const bus = new PipelineBusImpl({
+      onPacket: (route, packet) => {
+        if (packet.kind.startsWith("delegate.")) background.push({ route, packet });
+      },
+    });
+    buses.push(bus);
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({
+      type: "tool_call",
+      toolId: "call_obs_1",
+      toolName: "consult_knowledge",
+      args: { query: "When is the exam registration deadline?" },
+    });
+
+    await waitForCondition(() => adapter.injectedToolResults.length === 1);
+    await waitForCondition(() => background.length === 2);
+
+    expect(background.map((entry) => entry.route)).toEqual([Route.Background, Route.Background]);
+    const [query, result] = background.map((entry) => entry.packet);
+    expect(query).toMatchObject({
+      kind: "delegate.query",
+      query: "When is the exam registration deadline?",
+      toolId: "call_obs_1",
+      toolName: "consult_knowledge",
+    });
+    expect(query!.contextId).toBeTruthy();
+    expect(result).toMatchObject({
+      kind: "delegate.result",
+      query: "When is the exam registration deadline?",
+      answer: "The deadline is March 31.",
+      grounded: true,
+      toolId: "call_obs_1",
+      toolName: "consult_knowledge",
+      contextId: query!.contextId,
+    });
+    expect((result as DelegateResultPacket).durationMs).toBeGreaterThanOrEqual(0);
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("G2/WBS-1: delegate.result grounded=false when the reasoner used no tool", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "text-delta", text: "From memory." };
+        yield { type: "finish", reason: "stop", text: "From memory." };
+      })(),
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner);
+    const results: DelegateResultPacket[] = [];
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    bus.on("delegate.result", (pkt) => { results.push(pkt as DelegateResultPacket); });
+
+    const started = bus.start();
+    await bridge.initialize(bus, {});
+
+    adapter.emit({ type: "response_started" });
+    adapter.emit({
+      type: "tool_call",
+      toolId: "call_obs_2",
+      toolName: "consult_knowledge",
+      args: { query: "ungrounded" },
+    });
+
+    await waitForCondition(() => results.length === 1);
+    expect(results[0]!.grounded).toBe(false);
+
+    await bridge.close();
+    bus.stop();
+    await started;
+  });
+
+  it("G2/WBS-1: failed delegate emits delegate.query but no delegate.result", async () => {
+    const adapter = new FakeRealtimeAdapter();
+    const reasoner: Reasoner = {
+      stream: () => (async function* () {
+        yield { type: "error", cause: new Error("brain down"), recoverable: false };
+      })(),
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner);
+    const queries: DelegateQueryPacket[] = [];
+    const results: DelegateResultPacket[] = [];
+    const errors: LlmErrorPacket[] = [];
+    const bus = new PipelineBusImpl();
+    buses.push(bus);
+    bus.on("delegate.query", (pkt) => { queries.push(pkt as DelegateQueryPacket); });
+    bus.on("delegate.result", (pkt) => { results.push(pkt as DelegateResultPacket); });
+    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_obs_3",
+      toolName: "consult_knowledge",
+      args: { query: "will fail" },
+    });
+
+    await waitForCondition(() => errors.length === 1);
+    expect(queries).toHaveLength(1);
+    expect(results).toHaveLength(0);
 
     await bridge.close();
     bus.stop();
@@ -879,4 +1083,65 @@ describe("RealtimeBridge", () => {
 
     await session.close();
   });
+
+  it("BUG1: a barge-in DURING the reasoner gap drains speech_started, fires interrupt.detected, and aborts the delegate before it completes", async () => {
+    // The barge-in is delivered on the adapter EVENT STREAM (not a direct interrupt.tts bus
+    // push). With the old serial pump, awaiting the delegate froze the pump for the whole
+    // reasoner gap, so this speech_started stayed queued and never became interrupt.detected —
+    // the unwanted answer was then voiced over the user. The delegate must run off the pump.
+    const adapter = new FakeRealtimeAdapter();
+    let delegateSignal: AbortSignal | undefined;
+    let reasonerCompleted = false;
+    const reasoner: Reasoner = {
+      stream: ({ signal }) => {
+        delegateSignal = signal;
+        return (async function* () {
+          // The ~1.5–3s reasoner "thinking gap", exaggerated: the barge-in must abort it, not
+          // wait it out.
+          await new Promise((resolve) => setTimeout(resolve, 60_000));
+          reasonerCompleted = true;
+          yield { type: "finish", reason: "stop", text: "unwanted late answer" };
+        })();
+      },
+    };
+    const bridge = new RealtimeBridge(adapter, reasoner);
+    const session = new VoiceAgentSession({
+      plugins: { realtime: {} },
+      endpointingOwner: "timer",
+      minInterruptionMs: 0,
+    });
+    session.registerPlugin("realtime", bridge);
+
+    const interruptDetected: InterruptionDetectedPacket[] = [];
+    const turnChanges: TurnChangePacket[] = [];
+    session.bus.on("interrupt.detected", (pkt) => { interruptDetected.push(pkt as InterruptionDetectedPacket); });
+    session.bus.on("turn.change", (pkt) => { turnChanges.push(pkt as TurnChangePacket); });
+
+    await session.start();
+
+    // Turn A: front model responds, emits audio, then calls the delegate tool.
+    adapter.emit({ type: "response_started" });
+    await waitForCondition(() => turnChanges.length >= 1);
+    adapter.emit({ type: "audio", pcm16: frameSizedPcm24k(), sampleRateHz: 24_000 });
+    adapter.emit({
+      type: "tool_call",
+      toolId: "call_gap_delegate",
+      toolName: "consult_knowledge",
+      args: { query: "late add policy" },
+    });
+
+    // Delegate is now in flight (reasoner sleeping) — signal wired, not yet aborted.
+    await waitForCondition(() => delegateSignal !== undefined);
+    expect(delegateSignal!.aborted).toBe(false);
+
+    // User barges in mid-gap, on the adapter event stream.
+    adapter.emit({ type: "speech_started" });
+
+    // The pump kept draining: speech_started → interrupt.detected → session → interrupt.tts → abort.
+    await waitForCondition(() => interruptDetected.length >= 1);
+    await waitForCondition(() => delegateSignal!.aborted);
+    expect(reasonerCompleted).toBe(false);
+
+    await session.close();
+  });
 });

package/src/realtime-bridge.ts

@@ -3,6 +3,8 @@
 import {
   Route,
   categorizeLlmError,
+  type DelegateQueryPacket,
+  type DelegateResultPacket,
   type EndOfSpeechPacket,
   type InterruptTtsPacket,
   type InterruptionDetectedPacket,
@@ -13,6 +15,7 @@ import {
   type LlmToolResultPacket,
   type PipelineBus,
   type PluginConfig,
+  type RealtimeResumptionHandlePacket,
   type Reasoner,
   type ReasonerMessage,
   type UserAudioReceivedPacket,
@@ -32,8 +35,39 @@ const ENGINE_SAMPLE_RATE_HZ = 16_000;
 const FRAME_SAMPLES_20MS = 320;
 const FRAME_BYTES_20MS = FRAME_SAMPLES_20MS * 2;
 
+/**
+ * G1 — the structured delegate-result envelope (RFC bimodel-delegate-seam §4).
+ * The bridge wraps the accumulated reasoner answer in this JSON shape before
+ * `injectToolResult`, so the front model treats it as authoritative tool data
+ * and repeats it faithfully instead of paraphrasing or inventing facts. Field
+ * names mirror OpenAI's Realtime Prompting Guide "Tool Output Formatting"
+ * (`response_text` + `require_repeat_verbatim`) — the only field-validated
+ * envelope shape, and gpt-realtime is the primary front (OQ1).
+ */
+export interface DelegateResultEnvelope {
+  /** The authoritative answer — the front model's ONLY source of facts for the turn. */
+  readonly response_text: string;
+  readonly require_repeat_verbatim: true;
+  /** Optional app directive the front prompt keys on, e.g. "translate_faithfully". */
+  readonly render?: string;
+}
+
 export interface RealtimeBridgeOptions {
   readonly debug?: boolean;
+  /**
+   * How the delegate answer reaches the front model at `injectToolResult` time.
+   * `"envelope"` (default) wraps it as a {@link DelegateResultEnvelope}; `"string"`
+   * injects the raw answer (pre-envelope behavior). The envelope is applied to the
+   * already-buffered delegate answer — a synchronous JSON.stringify, no added latency
+   * (R2) — and never touches the cascade text-delta path. Bus packets
+   * (`llm.tool_result`, `delegate.result`) always carry the raw answer.
+   */
+  readonly toolResultFormat?: "envelope" | "string";
+  /**
+   * Optional `render` directive included in the envelope (e.g. `"translate_faithfully"`),
+   * for front prompts that key a rendering rule on it. Ignored with `toolResultFormat: "string"`.
+   */
+  readonly renderDirective?: string;
   /**
    * Supplies prior conversation context for delegate Reasoner turns. When omitted the delegate is
    * stateless — each tool call receives only the query extracted from the front-model tool args.
@@ -67,6 +101,7 @@ export class RealtimeBridge implements VoicePlugin {
   private turnAssistantDeltas = "";
   private sessionAbort: AbortController | null = null;
   private inflight: AbortController | undefined;
+  private delegateTask: Promise<void> | null = null;
   private playedMs = 0;
   private audioRemainder: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
   private readonly disposers: Array<() => void> = [];
@@ -109,6 +144,7 @@ export class RealtimeBridge implements VoicePlugin {
 
   async close(): Promise<void> {
     this.sessionAbort?.abort();
+    this.inflight?.abort();
     for (const dispose of this.disposers.splice(0)) dispose();
     await this.adapter.close();
     this.bus = null;
@@ -163,6 +199,18 @@ export class RealtimeBridge implements VoicePlugin {
       case "speech_started":
         this.onSpeechStarted(bus);
         break;
+      case "resumption_handle": {
+        // G4: persist-worthy native-resume handle (Gemini). Background route —
+        // a durable host stores the latest and passes it back on reconnect.
+        const packet: RealtimeResumptionHandlePacket = {
+          kind: "realtime.resumption_handle",
+          contextId: this.contextId,
+          timestampMs: Date.now(),
+          handle: ev.handle,
+        };
+        bus.push(Route.Background, packet);
+        break;
+      }
       case "error":
         this.onError(bus, ev.cause, ev.recoverable);
         break;
@@ -176,7 +224,7 @@ export class RealtimeBridge implements VoicePlugin {
     ev: { toolId: string; toolName: string; args: Record<string, unknown> },
   ): Promise<void> {
     if (ev.toolName === this.delegateToolName) {
-      if (this.reasoner) await this.runDelegate(bus, ev);
+      if (this.reasoner) this.dispatchDelegate(bus, ev);
       return;
     }
     if (this.opts.onFrontToolCall) {
@@ -207,15 +255,38 @@ export class RealtimeBridge implements VoicePlugin {
     this.adapter.injectToolResult(ev.toolId, result);
   }
 
+  /**
+   * Start the reasoner delegate OFF the serial event pump. The pump must keep draining adapter
+   * events during the multi-second reasoner "thinking gap" — above all `speech_started`, so a
+   * barge-in mid-delegate still fires `interrupt.detected` and (via `interrupt.tts`) aborts the
+   * now-unwanted delegate before its answer is voiced over the user. Awaiting the delegate inside
+   * the pump loop (the old shape) froze barge-in for the entire gap. `runDelegate` sets
+   * `this.inflight` synchronously before its first await, so a subsequently-pumped barge-in sees
+   * a live controller to abort.
+   */
+  private dispatchDelegate(
+    bus: PipelineBus,
+    ev: { toolId: string; toolName: string; args: Record<string, unknown> },
+  ): void {
+    this.delegateTask = this.runDelegate(bus, ev).catch((err) => {
+      if (!this.bus || isAbortError(err)) return;
+      this.onError(bus, err instanceof Error ? err : new Error(String(err)), false);
+    });
+  }
+
   private async runDelegate(
     bus: PipelineBus,
     ev: { toolId: string; toolName: string; args: Record<string, unknown> },
   ): Promise<void> {
-    if (!this.contextId) return;
+    // Pin the turn's contextId now: the pump keeps advancing while the delegate streams, so
+    // this.contextId may move to a later turn before we finish. The tool_call/tool_result pair
+    // must stay bound to the turn that issued the call (R1: never merge parts across turns).
+    const contextId = this.contextId;
+    if (!contextId) return;
 
     const toolCall: LlmToolCallPacket = {
       kind: "llm.tool_call",
-      contextId: this.contextId,
+      contextId,
       timestampMs: Date.now(),
       toolId: ev.toolId,
       toolName: ev.toolName,
@@ -235,8 +306,22 @@ export class RealtimeBridge implements VoicePlugin {
       return;
     }
 
-    this.inflight = new AbortController();
+    const controller = new AbortController();
+    this.inflight = controller;
     let answer = "";
+    let grounded = false;
+
+    // G2 observability: the query is on its way to the reasoner (Background route, R4).
+    const queryStartedMs = Date.now();
+    const delegateQuery: DelegateQueryPacket = {
+      kind: "delegate.query",
+      contextId,
+      timestampMs: queryStartedMs,
+      query: userText,
+      toolId: ev.toolId,
+      toolName: ev.toolName,
+    };
+    bus.push(Route.Background, delegateQuery);
 
     try {
       const messages = this.opts.contextProvider?.() ?? [];
@@ -244,13 +329,14 @@ export class RealtimeBridge implements VoicePlugin {
         userText,
         toolArgs: ev.args,
         messages,
-        signal: this.inflight.signal,
+        signal: controller.signal,
       })) {
         switch (part.type) {
           case "text-delta":
             answer += part.text;
             break;
           case "tool-result":
+            grounded = true;
             break;
           case "finish":
             if (!answer && part.text) answer = part.text;
@@ -274,7 +360,8 @@ export class RealtimeBridge implements VoicePlugin {
       this.onError(bus, err instanceof Error ? err : new Error(String(err)), false);
       return;
     } finally {
-      this.inflight = undefined;
+      // Only clear if still ours — a newer delegate may have replaced this.inflight.
+      if (this.inflight === controller) this.inflight = undefined;
     }
 
     if (answer.length === 0) {
@@ -282,16 +369,41 @@ export class RealtimeBridge implements VoicePlugin {
       return;
     }
 
+    const answeredMs = Date.now();
     const toolResult: LlmToolResultPacket = {
       kind: "llm.tool_result",
-      contextId: this.contextId,
-      timestampMs: Date.now(),
+      contextId,
+      timestampMs: answeredMs,
       toolId: ev.toolId,
       toolName: ev.toolName,
       result: answer,
     };
     bus.push(Route.Main, toolResult);
-    this.adapter.injectToolResult(ev.toolId, answer);
+    // G2 observability: the reasoner produced the final answer (Background route, R4).
+    const delegateResult: DelegateResultPacket = {
+      kind: "delegate.result",
+      contextId,
+      timestampMs: answeredMs,
+      query: userText,
+      answer,
+      durationMs: answeredMs - queryStartedMs,
+      grounded,
+      toolId: ev.toolId,
+      toolName: ev.toolName,
+    };
+    bus.push(Route.Background, delegateResult);
+    this.adapter.injectToolResult(ev.toolId, this.formatToolResult(answer));
+  }
+
+  /** G1: wrap the buffered delegate answer for the front model (synchronous — R2). */
+  private formatToolResult(answer: string): string {
+    if (this.opts.toolResultFormat === "string") return answer;
+    const envelope: DelegateResultEnvelope = {
+      response_text: answer,
+      require_repeat_verbatim: true,
+      ...(this.opts.renderDirective ? { render: this.opts.renderDirective } : {}),
+    };
+    return JSON.stringify(envelope);
   }
 
   private onSpeechStarted(bus: PipelineBus): void {