@kuralle-syrinx/aisdk 3.1.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/aisdk",
-  "version": "3.1.0",
+  "version": "4.1.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,7 @@
     "@ai-sdk/openai": "^3.0.67",
     "ai": "^6.0.0",
     "zod": "^4.1.8",
-    "@kuralle-syrinx/core": "3.1.0"
+    "@kuralle-syrinx/core": "4.1.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",

package/src/index.test.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 
 import { describe, expect, it } from "vitest";
-import { PipelineBusImpl, Route } from "@kuralle-syrinx/core";
+import { InMemoryReasonerSessionStore, PipelineBusImpl, Route } from "@kuralle-syrinx/core";
 import type {
   EndOfSpeechPacket,
   InterruptLlmPacket,
@@ -72,7 +72,75 @@ describe("ReasoningBridge", () => {
     });
   });
 
-  it("emits llm.error instead of llm.done when provider reaches token limit", async () => {
+  it("G2/WBS-1: cascade turn emits delegate.query then delegate.result on the Background route", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield toolCall("rag-1", "retrieve", { q: "deadline" });
+      yield toolResult("rag-1", "retrieve", "chunk");
+      yield textDelta("The deadline is March 31.");
+      yield finish("stop");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "When is the deadline?"));
+
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "delegate.result"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    const delegatePackets = packets.filter(({ packet }) =>
+      String((packet as { kind?: string }).kind).startsWith("delegate."),
+    );
+    expect(delegatePackets.map(({ route }) => route)).toEqual([Route.Background, Route.Background]);
+    expect(delegatePackets[0]!.packet).toMatchObject({
+      kind: "delegate.query",
+      contextId: "turn-1",
+      query: "When is the deadline?",
+    });
+    expect((delegatePackets[0]!.packet as { toolName?: string }).toolName).toBeUndefined();
+    expect(delegatePackets[1]!.packet).toMatchObject({
+      kind: "delegate.result",
+      contextId: "turn-1",
+      query: "When is the deadline?",
+      answer: "The deadline is March 31.",
+      grounded: true,
+    });
+    expect((delegatePackets[1]!.packet as { durationMs: number }).durationMs).toBeGreaterThanOrEqual(0);
+    // delegate.query precedes the reasoner's first output.
+    const queryIndex = packets.findIndex(({ packet }) => (packet as { kind?: string }).kind === "delegate.query");
+    const firstDeltaIndex = packets.findIndex(({ packet }) => (packet as { kind?: string }).kind === "llm.delta");
+    expect(queryIndex).toBeGreaterThanOrEqual(0);
+    expect(queryIndex).toBeLessThan(firstDeltaIndex);
+  });
+
+  it("G2/WBS-1: cascade delegate.result grounded=false without tool use; none on error", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield textDelta("From memory.");
+      yield finish("stop");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "delegate.result"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    const result = packets.find(({ packet }) => (packet as { kind?: string }).kind === "delegate.result")!;
+    expect(result.packet).toMatchObject({ grounded: false, answer: "From memory." });
+  });
+
+  it("accepts the truncated reply on token-limit finish (fails the turn, never the call)", async () => {
+    // A `length` finish means the model hit the token cap: the streamed reply is
+    // truncated but usable. It must be spoken and the call kept up (L2) — never
+    // escalated to a session-killing llm.error.
     const packets: Array<{ route: Route; packet: unknown }> = [];
     const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
       yield textDelta("This answer is incomplete");
@@ -84,20 +152,48 @@ describe("ReasoningBridge", () => {
     await plugin.initialize(bus, baseConfig());
     bus.push(Route.Main, turnComplete("turn-1", "Hi"));
 
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    // The partial reply is committed as a normal turn completion.
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.done", contextId: "turn-1", text: "This answer is incomplete" }),
+    });
+    // No session-killing error was emitted.
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.error")).toBe(false);
+    // The truncation is observable for telemetry.
+    expect(packets.some(({ packet }) => (packet as { kind?: string; name?: string }).name === "llm.finish_length_truncated")).toBe(true);
+  });
+
+  it("fails the turn recoverably (not the call) on an unfinished tool-loop finish", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const plugin = new ReasoningBridge(fromStreamFactory(async function* () {
+      yield textDelta("partial");
+      yield finish("tool-calls");
+    }));
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+
+    await plugin.initialize(bus, baseConfig());
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+
     await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.error"));
     bus.stop();
     await drain;
     await plugin.close();
 
-    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
     expect(packets).toContainEqual({
       route: Route.Critical,
       packet: expect.objectContaining({
         kind: "llm.error",
         contextId: "turn-1",
-        isRecoverable: false,
+        isRecoverable: true, // recoverable → fallback spoken, session stays open
       } satisfies Partial<LlmErrorPacket>),
     });
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
   });
 
   it("emits llm.error when the stream ends without finish metadata", async () => {
@@ -394,6 +490,110 @@ describe("ReasoningBridge", () => {
   });
 });
 
+describe("ReasoningBridge durable session (G4/WBS-4)", () => {
+  it("re-seeds context from the session store after a simulated eviction; no double-answer", async () => {
+    const store = new InMemoryReasonerSessionStore();
+
+    // First lifetime: one committed turn, then the host is evicted (bridge closed).
+    const first = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Answer one.");
+        yield finish("stop");
+      }),
+      { sessionStore: store, sessionId: "s1" },
+    );
+    const firstPackets: Array<{ packet: unknown }> = [];
+    const firstBus = new PipelineBusImpl({ onPacket: (_route, packet) => firstPackets.push({ packet }) });
+    const firstDrain = firstBus.start();
+    await first.initialize(firstBus, baseConfig());
+    firstBus.push(Route.Main, turnComplete("turn-1", "First question"));
+    await waitFor(() => firstPackets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    firstBus.stop();
+    await firstDrain;
+    await first.close();
+
+    // Second lifetime: a fresh bridge over the same store must hand the reasoner
+    // the prior turn as context — and must not re-answer it.
+    const seenMessages: Array<ReasonerTurn["messages"]> = [];
+    const secondReasoner: Reasoner = {
+      stream: (turn) => {
+        seenMessages.push([...turn.messages]);
+        return (async function* (): AsyncGenerator<ReasoningPart> {
+          yield { type: "text-delta", text: "Answer two." };
+          yield { type: "finish", reason: "stop", text: "Answer two." };
+        })();
+      },
+    };
+    const second = new ReasoningBridge(secondReasoner, { sessionStore: store, sessionId: "s1" });
+    const packets: Array<{ packet: unknown }> = [];
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await second.initialize(bus, baseConfig());
+    // Nothing speaks spontaneously on resume (no double-answer).
+    expect(packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done")).toBe(false);
+
+    bus.push(Route.Main, turnComplete("turn-2", "Second question"));
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    bus.stop();
+    await drain;
+    await second.close();
+
+    expect(seenMessages[0]).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "Answer one." },
+    ]);
+    // The store now carries both turns for the next resume.
+    expect(store.load("s1")).toEqual([
+      { role: "user", content: "First question" },
+      { role: "assistant", content: "Answer one." },
+      { role: "user", content: "Second question" },
+      { role: "assistant", content: "Answer two." },
+    ]);
+  });
+
+  it("persists the interrupted turn's history as the heard prefix", async () => {
+    const store = new InMemoryReasonerSessionStore();
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        yield textDelta("Full generated reply that was cut off.");
+        yield finish("stop");
+      }),
+      { sessionStore: store, sessionId: "s1" },
+    );
+    const packets: Array<{ packet: unknown }> = [];
+    const bus = new PipelineBusImpl({ onPacket: (_route, packet) => packets.push({ packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, turnComplete("turn-1", "Hi"));
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "llm.done"));
+    // What actually reached TTS before the barge-in.
+    bus.push(Route.Main, {
+      kind: "tts.text",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      text: "Full generated",
+    } satisfies TextToSpeechTextPacket);
+    await waitFor(() => packets.some(({ packet }) => (packet as { kind?: string }).kind === "tts.text"));
+    bus.push(Route.Critical, {
+      kind: "interrupt.llm",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+    } satisfies InterruptLlmPacket);
+    await waitFor(() =>
+      packets.some(({ packet }) => (packet as { name?: string }).name === "llm.history_truncated_to_spoken"),
+    );
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(store.load("s1")).toEqual([
+      { role: "user", content: "Hi" },
+      { role: "assistant", content: "Full generated" },
+    ]);
+  });
+});
+
 describe("ReasoningBridge suspend/resume", () => {
   it("clean suspend → resume: saves pointer, resumes with userText, discards on finish", async () => {
     const packets: Array<{ route: Route; packet: unknown }> = [];
@@ -593,6 +793,147 @@ function interruptLlm(contextId: string): InterruptLlmPacket {
   return { kind: "interrupt.llm", contextId, timestampMs: Date.now() };
 }
 
+function eosInterim(contextId: string, text: string): { kind: "eos.interim"; contextId: string; timestampMs: number; text: string } {
+  return { kind: "eos.interim", contextId, timestampMs: Date.now(), text };
+}
+
+function eosRetracted(contextId: string): { kind: "eos.retracted"; contextId: string; timestampMs: number } {
+  return { kind: "eos.retracted", contextId, timestampMs: Date.now() };
+}
+
+describe("ReasoningBridge speculative generation", () => {
+  function kinds(packets: Array<{ packet: unknown }>): string[] {
+    return packets.map(({ packet }) => (packet as { kind: string }).kind);
+  }
+
+  it("buffers a draft on eos.interim and flushes it on a matching eos.turn_complete (one generation)", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    let streams = 0;
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        streams += 1;
+        yield textDelta("The fee is ten dollars.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, eosInterim("turn-1", "what are the lab fees"));
+    // Give the draft time to stream fully — nothing may reach the bus yet.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(kinds(packets)).not.toContain("llm.delta");
+    expect(kinds(packets)).not.toContain("llm.done");
+    expect(kinds(packets)).not.toContain("delegate.query");
+
+    bus.push(Route.Main, turnComplete("turn-1", "what are the lab fees"));
+    await waitFor(() => kinds(packets).includes("llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(streams).toBe(1); // the draft WAS the generation — no second LLM call
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.delta", contextId: "turn-1", text: "The fee is ten dollars." }),
+    });
+    expect(packets).toContainEqual({
+      route: Route.Background,
+      packet: expect.objectContaining({ kind: "delegate.result", contextId: "turn-1", answer: "The fee is ten dollars." }),
+    });
+  });
+
+  it("discards the draft on eos.retracted — nothing is ever pushed for it", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    let streams = 0;
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        streams += 1;
+        yield textDelta("Draft answer.");
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, eosInterim("turn-1", "book a"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    bus.push(Route.Main, eosRetracted("turn-1"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    // The user finishes the real utterance later; a fresh generation answers it.
+    bus.push(Route.Main, turnComplete("turn-1", "book a room for tomorrow"));
+    await waitFor(() => kinds(packets).includes("llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(streams).toBe(2); // draft + fresh confirmed run
+    const deltas = packets.filter(({ packet }) => (packet as { kind: string }).kind === "llm.delta");
+    expect(deltas).toHaveLength(1); // the discarded draft's delta never surfaced
+  });
+
+  it("regenerates when the confirmed transcript differs from the draft's", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    const seenTexts: string[] = [];
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* (request: { userText: string }) {
+        seenTexts.push(request.userText);
+        yield textDelta(`Answer to: ${request.userText}`);
+        yield finish("stop");
+      }),
+      { speculative: true },
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, eosInterim("turn-1", "what are the"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    bus.push(Route.Main, turnComplete("turn-1", "what are the lab fees"));
+    await waitFor(() => kinds(packets).includes("llm.done"));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(seenTexts).toEqual(["what are the", "what are the lab fees"]);
+    expect(packets).toContainEqual({
+      route: Route.Main,
+      packet: expect.objectContaining({ kind: "llm.done", text: "Answer to: what are the lab fees" }),
+    });
+    const deltas = packets.filter(({ packet }) => (packet as { kind: string }).kind === "llm.delta");
+    expect(deltas).toHaveLength(1);
+  });
+
+  it("ignores eos.interim when speculative mode is off (default)", async () => {
+    const packets: Array<{ route: Route; packet: unknown }> = [];
+    let streams = 0;
+    const plugin = new ReasoningBridge(
+      fromStreamFactory(async function* () {
+        streams += 1;
+        yield textDelta("Hello.");
+        yield finish("stop");
+      }),
+    );
+    const bus = new PipelineBusImpl({ onPacket: (route, packet) => packets.push({ route, packet }) });
+    const drain = bus.start();
+    await plugin.initialize(bus, baseConfig());
+
+    bus.push(Route.Main, eosInterim("turn-1", "hi"));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    bus.stop();
+    await drain;
+    await plugin.close();
+
+    expect(streams).toBe(0);
+    expect(kinds(packets).filter((k) => k.startsWith("llm."))).toHaveLength(0);
+  });
+});
+
 function baseConfig(): Record<string, unknown> {
   return {
     api_key: "test-key",
@@ -617,6 +958,14 @@ function textDelta(text: string): TextStreamPart<ToolSet> {
   return { type: "text-delta", id: "0", text, providerMetadata: undefined } as TextStreamPart<ToolSet>;
 }
 
+function toolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): TextStreamPart<ToolSet> {
+  return { type: "tool-call", toolCallId, toolName, input } as TextStreamPart<ToolSet>;
+}
+
+function toolResult(toolCallId: string, toolName: string, output: unknown): TextStreamPart<ToolSet> {
+  return { type: "tool-result", toolCallId, toolName, input: {}, output } as TextStreamPart<ToolSet>;
+}
+
 function finish(finishReason: FinishReason, rawFinishReason?: string): TextStreamPart<ToolSet> {
   return {
     type: "finish",

package/src/index.ts

@@ -17,12 +17,14 @@ import {
   type VoicePlugin,
   type PluginConfig,
   type Reasoner,
+  type ReasonerSessionStore,
   type ReasonerTurn,
   type TtsWordTimestamp,
   categorizeLlmError,
   isRecoverable,
   readRetryConfig,
   waitForRetryDelay,
+  ErrorCategory,
   type RetryConfig,
 } from "@kuralle-syrinx/core";
 
@@ -51,12 +53,31 @@ export interface RunStore {
   discard(contextId: string): void | Promise<void>;
 }
 
+/**
+ * Gate for a speculative draft's side effects. While unpromoted, every bus push
+ * and history/store mutation is buffered; promotion replays them in order and
+ * lets the still-running stream continue live. A discarded draft's buffer is
+ * simply dropped — the generation was never observable.
+ */
+interface SpeculativeHold {
+  promoted: boolean;
+  failed: boolean;
+  buffered: Array<() => void>;
+}
+
 export class ReasoningBridge implements VoicePlugin {
   private bus: PipelineBus | null = null;
   private timeoutMs: number = 30_000;
   private maxHistoryTurns: number = 12;
   private history: Array<{ role: "system" | "user" | "assistant" | "tool"; content: string; toolCallId?: string }> = [];
   private activeGeneration: { contextId: string; controller: AbortController } | null = null;
+  // At most one speculative draft at a time; `hold` gates its side effects.
+  private speculativeDraft: {
+    contextId: string;
+    userText: string;
+    controller: AbortController;
+    hold: SpeculativeHold;
+  } | null = null;
   private retryConfig: RetryConfig = readRetryConfig({});
   private disposers: Array<() => void> = [];
   // G2/G25: per-turn state so a barged-in turn is remembered as what the user HEARD,
@@ -82,7 +103,29 @@ export class ReasoningBridge implements VoicePlugin {
 
   constructor(
     private readonly reasoner: Reasoner,
-    private readonly opts: { runStore?: RunStore; onResumeConflict?: "restart" | "replay" } = {},
+    private readonly opts: {
+      runStore?: RunStore;
+      onResumeConflict?: "restart" | "replay";
+      /**
+       * G4 durable session (RFC bimodel-delegate-seam): when set with `sessionId`, the
+       * bridge loads its conversation history from the store on initialize and persists
+       * the bounded snapshot after every committed (or interrupted-truncated) turn — a
+       * bridge re-created after host eviction resumes with the same context.
+       */
+      sessionStore?: ReasonerSessionStore;
+      sessionId?: string;
+      /**
+       * Speculative generation (LiveKit preemptive-generation / Deepgram Flux
+       * eager-EOT semantics): start the LLM on `eos.interim` with every side effect
+       * held back; commit as-is when `eos.turn_complete` confirms the same
+       * transcript, regenerate when it differs, discard on `eos.retracted`.
+       * Parallelizes LLM TTFT with the endpoint-confirmation window. Opt-in:
+       * unconfirmed endpoints cost extra LLM calls (Deepgram measures +50–70% at
+       * eager thresholds 0.3–0.5). Drafts never consume a suspended-run pointer —
+       * `runStore` resume stays confirmed-turn-only.
+       */
+      speculative?: boolean;
+    } = {},
   ) {
     if (this.opts.onResumeConflict === "replay") {
       throw new Error("onResumeConflict 'replay' not yet supported — use 'restart'");
@@ -95,6 +138,13 @@ export class ReasoningBridge implements VoicePlugin {
     this.maxHistoryTurns = readPositiveIntegerConfig(config["max_history_turns"], 12);
     this.retryConfig = readRetryConfig(config);
 
+    // G4: resume from durable history — the reasoner's next turn sees the same
+    // context as before the eviction/reconnect (R6). Load-only: nothing is spoken.
+    if (this.opts.sessionStore && this.opts.sessionId) {
+      const stored = await this.opts.sessionStore.load(this.opts.sessionId);
+      this.history = stored.map((message) => ({ ...message }));
+    }
+
     // Listen for EOS turn completions
     this.disposers.push(
       // Concurrent producer: a turn's LLM generation streams its own packets over
@@ -105,6 +155,26 @@ export class ReasoningBridge implements VoicePlugin {
       // still-in-flight generation (see below).
       bus.on("eos.turn_complete", async (pkt: unknown) => {
         const eos = pkt as { text: string; contextId: string };
+        // R2: a draft for this exact transcript is already generating (or done) —
+        // promote it instead of paying a second LLM call. Flux guarantees the
+        // EndOfTurn transcript matches the preceding EagerEndOfTurn when no
+        // TurnResumed intervened, so commit-as-is is safe.
+        const draft = this.speculativeDraft;
+        if (
+          draft &&
+          draft.contextId === eos.contextId &&
+          draft.userText === eos.text &&
+          !draft.controller.signal.aborted &&
+          !draft.hold.failed
+        ) {
+          this.speculativeDraft = null;
+          draft.hold.promoted = true;
+          for (const flush of draft.hold.buffered.splice(0)) flush();
+          return;
+        }
+        // Stale, mismatched, or failed draft: its speculation was wrong — drop it
+        // and answer the confirmed transcript fresh.
+        this.discardDraft();
         await this.processTurn(eos.text, eos.contextId);
       }, { concurrent: true }),
 
@@ -139,6 +209,7 @@ export class ReasoningBridge implements VoicePlugin {
       // said words the user never heard (nor amnesiac about the exchange).
       bus.on("interrupt.llm", (pkt: unknown) => {
         const contextId = (pkt as { contextId: string }).contextId;
+        if (this.speculativeDraft?.contextId === contextId) this.discardDraft();
         if (this.activeGeneration?.contextId === contextId) {
           this.activeGeneration.controller.abort();
           this.activeGeneration = null;
@@ -149,9 +220,45 @@ export class ReasoningBridge implements VoicePlugin {
         }
       }),
     );
+
+    if (this.opts.speculative) {
+      this.disposers.push(
+        bus.on("eos.interim", async (pkt: unknown) => {
+          const interim = pkt as { text?: string; contextId: string };
+          const text = (interim.text ?? "").trim();
+          if (!text) return;
+          await this.runDraft(text, interim.contextId);
+        }, { concurrent: true }),
+        bus.on("eos.retracted", (pkt: unknown) => {
+          const contextId = (pkt as { contextId: string }).contextId;
+          if (this.speculativeDraft?.contextId === contextId) this.discardDraft();
+        }),
+      );
+    }
+  }
+
+  /** Start (or restart, if a newer eager endpoint supersedes) the speculative draft. */
+  private async runDraft(userText: string, contextId: string): Promise<void> {
+    this.discardDraft();
+    const controller = new AbortController();
+    const hold: SpeculativeHold = { promoted: false, failed: false, buffered: [] };
+    this.speculativeDraft = { contextId, userText, controller, hold };
+    await this.processTurn(userText, contextId, hold, controller);
   }
 
-  private async processTurn(userText: string, contextId: string): Promise<void> {
+  private discardDraft(): void {
+    const draft = this.speculativeDraft;
+    if (!draft) return;
+    this.speculativeDraft = null;
+    if (!draft.hold.promoted) draft.controller.abort();
+  }
+
+  private async processTurn(
+    userText: string,
+    contextId: string,
+    hold?: SpeculativeHold,
+    presetController?: AbortController,
+  ): Promise<void> {
     if (!this.bus) return;
 
     this.turnUserText.set(contextId, userText);
@@ -159,18 +266,49 @@ export class ReasoningBridge implements VoicePlugin {
     // Handlers are concurrent, so a new turn can begin while a prior generation is
     // still in flight. Supersede it: abort the previous controller before starting.
     this.activeGeneration?.controller.abort();
-    const controller = new AbortController();
+    const controller = presetController ?? new AbortController();
     this.activeGeneration = { contextId, controller };
     const signal = controller.signal;
 
+    // R2: while a speculative hold is unpromoted, every push/mutation buffers.
+    // Packets are constructed eagerly (their timestamps are event time); only
+    // delivery is deferred. Promotion replays in order, then later effects run live.
+    const push = <T extends Parameters<PipelineBus["push"]>[1]>(route: Route, packet: T): void => {
+      if (hold && !hold.promoted) {
+        if ((packet as { kind?: string }).kind === "llm.error") hold.failed = true;
+        hold.buffered.push(() => this.bus?.push(route, packet));
+        return;
+      }
+      this.bus?.push(route, packet);
+    };
+    const defer = (fn: () => void): void => {
+      if (hold && !hold.promoted) hold.buffered.push(fn);
+      else fn();
+    };
+
     let reply = "";
     let emittedDelta = false;
     let committed = false;
+    let grounded = false;
+
+    // G2 observability: the turn's query is on its way to the reasoner (Background
+    // route, droppable — RFC bimodel-delegate-seam R4). Cascade turns have no
+    // front-model tool call, so toolId/toolName are absent.
+    const queryStartedMs = Date.now();
+    push(Route.Background, {
+      kind: "delegate.query",
+      contextId,
+      timestampMs: queryStartedMs,
+      query: userText,
+    });
 
     try {
       for (let attempt = 1; attempt <= this.retryConfig.maxAttempts; attempt += 1) {
+        grounded = false;
         try {
-          const pending = this.opts.runStore
+          // Drafts never consume a suspended-run pointer: takePending mutates the
+          // store, and a retracted draft would silently lose the resume.
+          const pending = this.opts.runStore && !hold
             ? await Promise.resolve(this.opts.runStore.takePending(contextId))
             : null;
           const resuming = pending !== null;
@@ -186,7 +324,7 @@ export class ReasoningBridge implements VoicePlugin {
               case "text-delta":
                 reply += part.text;
                 emittedDelta = true;
-                this.bus.push(Route.Main, {
+                push(Route.Main, {
                   kind: "llm.delta",
                   contextId,
                   timestampMs: Date.now(),
@@ -194,7 +332,7 @@ export class ReasoningBridge implements VoicePlugin {
                 });
                 break;
               case "tool-call":
-                this.bus.push(Route.Main, {
+                push(Route.Main, {
                   kind: "llm.tool_call",
                   contextId,
                   timestampMs: Date.now(),
@@ -204,7 +342,8 @@ export class ReasoningBridge implements VoicePlugin {
                 });
                 break;
               case "tool-result":
-                this.bus.push(Route.Main, {
+                grounded = true;
+                push(Route.Main, {
                   kind: "llm.tool_result",
                   contextId,
                   timestampMs: Date.now(),
@@ -216,12 +355,18 @@ export class ReasoningBridge implements VoicePlugin {
               case "error":
                 throw part.cause;
               case "finish":
-                this.recordFinishReason(contextId, "llm.finish_reason", part.reason);
+                push(Route.Background, {
+                  kind: "metric.conversation",
+                  contextId,
+                  timestampMs: Date.now(),
+                  name: "llm.finish_reason",
+                  value: part.reason,
+                });
                 finishReason = part.reason;
                 break;
               case "suspended": {
                 if (part.prompt && !emittedDelta) {
-                  this.bus.push(Route.Main, {
+                  push(Route.Main, {
                     kind: "llm.delta",
                     contextId,
                     timestampMs: Date.now(),
@@ -230,14 +375,14 @@ export class ReasoningBridge implements VoicePlugin {
                   reply += part.prompt;
                 }
                 if (signal.aborted) return;
-                this.bus.push(Route.Main, {
+                push(Route.Main, {
                   kind: "llm.done",
                   contextId,
                   timestampMs: Date.now(),
                   text: reply,
                 });
-                this.rememberTurn(userText, reply, contextId);
-                this.bus.push(Route.Background, {
+                defer(() => this.rememberTurn(userText, reply, contextId));
+                push(Route.Background, {
                   kind: "reasoning.suspended",
                   contextId,
                   timestampMs: Date.now(),
@@ -246,7 +391,13 @@ export class ReasoningBridge implements VoicePlugin {
                   payload: part.payload,
                 });
                 if (this.opts.runStore) {
-                  await Promise.resolve(this.opts.runStore.save(contextId, part.runId));
+                  const store = this.opts.runStore;
+                  const runId = part.runId;
+                  if (hold && !hold.promoted) {
+                    hold.buffered.push(() => void Promise.resolve(store.save(contextId, runId)).catch(() => undefined));
+                  } else {
+                    await Promise.resolve(store.save(contextId, runId));
+                  }
                 }
                 committed = true;
                 return;
@@ -254,19 +405,57 @@ export class ReasoningBridge implements VoicePlugin {
             }
           }
 
-          validateFinalFinishReason(finishReason);
+          // A non-"stop" finish must fail the TURN, never the call (L2). Killing the
+          // session on a token-cap or unfinished-tool-loop hangs up the caller
+          // mid-conversation. `length` = token cap: the streamed reply is truncated
+          // but usable, so accept it and continue (fall through to llm.done). Any
+          // other non-"stop" reason (tool loop ended, null) = fail the turn
+          // recoverably — the caller hears the graceful fallback, the call stays up.
+          if (finishReason !== "stop" && finishReason !== "length") {
+            if (signal.aborted) return;
+            push(Route.Critical, {
+              kind: "llm.error",
+              contextId,
+              timestampMs: Date.now(),
+              component: "bridge" as const,
+              category: ErrorCategory.InternalFault,
+              cause: new Error(`AI SDK turn ended on finishReason "${finishReason ?? "null"}"`),
+              isRecoverable: true,
+            });
+            return;
+          }
+          if (finishReason === "length") {
+            push(Route.Background, {
+              kind: "metric.conversation",
+              contextId,
+              timestampMs: Date.now(),
+              name: "llm.finish_length_truncated",
+              value: "1",
+            });
+          }
 
           // Interrupted as generation finished — the interrupt handler owns the history
           // for this turn (spoken prefix); don't commit the full reply or emit llm.done.
           if (signal.aborted) return;
 
-          this.bus.push(Route.Main, {
+          const answeredMs = Date.now();
+          push(Route.Main, {
             kind: "llm.done",
             contextId,
-            timestampMs: Date.now(),
+            timestampMs: answeredMs,
             text: reply,
           });
-          this.rememberTurn(userText, reply, contextId);
+          // G2 observability: the reasoner produced the turn's final answer.
+          push(Route.Background, {
+            kind: "delegate.result",
+            contextId,
+            timestampMs: answeredMs,
+            query: userText,
+            answer: reply,
+            durationMs: answeredMs - queryStartedMs,
+            grounded,
+          });
+          defer(() => this.rememberTurn(userText, reply, contextId));
           if (this.opts.runStore && resuming) {
             await Promise.resolve(this.opts.runStore.discard(contextId));
           }
@@ -277,7 +466,7 @@ export class ReasoningBridge implements VoicePlugin {
           const category = categorizeLlmError(err);
           const recoverable = isRecoverable(category);
           if (!recoverable || emittedDelta || attempt >= this.retryConfig.maxAttempts) {
-            this.bus.push(Route.Critical, {
+            push(Route.Critical, {
               kind: "llm.error",
               contextId,
               timestampMs: Date.now(),
@@ -289,7 +478,7 @@ export class ReasoningBridge implements VoicePlugin {
             return;
           }
 
-          this.bus.push(Route.Background, {
+          push(Route.Background, {
             kind: "metric.conversation",
             contextId,
             timestampMs: Date.now(),
@@ -307,21 +496,8 @@ export class ReasoningBridge implements VoicePlugin {
     }
   }
 
-  private recordFinishReason(
-    contextId: string,
-    name: string,
-    finishReason: "stop" | "tool" | "length",
-  ): void {
-    this.bus?.push(Route.Background, {
-      kind: "metric.conversation",
-      contextId,
-      timestampMs: Date.now(),
-      name,
-      value: finishReason,
-    });
-  }
-
   async close(): Promise<void> {
+    this.discardDraft();
     this.activeGeneration?.controller.abort();
     this.activeGeneration = null;
     for (const dispose of this.disposers.splice(0)) dispose();
@@ -338,6 +514,21 @@ export class ReasoningBridge implements VoicePlugin {
     this.history.push({ role: "user", content: userText }, assistantMsg);
     this.assistantMsgByContext.set(contextId, assistantMsg);
     this.trimHistory();
+    this.persistHistory();
+  }
+
+  /** G4: persist the bounded history snapshot, best-effort off the hot path. */
+  private persistHistory(): void {
+    const store = this.opts.sessionStore;
+    const sessionId = this.opts.sessionId;
+    if (!store || !sessionId) return;
+    try {
+      void Promise.resolve(store.save(sessionId, this.history.map((message) => ({ ...message })))).catch(
+        () => undefined,
+      );
+    } catch {
+      /* persistence must never fail the turn */
+    }
   }
 
   /**
@@ -390,6 +581,7 @@ export class ReasoningBridge implements VoicePlugin {
       name: "llm.history_truncated_to_spoken",
       value: String(spoken.length),
     });
+    this.persistHistory(); // G4: the durable snapshot reflects the heard prefix
     this.clearTurnState(contextId);
   }
 
@@ -413,17 +605,6 @@ export class ReasoningBridge implements VoicePlugin {
   }
 }
 
-function validateFinalFinishReason(finishReason: "stop" | "tool" | "length" | null): void {
-  if (finishReason === null) {
-    throw new Error("AI SDK stream ended without a provider finish reason");
-  }
-  if (finishReason === "length") {
-    throw new Error("AI SDK provider reached token limit before completing");
-  }
-  if (finishReason !== "stop") {
-    throw new Error("AI SDK provider did not complete normally");
-  }
-}
 
 function readPositiveIntegerConfig(value: unknown, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return fallback;