@vellumai/assistant 0.4.16 → 0.4.17

package/src/config/bundled-skills/chatgpt-import/tools/chatgpt-import.ts

@@ -4,11 +4,13 @@ import { inflateRawSync } from "node:zlib";
 import { eq } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import { getConfig } from "../../../../config/loader.js";
 import {
   addMessage,
   createConversation,
 } from "../../../../memory/conversation-store.js";
 import { getDb } from "../../../../memory/db.js";
+import { indexMessageNow } from "../../../../memory/indexer.js";
 import {
   conversationKeys,
   conversations,
@@ -88,7 +90,9 @@ export async function run(
     imported = parseChatGPTExport(filePath);
   } catch (err) {
     return {
-      content: `Error parsing export file: ${err instanceof Error ? err.message : String(err)}`,
+      content: `Error parsing export file: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
       isError: true,
     };
   }
@@ -121,9 +125,15 @@ export async function run(
 
     const conversation = createConversation(conv.title);
 
+    // Skip indexing during insert so we can backfill original timestamps first
     for (const msg of conv.messages) {
-      // Uses the daemon's addMessage which triggers memory indexing
-      await addMessage(conversation.id, msg.role, JSON.stringify(msg.content));
+      await addMessage(
+        conversation.id,
+        msg.role,
+        JSON.stringify(msg.content),
+        undefined,
+        { skipIndexing: true },
+      );
     }
 
     // Override timestamps to match ChatGPT originals
@@ -140,11 +150,26 @@ export async function run(
       .orderBy(messagesTable.createdAt)
       .all();
 
+    const memoryConfig = getConfig().memory;
     for (let i = 0; i < dbMessages.length && i < conv.messages.length; i++) {
+      const originalTimestamp = conv.messages[i].createdAt;
       db.update(messagesTable)
-        .set({ createdAt: conv.messages[i].createdAt })
+        .set({ createdAt: originalTimestamp })
         .where(eq(messagesTable.id, dbMessages[i].id))
         .run();
+
+      // Index with the original ChatGPT timestamp so memory segments
+      // reflect actual message age, not import time
+      indexMessageNow(
+        {
+          messageId: dbMessages[i].id,
+          conversationId: conversation.id,
+          role: conv.messages[i].role,
+          content: JSON.stringify(conv.messages[i].content),
+          createdAt: originalTimestamp,
+        },
+        memoryConfig,
+      );
     }
 
     db.insert(conversationKeys)

package/src/config/bundled-skills/messaging/SKILL.md

@@ -306,6 +306,7 @@ When a user asks to declutter, clean up, or organize their email — start scann
 1. **Scan**: Call `gmail_sender_digest` (or `messaging_sender_digest` for non-Gmail). Default query targets promotions from the last 90 days.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
    - **Gmail columns (exactly 3)**: Sender, Emails Found, Unsub?
+     - **Unsub? cell values**: Use rich cell format: `{ "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" }` when `has_unsubscribe` is true, `{ "text": "No", "icon": "minus.circle", "iconColor": "muted" }` when false.
    - **Non-Gmail columns (exactly 2)**: Sender, Emails Found (omit the Unsub? column — unsubscribe is not available)
    - **Pre-select all rows** (`selected: true`) — users deselect what they want to keep
    - **Caption**: "Showing emails from last 90 days in Promotions" (or adjusted to match the query used)
@@ -313,11 +314,11 @@ When a user asks to declutter, clean up, or organize their email — start scann
    - **Non-Gmail action button (exactly 1)**: "Archive Selected" (primary). Do not offer an unsubscribe button — it is Gmail-specific. **NEVER offer Delete, Trash, or any destructive action.**
 3. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button:
    - **Dismiss the table immediately** with `ui_dismiss` — it collapses to a completion chip
-   - **Show a `task_progress` card** with one step per selected sender (e.g., "Archiving TechCrunch (247 emails)"). Update each step from `in_progress` → `completed` as each sender finishes.
+   - **Show a `task_progress` card** with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step from `in_progress` → `completed` as each phase finishes.
    - When all senders are processed, set the progress card's `status: "completed"`.
-4. **Act on selection**: For each selected sender:
-   - Use `gmail_batch_archive` (or `messaging_archive_by_sender` for non-Gmail) with `scan_id` + the selected senders' `id` values as `sender_ids` — this resolves message IDs server-side without putting them in context
-   - If Gmail and the action is "Archive & Unsubscribe" and `has_unsubscribe` is true, call `gmail_unsubscribe` with the sender's `newest_message_id`
+4. **Act on selection** — batch, don't loop:
+   - **Archive all at once**: Call `gmail_batch_archive` (or `messaging_archive_by_sender` for non-Gmail) **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the Gmail API calls internally — never loop sender-by-sender.
+   - **Unsubscribe in bulk**: If Gmail and the action is "Archive & Unsubscribe", call `gmail_unsubscribe` for each sender that has `has_unsubscribe: true` — but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
 5. **Accurate summary**: The scan counts are exact — the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders." For Gmail, append: "Unsubscribed from [unsub_count]."
 6. **Ongoing protection offer (Gmail only)**: After reporting results, offer auto-archive filters:
    - "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"

package/src/config/bundled-skills/messaging/tools/messaging-reply.ts

@@ -54,17 +54,21 @@ function parseAddressList(header: string): string[] {
  *   - `user@example.com (team <ops>)`
  *
  * Extracts all angle-bracketed segments and picks the last one containing `@`,
- * falling back to the last segment, then to the raw string. This handles both
- * display names with angle brackets and trailing RFC 5322 comments that may
- * contain angle brackets.
+ * preferring the actual mailbox over display-name fragments like
+ * `"Acme <support@acme.com>" <owner@example.com>`. If no segment contains `@`,
+ * strips angle-bracketed portions and parenthetical comments, returning the
+ * remaining text. This handles display names with angle brackets and trailing
+ * RFC 5322 comments.
  */
 function extractEmail(address: string): string {
-  const segments = [...address.matchAll(/<([^>]+)>/g)].map((m) => m[1]);
+  // Strip parenthetical comments first to avoid matching addresses inside them
+  const cleaned = address.replace(/\(.*?\)/g, '');
+  const segments = [...cleaned.matchAll(/<([^>]+)>/g)].map((m) => m[1]);
   if (segments.length > 0) {
-    const emailSegment = segments.findLast((s) => s.includes('@'));
-    return (emailSegment ?? segments[segments.length - 1]).trim().toLowerCase();
+    const emailSegment = [...segments].reverse().find((s) => s.includes('@'));
+    if (emailSegment) return emailSegment.trim().toLowerCase();
   }
-  return address.trim().toLowerCase();
+  return address.replace(/<[^>]+>/g, '').replace(/\(.*?\)/g, '').trim().toLowerCase();
 }
 
 export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {

package/src/config/env.ts

@@ -14,10 +14,13 @@
  * without circular imports.
  */
 
-import { getLogger } from '../util/logger.js';
-import { checkUnrecognizedEnvVars,getEnableMonitoring } from './env-registry.js';
+import { getLogger } from "../util/logger.js";
+import {
+  checkUnrecognizedEnvVars,
+  getEnableMonitoring,
+} from "./env-registry.js";
 
-const log = getLogger('env');
+const log = getLogger("env");
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -35,7 +38,9 @@ function int(name: string, fallback?: number): number | undefined {
   if (!raw) return fallback;
   const n = parseInt(raw, 10);
   if (isNaN(n)) {
-    throw new Error(`Invalid integer for ${name}: "${raw}"${fallback !== undefined ? ` (fallback: ${fallback})` : ''}`);
+    throw new Error(
+      `Invalid integer for ${name}: "${raw}"${fallback !== undefined ? ` (fallback: ${fallback})` : ""}`,
+    );
   }
   return n;
 }
@@ -45,7 +50,7 @@ function int(name: string, fallback?: number): number | undefined {
 const DEFAULT_GATEWAY_PORT = 7830;
 
 export function getGatewayPort(): number {
-  return int('GATEWAY_PORT', DEFAULT_GATEWAY_PORT);
+  return int("GATEWAY_PORT", DEFAULT_GATEWAY_PORT);
 }
 
 /**
@@ -53,8 +58,8 @@ export function getGatewayPort(): number {
  * Prefers GATEWAY_INTERNAL_BASE_URL if set, otherwise derives from port.
  */
 export function getGatewayInternalBaseUrl(): string {
-  const explicit = str('GATEWAY_INTERNAL_BASE_URL');
-  if (explicit) return explicit.replace(/\/+$/, '');
+  const explicit = str("GATEWAY_INTERNAL_BASE_URL");
+  if (explicit) return explicit.replace(/\/+$/, "");
   return `http://127.0.0.1:${getGatewayPort()}`;
 }
 
@@ -62,7 +67,7 @@ export function getGatewayInternalBaseUrl(): string {
 
 /** Read the INGRESS_PUBLIC_BASE_URL env var (may be mutated at runtime by config handlers). */
 export function getIngressPublicBaseUrl(): string | undefined {
-  return str('INGRESS_PUBLIC_BASE_URL');
+  return str("INGRESS_PUBLIC_BASE_URL");
 }
 
 /** Set or clear the INGRESS_PUBLIC_BASE_URL env var (used by config handlers). */
@@ -77,29 +82,32 @@ export function setIngressPublicBaseUrl(value: string | undefined): void {
 // ── Runtime HTTP ─────────────────────────────────────────────────────────────
 
 export function getRuntimeHttpPort(): number {
-  return int('RUNTIME_HTTP_PORT') ?? 7821;
+  return int("RUNTIME_HTTP_PORT") ?? 7821;
 }
 
 export function getRuntimeHttpHost(): string {
-  return str('RUNTIME_HTTP_HOST') || '127.0.0.1';
+  return str("RUNTIME_HTTP_HOST") || "127.0.0.1";
 }
 
 export function getRuntimeProxyBearerToken(): string | undefined {
-  return str('RUNTIME_PROXY_BEARER_TOKEN');
+  return str("RUNTIME_PROXY_BEARER_TOKEN");
 }
 
 export function getRuntimeGatewayOriginSecret(): string | undefined {
-  return str('RUNTIME_GATEWAY_ORIGIN_SECRET');
+  return str("RUNTIME_GATEWAY_ORIGIN_SECRET");
 }
 
 /**
  * True when HTTP API auth is disabled via DISABLE_HTTP_AUTH=true AND the
  * safety gate VELLUM_UNSAFE_AUTH_BYPASS=1 is also set. Without the safety
  * gate, the bypass is ignored.
+ *
+ * Also returns true in test environments (bun test sets NODE_ENV=test)
+ * so that tests don't need to initialize the JWT signing key.
  */
 export function isHttpAuthDisabled(): boolean {
-  if (str('DISABLE_HTTP_AUTH')?.toLowerCase() !== 'true') return false;
-  return str('VELLUM_UNSAFE_AUTH_BYPASS')?.trim() === '1';
+  if (str("DISABLE_HTTP_AUTH")?.toLowerCase() !== "true") return false;
+  return str("VELLUM_UNSAFE_AUTH_BYPASS")?.trim() === "1";
 }
 
 /**
@@ -107,39 +115,39 @@ export function isHttpAuthDisabled(): boolean {
  * VELLUM_UNSAFE_AUTH_BYPASS=1 is missing — used for warning messages.
  */
 export function hasUngatedHttpAuthDisabled(): boolean {
-  if (str('DISABLE_HTTP_AUTH')?.toLowerCase() !== 'true') return false;
-  return str('VELLUM_UNSAFE_AUTH_BYPASS')?.trim() !== '1';
+  if (str("DISABLE_HTTP_AUTH")?.toLowerCase() !== "true") return false;
+  return str("VELLUM_UNSAFE_AUTH_BYPASS")?.trim() !== "1";
 }
 
 // ── Twilio ───────────────────────────────────────────────────────────────────
 
 export function getTwilioPhoneNumberEnv(): string | undefined {
-  return str('TWILIO_PHONE_NUMBER');
+  return str("TWILIO_PHONE_NUMBER");
 }
 
 export function getTwilioUserPhoneNumber(): string | undefined {
-  return str('TWILIO_USER_PHONE_NUMBER');
+  return str("TWILIO_USER_PHONE_NUMBER");
 }
 
 export function getTwilioWssBaseUrl(): string | undefined {
-  return str('TWILIO_WSS_BASE_URL');
+  return str("TWILIO_WSS_BASE_URL");
 }
 
 export function isTwilioWebhookValidationDisabled(): boolean {
   // Intentionally strict: only exact "true" disables validation (not "1").
   // This is a security-sensitive bypass — we don't want environments that
   // template booleans as "1" to silently skip webhook signature checks.
-  return process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED === 'true';
+  return process.env.TWILIO_WEBHOOK_VALIDATION_DISABLED === "true";
 }
 
 export function getCallWelcomeGreeting(): string | undefined {
-  return str('CALL_WELCOME_GREETING');
+  return str("CALL_WELCOME_GREETING");
 }
 
 // ── Monitoring ───────────────────────────────────────────────────────────────
 
 export function getLogfireToken(): string | undefined {
-  return str('LOGFIRE_TOKEN');
+  return str("LOGFIRE_TOKEN");
 }
 
 export function isMonitoringEnabled(): boolean {
@@ -147,25 +155,25 @@ export function isMonitoringEnabled(): boolean {
 }
 
 export function getSentryDsn(): string | undefined {
-  return str('SENTRY_DSN');
+  return str("SENTRY_DSN");
 }
 
 // ── Qdrant ───────────────────────────────────────────────────────────────────
 
 export function getQdrantUrlEnv(): string | undefined {
-  return str('QDRANT_URL');
+  return str("QDRANT_URL");
 }
 
 // ── Ollama ───────────────────────────────────────────────────────────────────
 
 export function getOllamaBaseUrlEnv(): string | undefined {
-  return str('OLLAMA_BASE_URL');
+  return str("OLLAMA_BASE_URL");
 }
 
 // ── Platform ─────────────────────────────────────────────────────────────────
 
 export function getPlatformBaseUrl(): string {
-  return str('PLATFORM_BASE_URL') ?? '';
+  return str("PLATFORM_BASE_URL") ?? "";
 }
 
 /**
@@ -173,7 +181,7 @@ export function getPlatformBaseUrl(): string {
  * Required for registering callback routes when containerized.
  */
 export function getPlatformAssistantId(): string {
-  return str('PLATFORM_ASSISTANT_ID') ?? '';
+  return str("PLATFORM_ASSISTANT_ID") ?? "";
 }
 
 /**
@@ -181,7 +189,7 @@ export function getPlatformAssistantId(): string {
  * with the platform's internal gateway callback route registration endpoint.
  */
 export function getPlatformInternalApiKey(): string {
-  return str('PLATFORM_INTERNAL_API_KEY') ?? '';
+  return str("PLATFORM_INTERNAL_API_KEY") ?? "";
 }
 
 // ── Startup validation ──────────────────────────────────────────────────────
@@ -203,7 +211,9 @@ export function validateEnv(): void {
   }
 
   if (getTwilioWssBaseUrl()) {
-    log.warn('TWILIO_WSS_BASE_URL env var is deprecated. Relay URL is now derived from ingress.publicBaseUrl.');
+    log.warn(
+      "TWILIO_WSS_BASE_URL env var is deprecated. Relay URL is now derived from ingress.publicBaseUrl.",
+    );
   }
 
   for (const warning of checkUnrecognizedEnvVars()) {

package/src/daemon/handlers/skills.ts

@@ -300,6 +300,7 @@ export async function handleSkillsInstall(
     );
     if (bundled) {
       // Auto-enable the bundled skill so it's immediately usable
+      let autoEnabled = false;
       try {
         const raw = loadRawConfig();
         ensureSkillEntry(raw, msg.slug).enabled = true;
@@ -319,6 +320,7 @@ export async function handleSkillsInstall(
           CONFIG_RELOAD_DEBOUNCE_MS,
         );
         ctx.updateConfigFingerprint();
+        autoEnabled = true;
       } catch (err) {
         log.warn(
           { err, skillId: msg.slug },
@@ -331,11 +333,13 @@ export async function handleSkillsInstall(
         operation: "install",
         success: true,
       });
-      ctx.broadcast({
-        type: "skills_state_changed",
-        name: msg.slug,
-        state: "enabled",
-      });
+      if (autoEnabled) {
+        ctx.broadcast({
+          type: "skills_state_changed",
+          name: msg.slug,
+          state: "enabled",
+        });
+      }
       return;
     }
 
@@ -357,6 +361,7 @@ export async function handleSkillsInstall(
     loadSkillCatalog();
 
     // Auto-enable the newly installed skill so it's immediately usable.
+    let autoEnabled = false;
     try {
       const raw = loadRawConfig();
       ensureSkillEntry(raw, skillId).enabled = true;
@@ -376,6 +381,7 @@ export async function handleSkillsInstall(
         CONFIG_RELOAD_DEBOUNCE_MS,
       );
       ctx.updateConfigFingerprint();
+      autoEnabled = true;
     } catch (err) {
       log.warn({ err, skillId }, "Failed to auto-enable installed skill");
     }
@@ -385,11 +391,13 @@ export async function handleSkillsInstall(
       operation: "install",
       success: true,
     });
-    ctx.broadcast({
-      type: "skills_state_changed",
-      name: skillId,
-      state: "enabled",
-    });
+    if (autoEnabled) {
+      ctx.broadcast({
+        type: "skills_state_changed",
+        name: skillId,
+        state: "enabled",
+      });
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err }, "Failed to install skill");

package/src/daemon/ipc-contract/messages.ts

@@ -240,6 +240,7 @@ export interface AssistantActivityState {
     | 'thinking_delta'
     | 'first_text_delta'
     | 'tool_use_start'
+    | 'tool_result_received'
     | 'confirmation_requested'
     | 'confirmation_resolved'
     | 'message_complete'

package/src/daemon/ipc-contract/surfaces.ts

@@ -104,9 +104,15 @@ export interface TableColumn {
   width?: number;
 }
 
+export interface TableCellValue {
+  text: string;
+  icon?: string;       // SF Symbol name
+  iconColor?: string;  // semantic token: "success" | "warning" | "error" | "muted"
+}
+
 export interface TableRow {
   id: string;
-  cells: Record<string, string>;
+  cells: Record<string, string | TableCellValue>;
   selectable?: boolean;
   selected?: boolean;
 }

package/src/daemon/session-agent-loop-handlers.ts

@@ -319,6 +319,11 @@ export function handleToolResult(
   // call re-emits the activity state transitions.
   state.firstTextDeltaEmitted = false;
   state.firstThinkingDeltaEmitted = false;
+
+  // Emit activity state immediately so clients show a thinking indicator
+  // during the gap between tool_result and the next thinking_delta/text_delta.
+  const statusText = `Processing ${friendlyToolName(state.lastCompletedToolName ?? '')} results`;
+  deps.ctx.emitActivityState('thinking', 'tool_result_received', 'assistant_turn', deps.reqId, statusText);
 }
 
 export function handleError(

package/src/daemon/session-agent-loop.ts

@@ -133,7 +133,7 @@ export interface AgentLoopSessionContext {
 
   emitActivityState(
     phase: 'idle' | 'thinking' | 'streaming' | 'tool_running' | 'awaiting_confirmation',
-    reason: 'message_dequeued' | 'thinking_delta' | 'first_text_delta' | 'tool_use_start' | 'confirmation_requested' | 'confirmation_resolved' | 'message_complete' | 'generation_cancelled' | 'error_terminal',
+    reason: 'message_dequeued' | 'thinking_delta' | 'first_text_delta' | 'tool_use_start' | 'tool_result_received' | 'confirmation_requested' | 'confirmation_resolved' | 'message_complete' | 'generation_cancelled' | 'error_terminal',
     anchor?: 'assistant_turn' | 'user_turn' | 'global',
     requestId?: string,
     statusText?: string,

package/src/daemon/session-process.ts

@@ -89,7 +89,7 @@ export interface ProcessSessionContext {
   setTurnInterfaceContext(ctx: TurnInterfaceContext): void;
   emitActivityState(
     phase: 'idle' | 'thinking' | 'streaming' | 'tool_running' | 'awaiting_confirmation',
-    reason: 'message_dequeued' | 'thinking_delta' | 'first_text_delta' | 'tool_use_start' | 'confirmation_requested' | 'confirmation_resolved' | 'message_complete' | 'generation_cancelled' | 'error_terminal',
+    reason: 'message_dequeued' | 'thinking_delta' | 'first_text_delta' | 'tool_use_start' | 'tool_result_received' | 'confirmation_requested' | 'confirmation_resolved' | 'message_complete' | 'generation_cancelled' | 'error_terminal',
     anchor?: 'assistant_turn' | 'user_turn' | 'global',
     requestId?: string,
     statusText?: string,

package/src/daemon/session-surfaces.ts

@@ -151,6 +151,10 @@ export interface SurfaceSessionContext {
     onEvent: (msg: ServerMessage) => void,
     requestId: string,
     activeSurfaceId?: string,
+    currentPage?: string,
+    metadata?: Record<string, unknown>,
+    options?: { isInteractive?: boolean },
+    displayContent?: string,
   ): { queued: boolean; rejected?: boolean; requestId: string };
   getQueueDepth(): number;
   processMessage(
@@ -158,6 +162,10 @@ export interface SurfaceSessionContext {
     attachments: never[],
     onEvent: (msg: ServerMessage) => void,
     requestId?: string,
+    activeSurfaceId?: string,
+    currentPage?: string,
+    options?: { isInteractive?: boolean },
+    displayContent?: string,
   ): Promise<string>;
   /** Serialize operations on a given surface to prevent read-modify-write races. */
   withSurface<T>(surfaceId: string, fn: () => T | Promise<T>): Promise<T>;
@@ -406,6 +414,8 @@ export function handleSurfaceAction(ctx: SurfaceSessionContext, surfaceId: strin
     fallbackContent += `\n\nAction data: ${JSON.stringify(data)}`;
   }
   const content = prompt || fallbackContent;
+  // Show the user plain-text instead of raw JSON action data.
+  const displayContent = prompt ? undefined : buildUserFacingLabel(pending.surfaceType, actionId, data);
 
   const requestId = uuid();
   ctx.surfaceActionRequestIds.add(requestId);
@@ -426,7 +436,7 @@ export function handleSurfaceAction(ctx: SurfaceSessionContext, surfaceId: strin
     attributes: { source: 'surface_action', surfaceId, actionId },
   });
 
-  const result = ctx.enqueueMessage(content, [], onEvent, requestId, surfaceId);
+  const result = ctx.enqueueMessage(content, [], onEvent, requestId, surfaceId, undefined, undefined, undefined, displayContent);
   if (result.queued) {
     const position = ctx.getQueueDepth();
     if (!retainPending) {
@@ -467,7 +477,7 @@ export function handleSurfaceAction(ctx: SurfaceSessionContext, surfaceId: strin
     ctx.pendingSurfaceActions.delete(surfaceId);
   }
   log.info({ surfaceId, actionId, requestId }, 'Processing surface action as follow-up');
-  ctx.processMessage(content, [], onEvent, requestId).catch((err) => {
+  ctx.processMessage(content, [], onEvent, requestId, surfaceId, undefined, undefined, displayContent).catch((err) => {
     const message = err instanceof Error ? err.message : String(err);
     log.error({ err, surfaceId, actionId }, 'Error processing surface action');
     onEvent({ type: 'error', message: `Failed to process surface action: ${message}` });
@@ -545,6 +555,36 @@ export function buildCompletionSummary(surfaceType: string | undefined, actionId
   return actionId.charAt(0).toUpperCase() + actionId.slice(1);
 }
 
+/**
+ * Build a plain-text label shown to the user in the chat bubble for a
+ * surface action. Unlike `buildCompletionSummary` (which is for the LLM),
+ * this produces natural language the user can glance at.
+ */
+export function buildUserFacingLabel(surfaceType: string | undefined, actionId: string, data?: Record<string, unknown>): string {
+  const count = (data?.selectedIds as string[] | undefined)?.length;
+
+  if (surfaceType === 'confirmation') {
+    if (actionId === 'cancel') return 'Cancelled';
+    if (actionId === 'confirm') return 'Confirmed';
+    return `Selected: ${actionId}`;
+  }
+  if (surfaceType === 'form') return 'Submitted';
+
+  // Table / list selection actions
+  if (count) {
+    const noun = count === 1 ? 'item' : 'items';
+    const action = actionId
+      .replace(/_/g, ' ')
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+    return `${action} ${count} ${noun}`;
+  }
+
+  // Generic fallback — humanize the action ID
+  return actionId
+    .replace(/_/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
 /**
  * Resolve a proxy tool call that targets a UI surface.
  * Handles ui_show, ui_update, ui_dismiss, request_file, computer_use_request_control, and app_open.