@kuralle-syrinx/cf-agents 3.1.0 → 4.1.0

package/src/with-voice.test.ts

@@ -9,8 +9,59 @@ import { describe, it, expect, vi } from "vitest";
 import type { PipelineBus, Reasoner, UserAudioReceivedPacket, VoicePlugin } from "@kuralle-syrinx/core";
 import { encodePcm16ToMuLaw } from "@kuralle-syrinx/core/audio";
 import type { RealtimeAdapter, RealtimeEvent } from "@kuralle-syrinx/realtime";
-import { withVoice, type ToolCallStartContext } from "./with-voice.js";
-import type { VoicePipeline } from "./build-session.js";
+import {
+  withVoice,
+  type DelegateQueryContext,
+  type DelegateResultContext,
+  type ToolCallStartContext,
+} from "./with-voice.js";
+import type { VoicePipeline, VoicePipelineContext } from "./build-session.js";
+
+/**
+ * In-memory emulation of the DO-SQLite statements SqliteReasonerSessionStore issues,
+ * shared across agent instances to simulate one Durable Object across evictions.
+ */
+function sqliteFake() {
+  const history = new Map<string, Array<{ seq: number; role: string; content: string; tool_call_id: string | null }>>();
+  const handles = new Map<string, string>();
+  const sql = (strings: TemplateStringsArray, ...values: unknown[]): unknown[] => {
+    const query = strings.join("?").replace(/\s+/g, " ").trim();
+    if (query.startsWith("CREATE TABLE")) return [];
+    if (query.includes("SELECT role, content, tool_call_id FROM syrinx_reasoner_history")) {
+      return [...(history.get(String(values[0])) ?? [])].sort((a, b) => a.seq - b.seq);
+    }
+    if (query.includes("DELETE FROM syrinx_reasoner_history")) {
+      history.delete(String(values[0]));
+      return [];
+    }
+    if (query.includes("INSERT INTO syrinx_reasoner_history")) {
+      const [sid, seq, role, content, toolCallId] = values;
+      const rows = history.get(String(sid)) ?? [];
+      rows.push({
+        seq: Number(seq),
+        role: String(role),
+        content: String(content),
+        tool_call_id: toolCallId === null ? null : String(toolCallId),
+      });
+      history.set(String(sid), rows);
+      return [];
+    }
+    if (query.includes("SELECT handle FROM syrinx_resume_handle")) {
+      const handle = handles.get(String(values[0]));
+      return handle ? [{ handle }] : [];
+    }
+    if (query.includes("DELETE FROM syrinx_resume_handle")) {
+      handles.delete(String(values[0]));
+      return [];
+    }
+    if (query.includes("INSERT INTO syrinx_resume_handle")) {
+      handles.set(String(values[0]), String(values[1]));
+      return [];
+    }
+    return [];
+  };
+  return { sql, history, handles };
+}
 
 /** Controllable fake realtime front — `emit()` pushes provider events into the bridge. */
 class FakeFront implements RealtimeAdapter {
@@ -37,7 +88,10 @@ class FakeFront implements RealtimeAdapter {
   async open(): Promise<void> {}
   sendAudio(): void {}
   cancelResponse(): void {}
-  injectToolResult(): void {}
+  readonly injected: Array<{ toolId: string; text: string }> = [];
+  injectToolResult(toolId: string, text: string): void {
+    this.injected.push({ toolId, text });
+  }
   async close(): Promise<void> {
     this.#closed = true;
     for (const w of this.#waiters.splice(0)) w(null);
@@ -75,8 +129,9 @@ class FakeAgentBase {
     return [];
   }
 
-  // Tagged-template stand-in; unused by the voice path.
-  sql(): unknown[] {
+  // Tagged-template stand-in; the durable-history path issues real statements
+  // against it (subclasses can back it with an in-memory emulation).
+  sql(_strings?: TemplateStringsArray, ..._values: unknown[]): unknown[] {
     return [];
   }
 
@@ -335,6 +390,119 @@ describe("withVoice(Agent)", () => {
     expect(calls[0]!.connection).toBe(conn);
   });
 
+  it("G2/WBS-1: fires onDelegateQuery/onDelegateResult around the reasoner run (SLIIT log-wrapper replacement)", async () => {
+    const front = new FakeFront();
+    const answeringReasoner = (): Reasoner => ({
+      stream: async function* () {
+        yield { type: "text-delta", text: "March 31." } as const;
+        yield { type: "finish", reason: "stop", text: "March 31." } as const;
+      },
+    });
+    const queries: DelegateQueryContext[] = [];
+    const results: DelegateResultContext[] = [];
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      {
+        pipeline: { kind: "realtime", front: () => front, delegateToolName: "consult_knowledge" },
+        reasoner: () => answeringReasoner(),
+        onDelegateQuery: (c) => { queries.push(c); },
+        onDelegateResult: (c) => { results.push(c); },
+      },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true));
+
+    front.emit({ type: "response_started" });
+    front.emit({ type: "tool_call", toolId: "t1", toolName: "consult_knowledge", args: { query: "exam deadline" } });
+
+    await vi.waitFor(() => expect(results.length).toBeGreaterThan(0));
+    expect(queries[0]).toMatchObject({
+      query: "exam deadline",
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      sessionId: "test-session",
+    });
+    expect(queries[0]!.connection).toBe(conn);
+    expect(results[0]).toMatchObject({
+      query: "exam deadline",
+      answer: "March 31.",
+      grounded: false,
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      sessionId: "test-session",
+    });
+    expect(results[0]!.durationMs).toBeGreaterThanOrEqual(0);
+    expect(results[0]!.connection).toBe(conn);
+  });
+
+  it("G2/WBS-1: throwing onDelegateQuery/onDelegateResult never break the call", async () => {
+    const front = new FakeFront();
+    const answered: string[] = [];
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      {
+        pipeline: { kind: "realtime", front: () => front, delegateToolName: "consult_knowledge" },
+        reasoner: () => ({
+          stream: async function* () {
+            yield { type: "finish", reason: "stop", text: "ok" } as const;
+          },
+        }),
+        onDelegateQuery: () => { throw new Error("query hook blew up"); },
+        onDelegateResult: (c) => { answered.push(c.answer); throw new Error("result hook blew up"); },
+      },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true));
+
+    front.emit({ type: "response_started" });
+    front.emit({ type: "tool_call", toolId: "t1", toolName: "consult_knowledge", args: { query: "x" } });
+
+    await vi.waitFor(() => expect(answered.length).toBeGreaterThan(0));
+    // The connection stays usable after both hooks threw.
+    expect(() => agent.onMessage(conn, JSON.stringify({ type: "ping" }))).not.toThrow();
+  });
+
+  it("G1/WBS-2: realtime pipeline wraps the delegate answer in the envelope (default) with the configured render directive", async () => {
+    const front = new FakeFront();
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      {
+        pipeline: {
+          kind: "realtime",
+          front: () => front,
+          delegateToolName: "consult_knowledge",
+          renderDirective: "translate_faithfully",
+        },
+        reasoner: () => ({
+          stream: async function* () {
+            yield { type: "finish", reason: "stop", text: "The fee is 5000 rupees." } as const;
+          },
+        }),
+      },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true));
+
+    front.emit({ type: "response_started" });
+    front.emit({ type: "tool_call", toolId: "t1", toolName: "consult_knowledge", args: { query: "fees" } });
+
+    await vi.waitFor(() => expect(front.injected.length).toBeGreaterThan(0));
+    expect(JSON.parse(front.injected[0]!.text)).toEqual({
+      response_text: "The fee is 5000 rupees.",
+      require_repeat_verbatim: true,
+      render: "translate_faithfully",
+    });
+  });
+
   it("a throwing onToolCallStart never breaks the call", async () => {
     const front = new FakeFront();
     const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
@@ -360,6 +528,159 @@ describe("withVoice(Agent)", () => {
     expect(() => agent.onMessage(conn, JSON.stringify({ type: "ping" }))).not.toThrow();
   });
 
+  it("G4/WBS-4: realtime transcript survives a simulated eviction — the next instance resumes with prior context", async () => {
+    const db = sqliteFake();
+    class DurableBase extends FakeAgentBase {
+      override sql(strings?: TemplateStringsArray, ...values: unknown[]): unknown[] {
+        return db.sql(strings!, ...values);
+      }
+    }
+    const fronts: FakeFront[] = [];
+    const seenResume: Array<VoicePipelineContext["resume"]> = [];
+    const capturedMessages: Array<readonly unknown[]> = [];
+    const makeAgentClass = () =>
+      withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(asBase(DurableBase), {
+        pipeline: {
+          kind: "realtime",
+          front: (_env: unknown, pipelineCtx: VoicePipelineContext) => {
+            seenResume.push(pipelineCtx.resume);
+            const front = new FakeFront();
+            fronts.push(front);
+            return front;
+          },
+        },
+        reasoner: () => ({
+          stream: (turn) => {
+            capturedMessages.push([...turn.messages]);
+            return (async function* () {
+              yield { type: "finish", reason: "stop", text: "ok" } as const;
+            })();
+          },
+        }),
+      });
+
+    // First lifetime: one spoken exchange lands in the durable transcript.
+    const FirstAgent = makeAgentClass();
+    const first = new FirstAgent({});
+    const firstConn = fakeConnection("c1");
+    first.onConnect(firstConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(firstConn).some((f) => f["type"] === "ready")).toBe(true));
+    fronts[0]!.emit({ type: "response_started" });
+    fronts[0]!.emit({ type: "transcript", role: "user", text: "What are the fees?", final: true });
+    fronts[0]!.emit({ type: "transcript", role: "assistant", text: "Fees are 5000 rupees.", final: true });
+    fronts[0]!.emit({ type: "response_done" });
+    await vi.waitFor(() => expect(db.history.get("test-session")?.length).toBe(2));
+    first.onClose(firstConn, 1000, "evicted", true);
+
+    // Second lifetime (fresh class + instance = evicted DO, same SQLite).
+    const SecondAgent = makeAgentClass();
+    const second = new SecondAgent({});
+    const secondConn = fakeConnection("c2");
+    second.onConnect(secondConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(secondConn).some((f) => f["type"] === "ready")).toBe(true));
+
+    // The front factory sees the prior transcript via ctx.resume.
+    expect(seenResume[1]?.history()).toEqual([
+      { role: "user", content: "What are the fees?" },
+      { role: "assistant", content: "Fees are 5000 rupees." },
+    ]);
+
+    // A delegate turn hands the reasoner the same prior context (re-seeded, R6).
+    fronts[1]!.emit({ type: "response_started" });
+    fronts[1]!.emit({ type: "tool_call", toolId: "t1", toolName: "consult_knowledge", args: { query: "deadlines?" } });
+    await vi.waitFor(() => expect(capturedMessages.length).toBeGreaterThan(0));
+    expect(capturedMessages[0]).toEqual([
+      { role: "user", content: "What are the fees?" },
+      { role: "assistant", content: "Fees are 5000 rupees." },
+    ]);
+  });
+
+  it("G4/WBS-4: persists the latest native resume handle and exposes it on the next instance (Gemini passthrough, no replay)", async () => {
+    const db = sqliteFake();
+    class DurableBase extends FakeAgentBase {
+      override sql(strings?: TemplateStringsArray, ...values: unknown[]): unknown[] {
+        return db.sql(strings!, ...values);
+      }
+    }
+    const fronts: FakeFront[] = [];
+    const seenResume: Array<VoicePipelineContext["resume"]> = [];
+    const makeAgentClass = () =>
+      withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(asBase(DurableBase), {
+        pipeline: {
+          kind: "realtime",
+          front: (_env: unknown, pipelineCtx: VoicePipelineContext) => {
+            seenResume.push(pipelineCtx.resume);
+            const front = new FakeFront();
+            fronts.push(front);
+            return front;
+          },
+        },
+        reasoner: () => stubReasoner(),
+      });
+
+    const FirstAgent = makeAgentClass();
+    const first = new FirstAgent({});
+    const firstConn = fakeConnection("c1");
+    first.onConnect(firstConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(firstConn).some((f) => f["type"] === "ready")).toBe(true));
+    expect(seenResume[0]?.providerHandle).toBeUndefined();
+    fronts[0]!.emit({ type: "resumption_handle", handle: "handle-1" });
+    fronts[0]!.emit({ type: "resumption_handle", handle: "handle-2" });
+    await vi.waitFor(() => expect(db.handles.get("test-session")).toBe("handle-2"));
+    first.onClose(firstConn, 1000, "evicted", true);
+
+    const SecondAgent = makeAgentClass();
+    const second = new SecondAgent({});
+    const secondConn = fakeConnection("c2");
+    second.onConnect(secondConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(secondConn).some((f) => f["type"] === "ready")).toBe(true));
+    expect(seenResume[1]?.providerHandle).toBe("handle-2");
+  });
+
+  it("G4/WBS-4: cascaded pipeline re-seeds the ReasoningBridge from durable history after eviction", async () => {
+    const db = sqliteFake();
+    class DurableBase extends FakeAgentBase {
+      override sql(strings?: TemplateStringsArray, ...values: unknown[]): unknown[] {
+        return db.sql(strings!, ...values);
+      }
+    }
+    const capturedMessages: Array<readonly unknown[]> = [];
+    const makeAgentClass = (reply: string) =>
+      withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(asBase(DurableBase), {
+        pipeline: cascadedPipeline(),
+        reasoner: () => ({
+          stream: (turn) => {
+            capturedMessages.push([...turn.messages]);
+            return (async function* () {
+              yield { type: "text-delta", text: reply } as const;
+              yield { type: "finish", reason: "stop", text: reply } as const;
+            })();
+          },
+        }),
+      });
+
+    const FirstAgent = makeAgentClass("Answer one.");
+    const first = new FirstAgent({});
+    const firstConn = fakeConnection("c1");
+    first.onConnect(firstConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(firstConn).some((f) => f["type"] === "ready")).toBe(true));
+    first.onMessage(firstConn, JSON.stringify({ type: "text", text: "First question", contextId: "turn-1" }));
+    await vi.waitFor(() => expect(db.history.get("test-session")?.length).toBe(2));
+    first.onClose(firstConn, 1000, "evicted", true);
+
+    const SecondAgent = makeAgentClass("Answer two.");
+    const second = new SecondAgent({});
+    const secondConn = fakeConnection("c2");
+    second.onConnect(secondConn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(secondConn).some((f) => f["type"] === "ready")).toBe(true));
+    second.onMessage(secondConn, JSON.stringify({ type: "text", text: "Second question", contextId: "turn-2" }));
+    await vi.waitFor(() => expect(capturedMessages.length).toBe(2));
+    expect(capturedMessages[1]).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "Answer one." },
+    ]);
+  });
+
   it("forceEndVoice closes the connection", () => {
     const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
       asBase(FakeAgentBase),

package/src/with-voice.ts

@@ -19,11 +19,12 @@
 import type { Agent, Connection, ConnectionContext, WSMessage } from "agents";
 import {
   runVoiceEdgeWebSocketConnection,
+  type BackgroundAudioConfig,
   type EdgeRecorder,
 } from "@kuralle-syrinx/server-websocket/edge";
 import { runTwilioEdgeWebSocketConnection } from "@kuralle-syrinx/server-websocket/edge-twilio";
 import { InMemorySessionStore } from "@kuralle-syrinx/server-websocket/session-store";
-import type { Reasoner } from "@kuralle-syrinx/core";
+import type { Reasoner, ReasonerMessage } from "@kuralle-syrinx/core";
 import { fromKuralleRuntime, type KuralleRuntimeLike } from "@kuralle-syrinx/kuralle";
 import {
   connectionManagedSocket,
@@ -34,11 +35,16 @@ import {
   buildVoiceSession,
   type VoicePipeline,
   type VoicePipelineContext,
+  type VoiceSessionWiring,
 } from "./build-session.js";
+import { SqliteReasonerSessionStore, type SqlTag } from "./durable-history.js";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mixin constructors require `any[]` rest params (TS2545)
 type Constructor<T = object> = new (...args: any[]) => T;
 
+/** Bound on the durable realtime transcript (12 turns), mirroring ReasoningBridge's default window. */
+const MAX_DURABLE_HISTORY_MESSAGES = 24;
+
 /** The Agent surface the voice mixin relies on. (`env`/`name`/`runtime` are read via VoiceHostSurface.) */
 type AgentLike = Constructor<
   Pick<Agent<Record<string, unknown>>, "sql" | "getConnections" | "keepAlive">
@@ -59,6 +65,41 @@ export interface ToolCallStartContext {
   readonly connection: VoiceConnection;
 }
 
+/**
+ * Delegate (Responder-Thinker) observability — fired when the bridge hands a query to
+ * the Reasoner (G2, RFC bimodel-delegate-seam). Replaces the consumer-side pattern of
+ * wrapping the Reasoner just to log the query. `toolId`/`toolName` are present on
+ * realtime delegate turns, absent on cascade turns.
+ */
+export interface DelegateQueryContext<Env = unknown> {
+  readonly query: string;
+  readonly toolId?: string;
+  readonly toolName?: string;
+  readonly turnId: string;
+  readonly sessionId: string;
+  readonly connection: VoiceConnection;
+  /** The Worker env — bindings for logging/persistence (e.g. an R2 bucket). */
+  readonly env: Env;
+}
+
+/**
+ * Fired when the Reasoner produced the turn's final answer. Self-contained (carries the
+ * query again) so a consumer can log/persist the grounded Q&A pair from this one hook.
+ */
+export interface DelegateResultContext<Env = unknown> {
+  readonly query: string;
+  readonly answer: string;
+  readonly durationMs: number;
+  readonly grounded: boolean;
+  readonly toolId?: string;
+  readonly toolName?: string;
+  readonly turnId: string;
+  readonly sessionId: string;
+  readonly connection: VoiceConnection;
+  /** The Worker env — bindings for logging/persistence (e.g. an R2 bucket). */
+  readonly env: Env;
+}
+
 export interface WithVoiceOptions<Env> {
   /**
    * The connection wire protocol this host speaks. `"edge"` (default) is the Syrinx
@@ -78,12 +119,45 @@ export interface WithVoiceOptions<Env> {
   readonly reasoner?: (env: Env, ctx: VoicePipelineContext) => Reasoner | Promise<Reasoner>;
   /** Optional per-call recorder (e.g. an R2-backed `EdgeRecorder`). Applies to the `"edge"` transport. */
   readonly recorder?: (env: Env, ctx: VoicePipelineContext) => EdgeRecorder | undefined;
+  /**
+   * Ambient/thinking bed mixed (ducked) under assistant speech on both transports.
+   * On the `"twilio"` transport the bed also fills the gaps between turns as
+   * comfort noise — pure digital silence on a phone line reads as "the call died".
+   * The thinking loop follows the G3 tool-call cues. Sources are raw mono PCM16
+   * (e.g. `ffmpeg -i office.mp3 -ac 1 -ar 16000 -f s16le office.pcm`).
+   */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   /**
    * Fired when the front model starts a delegate tool call, before the reasoner runs — the seam
    * for a deterministic latency-masking preamble / "thinking" earcon. Throwing here never affects
    * the call. See {@link ToolCallStartContext}.
    */
   readonly onToolCallStart?: (ctx: ToolCallStartContext) => void | Promise<void>;
+  /**
+   * Delegate observability (G2): fired when the bridge hands a query to the Reasoner.
+   * Subscribe instead of wrapping the Reasoner to log. Throwing here never affects the call.
+   */
+  readonly onDelegateQuery?: (ctx: DelegateQueryContext<Env>) => void | Promise<void>;
+  /**
+   * Delegate observability (G2): fired when the Reasoner produced the turn's final answer —
+   * the hook for logging/persisting the grounded Q&A pair (query + answer + durationMs +
+   * grounded). Throwing here never affects the call.
+   */
+  readonly onDelegateResult?: (ctx: DelegateResultContext<Env>) => void | Promise<void>;
+  /**
+   * G4 durable session state (default on). Persists the reasoner conversation to the
+   * Agent's DO-SQLite so a session resumes with the same context after eviction/
+   * hibernation: cascaded pipelines re-seed the ReasoningBridge; realtime pipelines
+   * record the transcript, feed it to delegate turns as prior context, and expose it
+   * (plus any provider-native resume handle) to the `front()` factory via
+   * `ctx.resume`. Set false for the pre-G4 ephemeral behavior.
+   */
+  readonly durableHistory?: boolean;
+  /**
+   * G3: ms a pending tool call may run before the time-triggered `tool_call_delayed`
+   * ("still working") wire cue fires. 0 disables the delayed phase. Default: 2000.
+   */
+  readonly delayCueAfterMs?: number;
   readonly inputSampleRateHz?: number;
   readonly outputSampleRateHz?: number;
   readonly resumeWindowMs?: number;
@@ -206,8 +280,76 @@ export function withVoice<Env, TBase extends AgentLike>(
 
       // Both runners assemble the session the same way — pipeline + (resolved) reasoner.
       const createSession = async () => {
-        const reasoner = await this.#resolveReasoner(env, sessionId);
-        const session = buildVoiceSession(options.pipeline, env, reasoner, { sessionId });
+        // G4 durable session state: load prior context from DO-SQLite, expose it to the
+        // factories via ctx.resume, and wire persistence per pipeline kind.
+        const durable = options.durableHistory !== false ? this.#durableStore() : undefined;
+        const liveHistory: ReasonerMessage[] = durable ? [...durable.load(sessionId)] : [];
+        const providerHandle = durable?.loadResumeHandle(sessionId);
+        const ctx: VoicePipelineContext = {
+          sessionId,
+          ...(durable
+            ? {
+                resume: {
+                  history: () =>
+                    liveHistory
+                      .filter((m): m is ReasonerMessage & { role: "user" | "assistant" } =>
+                        m.role === "user" || m.role === "assistant")
+                      .map((m) => ({ role: m.role, content: m.content })),
+                  ...(providerHandle ? { providerHandle } : {}),
+                },
+              }
+            : {}),
+        };
+        const wiring: VoiceSessionWiring = {
+          ...(options.delayCueAfterMs !== undefined ? { delayCueAfterMs: options.delayCueAfterMs } : {}),
+          ...(durable
+            ? options.pipeline.kind === "realtime"
+              ? { contextProvider: () => liveHistory }
+              : { reasonerSessionStore: durable }
+            : {}),
+        };
+        const reasoner = await this.#resolveReasoner(env, ctx);
+        const session = buildVoiceSession(options.pipeline, env, reasoner, ctx, wiring);
+        // Realtime pipelines have no ReasoningBridge to own history — record the
+        // transcript from the bus and persist the bounded snapshot per turn. The
+        // cascaded path persists inside ReasoningBridge instead (heard-prefix aware).
+        if (durable && options.pipeline.kind === "realtime") {
+          const persist = (): void => {
+            if (liveHistory.length > MAX_DURABLE_HISTORY_MESSAGES) {
+              liveHistory.splice(0, liveHistory.length - MAX_DURABLE_HISTORY_MESSAGES);
+            }
+            try {
+              durable.save(sessionId, liveHistory);
+            } catch {
+              /* persistence must never fail the call */
+            }
+          };
+          // The realtime bridge pushes llm.done (assistant transcript) BEFORE
+          // eos.turn_complete (user transcript) for the same turn — buffer the
+          // assistant text and commit the pair in conversation order at turn end.
+          const pendingAssistant = new Map<string, string>();
+          session.bus.on("llm.done", (pkt) => {
+            const done = pkt as { contextId: string; text?: string };
+            if (done.text?.trim()) pendingAssistant.set(done.contextId, done.text);
+          });
+          session.bus.on("eos.turn_complete", (pkt) => {
+            const turn = pkt as { contextId: string; text?: string };
+            const assistantText = pendingAssistant.get(turn.contextId);
+            pendingAssistant.delete(turn.contextId);
+            if (turn.text?.trim()) liveHistory.push({ role: "user", content: turn.text });
+            if (assistantText) liveHistory.push({ role: "assistant", content: assistantText });
+            if (turn.text?.trim() || assistantText) persist();
+          });
+          session.bus.on("realtime.resumption_handle", (pkt) => {
+            const handle = (pkt as { handle?: string }).handle;
+            if (!handle) return;
+            try {
+              durable.saveResumeHandle(sessionId, handle);
+            } catch {
+              /* persistence must never fail the call */
+            }
+          });
+        }
         // Surface the tool-call-start seam: VoiceAgentSession emits `agent_tool_call` the instant
         // the front model invokes the delegate tool, before the reasoner runs. A throwing app
         // callback must never break the call, so it is fully isolated.
@@ -222,6 +364,50 @@ export function withVoice<Env, TBase extends AgentLike>(
             }
           });
         }
+        // Delegate observability (G2): surface the bridge's delegate.query/delegate.result
+        // packets as app hooks. Same isolation contract as onToolCallStart — a throwing app
+        // callback must never break the call.
+        if (options.onDelegateQuery) {
+          session.on("delegate_query", (e) => {
+            try {
+              void Promise.resolve(
+                options.onDelegateQuery!({
+                  query: e.query,
+                  toolId: e.toolId,
+                  toolName: e.toolName,
+                  turnId: e.turnId,
+                  sessionId,
+                  connection: voiceConnection,
+                  env,
+                }),
+              ).catch(() => undefined);
+            } catch {
+              /* app hook threw synchronously — ignore */
+            }
+          });
+        }
+        if (options.onDelegateResult) {
+          session.on("delegate_result", (e) => {
+            try {
+              void Promise.resolve(
+                options.onDelegateResult!({
+                  query: e.query,
+                  answer: e.answer,
+                  durationMs: e.durationMs,
+                  grounded: e.grounded,
+                  toolId: e.toolId,
+                  toolName: e.toolName,
+                  turnId: e.turnId,
+                  sessionId,
+                  connection: voiceConnection,
+                  env,
+                }),
+              ).catch(() => undefined);
+            } catch {
+              /* app hook threw synchronously — ignore */
+            }
+          });
+        }
         return session;
       };
       // The runner reports startup failures to the client and disposes the socket
@@ -239,6 +425,7 @@ export function withVoice<Env, TBase extends AgentLike>(
             ? { engineSampleRateHz: options.inputSampleRateHz }
             : {}),
           ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+          ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
         }).catch(onRunnerSettled);
         return;
       }
@@ -264,6 +451,7 @@ export function withVoice<Env, TBase extends AgentLike>(
           ? { outputSampleRateHz: options.outputSampleRateHz }
           : {}),
         ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+        ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
         createSession,
       }).catch(onRunnerSettled);
     }
@@ -286,13 +474,25 @@ export function withVoice<Env, TBase extends AgentLike>(
       }
     }
 
-    async #resolveReasoner(env: Env, sessionId: string): Promise<Reasoner | undefined> {
-      if (options.reasoner) return options.reasoner(env, { sessionId });
+    async #resolveReasoner(env: Env, ctx: VoicePipelineContext): Promise<Reasoner | undefined> {
+      if (options.reasoner) return options.reasoner(env, ctx);
       const runtime = (this as unknown as VoiceHostSurface).runtime;
-      if (isKuralleRuntime(runtime)) return fromKuralleRuntime(runtime, { sessionId });
+      if (isKuralleRuntime(runtime)) return fromKuralleRuntime(runtime, { sessionId: ctx.sessionId });
       return undefined;
     }
 
+    // One durable store per DO instance; tables are created idempotently on first use.
+    #durable: SqliteReasonerSessionStore | null = null;
+    #durableStore(): SqliteReasonerSessionStore {
+      if (!this.#durable) {
+        const host = this as unknown as { sql: SqlTag };
+        this.#durable = new SqliteReasonerSessionStore(
+          (strings, ...values) => host.sql(strings, ...values),
+        );
+      }
+      return this.#durable;
+    }
+
     // Default: the client-supplied `?sessionId=` (so a reconnecting client can
     // resume its session within the resume window), else a per-connection random
     // id. Crucially NOT the Agent name — two concurrent connections to one