@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

package/src/live-voice/__tests__/protocol.test.ts

@@ -698,6 +698,53 @@ describe("parseLiveVoiceClientTextFrame", () => {
     });
   });
 
+  test("keeps known session controls and drops unknown ones", () => {
+    const result = validateLiveVoiceClientFrame({
+      type: "start",
+      sessionControls: [
+        "mute",
+        "look_stop",
+        "look_camera",
+        "end",
+        "mute",
+        7,
+        "fly",
+      ],
+      audio: { mimeType: "audio/pcm", sampleRate: 24000, channels: 1 },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    // A newer client's controls cost it nothing on an older daemon.
+    expect(result.frame).toMatchObject({
+      type: "start",
+      sessionControls: ["end", "mute", "look_camera", "look_stop"],
+    });
+  });
+
+  test.each([
+    ["absent", {}],
+    ["not an array", { sessionControls: "end" }],
+    ["all unknown", { sessionControls: ["fly"] }],
+  ])(
+    "omits sessionControls from the start frame when %s",
+    (_label, extra: Record<string, unknown>) => {
+      const result = validateLiveVoiceClientFrame({
+        type: "start",
+        ...extra,
+        audio: { mimeType: "audio/pcm", sampleRate: 24000, channels: 1 },
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) {
+        return;
+      }
+      expect("sessionControls" in result.frame).toBe(false);
+    },
+  );
+
   test("parses the textInput capability on the start frame", () => {
     const result = validateLiveVoiceClientFrame({
       type: "start",

package/src/live-voice/__tests__/session-controls.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+
+import type { VoiceProgressConfig } from "../../config/schemas/voice.js";
+import {
+  FEWER_UPDATES_INTERVAL_MS,
+  progressConfigForCadence,
+  requestedSessionControl,
+  sessionControlTeaching,
+} from "../session-controls.js";
+
+const CONFIG: VoiceProgressConfig = {
+  enabled: true,
+  opsThreshold: 3,
+  idleIntervalMs: 5_000,
+  maxSilenceMs: 35_000,
+  longOpMs: 15_000,
+  minGapMs: 6_000,
+  generationTimeoutMs: 1_500,
+};
+
+describe("progressConfigForCadence", () => {
+  test("normal is the configured cadence, untouched", () => {
+    expect(progressConfigForCadence(CONFIG, "normal")).toBe(CONFIG);
+  });
+
+  test("fewer silences tool activity and stretches the silence tick", () => {
+    const fewer = progressConfigForCadence(CONFIG, "fewer");
+
+    expect(fewer.opsThreshold).toBe(Number.MAX_SAFE_INTEGER);
+    expect(fewer.longOpMs).toBe(Number.MAX_SAFE_INTEGER);
+    expect(fewer.idleIntervalMs).toBe(FEWER_UPDATES_INTERVAL_MS);
+    expect(fewer.maxSilenceMs).toBe(FEWER_UPDATES_INTERVAL_MS);
+    // Narration stays on: a very long silence still proves the call is alive.
+    expect(fewer.enabled).toBe(true);
+  });
+
+  test("fewer never speaks more often than the configured heartbeat", () => {
+    const fewer = progressConfigForCadence(
+      { ...CONFIG, idleIntervalMs: 90_000, maxSilenceMs: 120_000 },
+      "fewer",
+    );
+
+    expect(fewer.idleIntervalMs).toBe(120_000);
+    expect(fewer.maxSilenceMs).toBe(120_000);
+  });
+});
+
+describe("requestedSessionControl", () => {
+  test("the update cadence needs no client declaration", () => {
+    expect(requestedSessionControl("Sure. [UPDATES:FEWER]", [])).toEqual({
+      action: "updates",
+      cadence: "fewer",
+    });
+  });
+
+  test("a client control needs the client's declaration", () => {
+    expect(requestedSessionControl("Bye. [END_CALL]", [])).toBeNull();
+    expect(requestedSessionControl("Bye. [END_CALL]", ["end"])).toEqual({
+      action: "end",
+    });
+  });
+});
+
+describe("sessionControlTeaching", () => {
+  test("teaches the update cadence and only the declared client controls", () => {
+    const teaching = sessionControlTeaching(["mute"], {});
+
+    expect(teaching).toContain("[UPDATES:FEWER]");
+    expect(teaching).toContain("[MUTE]");
+    expect(teaching).not.toContain("[END_CALL]");
+    expect(teaching).toContain("Never emit any other bracketed marker.");
+  });
+
+  test("a device that can show both asks which one a bare look means", () => {
+    const teaching = sessionControlTeaching(["look_screen", "look_camera"], {});
+
+    expect(teaching).toContain("[LOOK:SCREEN]");
+    expect(teaching).toContain("[LOOK:CAMERA]");
+    expect(teaching).toContain("ask which one instead of guessing");
+  });
+
+  test("a device that can look can be told to stop", () => {
+    const teaching = sessionControlTeaching(["look_screen", "look_stop"], {});
+
+    expect(teaching).toContain("[LOOK:STOP]");
+    expect(
+      requestedSessionControl("Stopping. [LOOK:STOP]", ["look_stop"]),
+    ).toEqual({ action: "look_stop" });
+  });
+
+  test("a device that can show one look needs no question", () => {
+    const teaching = sessionControlTeaching(["look_camera"], {});
+
+    expect(teaching).toContain("[LOOK:CAMERA]");
+    expect(teaching).not.toContain("[LOOK:SCREEN]");
+    expect(teaching).not.toContain("ask which one");
+    expect(teaching).not.toContain("cannot turn on a screen share");
+  });
+
+  // The silent failure in the report this exists for: asked to look, the
+  // assistant neither looked nor said it could not.
+  test("a device that can show neither says so rather than pretending", () => {
+    expect(sessionControlTeaching(["end"], {})).toContain(
+      "This call cannot turn on a screen share or the camera.",
+    );
+  });
+
+  test("the front-door leg keeps its verdict tokens", () => {
+    expect(sessionControlTeaching(["end"], { frontDoor: true })).not.toContain(
+      "Never emit any other bracketed marker.",
+    );
+  });
+});

package/src/live-voice/live-voice-metrics.ts

@@ -511,6 +511,15 @@ export class LiveVoiceMetricsCollector {
         turnId: turn.turnId,
         finishReason,
         ...aggregateFieldsForTurn(snapshotTurn(turn)),
+        // Stated even at zero, unlike the telemetry field this overrides.
+        // Zero is the single most informative value this count takes: it is
+        // what a turn asked for fewer updates looks like, and equally what a
+        // narrator that is failing every attempt looks like. Left absent, the
+        // two read identically to anyone reading the log, and "the feature is
+        // off" becomes indistinguishable from "the feature did its job".
+        // The wire payload keeps the omission (see optionalTurnFields), so
+        // turns that never engage narration are unchanged for telemetry.
+        progressUpdatesSpoken: turn.progressUpdatesSpoken,
       },
       "Live voice turn latency",
     );

package/src/live-voice/live-voice-session.ts

@@ -156,7 +156,14 @@ import {
   type LiveVoiceClientUpdateConfigFrame,
   LiveVoiceProtocolErrorCode,
   type LiveVoiceServerFramePayload,
+  type LiveVoiceSessionControl,
 } from "./protocol.js";
+import {
+  type ClientSessionControlRequest,
+  progressConfigForCadence,
+  requestedSessionControl,
+  sessionControlTeaching,
+} from "./session-controls.js";
 
 const log = getLogger("live-voice-session");
 
@@ -610,6 +617,10 @@ interface ActiveAssistantTurn {
   // Never set from anything the model says: the reveal is a consequence of
   // showing a surface, not a token the model has to remember.
   minimizeRequested: boolean;
+  // The session control the completed reply ended with (see
+  // session-controls.ts); consumed at TTS drain like the minimize, where the
+  // session_control frame goes out once the acknowledgement has been spoken.
+  sessionControlRequested: ClientSessionControlRequest | null;
   // The activity label the client was last told about, so a run of tools that
   // map to the same line sends one frame rather than one per call. Empty means
   // the client believes nothing is running, which is also where a turn ends.
@@ -757,7 +768,7 @@ interface ActiveAssistantTurn {
 // message. When a turn starts from a barge-in, the interruption merge note is
 // appended to it (see buildInterruptionMergeNote) so the model reconciles the
 // interrupted request with the new utterance.
-const LIVE_VOICE_CONTROL_PROMPT_BASE = `You are speaking in a local live voice session. ${SPOKEN_REPLY_LENGTH_RULE} ${SPOKEN_REPLY_PLAIN_TEXT_RULE} Speech is the main channel: say the answer, and do not narrate a surface instead of answering. You can also put something on screen when it genuinely helps (a form, a list to pick from, a progress card for long work); the call overlay minimizes by itself once you finish speaking, so the user sees it without doing anything. Never tell the user you cannot show them something. Reply in the language the caller is speaking; if they switch languages, switch with them. `;
+const LIVE_VOICE_CONTROL_PROMPT_BASE = `You are speaking in a local live voice session. ${SPOKEN_REPLY_LENGTH_RULE} ${SPOKEN_REPLY_PLAIN_TEXT_RULE} Speech is the main channel: say the answer, and do not narrate a surface instead of answering. You can also put something on screen when it genuinely helps (a form, a list to pick from, a progress card for long work, or a card with an image or a link instead of reading an address out); the call overlay minimizes by itself once you finish speaking, so the user sees it without doing anything. Never tell the user you cannot show them something. Reply in the language the caller is speaking; if they switch languages, switch with them. `;
 
 // Appended for the legs that can actually put something on screen: the main
 // leg and the escalated leg. The front-door (fast) leg never receives it, for
@@ -773,7 +784,7 @@ const LIVE_VOICE_CONTROL_PROMPT_BASE = `You are speaking in a local live voice s
 // model can get right, which is speaking as though the thing is already in
 // front of the user, because by the time it stops talking it is.
 const LIVE_VOICE_SCREEN_REVEAL_TEACHING =
-  "When the complete answer would run past a few sentences, say the short version out loud and put the detail on screen instead of reading it out. The call renders as a full-screen overlay covering the app. Whenever you put something on screen, the overlay minimizes by itself as soon as you finish speaking, and the user is looking at what you made. So speak as if you are showing it to them right now (for example, close with something like: take a look), and never say you cannot show it, that this is a voice call, or that they should check it later. Never emit bracketed markers of any kind. ";
+  "When the complete answer would run past a few sentences, say the short version out loud and put the detail on screen instead of reading it out. The call renders as a full-screen overlay covering the app. Whenever you put something on screen, the overlay minimizes by itself as soon as you finish speaking, and the user is looking at what you made. So speak as if you are showing it to them right now (for example, close with something like: take a look), and never say you cannot show it, that this is a voice call, or that they should check it later. ";
 
 // The setup-flow case, spelled out because it is the one the model gets wrong
 // on its own: connecting an account reads as something a call cannot do, so it
@@ -854,12 +865,14 @@ function buildLiveDeliveryNote(request: string, answer: string): string {
 function buildVoiceControlPrompt(
   turn: ActiveAssistantTurn,
   leg: { frontDoor?: boolean },
+  sessionControls: readonly LiveVoiceSessionControl[],
 ): string {
   let prompt =
     LIVE_VOICE_CONTROL_PROMPT_BASE +
     (leg.frontDoor === true
       ? ""
-      : LIVE_VOICE_SCREEN_REVEAL_TEACHING + LIVE_VOICE_SETUP_FLOW_TEACHING);
+      : LIVE_VOICE_SCREEN_REVEAL_TEACHING + LIVE_VOICE_SETUP_FLOW_TEACHING) +
+    sessionControlTeaching(sessionControls, leg);
   if (turn.language !== undefined) {
     prompt = `${prompt}\n\nThe caller has been speaking the language with code "${turn.language}" this turn. Reply in that language unless they clearly switch to another.`;
   }
@@ -1119,6 +1132,12 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
   // take a turn without the microphone. Governs one thing only: whether a
   // missing speech-to-text leg is fatal to startup (see start()).
   private readonly textInput: boolean;
+  // The session controls the client declared it can carry out; the only ones
+  // the model is taught and the only ones a reply's marker can trigger.
+  private readonly sessionControls: readonly LiveVoiceSessionControl[];
+  // How often progress updates are spoken, as the user last asked out loud.
+  // Session-scoped: it applies from the next turn to the end of the call.
+  private progressCadence: "fewer" | "normal" = "normal";
   // Whether this session's speech-to-text leg came up. False only when the
   // preflight found it missing and `textInput` let the session open anyway, in
   // which case nothing arms a transcriber and typed turns are the only input.
@@ -1393,6 +1412,7 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
       2 *
       SERVER_VAD_PENDING_AUDIO_MAX_SECONDS;
     this.textInput = context.startFrame.textInput === true;
+    this.sessionControls = context.startFrame.sessionControls ?? [];
   }
 
   get finalTranscriptText(): string {
@@ -5004,7 +5024,10 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
       handle: null,
       launchedAtMs: Date.now(),
       progress: createProgressCadence({
-        config: this.frontModelConfig.progress,
+        config: progressConfigForCadence(
+          this.frontModelConfig.progress,
+          this.progressCadence,
+        ),
         // Without TTS there is nothing to speak (the idle trigger's static
         // fallback still needs a generation attempt to fall back from).
         narrator: this.streamTtsAudio ? this.progressNarrator : null,
@@ -5039,6 +5062,7 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
       assistantCompleted: false,
       ttsDone: false,
       minimizeRequested: false,
+      sessionControlRequested: null,
       activityLabel: "",
       publishedApprovalRequestId: null,
       pendingApproval: null,
@@ -5298,6 +5322,9 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
         // as telemetry instead, on `voiceTelemetry` below.
         userMessageInterface: "macos",
         assistantMessageInterface: "macos",
+        ...(this.context.startFrame.client === "macos"
+          ? { macosDesktopSession: true }
+          : {}),
         voiceTelemetry: {
           sessionId: this.context.sessionId,
           ...(this.context.startFrame.client
@@ -5307,9 +5334,15 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
             ? { entry: this.context.startFrame.entry }
             : {}),
         },
-        voiceControlPrompt: buildVoiceControlPrompt(activeTurn, {
-          ...(leg.frontDoor !== undefined ? { frontDoor: leg.frontDoor } : {}),
-        }),
+        voiceControlPrompt: buildVoiceControlPrompt(
+          activeTurn,
+          {
+            ...(leg.frontDoor !== undefined
+              ? { frontDoor: leg.frontDoor }
+              : {}),
+          },
+          this.sessionControls,
+        ),
         onApprovalPending: (requestId) => {
           this.revealRoomForPendingApproval(activeTurn, requestId);
         },
@@ -5414,6 +5447,26 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
             if (!leg.frontDoor && msg.type === "message_complete") {
               flushLegText(rawText, { force: true });
             }
+            // Read off the leg that finished the reply: a front-door answer
+            // or the escalated leg. A handed-off front-door leg returned
+            // above, so its holding phrase can never end a call.
+            if (msg.type === "message_complete") {
+              const request = requestedSessionControl(
+                rawText,
+                this.sessionControls,
+              );
+              if (request?.action === "updates") {
+                // The session's own control: nothing to send, and nothing to
+                // wait for, since it shapes turns that have not started yet.
+                this.progressCadence = request.cadence;
+                log.info(
+                  { turnId, cadence: request.cadence },
+                  "Live voice progress cadence changed",
+                );
+              } else {
+                current.sessionControlRequested = request;
+              }
+            }
             current.assistantCompleted = true;
             if (msg.type === "generation_cancelled") {
               void this.finalizeAssistantTurn(
@@ -5826,6 +5879,34 @@ export class LiveVoiceSession implements LiveVoiceSessionContract {
         // leave the last tool it touched on screen through the next silence.
         this.publishActivity(currentTurn, "");
 
+        // Drain-scoped session control, under the same terms as the minimize
+        // below: after the acknowledgement has been spoken, never for a
+        // barged-in turn (talking over "okay, bye" means they are not
+        // leaving), at most once per turn. Ending the call makes revealing
+        // the screen moot, so an end takes the minimize's place.
+        const sessionControl = currentTurn.sessionControlRequested;
+        currentTurn.sessionControlRequested = null;
+        if (
+          sessionControl !== null &&
+          !currentTurn.abortController.signal.aborted
+        ) {
+          log.info(
+            { turnId: currentTurn.turnId, action: sessionControl.action },
+            "Live voice reply requested a session control",
+          );
+          if (sessionControl.action === "end") {
+            currentTurn.minimizeRequested = false;
+          }
+          await this.sendFrame(
+            {
+              type: "session_control",
+              turnId: currentTurn.turnId,
+              ...sessionControl,
+            },
+            () => !this.isClosed,
+          );
+        }
+
         // Drain-scoped minimize: the latched marker is consumed here, after
         // the turn's speech has fully drained — never mid-speech, never for
         // a barged-in turn, at most once per turn.

package/src/live-voice/protocol.ts

@@ -30,6 +30,7 @@ const _LIVE_VOICE_SERVER_FRAME_TYPES = [
   "tts_done",
   "turn_cancelled",
   "minimize_room",
+  "session_control",
   "metrics",
   "archived",
   "error",
@@ -152,6 +153,46 @@ export interface LiveVoiceClientStartFrame {
    * malformed value costs a chart facet and never the session.
    */
   readonly entry?: string;
+  /**
+   * The session controls this client can carry out when a reply asks for one
+   * (see {@link LiveVoiceSessionControlServerFrame}). The session teaches the
+   * model only the controls listed here, so a client that cannot hang up or
+   * mute is never told it can.
+   *
+   * Absent means none: a client that predates the field would ignore the
+   * frame, and a spoken "okay, ending the call" that ends nothing is worse
+   * than the model not offering. Values this daemon does not know are dropped
+   * rather than rejected, so a newer client can list controls an older daemon
+   * has never heard of.
+   */
+  readonly sessionControls?: readonly LiveVoiceSessionControl[];
+}
+
+const LIVE_VOICE_SESSION_CONTROLS = [
+  "end",
+  "mute",
+  "look_screen",
+  "look_camera",
+  "look_stop",
+] as const;
+
+/** A session control a client can carry out on the assistant's behalf. */
+export type LiveVoiceSessionControl =
+  (typeof LIVE_VOICE_SESSION_CONTROLS)[number];
+
+/**
+ * A start frame's `sessionControls`, reduced to the known values with
+ * duplicates removed; empty when the field is absent or not an array.
+ */
+export function parseLiveVoiceSessionControls(
+  value: unknown,
+): LiveVoiceSessionControl[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return LIVE_VOICE_SESSION_CONTROLS.filter((control) =>
+    value.includes(control),
+  );
 }
 
 /**
@@ -586,6 +627,29 @@ export interface LiveVoiceMinimizeRoomServerFrame extends LiveVoiceServerFrameBa
   readonly turnId: string;
 }
 
+/**
+ * A session control the just-completed reply asked for with a terminal marker
+ * (`[END_CALL]`, `[MUTE]`, `[MUTE:<seconds>]`). Sent only after the turn's TTS
+ * has fully drained, so the spoken acknowledgement is heard first, never for a
+ * turn the user barged in on, at most once per turn, and only for a control
+ * the client listed in the start frame's `sessionControls`.
+ *
+ * - `end`: end the session the way the client's own end control does.
+ * - `mute`: mute the microphone. With `durationMs`, unmute again once it
+ *   elapses; without, stay muted until the user unmutes. The timer is the
+ *   client's: a muted microphone sends silence, so the daemon cannot hear an
+ *   "unmute".
+ * - `look_screen`: start showing the call the user's screen.
+ * - `look_camera`: start showing the call what the camera sees.
+ * - `look_stop`: stop showing the call the screen and the camera.
+ */
+export interface LiveVoiceSessionControlServerFrame extends LiveVoiceServerFrameBase {
+  readonly type: "session_control";
+  readonly turnId: string;
+  readonly action: LiveVoiceSessionControl;
+  readonly durationMs?: number;
+}
+
 export interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
   readonly type: "metrics";
   readonly event?: string;
@@ -707,6 +771,7 @@ export type LiveVoiceServerFrame =
   | LiveVoiceTtsDoneServerFrame
   | LiveVoiceTurnCancelledServerFrame
   | LiveVoiceMinimizeRoomServerFrame
+  | LiveVoiceSessionControlServerFrame
   | LiveVoiceMetricsServerFrame
   | LiveVoiceArchivedServerFrame
   | LiveVoiceErrorServerFrame;
@@ -728,6 +793,7 @@ export type LiveVoiceServerFramePayload =
   | WithoutSeq<LiveVoiceTtsDoneServerFrame>
   | WithoutSeq<LiveVoiceTurnCancelledServerFrame>
   | WithoutSeq<LiveVoiceMinimizeRoomServerFrame>
+  | WithoutSeq<LiveVoiceSessionControlServerFrame>
   | WithoutSeq<LiveVoiceMetricsServerFrame>
   | WithoutSeq<LiveVoiceArchivedServerFrame>
   | WithoutSeq<LiveVoiceErrorServerFrame>;
@@ -1218,6 +1284,8 @@ function validateStartFrame(
   const client = parseClientOs(value.client);
   // Same policy for the same reason: a dimension, not a capability.
   const entry = parseLiveVoiceEntry(value.entry);
+  // Same policy again: an unknown control is a newer client, not a bad frame.
+  const sessionControls = parseLiveVoiceSessionControls(value.sessionControls);
 
   return {
     ok: true,
@@ -1239,6 +1307,7 @@ function validateStartFrame(
         ? { bargeInMinSpeechMs: value.bargeInMinSpeechMs }
         : {}),
       ...(value.textInput === true ? { textInput: true } : {}),
+      ...(sessionControls.length > 0 ? { sessionControls } : {}),
     },
   };
 }

package/src/live-voice/session-controls.ts

@@ -0,0 +1,139 @@
+import {
+  END_CALL_MARKER,
+  FEWER_UPDATES_MARKER,
+  LOOK_CAMERA_MARKER,
+  LOOK_SCREEN_MARKER,
+  LOOK_STOP_MARKER,
+  MUTE_MARKER,
+  NORMAL_UPDATES_MARKER,
+  parseTerminalSessionControl,
+  type SessionControlRequest,
+} from "../calls/voice-control-protocol.js";
+import type { VoiceProgressConfig } from "../config/schemas/voice.js";
+import type { LiveVoiceSessionControl } from "./protocol.js";
+
+/**
+ * Spoken session controls: the user asks out loud to end the call, mute their
+ * microphone, or hear fewer progress updates, the reply acknowledges it and
+ * ends with a marker, and the session carries it out once that
+ * acknowledgement has been spoken.
+ *
+ * A marker rather than a tool, because these are the turns a front-door leg
+ * answers on its own: "okay, I'm gonna go" should not wait on an escalation to
+ * a stronger model before the call can end. The marker is judged by the
+ * model, never by matching the user's words, so "I'm all done with that
+ * email" does not hang up.
+ */
+
+const CLIENT_CONTROL_LINES: Record<LiveVoiceSessionControl, string> = {
+  end: `- To end the call (for example "I'm all done" or "okay, I'm gonna go"), say a brief goodbye, then end your reply with ${END_CALL_MARKER}. Being done with a task is not the same as leaving the call; end only when they are leaving.`,
+  look_screen: `- To look at their screen (for example "take a look at my screen" or "can you see what I'm looking at?"), say you are taking a look, then end your reply with ${LOOK_SCREEN_MARKER}. Their screen starts being shared with you once you finish speaking, so you cannot describe it yet: ask what they want you to look at, or say you will take it from their next words.`,
+  look_camera: `- To look through their camera (for example "look at this" or "can you see this?" while they hold something up), say you are taking a look, then end your reply with ${LOOK_CAMERA_MARKER}. The camera turns on once you finish speaking, so you cannot describe what it sees yet: ask them to show you, or say you will take it from their next words.`,
+  look_stop: `- To stop showing you their screen or camera (for example "stop sharing" or "you can stop looking now"), confirm in a few words, then end your reply with ${LOOK_STOP_MARKER}.`,
+  mute: `- To mute their microphone (for example "mute for 30 seconds" or "mute yourself, I need to take this"), confirm in a few words, then end your reply with [MUTE:<seconds>] when they gave a duration or ${MUTE_MARKER} when they did not. While muted you cannot hear them, so mention they can unmute from the call controls unless the mute is timed.`,
+};
+
+// Always taught: narration is the session's own, so no client has to be able
+// to carry it out.
+const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (for example "don't give me updates so often"), confirm that you will only check in now and then and will tell them when it is done, then end your reply with ${FEWER_UPDATES_MARKER}. If they later want regular updates back, confirm and end with ${NORMAL_UPDATES_MARKER}.`;
+
+/**
+ * The control-prompt block that teaches the session controls: the ones the
+ * client declared plus the progress-update cadence. Every leg gets it,
+ * including the toolless front-door leg: these turns are its to answer.
+ *
+ * The no-other-markers rule is withheld from the front-door leg, whose
+ * routing rule teaches it leading verdict tokens and already confines
+ * everything else to speech.
+ */
+export function sessionControlTeaching(
+  controls: readonly LiveVoiceSessionControl[],
+  leg: { frontDoor?: boolean },
+): string {
+  return [
+    "The user can also control this call by asking you. Only when they clearly ask:",
+    ...controls.map((control) => CLIENT_CONTROL_LINES[control]),
+    ...lookGuidance(controls),
+    UPDATES_LINE,
+    `The marker must be the very last thing in your reply. It is never spoken and does nothing anywhere else.${leg.frontDoor === true ? "" : " Never emit any other bracketed marker."}`,
+  ].join("\n");
+}
+
+/**
+ * What to say about looking beyond the per-control lines: ask which when the
+ * device can do both and the request does not say, and say so plainly when it
+ * can do neither, rather than failing silently.
+ */
+function lookGuidance(controls: readonly LiveVoiceSessionControl[]): string[] {
+  const screen = controls.includes("look_screen");
+  const camera = controls.includes("look_camera");
+  if (screen && camera) {
+    return [
+      `- If they just say "take a look" and it is not clear whether they mean their screen or their camera, ask which one instead of guessing, and use no marker until they answer.`,
+    ];
+  }
+  if (!screen && !camera) {
+    return [
+      "- This call cannot turn on a screen share or the camera. If they ask you to look at their screen or at something and you have no other way to see it, say so briefly instead of pretending to look.",
+    ];
+  }
+  return [];
+}
+
+/** A session control the client carries out, sent as a `session_control` frame. */
+export type ClientSessionControlRequest = Exclude<
+  SessionControlRequest,
+  { action: "updates" }
+>;
+
+/**
+ * The control a completed leg's raw text asks for; null when there is none or
+ * when it is a client control the client did not declare. An undeclared
+ * control is dropped rather than sent: the client said it cannot carry it out.
+ * The update cadence always passes, since the session carries it out itself.
+ */
+export function requestedSessionControl(
+  rawText: string,
+  controls: readonly LiveVoiceSessionControl[],
+): SessionControlRequest | null {
+  const request = parseTerminalSessionControl(rawText);
+  if (request === null) {
+    return null;
+  }
+  if (request.action === "updates") {
+    return request;
+  }
+  return controls.includes(request.action) ? request : null;
+}
+
+/**
+ * Silence (ms) a session that asked for fewer updates waits through before a
+ * progress update. Long enough that a minute-long task runs without a word;
+ * short enough that a really long one still proves the call is alive.
+ */
+export const FEWER_UPDATES_INTERVAL_MS = 60_000;
+
+/**
+ * The progress config a turn runs on under the session's update cadence.
+ *
+ * Fewer updates means no update for tool activity (a burst of ops or a long
+ * op finishing, each normally its own beat) and the silence tick stretched to
+ * {@link FEWER_UPDATES_INTERVAL_MS}, so the only thing that speaks is a long
+ * stretch of silence. Done is still said: the reply itself is the "it's done".
+ */
+export function progressConfigForCadence(
+  config: VoiceProgressConfig,
+  cadence: "fewer" | "normal",
+): VoiceProgressConfig {
+  if (cadence === "normal") {
+    return config;
+  }
+  const intervalMs = Math.max(FEWER_UPDATES_INTERVAL_MS, config.maxSilenceMs);
+  return {
+    ...config,
+    opsThreshold: Number.MAX_SAFE_INTEGER,
+    longOpMs: Number.MAX_SAFE_INTEGER,
+    idleIntervalMs: intervalMs,
+    maxSilenceMs: intervalMs,
+  };
+}