@vellumai/assistant 0.11.1 → 0.11.2-staging.1

package/src/live-voice/__tests__/live-activity-reporter.test.ts

@@ -34,16 +34,26 @@ function sttFinal(text: string): LiveVoiceServerFramePayload {
 
 /** A reporter whose dispatches are captured instead of sent. */
 class RecordingReporter extends LiveActivityReporter {
-  readonly dispatched: Array<{ phase: string; event: string }> = [];
+  readonly dispatched: Array<{ phase: string; event: string; detail: string }> =
+    [];
 
   protected override async dispatch(
     phase: string,
     event: "update" | "end",
+    detail: string,
   ): Promise<void> {
-    this.dispatched.push({ phase, event });
+    this.dispatched.push({ phase, event, detail });
   }
 }
 
+function activity(label: string): LiveVoiceServerFramePayload {
+  return {
+    type: "activity",
+    turnId: "t1",
+    label,
+  } as LiveVoiceServerFramePayload;
+}
+
 describe("phaseForFrame", () => {
   test("maps the frames the client derives phases from", () => {
     expect(phaseForFrame(frame("utterance_end"), "listening")).toBe(
@@ -92,7 +102,7 @@ describe("LiveActivityReporter", () => {
     reporter.report(frame("thinking"));
 
     expect(reporter.dispatched).toEqual([
-      { phase: "thinking", event: "update" },
+      { phase: "thinking", event: "update", detail: "" },
     ]);
   });
 
@@ -105,7 +115,7 @@ describe("LiveActivityReporter", () => {
     reporter.report(frame("tts_audio"));
 
     expect(reporter.dispatched).toEqual([
-      { phase: "speaking", event: "update" },
+      { phase: "speaking", event: "update", detail: "" },
     ]);
   });
 
@@ -144,6 +154,7 @@ describe("LiveActivityReporter", () => {
     expect(reporter.dispatched.at(-1)).toEqual({
       phase: "ending",
       event: "end",
+      detail: "",
     });
   });
 
@@ -165,7 +176,77 @@ describe("LiveActivityReporter", () => {
     reporter.end();
     reporter.report(frame("tts_audio"));
 
-    expect(reporter.dispatched).toEqual([{ phase: "ending", event: "end" }]);
+    expect(reporter.dispatched).toEqual([
+      { phase: "ending", event: "end", detail: "" },
+    ]);
+  });
+});
+
+describe("LiveActivityReporter activity line", () => {
+  test("carries the activity label alongside the phase it holds", () => {
+    const reporter = new RecordingReporter("conv-1");
+
+    reporter.report(frame("utterance_end"));
+    reporter.report(frame("thinking"));
+    reporter.report(activity("Running a command"));
+
+    expect(reporter.dispatched.at(-1)).toEqual({
+      phase: "thinking",
+      event: "update",
+      detail: "Running a command",
+    });
+  });
+
+  // A push replaces the whole content state, so the label has to ride along on
+  // phase changes too, or the next phase would blank it.
+  test("keeps the label through a later phase change", () => {
+    const reporter = new RecordingReporter("conv-1");
+
+    reporter.report(frame("thinking"));
+    reporter.report(activity("Reading a file"));
+    reporter.report(frame("tts_audio"));
+
+    expect(reporter.dispatched.at(-1)).toEqual({
+      phase: "speaking",
+      event: "update",
+      detail: "Reading a file",
+    });
+  });
+
+  test("an empty label clears the line", () => {
+    const reporter = new RecordingReporter("conv-1");
+
+    reporter.report(frame("thinking"));
+    reporter.report(activity("Reading a file"));
+    reporter.report(activity(""));
+
+    expect(reporter.dispatched.at(-1)?.detail).toBe("");
+  });
+
+  test("does not dispatch a label it already sent", () => {
+    const reporter = new RecordingReporter("conv-1");
+
+    reporter.report(frame("thinking"));
+    reporter.report(activity("Reading a file"));
+    const before = reporter.dispatched.length;
+    reporter.report(activity("Reading a file"));
+
+    expect(reporter.dispatched.length).toBe(before);
+  });
+
+  // A tool can start before any phase-bearing frame lands. There is no content
+  // state to attach a label to yet, and the phase that follows carries it.
+  test("holds a label that arrives before any phase", () => {
+    const reporter = new RecordingReporter("conv-1");
+
+    reporter.report(activity("Searching the web"));
+    expect(reporter.dispatched).toEqual([]);
+
+    reporter.report(frame("thinking"));
+
+    expect(reporter.dispatched).toEqual([
+      { phase: "thinking", event: "update", detail: "Searching the web" },
+    ]);
   });
 });
 

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

@@ -157,13 +157,24 @@ async function waitFor(
 function createCapturingTurnStarter(): {
   startVoiceTurn: LiveVoiceTurnStarter;
   getCallbacks: () => VoiceTurnCallbacks | undefined;
+  announceApprovalPending: () => void;
+  announceApprovalsResolved: () => void;
 } {
   let callbacks: VoiceTurnCallbacks | undefined;
+  let onApprovalPending: ((requestId: string) => void) | undefined;
+  let onApprovalsResolved: (() => void) | undefined;
   const startVoiceTurn = mock(async (options: VoiceTurnOptions) => {
     callbacks = options.callbacks;
+    onApprovalPending = options.onApprovalPending;
+    onApprovalsResolved = options.onApprovalsResolved;
     return { turnId: "bridge-turn-1", abort: mock() };
   });
-  return { startVoiceTurn, getCallbacks: () => callbacks };
+  return {
+    startVoiceTurn,
+    getCallbacks: () => callbacks,
+    announceApprovalPending: () => onApprovalPending?.("req-1"),
+    announceApprovalsResolved: () => onApprovalsResolved?.(),
+  };
 }
 
 function createRecordingTtsStreamer(): {
@@ -442,7 +453,7 @@ describe("LiveVoiceSession assistant turn", () => {
     });
   });
 
-  test("records tool_use_start on the active turn without emitting frames", async () => {
+  test("records tool_use_start on the active turn and publishes what it is doing", async () => {
     let callbacks: VoiceTurnCallbacks | undefined;
     const startVoiceTurn = mock(async (options: VoiceTurnOptions) => {
       callbacks = options.callbacks;
@@ -459,9 +470,8 @@ describe("LiveVoiceSession assistant turn", () => {
       "thinking",
     ]);
 
-    const frameCountBefore = frames.length;
     callbacks?.tool_use_start?.("some_tool");
-    await flushAsyncCallbacks();
+    await waitForFrameCount(frames, 4);
 
     const activeTurn = (
       session as unknown as {
@@ -469,20 +479,30 @@ describe("LiveVoiceSession assistant turn", () => {
       }
     ).activeAssistantTurn;
     expect(activeTurn?.toolUseStarted).toBe(true);
-    expect(frames).toHaveLength(frameCountBefore);
+    // One activity frame, so a silent stretch of tool work is visible on the
+    // surfaces that show the session. An unrecognized tool still gets a line.
+    expect(frames.at(-1)).toMatchObject({
+      type: "activity",
+      label: "Working on it",
+    });
 
     callbacks?.message_complete?.({
       type: "message_complete",
       conversationId: "conversation-123",
       messageId: "assistant-message-123",
     });
-    await waitForFrameCount(frames, 4);
+    await waitForFrameCount(frames, 6);
     expect(frames.map((frame) => frame.type)).toEqual([
       "ready",
       "stt_final",
       "thinking",
+      "activity",
       "tts_done",
+      // The turn is over, so the line clears: no surface should keep showing
+      // the last tool it touched through the silence that follows.
+      "activity",
     ]);
+    expect(frames.at(-1)).toMatchObject({ type: "activity", label: "" });
   });
 
   test("interrupt aborts the in-flight turn and ignores late bridge events", async () => {
@@ -609,7 +629,7 @@ describe("LiveVoiceSession tool-use spoken ack", () => {
   });
 });
 
-describe("LiveVoiceSession minimize-room marker", () => {
+describe("LiveVoiceSession room reveal", () => {
   function createMarkerHarness() {
     const { startVoiceTurn, getCallbacks } = createCapturingTurnStarter();
     const { streamTtsAudio, ttsTexts } = createRecordingTtsStreamer();
@@ -624,11 +644,10 @@ describe("LiveVoiceSession minimize-room marker", () => {
   }
 
   /**
-   * Marker-command harness for the leg that can actually put something on
-   * screen: routing fronts every turn with the fast leg, so the front-door
-   * call is scripted to escalate ("[1] Working on it.") and the returned
-   * callbacks drive the ESCALATED leg — the only leg whose completion may
-   * latch `minimizeRequested`.
+   * Harness for the leg that can actually put something on screen: routing
+   * fronts every turn with the fast leg, so the front-door call is scripted to
+   * escalate ("[1] Working on it.") and the returned callbacks drive the
+   * ESCALATED leg; the toolless front door can never run a ui tool.
    */
   function createEscalatedMarkerHarness() {
     let escalatedCallbacks: VoiceTurnCallbacks | undefined;
@@ -664,35 +683,175 @@ describe("LiveVoiceSession minimize-room marker", () => {
     };
   }
 
-  test("strips a terminal [-1] from deltas and TTS and emits minimize_room after tts_done", async () => {
-    const { frames, session, getCallbacks, ttsTexts } =
-      createEscalatedMarkerHarness();
+  /** Run a ui tool to completion, as the agent loop would. */
+  function runUiTool(
+    getCallbacks: () => VoiceTurnCallbacks | undefined,
+    toolName: string,
+    opts?: { isError?: boolean },
+  ): void {
+    getCallbacks()?.tool_use_start?.(toolName);
+    getCallbacks()?.tool_result?.({
+      toolName,
+      resultPreview: "",
+      ...(opts?.isError === true ? { isError: true } : {}),
+    });
+  }
+
+  // Showing a surface is what reveals the screen. Nothing the model says does,
+  // so the user never loses the reveal to a forgotten token.
+  test("a ui tool emits minimize_room after tts_done", async () => {
+    const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
 
     await startReleasedTurn(session, getCallbacks);
-    emitTextDelta(getCallbacks, "hello world. [-1]");
+    runUiTool(getCallbacks, "ui_show");
+    emitTextDelta(getCallbacks, "Here is the summary.");
     emitMessageComplete(getCallbacks);
     await waitFor(() => frames.some((frame) => frame.type === "minimize_room"));
 
-    const joined = assistantDeltaTexts(frames).join("");
-    expect(joined).toContain("hello world. ");
-    expect(joined).not.toContain("[-1]");
-    expect(ttsTexts.join(" ")).not.toContain("[-1]");
     const ttsDoneIndex = frames.findIndex((frame) => frame.type === "tts_done");
     const minimizeIndex = frames.findIndex(
       (frame) => frame.type === "minimize_room",
     );
     expect(ttsDoneIndex).toBeGreaterThanOrEqual(0);
+    // After the speech drains, never mid-sentence.
     expect(minimizeIndex).toBeGreaterThan(ttsDoneIndex);
     expect(frames[minimizeIndex]).toMatchObject({
       type: "minimize_room",
       turnId: "live-turn-1",
     });
+    // At most once, however many surfaces the turn touched.
     expect(
       frames.filter((frame) => frame.type === "minimize_room"),
     ).toHaveLength(1);
   });
 
-  test("holds a marker split across deltas, never leaks the partial, and still emits", async () => {
+  // The reveal follows the surface, not the attempt: a rejected call (no
+  // surface_type, an empty card, a client that never acks) rendered nothing,
+  // and minimizing to show nothing is worse than staying put.
+  test("a failed ui call reveals nothing", async () => {
+    const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
+
+    await startReleasedTurn(session, getCallbacks);
+    runUiTool(getCallbacks, "ui_show", { isError: true });
+    emitTextDelta(getCallbacks, "I could not show that.");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+
+    expect(frames.some((frame) => frame.type === "minimize_room")).toBe(false);
+  });
+
+  test("a surface taken away before the reply ends reveals nothing", async () => {
+    const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
+
+    await startReleasedTurn(session, getCallbacks);
+    runUiTool(getCallbacks, "ui_show");
+    runUiTool(getCallbacks, "ui_dismiss");
+    emitTextDelta(getCallbacks, "Never mind, sorted it.");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+
+    expect(frames.some((frame) => frame.type === "minimize_room")).toBe(false);
+  });
+
+  // Opening an app puts something on screen just as a card does; a list keyed
+  // on "ui_" would have missed it.
+  test("opening an app reveals the screen", async () => {
+    const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
+
+    await startReleasedTurn(session, getCallbacks);
+    runUiTool(getCallbacks, "app_open");
+    emitTextDelta(getCallbacks, "Opened it up.");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "minimize_room"));
+
+    expect(frames.some((frame) => frame.type === "minimize_room")).toBe(true);
+  });
+
+  // A blocked turn has no speech left to drain, and the card it is blocked on
+  // renders behind the room. Waiting for a drain that is not coming would
+  // leave the call silent in front of a decision the user cannot see.
+  test("a pending approval reveals the screen immediately", async () => {
+    const { startVoiceTurn, announceApprovalPending } =
+      createCapturingTurnStarter();
+    const { frames, session } = createSessionHarness({ startVoiceTurn });
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+    await waitFor(() => frames.some((frame) => frame.type === "thinking"));
+
+    announceApprovalPending();
+    await waitFor(() => frames.some((frame) => frame.type === "minimize_room"));
+
+    // Before any tts_done, unlike the drain-scoped reveal a shown surface gets.
+    expect(frames.some((frame) => frame.type === "tts_done")).toBe(false);
+  });
+
+  // Every phrase progress narration has describes work in flight ("still on
+  // it", "almost there"). While the turn is blocked on the user, all of them
+  // are false, and the one that matters is the one about who is being waited
+  // on.
+  test("says it is waiting, once, and stops narrating progress", async () => {
+    const {
+      startVoiceTurn,
+      announceApprovalPending,
+      announceApprovalsResolved,
+    } = createCapturingTurnStarter();
+    const { streamTtsAudio, ttsTexts } = createRecordingTtsStreamer();
+    const { frames, session } = createSessionHarness({
+      startVoiceTurn,
+      streamTtsAudio,
+    });
+
+    await session.start();
+    await session.handleClientFrame({ type: "ptt_release" });
+    await waitFor(() => frames.some((frame) => frame.type === "thinking"));
+
+    announceApprovalPending();
+    await waitFor(() => ttsTexts.join(" ").includes("okay"));
+    // Repeat announcements do not repeat the line.
+    announceApprovalPending();
+    await flushAsyncCallbacks();
+
+    const saidWaiting = ttsTexts.filter((text) => text.includes("okay")).length;
+    expect(saidWaiting).toBe(1);
+
+    announceApprovalsResolved();
+    await flushAsyncCallbacks();
+  });
+
+  test("dismissing a surface does not reveal the screen", async () => {
+    const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
+
+    await startReleasedTurn(session, getCallbacks);
+    runUiTool(getCallbacks, "ui_dismiss");
+    emitTextDelta(getCallbacks, "Cleared that away.");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+
+    // Minimizing to show the user something that is no longer there is the
+    // opposite of the point.
+    expect(frames.some((frame) => frame.type === "minimize_room")).toBe(false);
+  });
+
+  // The marker is no longer taught to any leg, so this is about a model that
+  // emits one anyway: it must not be spoken, and it must not move the room.
+  test("a terminal [-1] is stripped from deltas and TTS and reveals nothing", async () => {
+    const { frames, session, getCallbacks, ttsTexts } =
+      createEscalatedMarkerHarness();
+
+    await startReleasedTurn(session, getCallbacks);
+    emitTextDelta(getCallbacks, "hello world. [-1]");
+    emitMessageComplete(getCallbacks);
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
+
+    const joined = assistantDeltaTexts(frames).join("");
+    expect(joined).toContain("hello world. ");
+    expect(joined).not.toContain("[-1]");
+    expect(ttsTexts.join(" ")).not.toContain("[-1]");
+    expect(frames.some((frame) => frame.type === "minimize_room")).toBe(false);
+  });
+
+  test("holds a marker split across deltas and never leaks the partial", async () => {
     const { frames, session, getCallbacks, ttsTexts } =
       createEscalatedMarkerHarness();
 
@@ -703,14 +862,14 @@ describe("LiveVoiceSession minimize-room marker", () => {
 
     emitTextDelta(getCallbacks, "1]");
     emitMessageComplete(getCallbacks);
-    await waitFor(() => frames.some((frame) => frame.type === "minimize_room"));
+    await waitFor(() => frames.some((frame) => frame.type === "tts_done"));
 
     const joined = assistantDeltaTexts(frames).join("");
     expect(joined).not.toContain("[-");
     expect(ttsTexts.join(" ")).not.toContain("[-");
   });
 
-  test("a mid-reply [-1] (content, not command) is stripped from speech but never minimizes", async () => {
+  test("a mid-reply [-1] is stripped from speech and never minimizes", async () => {
     const { frames, session, getCallbacks } = createMarkerHarness();
 
     await startReleasedTurn(session, getCallbacks);
@@ -728,7 +887,8 @@ describe("LiveVoiceSession minimize-room marker", () => {
     const { frames, session, getCallbacks } = createEscalatedMarkerHarness();
 
     await startReleasedTurn(session, getCallbacks);
-    emitTextDelta(getCallbacks, "Minimizing now. [-1]");
+    runUiTool(getCallbacks, "ui_show");
+    emitTextDelta(getCallbacks, "Showing you now.");
     await flushAsyncCallbacks();
 
     await session.handleClientFrame({ type: "interrupt" });
@@ -738,7 +898,7 @@ describe("LiveVoiceSession minimize-room marker", () => {
     expect(frames.some((frame) => frame.type === "minimize_room")).toBe(false);
   });
 
-  test("a turn without the marker emits no minimize_room frame", async () => {
+  test("a turn that shows nothing emits no minimize_room frame", async () => {
     const { frames, session, getCallbacks } = createMarkerHarness();
 
     await startReleasedTurn(session, getCallbacks);

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

@@ -254,13 +254,13 @@ 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 no-UI rule (voice turns are
-      // non-interactive — everything is conveyed in speech) and the shared
-      // no-setup-flows rule (no OAuth/browser flows mid-call). The [-1]
+      // first leg of every routed turn): the speech-first rule (which now
+      // permits a surface, since the room reveals one by itself) and the
+      // shared no-setup-flows rule (no OAuth/browser flows mid-call). The [-1]
       // room-minimize teaching is deliberately absent — only the escalated
       // leg learns it (see live-voice-triage-escalate.test.ts).
       voiceControlPrompt:
-        "You are speaking in a local live voice session. Keep replies brief and conversational. You cannot display cards, forms, or any on-screen UI during the call — convey everything in speech. " +
+        "You are speaking in a local live voice session. Keep replies brief and conversational. 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. " +
         VOICE_NO_SETUP_FLOWS_RULE,
     });
     callbacks?.assistant_text_delta?.(makeTextDelta("Hello there."));

package/src/live-voice/__tests__/live-voice-triage-escalate.test.ts

@@ -190,7 +190,7 @@ describe("live-voice triage-and-escalate routing", () => {
     expect(escalated?.content).toBe(ESCALATION_CONTINUATION_CONTENT);
   });
 
-  test("the [-1] teaching reaches the escalated leg's prompt but never the front-door leg's", async () => {
+  test("the screen-reveal teaching reaches the escalated leg's prompt but never the front-door leg's", async () => {
     const { starter } = scriptedStartVoiceTurn({
       frontDoor: ["[1] ", "Let me think about that."],
       escalated: ["The detailed answer is 42."],
@@ -205,10 +205,14 @@ describe("live-voice triage-and-escalate routing", () => {
       starter.mock.calls[0]?.[0]?.voiceControlPrompt ?? "";
     const escalatedPrompt =
       starter.mock.calls[1]?.[0]?.voiceControlPrompt ?? "";
-    // The toolless fast leg has nothing to show and its decision rule promises
-    // verbatim speech — it must never learn the marker.
+    // The toolless fast leg has nothing to show, so it is never told the
+    // screen will be revealed.
+    expect(frontDoorPrompt).not.toContain("the overlay minimizes");
+    expect(escalatedPrompt).toContain("the overlay minimizes");
+    // No leg is taught a marker any more: the reveal is decided by whether a
+    // ui tool ran, never by anything the model emits.
     expect(frontDoorPrompt).not.toContain("[-1]");
-    expect(escalatedPrompt).toContain("[-1]");
+    expect(escalatedPrompt).not.toContain("[-1]");
   });
 
   test("the verdict token and any text past the bridge cap never reach the transcript", async () => {

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

@@ -1207,8 +1207,16 @@ describe("LiveVoiceSession server VAD", () => {
     });
     // The barge-in utterance transcribes to nothing, so no follow-up turn
     // consumes the stash before the interrupt lands.
+    //
+    // "third question" is repeated because finals are handed out by transcriber
+    // creation order, and the session pre-arms a transcriber for the next
+    // utterance. The interrupt below can discard that pre-armed one and re-arm,
+    // which shifts the final utterance onto the following index — with a
+    // 3-entry list it would fall off the end and transcribe to the "utterance
+    // N" placeholder, so the wait for "third question" would time out rather
+    // than fail on the assertion. Both landing spots carry the same text.
     const { frames, session } = createHarness({
-      finals: ["first question", "", "third question"],
+      finals: ["first question", "", "third question", "third question"],
       startVoiceTurn,
       streamTtsAudio,
       spawnBackgroundContinuation,

package/src/live-voice/activity-label.ts

@@ -0,0 +1,141 @@
+/**
+ * Turns a tool call into one short user-facing line for the surfaces that show
+ * a running voice session.
+ *
+ * ## Why the copy lives here
+ *
+ * The iOS Live Activity has two drivers that must carry identical content: the
+ * live-voice socket, and an APNs push the daemon dispatches when the app is
+ * backgrounded and the web layer is suspended. Only one of them runs web code,
+ * so a label composed client-side could not be reproduced by the other. Both
+ * are therefore handed the same string, and this is where it is made.
+ *
+ * That does not contradict the rule that phase wording belongs to the web
+ * layer. The reason phase copy lives there is cadence: the iOS shell ships on
+ * App Store review while the web bundle deploys continuously, so a native
+ * `switch` would fossilize. This module deploys with the daemon, i.e.
+ * continuously, and it is the only layer that knows a tool ran at all.
+ *
+ * ## What makes a good label
+ *
+ * It is read on a Lock Screen, in a glance, by someone who is mid-conversation
+ * and not looking for detail. So: a present-participle phrase, no tool names,
+ * no arguments, no punctuation, and short enough to survive one line. Arguments
+ * are deliberately absent even though {@link summarizeToolInput} could supply
+ * them: a path or a URL on a Lock Screen is unreadable at a glance and can
+ * carry content the user would not choose to show a passer-by.
+ */
+
+/**
+ * The tools that put something on screen worth looking at.
+ *
+ * `app_open` belongs here with the ui-surface tools: it proxies to a connected
+ * client to bring an app up, which is the same thing from the user's side, and
+ * a list keyed on "ui_" would have missed it.
+ *
+ * `ui_dismiss` is deliberately absent, and is handled as its own case: it
+ * retires a surface, and revealing the screen to show the user something that
+ * is no longer there is the opposite of the point.
+ */
+const UI_REVEAL_TOOLS: ReadonlySet<string> = new Set([
+  "ui_show",
+  "ui_update",
+  "app_open",
+]);
+
+/** The tool that takes a surface away again. */
+const UI_DISMISS_TOOL = "ui_dismiss";
+
+/**
+ * Whether running `toolName` leaves something on screen the user should be
+ * shown, which is what makes a live-voice turn reveal the screen behind the
+ * call overlay.
+ */
+export function revealsUiSurface(toolName: string): boolean {
+  return UI_REVEAL_TOOLS.has(toolName);
+}
+
+/** Whether `toolName` takes a surface off the screen. */
+export function dismissesUiSurface(toolName: string): boolean {
+  return toolName === UI_DISMISS_TOOL;
+}
+
+/**
+ * Present-participle phrases for the built-in tools, by exact name.
+ *
+ * Grouped by what the user would say is happening, not by how the tool is
+ * implemented: `bash` and `host_bash` differ in where they run, which is not a
+ * distinction anyone glancing at a Lock Screen is making.
+ */
+const TOOL_ACTIVITY_LABELS: Readonly<Record<string, string>> = {
+  bash: "Running a command",
+  terminal: "Running a command",
+  host_bash: "Running a command",
+  file_read: "Reading a file",
+  host_file_read: "Reading a file",
+  file_write: "Writing a file",
+  host_file_write: "Writing a file",
+  file_edit: "Editing a file",
+  host_file_edit: "Editing a file",
+  host_file_transfer: "Moving a file",
+  file_search: "Searching files",
+  web_search: "Searching the web",
+  web_fetch: "Reading a page",
+  network_request: "Making a request",
+  browser: "Using the browser",
+  computer_use: "Using the computer",
+  memory: "Checking memory",
+  schedule: "Checking the schedule",
+  ui_show: "Putting something on screen",
+  ui_update: "Putting something on screen",
+  app_open: "Opening an app",
+};
+
+/**
+ * Prefix-matched fallbacks, tried in order when a tool has no exact entry.
+ *
+ * The tool vocabulary is open: plugins, MCP servers, and skills all contribute
+ * names this module has never seen, and a new built-in should not have to be
+ * registered here to avoid a blank island. Prefixes cover the families whose
+ * names are structured; {@link GENERIC_ACTIVITY_LABEL} covers the rest.
+ */
+const TOOL_ACTIVITY_LABEL_PREFIXES: ReadonlyArray<readonly [string, string]> = [
+  ["browser_", "Using the browser"],
+  ["computer_", "Using the computer"],
+  ["file_", "Working with files"],
+  ["host_file_", "Working with files"],
+  ["web_", "Looking something up"],
+  ["mcp_", "Using a connected app"],
+  ["skill_", "Running a skill"],
+  ["subagent", "Working on it"],
+];
+
+/**
+ * What an unrecognized tool reads as.
+ *
+ * Deliberately vague rather than derived from the tool's name. A humanized
+ * `slack_conversations_history` is worse than "Working on it": it is longer
+ * than the slot, it leaks an internal vocabulary, and it reads like an error
+ * message. The label's job is to show the turn is alive and doing something,
+ * and this does that job for every tool that will ever exist.
+ */
+export const GENERIC_ACTIVITY_LABEL = "Working on it";
+
+/**
+ * The line to show while `toolName` runs.
+ *
+ * Total, by construction: every tool gets a label, because the alternative is
+ * a surface that goes blank precisely when the assistant is busiest.
+ */
+export function activityLabelForTool(toolName: string): string {
+  const exact = TOOL_ACTIVITY_LABELS[toolName];
+  if (exact !== undefined) {
+    return exact;
+  }
+  for (const [prefix, label] of TOOL_ACTIVITY_LABEL_PREFIXES) {
+    if (toolName.startsWith(prefix)) {
+      return label;
+    }
+  }
+  return GENERIC_ACTIVITY_LABEL;
+}