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

package/src/live-voice/__tests__/live-voice-agent-turn.test.ts

@@ -980,3 +980,124 @@ describe("LiveVoiceSession room reveal", () => {
     expect(ttsTexts.join(" ")).not.toContain("ASK_GUARDIAN_APPROVAL");
   });
 });
+
+describe("LiveVoiceSession spoken session controls", () => {
+  function createControlsHarness(
+    sessionControls?: LiveVoiceClientStartFrame["sessionControls"],
+  ) {
+    const { startVoiceTurn, getCallbacks } = createCapturingTurnStarter();
+    const { streamTtsAudio, ttsTexts } = createRecordingTtsStreamer();
+    const harness = createSessionHarness({
+      startVoiceTurn,
+      streamTtsAudio,
+      startFrame: {
+        ...START_FRAME,
+        ...(sessionControls ? { sessionControls } : {}),
+      },
+    });
+    return { ...harness, getCallbacks, ttsTexts };
+  }
+
+  test("a reply ending with [END_CALL] sends an end control after tts_done", async () => {
+    const { frames, session, getCallbacks, ttsTexts } = createControlsHarness([
+      "end",
+      "mute",
+    ]);
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "Okay, talk soon. [END_CALL]");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() =>
+      frames.some((frame) => frame.type === "session_control"),
+    );
+
+    const ttsDoneIndex = frames.findIndex((frame) => frame.type === "tts_done");
+    const controlIndex = frames.findIndex(
+      (frame) => frame.type === "session_control",
+    );
+    // The goodbye is heard before the call ends.
+    expect(controlIndex).toBeGreaterThan(ttsDoneIndex);
+    expect(frames[controlIndex]).toMatchObject({
+      type: "session_control",
+      turnId: "live-turn-1",
+      action: "end",
+    });
+    expect(assistantDeltaTexts(frames).join("").trim()).toBe(
+      "Okay, talk soon.",
+    );
+    expect(ttsTexts.join(" ")).not.toContain("[END_CALL]");
+  });
+
+  test("a timed mute carries its duration", async () => {
+    const { frames, session, getCallbacks } = createControlsHarness(["mute"]);
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "Muting you for thirty seconds. [MUTE:30]");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() =>
+      frames.some((frame) => frame.type === "session_control"),
+    );
+
+    expect(
+      frames.find((frame) => frame.type === "session_control"),
+    ).toMatchObject({ action: "mute", durationMs: 30_000 });
+  });
+
+  test("a control the client did not declare is never sent", async () => {
+    const { frames, session, getCallbacks } = createControlsHarness(["mute"]);
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "Bye. [END_CALL]");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+    await flushAsyncCallbacks();
+
+    expect(frames.some((frame) => frame.type === "session_control")).toBe(
+      false,
+    );
+  });
+
+  test("a marker mid-reply controls nothing", async () => {
+    const { frames, session, getCallbacks } = createControlsHarness(["end"]);
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "Say [END_CALL] and I would hang up, but no.");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+    await flushAsyncCallbacks();
+
+    expect(frames.some((frame) => frame.type === "session_control")).toBe(
+      false,
+    );
+  });
+
+  // Talking over "okay, bye" means they are not leaving.
+  test("an interrupted goodbye does not end the call", async () => {
+    const { frames, session, getCallbacks } = createControlsHarness(["end"]);
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "Okay, talk soon. [END_CALL]");
+    await flushAsyncCallbacks();
+    await session.handleClientFrame({ type: "interrupt" });
+    emitMessageComplete(getCallbacks);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(frames.some((frame) => frame.type === "session_control")).toBe(
+      false,
+    );
+  });
+
+  test("the prompt teaches only the declared controls", async () => {
+    const { session, getCallbacks, startVoiceTurn } = createControlsHarness([
+      "mute",
+    ]);
+
+    await startReleasedTurn(session, getCallbacks);
+    const prompt =
+      (startVoiceTurn as ReturnType<typeof mock>).mock.calls[0]?.[0]
+        ?.voiceControlPrompt ?? "";
+
+    expect(prompt).toContain("[MUTE]");
+    expect(prompt).not.toContain("[END_CALL]");
+  });
+});

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

@@ -253,14 +253,15 @@ describe("LiveVoiceSession archive and metrics events", () => {
       userMessageInterface: "macos",
       assistantMessageInterface: "macos",
       // Pins the full production control prompt for the FRONT-DOOR leg (the
-      // first leg of every routed turn): the speech-first rule, and nothing
-      // else. This leg is toolless, so both the screen-reveal and setup-flow
-      // teachings are deliberately absent. It has nothing to show and no
-      // connection to run, and its capability digest already routes anything
-      // needing a tool to the escalated leg (see
-      // live-voice-triage-escalate.test.ts).
+      // first leg of every routed turn): the speech-first rule and the session
+      // controls, and nothing else. This leg is toolless, so both the
+      // screen-reveal and setup-flow teachings are deliberately absent. It
+      // has nothing to show and no connection to run, and its capability
+      // digest already routes anything needing a tool to the escalated leg
+      // (see live-voice-triage-escalate.test.ts). The start frame declares no
+      // client controls, so only the session's own update cadence is taught.
       voiceControlPrompt:
-        "You are speaking in a local live voice session. Keep each reply to one to three spoken sentences. The caller is listening, not reading: lead with the answer, say it in the fewest words that are still complete, and stop. No preamble, no recap of the question, no closing offer of more. Your text is sent directly to a text-to-speech engine. Never use markdown formatting (asterisks, headers, backticks, links), bulleted or numbered lists, or emojis. Write plain conversational text only; if something is naturally a list, say it as one sentence. 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. ",
+        'You are speaking in a local live voice session. Keep each reply to one to three spoken sentences. The caller is listening, not reading: lead with the answer, say it in the fewest words that are still complete, and stop. No preamble, no recap of the question, no closing offer of more. Your text is sent directly to a text-to-speech engine. Never use markdown formatting (asterisks, headers, backticks, links), bulleted or numbered lists, or emojis. Write plain conversational text only; if something is naturally a list, say it as one sentence. 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. The user can also control this call by asking you. Only when they clearly ask:\n- 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 [UPDATES:FEWER]. If they later want regular updates back, confirm and end with [UPDATES:NORMAL].\nThe marker must be the very last thing in your reply. It is never spoken and does nothing anywhere else.',
     });
     callbacks?.assistant_text_delta?.(makeTextDelta("Hello there."));
     callbacks?.message_complete?.(makeMessageComplete());

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

@@ -927,3 +927,82 @@ describe("LiveVoiceSession progress narration", () => {
     emitMessageComplete(getCallbacks);
   });
 });
+
+describe("LiveVoiceSession spoken update cadence", () => {
+  async function runTurnAskingFor(
+    session: LiveVoiceSession,
+    getCallbacks: () => VoiceTurnCallbacks | undefined,
+    frames: { type: string }[],
+    reply: string,
+  ): Promise<void> {
+    emitTextDelta(getCallbacks, reply);
+    emitMessageComplete(getCallbacks);
+    await waitFor(
+      () => frames.some((frame) => frame.type === "tts_done"),
+      "first turn never finished",
+    );
+    // Let the post-turn re-arm run before releasing the next turn.
+    await sleep(20);
+    const previous = getCallbacks();
+    // Typed, because a manual session's microphone re-arm is not what this
+    // exercises: the cadence is the session's, however the next turn arrives.
+    await session.handleClientFrame({ type: "text", text: "go ahead" });
+    await waitFor(() => getCallbacks() !== previous, "next turn never started");
+  }
+
+  test("after the user asks for fewer updates, tool activity no longer narrates", async () => {
+    const generateProgressText = mock(async () => GENERATED_NARRATION);
+    const { frames, session, getCallbacks, ttsTexts } = createProgressHarness({
+      frontModelConfig: progressConfig({ opsThreshold: 3, minGapMs: 10 }),
+      progressNarrator: makeProgressNarrator(generateProgressText),
+    });
+
+    await startReleasedTurn(session, getCallbacks);
+    await runTurnAskingFor(
+      session,
+      getCallbacks,
+      frames,
+      "Sure, I'll only check in now and then. [UPDATES:FEWER]",
+    );
+    emitToolStart(getCallbacks, "web_search", "tool-1");
+    emitToolResult(getCallbacks, "web_search", "tool-1");
+    emitToolStart(getCallbacks, "file_read", "tool-2");
+    emitToolResult(getCallbacks, "file_read", "tool-2");
+    emitToolStart(getCallbacks, "web_search", "tool-3");
+    await sleep(40);
+
+    expect(generateProgressText).not.toHaveBeenCalled();
+    expect(ttsTexts.join(" ")).not.toContain("[UPDATES");
+    emitMessageComplete(getCallbacks);
+  });
+
+  test("asking for updates back restores the normal cadence", async () => {
+    const generateProgressText = mock(async () => GENERATED_NARRATION);
+    const { frames, session, getCallbacks, ttsTexts } = createProgressHarness({
+      frontModelConfig: progressConfig({ opsThreshold: 3, minGapMs: 10 }),
+      progressNarrator: makeProgressNarrator(generateProgressText),
+    });
+
+    await startReleasedTurn(session, getCallbacks);
+    await runTurnAskingFor(
+      session,
+      getCallbacks,
+      frames,
+      "Okay, fewer updates. [UPDATES:FEWER]",
+    );
+    frames.length = 0;
+    await runTurnAskingFor(
+      session,
+      getCallbacks,
+      frames,
+      "Got it, I'll keep you posted. [UPDATES:NORMAL]",
+    );
+    emitToolStart(getCallbacks, "web_search", "tool-1");
+    emitToolStart(getCallbacks, "file_read", "tool-2");
+    emitToolStart(getCallbacks, "web_search", "tool-3");
+    await waitFor(() => ttsTexts.includes(GENERATED_NARRATION));
+
+    expect(generateProgressText).toHaveBeenCalledTimes(1);
+    emitMessageComplete(getCallbacks);
+  });
+});

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

@@ -698,6 +698,45 @@ describe("parseLiveVoiceClientTextFrame", () => {
     });
   });
 
+  test("keeps known session controls and drops unknown ones", () => {
+    const result = validateLiveVoiceClientFrame({
+      type: "start",
+      sessionControls: ["mute", "look_screen", "end", "mute", 7],
+      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"],
+    });
+  });
+
+  test.each([
+    ["absent", {}],
+    ["not an array", { sessionControls: "end" }],
+    ["all unknown", { sessionControls: ["look_screen"] }],
+  ])(
+    "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,79 @@
+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("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-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,
@@ -5307,9 +5331,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 +5444,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 +5876,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,40 @@ 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"] 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 +621,26 @@ 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".
+ */
+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 +762,7 @@ export type LiveVoiceServerFrame =
   | LiveVoiceTtsDoneServerFrame
   | LiveVoiceTurnCancelledServerFrame
   | LiveVoiceMinimizeRoomServerFrame
+  | LiveVoiceSessionControlServerFrame
   | LiveVoiceMetricsServerFrame
   | LiveVoiceArchivedServerFrame
   | LiveVoiceErrorServerFrame;
@@ -728,6 +784,7 @@ export type LiveVoiceServerFramePayload =
   | WithoutSeq<LiveVoiceTtsDoneServerFrame>
   | WithoutSeq<LiveVoiceTurnCancelledServerFrame>
   | WithoutSeq<LiveVoiceMinimizeRoomServerFrame>
+  | WithoutSeq<LiveVoiceSessionControlServerFrame>
   | WithoutSeq<LiveVoiceMetricsServerFrame>
   | WithoutSeq<LiveVoiceArchivedServerFrame>
   | WithoutSeq<LiveVoiceErrorServerFrame>;
@@ -1218,6 +1275,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 +1298,7 @@ function validateStartFrame(
         ? { bargeInMinSpeechMs: value.bargeInMinSpeechMs }
         : {}),
       ...(value.textInput === true ? { textInput: true } : {}),
+      ...(sessionControls.length > 0 ? { sessionControls } : {}),
     },
   };
 }