@kuralle-syrinx/core 3.1.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/core",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/conversation-event.ts

@@ -49,7 +49,11 @@ export function createConversationEventStream(): [
   });
 
   const push = (event: ConversationEvent): void => {
-    if (controller) {
+    // Only retain events when a reader is attached. A ReadableStream buffers
+    // enqueue() without bound; with no debug consumer (nothing in-tree reads this
+    // by default) every packet's event would be retained for the whole call and
+    // grow memory unbounded. `locked` is true once getReader() is called.
+    if (controller && stream.locked) {
       try {
         controller.enqueue(event);
       } catch {

package/src/index.ts

@@ -63,6 +63,20 @@ export {
   type ReasoningResumePacket,
 } from "./packets.js";
 
+// Pipeline packets — delegate (Responder-Thinker) observability
+export {
+  type DelegateQueryPacket,
+  type DelegateResultPacket,
+  type DelegatePacket,
+  type RealtimeResumptionHandlePacket,
+} from "./packets.js";
+
+// Durable reasoner session state (G4)
+export {
+  InMemoryReasonerSessionStore,
+  type ReasonerSessionStore,
+} from "./reasoner-session-store.js";
+
 // Pipeline packets — TTS
 export {
   type TextToSpeechTextPacket,

package/src/packets.ts

@@ -300,12 +300,58 @@ export interface ReasoningSuspendedPacket extends VoicePacket {
   readonly payload: unknown;
 }
 
+// =============================================================================
+// Delegate (Responder-Thinker) observability packets (Background route)
+// =============================================================================
+
+/**
+ * The bridge handed a query to the Reasoner. Emitted the moment the delegate
+ * turn starts (RealtimeBridge `runDelegate`) or the cascade turn reaches the
+ * reasoner (ReasoningBridge), BEFORE the stream runs. Background route:
+ * droppable, never blocks the hot path (RFC bimodel-delegate-seam R4).
+ * `toolId`/`toolName` are present on realtime delegate turns (the front-model
+ * tool call that triggered the delegate); absent on cascade turns.
+ */
+export interface DelegateQueryPacket extends VoicePacket {
+  readonly kind: "delegate.query";
+  readonly query: string;
+  readonly toolId?: string;
+  readonly toolName?: string;
+}
+
+/**
+ * The Reasoner produced the turn's final answer. Self-contained: carries the
+ * `query` again so a consumer can log/persist the Q&A pair from this one packet
+ * without correlating against the earlier `delegate.query`. `durationMs` spans
+ * query → answer; `grounded` is true when the reasoner stream surfaced at least
+ * one `tool-result` part (e.g. a retrieval hit) while producing the answer.
+ */
+export interface DelegateResultPacket extends VoicePacket {
+  readonly kind: "delegate.result";
+  readonly query: string;
+  readonly answer: string;
+  readonly durationMs: number;
+  readonly grounded: boolean;
+  readonly toolId?: string;
+  readonly toolName?: string;
+}
+
 export interface ReasoningResumePacket extends VoicePacket {
   readonly kind: "reasoning.resume";
   readonly runId: string;
   readonly data: unknown;
 }
 
+/**
+ * G4: a realtime provider with native session resume (Gemini Live) issued a new
+ * resumption handle. Background route; a durable host (e.g. cf-agents) persists
+ * the latest handle and passes it back on reconnect instead of replaying history.
+ */
+export interface RealtimeResumptionHandlePacket extends VoicePacket {
+  readonly kind: "realtime.resumption_handle";
+  readonly handle: string;
+}
+
 // =============================================================================
 // Output Pipeline Packets (LLM text → TTS audio)
 // =============================================================================
@@ -551,3 +597,6 @@ export type AnyErrorPacket =
 
 /** Observability packets (Background route). */
 export type ObservabilityPacket = ConversationMetricPacket | TurnBoundaryEventPacket;
+
+/** Delegate (Responder-Thinker) lifecycle packets (Background route). */
+export type DelegatePacket = DelegateQueryPacket | DelegateResultPacket;

package/src/pipeline-bus.test.ts

@@ -171,6 +171,20 @@ describe("PipelineBusImpl", () => {
         packet: { kind: "critical.event", contextId: "critical-1" },
       });
     });
+
+    it("does not retain packets when no reader is attached (drop-on-unread)", async () => {
+      const bus = createBus();
+      // No getReader() → stream unlocked → nothing retained (else a call with no
+      // recorder would buffer every audio packet and OOM).
+      for (let i = 0; i < 1000; i++) bus.push(Route.Main, pkt("main.event", `n-${i}`));
+
+      // A reader that attaches later sees only packets pushed AFTER it attaches.
+      const reader = bus.allPackets.getReader();
+      bus.push(Route.Main, pkt("main.event", "after-reader"));
+      const next = await reader.read();
+      reader.releaseLock();
+      expect(next.value).toMatchObject({ packet: { contextId: "after-reader" } });
+    });
   });
 
   describe("error handling", () => {

package/src/pipeline-bus.ts

@@ -239,6 +239,11 @@ export class PipelineBusImpl implements PipelineBus {
   private publishAllPackets(route: Route, packet: VoicePacket): void {
     this.onPacket?.(route, packet);
     if (!this.allPacketsController) return;
+    // Only retain packets when a reader is actually attached. A ReadableStream
+    // buffers enqueue() without bound until read, so with no consumer (the default
+    // deployment — recorder is optional) this would retain every audio buffer of
+    // the whole call and OOM. `locked` is true once getReader() is called.
+    if (!this.allPackets.locked) return;
     try {
       this.allPacketsController.enqueue({ route, packet });
     } catch {

package/src/reasoner-session-store.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — durable reasoner session state (G4, RFC bimodel-delegate-seam)
+//
+// The bridge owns conversation history (reasoner.ts §4.5); this seam makes that
+// history durable so a reasoner resumes with the same context after a host
+// eviction/reconnect instead of restarting amnesiac. Concrete backends: the
+// in-memory impl below (Node/tests), a DO-SQLite impl in @kuralle-syrinx/cf-agents.
+
+import type { ReasonerMessage } from "./reasoner.js";
+
+/**
+ * Durable per-session reasoner conversation history. `save` persists the full
+ * (already bounded) history snapshot — snapshot semantics, not append, because
+ * barge-in truncation rewrites earlier messages to the heard prefix (G25).
+ */
+export interface ReasonerSessionStore {
+  load(sessionId: string): Promise<readonly ReasonerMessage[]> | readonly ReasonerMessage[];
+  save(sessionId: string, messages: readonly ReasonerMessage[]): Promise<void> | void;
+  clear(sessionId: string): Promise<void> | void;
+}
+
+export class InMemoryReasonerSessionStore implements ReasonerSessionStore {
+  private readonly sessions = new Map<string, readonly ReasonerMessage[]>();
+
+  load(sessionId: string): readonly ReasonerMessage[] {
+    return this.sessions.get(sessionId) ?? [];
+  }
+
+  save(sessionId: string, messages: readonly ReasonerMessage[]): void {
+    this.sessions.set(sessionId, [...messages]);
+  }
+
+  clear(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+}

package/src/tts-playout-clock.ts

@@ -89,6 +89,20 @@ export class TtsPlayoutClock {
     return this.active.has(contextId);
   }
 
+  /** All still-active contexts, insertion order (oldest first). */
+  activeContexts(): string[] {
+    return [...this.active];
+  }
+
+  /**
+   * Wall-clock estimate of when this context's audio finishes playing out, or
+   * undefined if unknown. Anchors the idle timer to real playout end rather than
+   * chunk-arrival (TTS streams faster than realtime).
+   */
+  playoutEnd(contextId: string): number | undefined {
+    return this.playoutEndMs.get(contextId);
+  }
+
   /** The most-recently-added still-active context (insertion order), or "" if none. */
   latestActive(): string {
     let latest = "";

package/src/turn-arbiter.ts

@@ -49,7 +49,7 @@ const BACKCHANNELS = new Set([
   "oh",
 ]);
 
-function isBackchannel(text: string): boolean {
+export function isBackchannel(text: string): boolean {
   const norm = text
     .toLowerCase()
     .replace(/[^a-z\s'-]/g, "")

package/src/voice-agent-session.test.ts

@@ -321,6 +321,198 @@ describe("VoiceAgentSession", () => {
     await closeSession(session);
   });
 
+  it("G2/WBS-1: surfaces delegate.query/delegate.result packets as delegate_query/delegate_result session events", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    const queries: Array<{ turnId: string; query: string; toolName?: string }> = [];
+    const results: Array<{ turnId: string; query: string; answer: string; durationMs: number; grounded: boolean }> = [];
+    session.on("delegate_query", (event) => queries.push(event));
+    session.on("delegate_result", (event) => results.push(event));
+    await session.start();
+
+    session.bus.push(Route.Background, {
+      kind: "delegate.query",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      query: "When is the deadline?",
+      toolId: "call_1",
+      toolName: "consult_knowledge",
+    });
+    session.bus.push(Route.Background, {
+      kind: "delegate.result",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      query: "When is the deadline?",
+      answer: "March 31.",
+      durationMs: 42,
+      grounded: true,
+      toolId: "call_1",
+      toolName: "consult_knowledge",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(queries).toEqual([
+      { tsMs: expect.any(Number), turnId: "turn-1", query: "When is the deadline?", toolId: "call_1", toolName: "consult_knowledge" },
+    ]);
+    expect(results).toEqual([
+      {
+        tsMs: expect.any(Number),
+        turnId: "turn-1",
+        query: "When is the deadline?",
+        answer: "March 31.",
+        durationMs: 42,
+        grounded: true,
+        toolId: "call_1",
+        toolName: "consult_knowledge",
+      },
+    ]);
+
+    await closeSession(session);
+  });
+
+  it("G3/WBS-3: tool-call lifecycle cues fire started → delayed → complete", async () => {
+    const session = new VoiceAgentSession({ plugins: {}, delayCueAfterMs: 30 });
+    const cues: Array<{ phase: string; turnId: string; toolId: string; toolName: string; afterMs?: number }> = [];
+    session.on("tool_call_cue", (event) => cues.push(event));
+    await session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: { query: "fees" },
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 70));
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_result",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      result: "answer",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(cues.map((cue) => cue.phase)).toEqual(["started", "delayed", "complete"]);
+    expect(cues[0]).toMatchObject({ turnId: "turn-1", toolId: "t1", toolName: "consult_knowledge" });
+    expect(cues[1]!.afterMs).toBe(30);
+
+    await closeSession(session);
+  });
+
+  it("G3/WBS-3: no delayed cue when the result beats the timer; timer 0 disables it", async () => {
+    const session = new VoiceAgentSession({ plugins: {}, delayCueAfterMs: 5000 });
+    const cues: Array<{ phase: string }> = [];
+    session.on("tool_call_cue", (event) => cues.push(event));
+    await session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: {},
+    });
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_result",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      result: "fast answer",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(cues.map((cue) => cue.phase)).toEqual(["started", "complete"]);
+
+    await closeSession(session);
+
+    const disabled = new VoiceAgentSession({ plugins: {}, delayCueAfterMs: 0 });
+    const disabledCues: Array<{ phase: string }> = [];
+    disabled.on("tool_call_cue", (event) => disabledCues.push(event));
+    await disabled.start();
+    disabled.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-2",
+      timestampMs: Date.now(),
+      toolId: "t2",
+      toolName: "consult_knowledge",
+      toolArgs: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(disabledCues.map((cue) => cue.phase)).toEqual(["started"]);
+    await closeSession(disabled);
+  });
+
+  it("G3/WBS-3: llm.error while a tool call is pending fires the failed cue", async () => {
+    const session = new VoiceAgentSession({ plugins: {}, delayCueAfterMs: 0 });
+    const cues: Array<{ phase: string; toolId: string }> = [];
+    session.on("tool_call_cue", (event) => cues.push(event));
+    await session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10)); // let Main drain before the Critical error
+    session.bus.push(Route.Critical, {
+      kind: "llm.error",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      component: "bridge",
+      category: ErrorCategory.NetworkTimeout,
+      cause: new Error("delegate failed"),
+      isRecoverable: true,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(cues.map((cue) => cue.phase)).toEqual(["started", "failed"]);
+    expect(cues[1]!.toolId).toBe("t1");
+
+    await closeSession(session);
+  });
+
+  it("G3/WBS-3 (R5): barge-in fails the pending cue and the interrupt path is unaffected", async () => {
+    const session = new VoiceAgentSession({ plugins: {}, delayCueAfterMs: 5000, minInterruptionMs: 0 });
+    const cues: Array<{ phase: string }> = [];
+    const interrupts: string[] = [];
+    session.on("tool_call_cue", (event) => cues.push(event));
+    session.bus.on("interrupt.tts", (pkt) => { interrupts.push((pkt as { contextId: string }).contextId); });
+    await session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10)); // let Main drain before the Critical interrupt
+    session.bus.push(Route.Critical, {
+      kind: "interrupt.detected",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      source: "client",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(cues.map((cue) => cue.phase)).toEqual(["started", "failed"]);
+    expect(interrupts).toContain("turn-1"); // barge-in cancel still flowed
+
+    await closeSession(session);
+  });
+
   it("emits normalized debug events for bus packets", async () => {
     const session = new VoiceAgentSession({ plugins: {} });
     const reader = session.debugEvents.getReader();
@@ -2485,3 +2677,85 @@ describe("VoiceAgentSession — handler errors must not kill the call", () => {
     await closeSession(session);
   });
 });
+
+describe("VoiceAgentSession supersede + thinking-phase barge-in", () => {
+  it("cancels a still-playing prior turn's TTS when a new turn completes (L1)", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    const interruptTts: InterruptTtsPacket[] = [];
+    await session.start();
+    session.bus.on("interrupt.tts", (pkt) => { interruptTts.push(pkt as InterruptTtsPacket); });
+
+    // Turn 1 is generating + has streamed audio (still playing out).
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete", contextId: "turn-1", timestampMs: Date.now(), text: "one", transcripts: [],
+    } satisfies EndOfSpeechPacket);
+    await new Promise((r) => setTimeout(r, 5));
+    session.bus.push(Route.Main, {
+      kind: "tts.audio", contextId: "turn-1", timestampMs: Date.now(),
+      audio: new Uint8Array(16000), sampleRateHz: 16000, // ~0.5s of audio still playing
+    } satisfies TextToSpeechAudioPacket);
+    await new Promise((r) => setTimeout(r, 5));
+
+    // Turn 2 completes while turn 1 is still playing → turn 1 must be cancelled.
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete", contextId: "turn-2", timestampMs: Date.now(), text: "two", transcripts: [],
+    } satisfies EndOfSpeechPacket);
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(interruptTts.some((p) => p.contextId === "turn-1")).toBe(true);
+    expect(interruptTts.some((p) => p.contextId === "turn-2")).toBe(false);
+
+    await closeSession(session);
+  });
+
+  it("honors a client interrupt during the reasoner TTFT gap, before any audio (B3)", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    const interruptLlm: InterruptLlmPacket[] = [];
+    await session.start();
+    session.bus.on("interrupt.llm", (pkt) => { interruptLlm.push(pkt as InterruptLlmPacket); });
+
+    // Turn completes; generation is in-flight but NO tts.audio has played yet.
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete", contextId: "turn-think", timestampMs: Date.now(), text: "q", transcripts: [],
+    } satisfies EndOfSpeechPacket);
+    await new Promise((r) => setTimeout(r, 5));
+
+    session.requestClientInterrupt("turn-think");
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(interruptLlm.some((p) => p.contextId === "turn-think")).toBe(true);
+
+    await closeSession(session);
+  });
+
+  it("drops a backchannel during the assistant's turn: no cancel, no second response (B4)", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    const interruptTts: InterruptTtsPacket[] = [];
+    const userInputs: UserInputPacket[] = [];
+    await session.start();
+    session.bus.on("interrupt.tts", (pkt) => { interruptTts.push(pkt as InterruptTtsPacket); });
+    session.bus.on("user.input", (pkt) => { userInputs.push(pkt as UserInputPacket); });
+
+    // Assistant is speaking turn-1 (audio actively playing out).
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete", contextId: "turn-1", timestampMs: Date.now(), text: "here is the answer", transcripts: [],
+    } satisfies EndOfSpeechPacket);
+    await new Promise((r) => setTimeout(r, 5));
+    session.bus.push(Route.Main, {
+      kind: "tts.audio", contextId: "turn-1", timestampMs: Date.now(), audio: new Uint8Array(16000), sampleRateHz: 16000,
+    } satisfies TextToSpeechAudioPacket);
+    await new Promise((r) => setTimeout(r, 5));
+
+    // User says "uh-huh" (a rotated context) mid-answer — a backchannel, not a turn.
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete", contextId: "turn-2", timestampMs: Date.now(), text: "uh-huh", transcripts: [],
+    } satisfies EndOfSpeechPacket);
+    await new Promise((r) => setTimeout(r, 10));
+
+    // The assistant's turn is NOT cancelled and the backchannel does NOT drive the LLM.
+    expect(interruptTts.some((p) => p.contextId === "turn-1")).toBe(false);
+    expect(userInputs.some((p) => p.contextId === "turn-2")).toBe(false);
+
+    await closeSession(session);
+  });
+});

package/src/voice-agent-session.ts

@@ -29,6 +29,8 @@ import type {
   UserAudioReceivedPacket,
   UserTextReceivedPacket,
   InterruptionDetectedPacket,
+  DelegateQueryPacket,
+  DelegateResultPacket,
   LlmDeltaPacket,
   LlmResponseDonePacket,
   LlmToolCallPacket,
@@ -61,7 +63,7 @@ import { LatencyFillerController } from "./latency-filler.js";
 import { PrimarySpeakerGate } from "./primary-speaker-gate.js";
 import { takeCompleteVoiceText, isCompleteVoiceText, appendVoiceText } from "./voice-text.js";
 import { TtsPlayoutClock } from "./tts-playout-clock.js";
-import { TurnArbiter } from "./turn-arbiter.js";
+import { TurnArbiter, isBackchannel } from "./turn-arbiter.js";
 import * as make from "./packet-factories.js";
 import { pluginStage, stageOrder, isAudioStage } from "./init-stage-order.js";
 import {
@@ -147,6 +149,14 @@ export interface VoiceAgentSessionConfig {
    * (TTS/STT-failure fallback needs canned audio / a clarification prompt — out of scope.)
    */
   errorFallbackText?: string;
+  /**
+   * G3 (RFC bimodel-delegate-seam): ms a tool call may stay pending before the
+   * `tool_call_cue` session event fires its time-triggered `"delayed"` phase — the
+   * "still working" cue clients render during a long reasoner wait (cf. Vapi's
+   * `request-response-delayed` + `timingMilliseconds`). 0 disables the delayed
+   * phase; started/complete/failed always fire. Default: 2000.
+   */
+  delayCueAfterMs?: number;
   /**
    * Which component owns turn boundary (EOS) for this session. Defaults to
    * provider STT ownership; Smart Turn sessions must opt in explicitly.
@@ -170,6 +180,16 @@ export interface VoiceAgentSessionEvents {
   agent_text_delta: (event: { tsMs: number; turnId: string; delta: string }) => void;
   agent_tool_call: (event: { tsMs: number; turnId: string; id: string; name: string; args: Record<string, unknown> }) => void;
   agent_tool_result: (event: { tsMs: number; turnId: string; id: string; result: string; durationMs: number }) => void;
+  delegate_query: (event: { tsMs: number; turnId: string; query: string; toolId?: string; toolName?: string }) => void;
+  delegate_result: (event: { tsMs: number; turnId: string; query: string; answer: string; durationMs: number; grounded: boolean; toolId?: string; toolName?: string }) => void;
+  /**
+   * G3: typed preamble/filler lifecycle for a pending tool call (Vapi-shaped:
+   * started / delayed / complete / failed). `delayed` is time-triggered by
+   * `delayCueAfterMs` while the call is still pending; `failed` fires on an LLM/bridge
+   * error, a barge-in, or a superseding turn while pending (R5). Transports surface
+   * these as `tool_call_*` wire messages — the standard "thinking" cue.
+   */
+  tool_call_cue: (event: { tsMs: number; turnId: string; phase: "started" | "delayed" | "complete" | "failed"; toolId: string; toolName: string; afterMs?: number }) => void;
   agent_first_audio: (event: { tsMs: number; turnId: string }) => void;
   agent_finished: (event: { tsMs: number; turnId: string } & Record<string, unknown>) => void;
   error: (event: { tsMs: number; stage: string; category: string; message: string }) => void;
@@ -187,6 +207,11 @@ interface TtsTextBuffer {
 /** Suffix marking a context created to speak an error fallback, so it never recurses. */
 const FALLBACK_CONTEXT_SUFFIX = ":error-fallback";
 
+/** Scheduler key for a pending tool call's G3 delayed-cue timer. */
+function toolCueTimerKey(contextId: string, toolId: string): string {
+  return `tool_cue:${contextId}:${toolId}`;
+}
+
 // =============================================================================
 // Session Implementation
 // =============================================================================
@@ -211,6 +236,10 @@ export class VoiceAgentSession {
   private readonly scheduler: Scheduler;
   private readonly ttsPlayout: TtsPlayoutClock;
   private interruptedGenerationContextIds = new Set<string>();
+  // Turns whose generation is in-flight (eos.turn_complete emitted, not yet
+  // finished/interrupted). Lets a client "stop" during the reasoner TTFT gap —
+  // before any audio plays — still abort the turn (thinking-phase barge-in, B3).
+  private generatingContextIds = new Set<string>();
   private ttsTextBuffers = new Map<string, TtsTextBuffer>();
   private readonly minInterruptionMs: number;
   private readonly primarySpeakerGate: PrimarySpeakerGate;
@@ -227,6 +256,9 @@ export class VoiceAgentSession {
   private firstTtsAudioFired = new Set<string>();
   private readonly errorFallbackText: string;
   private fallbackInjectedContexts = new Set<string>();
+  // G3: pending tool calls per context (toolId → toolName) driving the tool_call_cue lifecycle.
+  private readonly delayCueAfterMs: number;
+  private pendingToolCues = new Map<string, Map<string, string>>();
   private readonly endpointingOwner: "provider_stt" | "smart_turn" | "timer";
   private lastFinalizedContextId = "";
 
@@ -241,6 +273,7 @@ export class VoiceAgentSession {
     this.ttsPlayout = new TtsPlayoutClock(this.scheduler);
     this.sttForceFinalizeTimeoutMs = config.sttForceFinalizeTimeoutMs ?? 7000;
     this.minInterruptionMs = config.minInterruptionMs ?? 280;
+    this.delayCueAfterMs = config.delayCueAfterMs ?? 2000;
     this.primarySpeakerGate = new PrimarySpeakerGate({
       enabled: config.primarySpeakerBargeInEnabled !== false,
     });
@@ -394,6 +427,10 @@ export class VoiceAgentSession {
     this.ttsTextBuffers.clear();
     this.interruptedGenerationContextIds.clear();
     this.firstLlmDeltaReceived.clear();
+    for (const [contextId, pending] of this.pendingToolCues) {
+      for (const toolId of pending.keys()) this.scheduler.cancel(toolCueTimerKey(contextId, toolId));
+    }
+    this.pendingToolCues.clear();
 
     // 2. Run finalize chain (reverse order)
     await runFinalizeChain(this.initSteps);
@@ -414,7 +451,16 @@ export class VoiceAgentSession {
   }
 
   requestClientInterrupt(contextId: string): void {
-    this.turnArbiter.commitClientInterrupt(contextId);
+    // Playing out → the arbiter owns the barge-in (primary-speaker reset + metrics).
+    if (this.ttsPlayout.isActive(contextId)) {
+      this.turnArbiter.commitClientInterrupt(contextId);
+      return;
+    }
+    // Thinking-phase barge-in (B3): no audio yet, but a generation is in-flight —
+    // abort it so "stop" during the reasoner TTFT gap is honored, not dropped.
+    if (this.generatingContextIds.has(contextId)) {
+      this.bus.push(Route.Critical, make.interruptDetected(contextId, Date.now(), "client"));
+    }
   }
 
   // =========================================================================
@@ -486,6 +532,10 @@ export class VoiceAgentSession {
     this.bus.on("llm.tool_call", this.handleLlmToolCall.bind(this));
     this.bus.on("llm.tool_result", this.handleLlmToolResult.bind(this));
 
+    // Delegate (Responder-Thinker) observability — G2, RFC bimodel-delegate-seam
+    this.bus.on("delegate.query", this.handleDelegateQuery.bind(this));
+    this.bus.on("delegate.result", this.handleDelegateResult.bind(this));
+
     // TTS
     this.bus.on("tts.audio", this.handleTtsAudio.bind(this));
     this.bus.on("tts.end", this.handleTtsEnd.bind(this));
@@ -699,6 +749,20 @@ export class VoiceAgentSession {
       this.bus.push(Route.Background, make.metric(pkt.contextId, "eos.duplicate_dropped", "1"));
       return;
     }
+
+    // A backchannel ("uh-huh", "okay") uttered WHILE the assistant is still speaking
+    // is not a turn (B4). Dropping it here does two things: it does NOT cancel the
+    // assistant's in-flight answer (the supersede path below would otherwise kill it),
+    // and it does NOT spawn a second LLM response to the backchannel (the double-reply
+    // bug). A backchannel with no assistant currently speaking IS a real turn — only
+    // suppress when another context's TTS is actively playing. (English-only classifier
+    // today — locale-aware backchannels are a separate improvement.)
+    const otherTtsActive = this.ttsPlayout.activeContexts().some((c) => c !== pkt.contextId);
+    if (otherTtsActive && isBackchannel(pkt.text)) {
+      this.bus.push(Route.Background, make.metric(pkt.contextId, "turn.backchannel_dropped", pkt.text));
+      return;
+    }
+
     this.lastFinalizedContextId = pkt.contextId;
 
     // Re-arm per-turn guard state for the next turn. Transports with a stable
@@ -711,6 +775,16 @@ export class VoiceAgentSession {
     this.interruptedGenerationContextIds.delete(pkt.contextId);
     this.fallbackInjectedContexts.delete(pkt.contextId);
 
+    // Supersede (L1): a new turn must cancel any still-active prior-turn TTS or
+    // generation. Without this, a false-EOS (early endpoint on a mid-sentence
+    // pause) starts turn N, the user resumes, turn N's already-emitted audio
+    // keeps synthesizing, and it plays over the user while turn N+1 is answered.
+    // The bridge supersedes the *LLM*; only the session can stop the *TTS*.
+    for (const activeCtx of this.ttsPlayout.activeContexts()) {
+      if (activeCtx !== pkt.contextId) this.cancelStaleGeneration(activeCtx, pkt.timestampMs);
+    }
+
+    this.generatingContextIds.add(pkt.contextId);
     this.currentTurnId = pkt.contextId;
     this.idleTimeout.setContextId(pkt.contextId);
 
@@ -727,8 +801,11 @@ export class VoiceAgentSession {
       timestampMs: pkt.timestampMs,
     });
 
-    // Stop idle timeout while LLM is processing
-    this.bus.push(Route.Main, make.stopIdleTimeout(pkt.contextId, Date.now(), false));
+    // Stop idle timeout while the LLM processes. The user just spoke — that is
+    // genuine engagement, so reset the idle *escalation* count (P2): a user who
+    // answers the first "are you there?" must not be escalated straight to the
+    // disconnect prompt later in the call.
+    this.bus.push(Route.Main, make.stopIdleTimeout(pkt.contextId, Date.now(), true));
 
     const fillerText = this.latencyFiller.start(pkt.contextId, pkt.text, pkt.timestampMs);
     if (fillerText) {
@@ -785,6 +862,7 @@ export class VoiceAgentSession {
   }
 
   private handleLlmDone(pkt: LlmResponseDonePacket): void {
+    this.generatingContextIds.delete(pkt.contextId);
     if (this.interruptedGenerationContextIds.has(pkt.contextId)) {
       this.ttsTextBuffers.delete(pkt.contextId);
       this.bus.push(Route.Background, make.metric(pkt.contextId, "llm.done_ignored_after_interrupt", "1"));
@@ -865,9 +943,101 @@ export class VoiceAgentSession {
       },
       timestampMs: pkt.timestampMs,
     });
+
+    // G3: arm the typed preamble/filler lifecycle for this pending tool call.
+    const pending = this.pendingToolCues.get(pkt.contextId) ?? new Map<string, string>();
+    pending.set(pkt.toolId, pkt.toolName);
+    this.pendingToolCues.set(pkt.contextId, pending);
+    this.emitToolCallCue(pkt.contextId, "started", pkt.toolId, pkt.toolName);
+    if (this.delayCueAfterMs > 0) {
+      const afterMs = this.delayCueAfterMs;
+      this.scheduler.schedule(toolCueTimerKey(pkt.contextId, pkt.toolId), afterMs, () => {
+        if (!this.pendingToolCues.get(pkt.contextId)?.has(pkt.toolId)) return;
+        this.emitToolCallCue(pkt.contextId, "delayed", pkt.toolId, pkt.toolName, afterMs);
+      });
+    }
+  }
+
+  private emitToolCallCue(
+    contextId: string,
+    phase: "started" | "delayed" | "complete" | "failed",
+    toolId: string,
+    toolName: string,
+    afterMs?: number,
+  ): void {
+    this.emit("tool_call_cue", {
+      tsMs: Date.now(),
+      turnId: contextId,
+      phase,
+      toolId,
+      toolName,
+      ...(afterMs !== undefined ? { afterMs } : {}),
+    });
+  }
+
+  /** G3: resolve one pending tool call with a terminal cue phase. */
+  private resolveToolCue(contextId: string, toolId: string, phase: "complete" | "failed"): void {
+    const pending = this.pendingToolCues.get(contextId);
+    const toolName = pending?.get(toolId);
+    if (toolName === undefined) return;
+    pending!.delete(toolId);
+    if (pending!.size === 0) this.pendingToolCues.delete(contextId);
+    this.scheduler.cancel(toolCueTimerKey(contextId, toolId));
+    this.emitToolCallCue(contextId, phase, toolId, toolName);
+  }
+
+  /** G3: fail every pending tool call for a context (error / barge-in / supersede). */
+  private failPendingToolCues(contextId: string): void {
+    const pending = this.pendingToolCues.get(contextId);
+    if (!pending) return;
+    for (const toolId of [...pending.keys()]) this.resolveToolCue(contextId, toolId, "failed");
+  }
+
+  private handleDelegateQuery(pkt: DelegateQueryPacket): void {
+    this.emit("delegate_query", {
+      tsMs: pkt.timestampMs,
+      turnId: pkt.contextId,
+      query: pkt.query,
+      toolId: pkt.toolId,
+      toolName: pkt.toolName,
+    });
+    this.debugPush({
+      component: "delegate",
+      type: "query",
+      data: {
+        context_id: pkt.contextId,
+        query: pkt.query,
+        ...(pkt.toolName ? { tool_name: pkt.toolName } : {}),
+      },
+      timestampMs: pkt.timestampMs,
+    });
+  }
+
+  private handleDelegateResult(pkt: DelegateResultPacket): void {
+    this.emit("delegate_result", {
+      tsMs: pkt.timestampMs,
+      turnId: pkt.contextId,
+      query: pkt.query,
+      answer: pkt.answer,
+      durationMs: pkt.durationMs,
+      grounded: pkt.grounded,
+      toolId: pkt.toolId,
+      toolName: pkt.toolName,
+    });
+    this.debugPush({
+      component: "delegate",
+      type: "result",
+      data: {
+        context_id: pkt.contextId,
+        duration_ms: String(pkt.durationMs),
+        grounded: String(pkt.grounded),
+      },
+      timestampMs: pkt.timestampMs,
+    });
   }
 
   private handleLlmToolResult(pkt: LlmToolResultPacket): void {
+    this.resolveToolCue(pkt.contextId, pkt.toolId, "complete");
     this.emit("agent_tool_result", {
       tsMs: pkt.timestampMs,
       turnId: pkt.contextId,
@@ -913,14 +1083,20 @@ export class VoiceAgentSession {
     // Audio just arrived — (re)arm the stall watchdog for this turn's TTS output.
     this.watchdogs.armTtsStallTimer(pkt.contextId);
 
-    // Extend idle timeout by audio duration to prevent timeout during playback.
+    // Mark active and advance this context's playout cursor by the chunk's
+    // realtime duration.
     const sampleRateHz = requireTtsAudioSampleRate(pkt.sampleRateHz);
     const audioDurationMs = estimatePcm16Duration(pkt.audio, sampleRateHz);
-    this.idleTimeout.extend(audioDurationMs);
+    const now = Date.now();
+    this.ttsPlayout.noteAudio(pkt.contextId, audioDurationMs, now);
 
-    // Mark active and advance this context's playout cursor by the chunk's
-    // realtime duration.
-    this.ttsPlayout.noteAudio(pkt.contextId, audioDurationMs, Date.now());
+    // Anchor the idle timer to when playout actually *ends* (P2), not to chunk
+    // arrival. TTS streams faster than realtime, so extending by each chunk's
+    // duration from arrival lets the timer fire mid-speech on a long answer.
+    // playoutEnd() is cumulative across chunks, so this re-arms to durationMs
+    // after the audio delivered so far finishes playing.
+    const playoutEndMs = this.ttsPlayout.playoutEnd(pkt.contextId);
+    this.idleTimeout.extend(playoutEndMs !== undefined ? Math.max(0, playoutEndMs - now) : audioDurationMs);
 
     this.debugPush({
       component: "tts",
@@ -938,6 +1114,7 @@ export class VoiceAgentSession {
   private handleTtsEnd(pkt: TextToSpeechEndPacket): void {
     // Generation finished, but the streamed audio is still playing out. Keep the
     // context interruptible until its playout estimate elapses, then release it.
+    this.generatingContextIds.delete(pkt.contextId);
     this.ttsPlayout.scheduleRelease(pkt.contextId, Date.now());
     this.watchdogs.clearTtsStallTimerFor(pkt.contextId);
     this.debugPush({
@@ -954,6 +1131,7 @@ export class VoiceAgentSession {
 
   private handleInterruptDetected(pkt: InterruptionDetectedPacket): void {
     this.interruptedGenerationContextIds.add(pkt.contextId);
+    this.failPendingToolCues(pkt.contextId); // G3: the aborted delegate's cue fails (R5)
     this.latencyFiller.cancel(pkt.contextId);
     this.firstLlmDeltaReceived.delete(pkt.contextId);
     this.ttsTextBuffers.delete(pkt.contextId);
@@ -990,6 +1168,28 @@ export class VoiceAgentSession {
     // segments into the next turn when a client reuses the same contextId
     // (the provider STT plugins listen for interrupt.stt; previously unfired).
     this.bus.push(Route.Critical, make.interruptStt(pkt.contextId, pkt.timestampMs));
+    this.generatingContextIds.delete(pkt.contextId);
+  }
+
+  /**
+   * Cancel a stale prior-turn generation/playout when a new turn supersedes it
+   * (L1). Mirrors the interrupt teardown but without the barge-in metrics — this
+   * is a turn boundary, not a user interruption. Stops leftover TTS audio, aborts
+   * the LLM, and drops late deltas/audio for the stale context.
+   */
+  private cancelStaleGeneration(contextId: string, timestampMs: number): void {
+    this.interruptedGenerationContextIds.add(contextId);
+    this.failPendingToolCues(contextId); // G3: a superseded turn's pending cue fails
+    this.generatingContextIds.delete(contextId);
+    this.latencyFiller.cancel(contextId);
+    this.firstLlmDeltaReceived.delete(contextId);
+    this.ttsTextBuffers.delete(contextId);
+    this.ttsPlayout.release(contextId);
+    this.watchdogs.clearTtsStallTimerFor(contextId);
+    this.bus.push(Route.Critical, make.recordAssistantTruncate(contextId, Date.now()));
+    this.bus.push(Route.Critical, make.interruptTts(contextId, timestampMs));
+    this.bus.push(Route.Critical, make.interruptLlm(contextId, timestampMs));
+    this.bus.push(Route.Background, make.metric(contextId, "supersede.cancelled_stale_generation", "1"));
   }
 
   private handleComponentError(pkt: VoiceErrorPacket): void {
@@ -1011,7 +1211,12 @@ export class VoiceAgentSession {
       timestampMs: pkt.timestampMs,
     });
 
+    // G3: an LLM/bridge error while a tool call is pending means no result is coming.
+    if (pkt.component === "llm" || pkt.component === "bridge") {
+      this.failPendingToolCues(pkt.contextId);
+    }
     this.latencyFiller.clear(pkt.contextId);
+    this.generatingContextIds.delete(pkt.contextId);
     // The packet's own recoverability verdict is authoritative when present: the
     // bus marks handler exceptions (pipeline.error) recoverable by design — one
     // misbehaving handler must degrade the turn, not kill the whole call.

package/src/voice-text.test.ts

@@ -25,6 +25,19 @@ describe("isCompleteVoiceText", () => {
     expect(isCompleteVoiceText("مرحبا؟")).toBe(true); // Arabic question mark
     expect(isCompleteVoiceText("नमस्ते।")).toBe(true); // Devanagari danda
   });
+
+  it("does not treat abbreviation or decimal dots as sentence ends", () => {
+    // These would otherwise be voiced with a falling intonation and split from
+    // their continuation ("Dr." | "Smith", "twelve." | "fifty").
+    expect(isCompleteVoiceText("Dr.")).toBe(false);
+    expect(isCompleteVoiceText("e.g.")).toBe(false);
+    expect(isCompleteVoiceText("The total is $12.")).toBe(false);
+    expect(isCompleteVoiceText("Meet at 3 p.m.")).toBe(false);
+    expect(isCompleteVoiceText("His name is J.")).toBe(false);
+    // But a real sentence end after an abbreviation earlier in the text is fine.
+    expect(isCompleteVoiceText("Dr. Smith will see you now.")).toBe(true);
+    expect(isCompleteVoiceText("The total is $12.50 today.")).toBe(true);
+  });
 });
 
 describe("takeCompleteVoiceText", () => {

package/src/voice-text.ts

@@ -33,12 +33,41 @@ export function takeCompleteVoiceText(text: string): { text: string; remaining:
   return { text: emitted.trimEnd(), remaining };
 }
 
+// Common abbreviations whose trailing "." is not a sentence end. Lowercased,
+// dots stripped, so "e.g." matches "eg". Kept small and English-centric — the
+// turn-end flush handles anything that legitimately ends here.
+const ABBREVIATIONS = new Set([
+  "mr", "mrs", "ms", "dr", "prof", "sr", "jr", "st", "vs", "etc", "eg", "ie",
+  "am", "pm", "no", "vol", "inc", "ltd", "co", "gen", "gov", "sen", "rep",
+  "apt", "dept", "approx", "est", "min", "max",
+]);
+
+/**
+ * A segment ending in "." is not necessarily a finished sentence: it may be a
+ * decimal point ("$12." before "50") or an abbreviation dot ("Dr." before a
+ * name, "e.g."). Voicing those as sentence ends produces "twelve." (falling
+ * intonation) … "fifty", or splits "Dr." from the name. Defer them — if nothing
+ * follows, the turn-end flush still speaks the tail.
+ */
+function isFalseTerminalDot(endsWithDot: string): boolean {
+  const beforeDot = endsWithDot.slice(0, -1);
+  if (/\d$/.test(beforeDot)) return true; // decimal / ordinal: "12." , "$3."
+  const word = beforeDot.match(/([A-Za-z][A-Za-z.]*)$/);
+  if (!word) return false;
+  const normalized = word[1]!.replace(/\./g, "").toLowerCase();
+  if (ABBREVIATIONS.has(normalized)) return true;
+  if (normalized.length === 1) return true; // single initial: "J."
+  return false;
+}
+
 export function isCompleteVoiceText(text: string): boolean {
   const trimmed = text.trim();
   for (let index = trimmed.length - 1; index >= 0; index -= 1) {
     const char = trimmed[index]!;
     if (isClosingPunctuation(char)) continue;
-    return isTerminalPunctuation(char);
+    if (!isTerminalPunctuation(char)) return false;
+    if (char === "." && isFalseTerminalDot(trimmed.slice(0, index + 1))) return false;
+    return true;
   }
   return false;
 }
@@ -68,8 +97,19 @@ function isTerminalPunctuation(char: string): boolean {
     char === "॥";
 }
 
+// The ICU sentence segmenter is one of the more expensive Intl allocations;
+// building one per LLM delta (50–200/turn) is avoidable CPU/GC churn on the
+// token→TTS latency path. It is stateless, so cache one per process. `undefined`
+// = not yet computed; `null` = unavailable (fall back to the regex splitter).
+let cachedSegmenter: { segment(text: string): Iterable<SentenceSegment> } | null | undefined;
+
+function getSentenceSegmenter(): { segment(text: string): Iterable<SentenceSegment> } | null {
+  if (cachedSegmenter === undefined) cachedSegmenter = createSentenceSegmenter();
+  return cachedSegmenter;
+}
+
 function segmentSentences(text: string): string[] {
-  const segmenter = createSentenceSegmenter();
+  const segmenter = getSentenceSegmenter();
   if (segmenter) {
     return Array.from(segmenter.segment(text), (part) => part.segment);
   }