@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/calls/call-transport.ts

@@ -98,4 +98,20 @@ export interface CallTransport {
    * this — the controller then treats playback as already drained.
    */
   awaitPlaybackDrained?(): Promise<void>;
+
+  /**
+   * Whether no assistant speech is buffered, queued, in flight, or
+   * (estimatedly) still playing to the caller. Progress narration speaks
+   * only into audible silence, so it asks before every update. Transports
+   * that play speech synchronously may omit this; the controller then
+   * treats the transport as idle.
+   */
+  isPlaybackIdle?(): boolean;
+
+  /**
+   * Wall-clock estimate of when audio already sent finishes playing to the
+   * caller, 0 when nothing is playing. Anchors the dead-air countdown for
+   * progress narration to when the caller last heard something.
+   */
+  playbackTailUntilMs?(): number;
 }

package/src/calls/media-stream-output.ts

@@ -327,6 +327,14 @@ export class MediaStreamOutput implements CallTransport {
   /** True when the queue drain loop is actively running. */
   private draining = false;
 
+  /**
+   * Estimated wall-clock instant the audio already sent to Twilio finishes
+   * playing to the caller. Frames leave faster than real time and Twilio
+   * buffers them, so the only local view of "still audible" is this running
+   * sum of sent frame durations; a `clear` drops the buffer and resets it.
+   */
+  private playbackTailAtMs = 0;
+
   /** Abort controller for the currently in-flight synthesis/fetch. */
   private activePlaybackAbort: AbortController | null = null;
 
@@ -659,6 +667,7 @@ export class MediaStreamOutput implements CallTransport {
       return;
     }
     this.sendClearCommand();
+    this.playbackTailAtMs = 0;
     // Twilio drops its buffered audio (and the marks within it) on `clear`, so
     // any end-of-turn mark already sent will never echo. Treat those as drained
     // so a pending end-call drain wait resolves instead of stalling on the cap.
@@ -716,6 +725,24 @@ export class MediaStreamOutput implements CallTransport {
     return this.playbackQueue.length;
   }
 
+  /**
+   * Whether no speech is buffered toward a sentence, queued, being
+   * synthesized or fetched, or (estimatedly) still playing at Twilio.
+   */
+  isPlaybackIdle(): boolean {
+    return (
+      this.textBuffer.length === 0 &&
+      this.playbackQueue.length === 0 &&
+      !this.draining &&
+      Date.now() >= this.playbackTailAtMs
+    );
+  }
+
+  /** See {@link CallTransport.playbackTailUntilMs}. */
+  playbackTailUntilMs(): number {
+    return this.playbackTailAtMs;
+  }
+
   /**
    * Runtime check for closed state. Used instead of direct property access
    * in async methods because TypeScript's control flow analysis cannot
@@ -772,6 +799,7 @@ export class MediaStreamOutput implements CallTransport {
     this.playbackQueue.length = 0;
     this.playbackVersion++;
     this.audioStartCallback = null;
+    this.playbackTailAtMs = 0;
     if (this.activePlaybackAbort) {
       this.activePlaybackAbort.abort();
       this.activePlaybackAbort = null;
@@ -854,6 +882,10 @@ export class MediaStreamOutput implements CallTransport {
     for (const frame of frames) {
       this.sendAudioPayload(frame);
     }
+    const durationMs =
+      (frames.length * MULAW_FRAME_SIZE * 1000) / TELEPHONY_SAMPLE_RATE_HZ;
+    this.playbackTailAtMs =
+      Math.max(Date.now(), this.playbackTailAtMs) + durationMs;
   }
 
   /**

package/src/calls/media-stream-server.ts

@@ -47,6 +47,11 @@ import { addMessage } from "../persistence/conversation-crud.js";
 import { resolveGuardianName } from "../prompts/user-reference.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { getLogger } from "../util/logger.js";
+import {
+  type BargeInGuard,
+  createBargeInGuard,
+  DEFAULT_BARGE_IN_MIN_SPEECH_MS,
+} from "./barge-in-guard.js";
 import { CallController } from "./call-controller.js";
 import {
   formatDuration,
@@ -188,6 +193,8 @@ export class MediaStreamCallSession {
   private bargeInAccepted = 0;
   /** Number of barge-in attempts that were ignored (assistant not speaking). */
   private bargeInIgnored = 0;
+  /** Armed by caller speech while a turn or its tail is interruptible. */
+  private bargeInGuard: BargeInGuard | null = null;
   /** Number of turn-start transitions detected by the STT session. */
   private turnStarts = 0;
   /** Number of transcript finals produced (non-empty). */
@@ -215,6 +222,9 @@ export class MediaStreamCallSession {
     // Create STT session with callbacks wired to the controller.
     const callbacks: MediaStreamSttSessionCallbacks = {
       onSpeechStart: () => this.handleSpeechStart(),
+      onMediaFrame: (hasSpeech, durationMs) =>
+        this.handleMediaFrame(hasSpeech, durationMs),
+      onSpeechEnd: () => this.handleSpeechEnd(),
       onTranscriptFinal: (text, durationMs) =>
         this.handleTranscriptFinal(text, durationMs),
       onDtmf: (digit) => this.handleDtmf(digit),
@@ -768,38 +778,80 @@ export class MediaStreamCallSession {
 
   private handleSpeechStart(): void {
     this.turnStarts++;
+  }
 
-    // Barge-in: clear queued outbound audio and abort the in-flight LLM
-    // turn only when the assistant is actively speaking. Uses the gated
-    // handleBargeIn path so initial inbound audio frames do not cancel a
-    // still-starting initial turn.
-    //
-    // clearAudio runs via the onAccepted hook so it only fires when the
-    // barge-in passes the speaking gate — an ignored barge-in (controller
-    // idle/processing) must not flush queued/in-flight TTS such as a
-    // buffered greeting. The hook runs before handleInterrupt so the
-    // end-of-turn mark it enqueues survives the queue flush.
-    if (this.output && this.controller) {
-      const output = this.output;
-      const accepted = this.controller.handleBargeIn(() => output.clearAudio());
-      if (accepted) {
-        this.bargeInAccepted++;
-        log.info(
-          { callSessionId: this.callSessionId },
-          "Media-stream barge-in accepted — cleared outbound audio",
-        );
-      } else {
-        // No turn to abort, but a completed turn's tail can still be
-        // playing from Twilio's buffer — flush only that buffer so the
-        // caller isn't talked over. Queued speech that hasn't reached
-        // Twilio yet (greeting, handoff prompt) is preserved.
-        output.clearBufferedAudio();
-        this.bargeInIgnored++;
-        log.debug(
-          { callSessionId: this.callSessionId },
-          "Media-stream barge-in ignored — assistant not speaking",
-        );
+  // Sustained-speech barge-in guard, fed by every inbound frame. Speech only
+  // counts while there is something to interrupt: an assistant turn in
+  // flight (thinking or speaking) or a completed turn's tail still playing
+  // from Twilio's buffer. Outside that window the guard is dropped, so
+  // speech from the caller's own utterance never carries into a turn that
+  // starts before the local VAD has ended the utterance (a streaming final
+  // can start the turn first). A speech frame inside the window arms the
+  // guard; a fired guard reaches the controller. A line click, a cough, or
+  // TTS bleed never gets that far.
+  private handleMediaFrame(hasSpeech: boolean, durationMs: number): void {
+    if (!this.output || !this.controller) {
+      return;
+    }
+    const bargeable =
+      this.controller.getState() !== "idle" || !this.output.isPlaybackIdle();
+    if (!bargeable) {
+      this.bargeInGuard = null;
+      return;
+    }
+    if (this.bargeInGuard === null) {
+      if (!hasSpeech) {
+        return;
       }
+      this.bargeInGuard = createBargeInGuard(DEFAULT_BARGE_IN_MIN_SPEECH_MS);
+    }
+    const step = this.bargeInGuard.track(
+      hasSpeech ? "speech" : "silence",
+      durationMs,
+    );
+    if (step === "fired") {
+      this.bargeInGuard = null;
+      this.fireBargeIn();
+    }
+  }
+
+  private handleSpeechEnd(): void {
+    // An untripped guard was noise or a fragment: the run never reached the
+    // threshold before the caller's turn ended.
+    this.bargeInGuard = null;
+  }
+
+  // Sustained caller speech landed: clear queued outbound audio and abort
+  // the in-flight LLM turn when one is in flight (thinking or speaking).
+  //
+  // clearAudio runs via the onAccepted hook so it only fires when the
+  // barge-in passes the controller's gate; an ignored barge-in (controller
+  // idle) must not flush queued/in-flight TTS such as a buffered greeting.
+  // The hook runs before handleInterrupt so the end-of-turn mark it
+  // enqueues survives the queue flush.
+  private fireBargeIn(): void {
+    if (!this.output || !this.controller) {
+      return;
+    }
+    const output = this.output;
+    const accepted = this.controller.handleBargeIn(() => output.clearAudio());
+    if (accepted) {
+      this.bargeInAccepted++;
+      log.info(
+        { callSessionId: this.callSessionId },
+        "Media-stream barge-in accepted: cleared outbound audio",
+      );
+    } else {
+      // No turn to abort, but a completed turn's tail can still be
+      // playing from Twilio's buffer, so flush only that buffer so the
+      // caller isn't talked over. Queued speech that hasn't reached
+      // Twilio yet (greeting, handoff prompt) is preserved.
+      output.clearBufferedAudio();
+      this.bargeInIgnored++;
+      log.debug(
+        { callSessionId: this.callSessionId },
+        "Media-stream barge-in ignored: no turn in flight",
+      );
     }
   }
 

package/src/calls/media-stream-stt-session.ts

@@ -120,6 +120,16 @@ export interface MediaStreamSttSessionCallbacks {
   /** Called when the turn detector transitions to active (first speech-bearing chunk). */
   onSpeechStart?: () => void;
 
+  /**
+   * Called for every inbound frame with the local VAD's verdict on it and
+   * the frame's duration. Drives the sustained-speech barge-in guard, which
+   * needs the silence frames inside a detector turn as well as the speech.
+   */
+  onMediaFrame?: (hasSpeech: boolean, durationMs: number) => void;
+
+  /** Called when the turn detector ends the caller's turn (silence or cap). */
+  onSpeechEnd?: () => void;
+
   /**
    * Called when a completed caller utterance has been transcribed.
    *
@@ -255,6 +265,7 @@ export class MediaStreamSttSession {
         this.callbacks.onSpeechStart?.();
       },
       onTurnEnd: (reason, durationMs) => {
+        this.callbacks.onSpeechEnd?.();
         void this.handleTurnEnd(reason, durationMs);
       },
     });
@@ -377,6 +388,10 @@ export class MediaStreamSttSession {
     const raw = Buffer.from(event.media.payload, "base64");
     const hasSpeech = detectSpeechActivity(raw);
     this.turnDetector.onMediaChunk(hasSpeech);
+    this.callbacks.onMediaFrame?.(
+      hasSpeech,
+      raw.length / (TELEPHONY_SOURCE_SAMPLE_RATE / 1000),
+    );
 
     if (this.mode === "batch") {
       this.currentTurnChunks.push(event.media.payload);

package/src/{live-voice → calls}/progress-narration.ts

@@ -5,7 +5,7 @@
  * The voice front door owns hold, escalation, and direct-response behavior.
  */
 
-import type { LiveVoiceProgressConfig } from "../config/schemas/live-voice.js";
+import type { VoiceProgressConfig } from "../config/schemas/voice.js";
 import {
   extractToolUse,
   getConfiguredProvider,
@@ -216,7 +216,7 @@ export function effectiveSpokenTextMaxChars(
 }
 
 export function createVoiceProgressNarrator(options: {
-  config: LiveVoiceProgressConfig;
+  config: VoiceProgressConfig;
   /** Provider resolver, injectable for tests. */
   getProvider?: () => Promise<Provider | null>;
 }): VoiceProgressNarrator {

package/src/calls/resolve-call-tts-provider.ts

@@ -8,6 +8,7 @@
  */
 
 import { loadConfig } from "../config/loader.js";
+import { resolveEffectiveSpeechProviders } from "../config/managed-speech-defaults.js";
 import {
   getCatalogProvider,
   getTtsProvider,
@@ -73,6 +74,13 @@ export interface ResolveCallTtsOptions {
 /**
  * Resolve the active TTS provider via the global provider abstraction.
  *
+ * The provider is the effective one after managed-speech defaulting
+ * ({@link resolveEffectiveSpeechProviders}): a configured BYOK provider
+ * whose credential does not resolve is stood in for by managed speech
+ * while the platform connection is usable, the same substitution live
+ * voice makes, so a fresh Vellum connection speaks on the phone with zero
+ * TTS configuration.
+ *
  * The native-vs-synthesized decision is driven by the catalog's
  * `callMode` field via {@link resolveCallStrategy}. Providers with
  * `callMode: "synthesized-play"` have their audio streamed through the
@@ -94,10 +102,11 @@ export async function resolveCallTtsProvider(
 ): Promise<ResolvedCallTts> {
   try {
     const config = loadConfig();
-    const resolved = resolveTtsConfig(config);
+    const effectiveProviderId = await effectiveTtsProviderId(config);
+    const resolved = resolveTtsConfig(config, effectiveProviderId);
 
     // Use the catalog's callMode to decide the call path.
-    const strategy = resolveCallStrategy(config);
+    const strategy = resolveCallStrategy(config, effectiveProviderId);
 
     let providerId = resolved.provider;
     let useSynthesizedPath = strategy.callMode === "synthesized-play";
@@ -175,6 +184,28 @@ export async function resolveCallTtsProvider(
   }
 }
 
+/**
+ * The TTS provider the call actually uses after managed-speech defaulting.
+ * A failure inside the managed lookup (platform client, credential store)
+ * keeps the configured provider: a managed-speech hiccup must not demote a
+ * working BYOK provider, and the outer resolver's own fallback is the
+ * silent native path.
+ */
+async function effectiveTtsProviderId(
+  config: ReturnType<typeof loadConfig>,
+): Promise<TtsProviderId | undefined> {
+  try {
+    const { tts } = await resolveEffectiveSpeechProviders(config);
+    return tts;
+  } catch (err) {
+    log.warn(
+      { err },
+      "Managed-speech defaulting failed for call TTS; keeping the configured provider",
+    );
+    return undefined;
+  }
+}
+
 /**
  * Decode a resolved call audio format into the provider request format
  * and the audio-store format.

package/src/calls/tts-call-strategy.ts

@@ -40,17 +40,21 @@ export interface TtsCallStrategy {
 }
 
 /**
- * Resolve the call strategy for the currently configured TTS provider.
+ * Resolve the call strategy for the active TTS provider.
  *
- * Reads the active provider from config via {@link resolveTtsConfig},
- * then looks up the provider's `callMode` in the catalog.
+ * Reads the provider from config via {@link resolveTtsConfig} (or takes
+ * `providerOverride`, the provider a caller already resolved after
+ * managed-speech defaulting), then looks up its `callMode` in the catalog.
  *
  * Falls back to `native-twilio` with `"elevenlabs"` when the config
  * or catalog is unavailable (e.g. test mocks, pre-migration configs).
  */
-export function resolveCallStrategy(config: AssistantConfig): TtsCallStrategy {
+export function resolveCallStrategy(
+  config: AssistantConfig,
+  providerOverride?: TtsProviderId,
+): TtsCallStrategy {
   try {
-    const resolved = resolveTtsConfig(config);
+    const resolved = resolveTtsConfig(config, providerOverride);
     const catalogEntry = getCatalogProvider(resolved.provider);
     return {
       providerId: catalogEntry.id,

package/src/calls/types.ts

@@ -11,6 +11,8 @@ export type CallEventType =
   | "call_connected"
   | "caller_spoke"
   | "assistant_spoke"
+  | "tool_use_started"
+  | "tool_use_completed"
   | "user_question_asked"
   | "user_answered"
   | "user_instruction_relayed"

package/src/calls/voice-control-protocol.ts

@@ -29,11 +29,11 @@ export const HOLD_VERDICT_TOKEN = "[0]";
 export const ESCALATE_VERDICT_TOKEN = "[1]";
 
 /**
- * Emitted inline by the main/escalated voice leg to ask the live-voice
- * client to minimize the voice room and reveal the screen behind it
- * (e.g. after creating an app worth showing). Advisory: the daemon
- * translates it into a `minimize_room` server frame after the turn's TTS
- * drains; it is never spoken and never persisted.
+ * Room-minimize token, kept in the marker table so it is stripped from
+ * speech and from persisted rows. No prompt teaches it: the live-voice
+ * session decides a minimize from whether a ui-surface tool ran during the
+ * turn (`revealsUiSurface` on `tool_result`) and sends the `minimize_room`
+ * frame itself, so a model that emits this token regardless moves nothing.
  */
 export const MINIMIZE_ROOM_MARKER = "[-1]";
 
@@ -192,9 +192,9 @@ export function stripInternalSpeechMarkers(text: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * All known control marker prefixes. Used by couldBeControlMarker to detect
- * whether a buffer that starts with `[` might be the beginning of a control
- * marker (and should therefore be held rather than flushed to TTS).
+ * All known control marker prefixes. Used by isIncompleteControlMarkerTail to
+ * detect whether a buffer that starts with `[` might be the beginning of a
+ * control marker (and should therefore be held rather than flushed to TTS).
  */
 const CONTROL_MARKER_STRINGS = [
   "[ASK_GUARDIAN_APPROVAL:",
@@ -211,19 +211,6 @@ const CONTROL_MARKER_STRINGS = [
   "[GUARDIAN_UNAVAILABLE]",
 ];
 
-/**
- * Check whether `text` could be a partial or complete control marker.
- *
- * Returns true if any known marker string is a prefix of `text`
- * (text starts with the marker) or `text` is a prefix of a marker
- * (the marker starts with text — i.e. text is still being streamed).
- */
-export function couldBeControlMarker(text: string): boolean {
-  return CONTROL_MARKER_STRINGS.some(
-    (marker) => marker.startsWith(text) || text.startsWith(marker),
-  );
-}
-
 // Colon-style markers whose bodies terminate at the first "]" — their strip
 // regexes are non-greedy (`.+?\]`), so the first bracket IS the terminator.
 // ASK_GUARDIAN_APPROVAL is deliberately absent: its balanced-JSON body may
@@ -267,3 +254,48 @@ export function isIncompleteControlMarkerTail(tail: string): boolean {
   }
   return false;
 }
+
+/**
+ * Control-marker hygiene for one model leg's streamed text, shared by the
+ * phone call controller and the live-voice session. The returned flush is
+ * called with the leg's cumulative raw text so far and forwards, through
+ * `emit`, the stripped ({@link stripInternalSpeechMarkers}) prefix that has
+ * not been emitted yet and cannot contain a still-streaming control marker:
+ * the flush stops at the first "[" whose tail is an incomplete marker
+ * ({@link isIncompleteControlMarkerTail}) and holds from there until a later
+ * delta completes or disproves it. `force` (leg completion) emits the held
+ * tail so real text that merely resembles a marker prefix is not dropped.
+ *
+ * The scan runs forward from the emitted boundary, not from the last "[", so
+ * brackets INSIDE a streaming marker body (a JSON array or "]"-bearing string
+ * in ASK_GUARDIAN_APPROVAL) can neither mask the marker's start nor pass as
+ * its terminator. Markers are stripped, never acted on: a consumer that acts
+ * on a marker reads the leg's full raw text for it separately.
+ */
+export function createControlMarkerHoldback(
+  emit: (chunk: string) => void,
+): (raw: string, opts?: { force?: boolean }) => void {
+  let emitted = 0;
+  return (raw, opts) => {
+    let safeEnd = raw.length;
+    if (opts?.force !== true) {
+      for (
+        let i = raw.indexOf("[", emitted);
+        i !== -1;
+        i = raw.indexOf("[", i + 1)
+      ) {
+        if (isIncompleteControlMarkerTail(raw.slice(i))) {
+          safeEnd = i;
+          break;
+        }
+      }
+    }
+    if (safeEnd > emitted) {
+      const chunk = stripInternalSpeechMarkers(raw.slice(emitted, safeEnd));
+      emitted = safeEnd;
+      if (chunk.length > 0) {
+        emit(chunk);
+      }
+    }
+  };
+}

package/src/calls/voice-leg-coordinator.ts

@@ -0,0 +1,189 @@
+/**
+ * The front-door leg coordinator, shared by the live-voice session and the
+ * phone call controller.
+ *
+ * A triaged voice turn opens on a fast, toolless front-door leg whose
+ * leading tokens carry its verdict (see `voice-triage-escalate.ts`). The
+ * coordinator reads that leg's raw stream through the verdict machine and
+ * sequences what follows: an answer is released as speech, a hold discards
+ * a speculative turn, and an escalate verdict hands the turn off to the
+ * escalated leg with a spoken bridge. The hand-off order is the part that
+ * must not drift between drivers: pause narration, abort the front-door
+ * leg, resolve and speak the bridge, mark it as the floor holder, start the
+ * escalated leg, re-arm narration. A leg that was cancelled never hands off.
+ *
+ * Everything transport-specific comes in through {@link FrontDoorLegHost}:
+ * how answer text and the bridge are spoken, how a leg is started or
+ * aborted, and the speculative hold and commit that only live voice has.
+ */
+
+import type { ProgressCadence } from "./voice-progress-cadence.js";
+import {
+  createFrontDoorVerdictMachine,
+  ESCALATION_CONTINUATION_CONTENT,
+  resolveSpokenEscalationBridge,
+} from "./voice-triage-escalate.js";
+
+/** The phrase spoken across the hand-off, as {@link resolveSpokenEscalationBridge} settles it. */
+export type SpokenEscalationBridge = ReturnType<
+  typeof resolveSpokenEscalationBridge
+>;
+
+/** The leg that answers for real after the front-door leg handed off. */
+export interface EscalatedLeg {
+  content: string;
+  routingLeg: "escalated";
+  /**
+   * The bridge the listener heard, quoted to the escalated continuation
+   * rule so the quality model does not re-announce it.
+   */
+  spokenEscalationBridge: string;
+}
+
+/**
+ * The escalated leg for a hand-off whose bridge was `spokenBridge`. The
+ * bridge pins this leg to the conversation's own profile, so no profile
+ * override rides along.
+ */
+export function escalatedLegFor(spokenBridge: string): EscalatedLeg {
+  return {
+    content: ESCALATION_CONTINUATION_CONTENT,
+    routingLeg: "escalated",
+    spokenEscalationBridge: spokenBridge,
+  };
+}
+
+/** The driver's half of a front-door leg. */
+export interface FrontDoorLegHost {
+  /**
+   * Whether the turn is still live: not cancelled, not finalized. A dead
+   * turn must not spawn an escalated leg.
+   */
+  isLive(): boolean;
+  /** The turn's spoken language, for the canned bridge. */
+  language(): string | undefined;
+  /**
+   * Progress narration to pause across the hand-off: the bridge holds the
+   * floor, and audible-silence gating keeps narration quiet until it has
+   * played on the escalated leg.
+   */
+  progress?: Pick<ProgressCadence, "clear" | "noteFloorHolder" | "arm">;
+  /**
+   * Speculative legs only: the model judged the speaker mid-thought, so the
+   * leg is discarded and listening continues.
+   */
+  onHold?(): void;
+  /**
+   * Speculative legs only: commit the turn before acting on an answer or
+   * escalate verdict. Returns false when the turn is gone, which stops the
+   * verdict from being acted on.
+   */
+  commit?(): boolean;
+  /**
+   * Answer text released by the verdict machine, in stream order. On the
+   * transition it includes the leading text held while the verdict was
+   * pending. The driver runs its own control-marker holdback over it.
+   */
+  onAnswerText(text: string): void;
+  /**
+   * Abort the front-door leg so a model that keeps generating past the
+   * bridge cap adds no latency before the escalated leg starts.
+   */
+  abortLeg(): void;
+  /**
+   * Speak the bridge so the strong-model call has no dead air. The model's
+   * own bridge is real assistant speech; the canned fallback is audio-only,
+   * matching the row the bridge's transcript hygiene deletes for it.
+   */
+  speakBridge(bridge: SpokenEscalationBridge): void;
+  /** Start the escalated leg on the same turn. */
+  startEscalatedLeg(leg: EscalatedLeg): void;
+}
+
+export interface FrontDoorLegCoordinator {
+  /** Whether this leg handed the turn off to the escalated leg. */
+  readonly handedOff: boolean;
+  /** Feed one raw delta of the front-door leg's stream. */
+  push(text: string): void;
+  /**
+   * The leg completed normally (not cancelled). A leg that stopped
+   * mid-bridge (a bare escalate verdict, or a holding phrase with no
+   * sentence terminator) hands off now with what arrived; the canned
+   * fallback covers an empty bridge. Returns whether the leg handed off.
+   */
+  complete(): boolean;
+}
+
+export function createFrontDoorLegCoordinator(options: {
+  /**
+   * Whether the leg's decision rule teaches the hold token: true only for
+   * speculative legs, whose leading tokens are interpreted.
+   */
+  holdEnabled: boolean;
+  host: FrontDoorLegHost;
+}): FrontDoorLegCoordinator {
+  const { host } = options;
+  const verdict = createFrontDoorVerdictMachine(options.holdEnabled);
+  let handedOff = false;
+
+  const handOff = (cappedBridge: string): void => {
+    if (handedOff || !host.isLive()) {
+      return;
+    }
+    handedOff = true;
+    host.progress?.clear();
+    host.abortLeg();
+    const bridge = resolveSpokenEscalationBridge(cappedBridge, host.language());
+    host.speakBridge(bridge);
+    // The bridge is the turn's spoken acknowledgement: narration keeps its
+    // minimum gap from it rather than following it back to back.
+    host.progress?.noteFloorHolder();
+    host.startEscalatedLeg(escalatedLegFor(bridge.spokenBridge));
+    // The escalated leg runs the slowest work in the system, and the bridge
+    // only covers its first couple of seconds: the dead air narration
+    // exists for.
+    host.progress?.arm();
+  };
+
+  return {
+    get handedOff() {
+      return handedOff;
+    },
+    push(text) {
+      if (handedOff) {
+        return;
+      }
+      const step = verdict.push(text);
+      if (step.kind === "hold") {
+        host.onHold?.();
+        return;
+      }
+      if (
+        (step.kind === "escalate" || step.kind === "answer") &&
+        host.commit !== undefined &&
+        !host.commit()
+      ) {
+        return;
+      }
+      if (step.kind === "answer") {
+        host.onAnswerText(step.text);
+        return;
+      }
+      if (
+        (step.kind === "escalate" || step.kind === "bridge") &&
+        step.bridge !== null
+      ) {
+        handOff(step.bridge);
+      }
+    },
+    complete() {
+      if (!handedOff && host.isLive()) {
+        const step = verdict.finish();
+        if (step.kind === "bridge") {
+          handOff(step.bridge);
+        }
+      }
+      return handedOff;
+    },
+  };
+}