@vellumai/assistant 0.12.1 → 0.12.2-staging.2

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,14 +29,37 @@ 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]";
 
+/**
+ * Mic-mute session control for live voice: `[MUTE]` mutes until the user
+ * unmutes, `[MUTE:<seconds>]` mutes for that long. Like {@link END_CALL_MARKER}
+ * on a live-voice session, it is acted on only at the very end of a reply
+ * (see {@link parseTerminalSessionControl}), after the acknowledgement that
+ * precedes it has been spoken.
+ */
+export const MUTE_MARKER = "[MUTE]";
+const MUTE_MARKER_PREFIX = "[MUTE:";
+
+/** Longest timed mute a marker can ask for; longer asks mute until unmuted. */
+export const MAX_TIMED_MUTE_SECONDS = 3600;
+
+/**
+ * Progress-update cadence for the rest of a live-voice session:
+ * {@link FEWER_UPDATES_MARKER} after "don't give me updates so often",
+ * {@link NORMAL_UPDATES_MARKER} to go back. Terminal like the other session
+ * controls, but carried out by the session itself: narration is the daemon's.
+ */
+export const FEWER_UPDATES_MARKER = "[UPDATES:FEWER]";
+export const NORMAL_UPDATES_MARKER = "[UPDATES:NORMAL]";
+const UPDATES_MARKER_PREFIX = "[UPDATES:";
+
 // ---------------------------------------------------------------------------
 // Regexes
 // ---------------------------------------------------------------------------
@@ -57,6 +80,8 @@ const END_CALL_MARKER_REGEX = /\[END_CALL\]/g;
 const HOLD_VERDICT_TOKEN_REGEX = /\[0\]/g;
 const ESCALATE_VERDICT_TOKEN_REGEX = /\[1\]/g;
 const MINIMIZE_ROOM_MARKER_REGEX = /\[-1\]/g;
+const MUTE_MARKER_REGEX = /\[MUTE(?::\s*[^\]]*)?\]/g;
+const UPDATES_MARKER_REGEX = /\[UPDATES:\s*[^\]]*\]/g;
 const GUARDIAN_TIMEOUT_MARKER_REGEX = /\[GUARDIAN_TIMEOUT\]/g;
 const GUARDIAN_UNAVAILABLE_MARKER_REGEX = /\[GUARDIAN_UNAVAILABLE\]/g;
 
@@ -182,6 +207,8 @@ export function stripInternalSpeechMarkers(text: string): string {
     .replace(HOLD_VERDICT_TOKEN_REGEX, "")
     .replace(ESCALATE_VERDICT_TOKEN_REGEX, "")
     .replace(MINIMIZE_ROOM_MARKER_REGEX, "")
+    .replace(MUTE_MARKER_REGEX, "")
+    .replace(UPDATES_MARKER_REGEX, "")
     .replace(GUARDIAN_TIMEOUT_MARKER_REGEX, "")
     .replace(GUARDIAN_UNAVAILABLE_MARKER_REGEX, "");
   return result;
@@ -192,9 +219,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:",
@@ -207,23 +234,13 @@ const CONTROL_MARKER_STRINGS = [
   "[0]",
   "[1]",
   "[-1]",
+  MUTE_MARKER,
+  MUTE_MARKER_PREFIX,
+  UPDATES_MARKER_PREFIX,
   "[GUARDIAN_TIMEOUT]",
   "[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
@@ -233,6 +250,8 @@ const FIRST_BRACKET_TERMINATED_PREFIXES = [
   "[ASK_GUARDIAN:",
   "[USER_ANSWERED:",
   "[USER_INSTRUCTION:",
+  MUTE_MARKER_PREFIX,
+  UPDATES_MARKER_PREFIX,
 ];
 
 const GUARDIAN_APPROVAL_PREFIX = "[ASK_GUARDIAN_APPROVAL:";
@@ -267,3 +286,118 @@ 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);
+      }
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Live-voice session controls
+// ---------------------------------------------------------------------------
+
+/**
+ * A session control a live-voice reply asked for with a terminal marker:
+ * `end` from {@link END_CALL_MARKER}, `mute` from {@link MUTE_MARKER} or its
+ * timed form, `updates` from the progress-cadence markers.
+ */
+export type SessionControlRequest =
+  | { readonly action: "end" }
+  | { readonly action: "mute"; readonly durationMs?: number }
+  | { readonly action: "updates"; readonly cadence: "fewer" | "normal" };
+
+const TERMINAL_SESSION_CONTROL_REGEX =
+  /(\[END_CALL\]|\[UPDATES:(FEWER|NORMAL)\]|\[MUTE\]|\[MUTE:\s*([^\]]*)\])\s*$/;
+
+/**
+ * The session control a reply ends with, or null.
+ *
+ * **Terminal position only.** The marker follows the spoken acknowledgement
+ * ("Okay, talk soon."), so a reply that merely mentions a marker mid-text, or
+ * parrots one from history before carrying on, controls nothing. This is the
+ * same rule the minimize marker's transcript hygiene applies.
+ *
+ * A timed mute whose body is not a positive number of seconds degrades to an
+ * untimed mute rather than to nothing: the user asked to be muted, and muting
+ * until they unmute is the conservative reading of a garbled duration. Asks
+ * past {@link MAX_TIMED_MUTE_SECONDS} degrade the same way.
+ */
+export function parseTerminalSessionControl(
+  text: string,
+): SessionControlRequest | null {
+  const match = TERMINAL_SESSION_CONTROL_REGEX.exec(text);
+  if (!match) {
+    return null;
+  }
+  if (match[1] === END_CALL_MARKER) {
+    return { action: "end" };
+  }
+  if (match[2] !== undefined) {
+    return {
+      action: "updates",
+      cadence: match[2] === "FEWER" ? "fewer" : "normal",
+    };
+  }
+  const seconds = match[3] === undefined ? NaN : Number(match[3].trim());
+  if (
+    Number.isFinite(seconds) &&
+    seconds > 0 &&
+    seconds <= MAX_TIMED_MUTE_SECONDS
+  ) {
+    return { action: "mute", durationMs: Math.round(seconds * 1000) };
+  }
+  return { action: "mute" };
+}
+
+/**
+ * Length of the marker a row's text ends with, ignoring trailing whitespace,
+ * when it is one the transcript hygiene pass strips from the persisted row
+ * (the minimize marker or a session control); 0 otherwise.
+ */
+export function terminalControlMarkerLength(text: string): number {
+  const trimmed = text.trimEnd();
+  if (trimmed.endsWith(MINIMIZE_ROOM_MARKER)) {
+    return MINIMIZE_ROOM_MARKER.length;
+  }
+  return TERMINAL_SESSION_CONTROL_REGEX.exec(trimmed)?.[1]?.length ?? 0;
+}