@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/tools/acp/spawn.test.ts

@@ -124,11 +124,22 @@ const spawnMock = mock(
     _cwd: string,
     _parentConversationId: string,
     _sendToVellum: (msg: unknown) => void,
-    _parentToolUseId?: string,
-  ) => ({
-    acpSessionId: "acp-session-test",
-    protocolSessionId: "proto-session-test",
-  }),
+    _options?: { parentToolUseId?: string; model?: string },
+  ): Promise<{
+    acpSessionId: string;
+    protocolSessionId: string;
+    requestedModel?: string;
+    effectiveModel?: string;
+    modelWarning?: string;
+  }> => {
+    const requestedModel = _options?.model?.trim() || undefined;
+    return {
+      acpSessionId: "acp-session-test",
+      protocolSessionId: "proto-session-test",
+      requestedModel,
+      effectiveModel: "opus",
+    };
+  },
 );
 
 // Spread the real module's exports so transitive importers that pull other
@@ -201,6 +212,8 @@ describe("executeAcpSpawn - happy path", () => {
     const payload = JSON.parse(result.content);
     expect(payload.acpSessionId).toBe("acp-session-test");
     expect(payload.status).toBe("running");
+    expect(payload.requestedModel).toBeNull();
+    expect(payload.effectiveModel).toBe("opus");
     // The real adapter binary is spawned (no `bun x` wrapper).
     const agentConfigArg = spawnMock.mock.calls[0][1] as { command: string };
     expect(agentConfigArg.command).toBe("claude-agent-acp");
@@ -214,8 +227,10 @@ describe("executeAcpSpawn - happy path", () => {
 
     expect(result.isError).toBe(false);
     expect(spawnMock).toHaveBeenCalledTimes(1);
-    // parentToolUseId is the 7th positional arg to spawn().
-    expect(spawnMock.mock.calls[0][6]).toBe("toolu_abc123");
+    // The options bag is the 7th positional arg to spawn().
+    expect(spawnMock.mock.calls[0][6]).toEqual({
+      parentToolUseId: "toolu_abc123",
+    });
   });
 
   test("default-profile fallback when user config is empty", async () => {
@@ -272,7 +287,7 @@ describe("executeAcpSpawn — input validation", () => {
     expect(result.isError).toBe(true);
     expect(result.content).toContain("claude-agent-acp is not on PATH");
     expect(result.content).toContain(
-      "bun add -g @agentclientprotocol/claude-agent-acp",
+      "bun add -g @agentclientprotocol/claude-agent-acp@0.75.1",
     );
     expect(execFileMock).not.toHaveBeenCalled();
     expect(spawnMock).not.toHaveBeenCalled();
@@ -309,7 +324,7 @@ describe("executeAcpSpawn: sandboxed bun auto-install on missing binary", () =>
     expect(spawnMock).toHaveBeenCalledTimes(1);
     const payload = JSON.parse(result.content);
     expect(payload.message).toContain(
-      "Installed @agentclientprotocol/claude-agent-acp automatically.",
+      "Installed @agentclientprotocol/claude-agent-acp@0.75.1 automatically.",
     );
     // The real binary was spawned with cwd = the project dir and token
     // injected (trusted-binary config, no resolution at spawn).
@@ -330,7 +345,7 @@ describe("executeAcpSpawn: sandboxed bun auto-install on missing binary", () =>
     expect(args).toEqual([
       "add",
       "--global",
-      "@agentclientprotocol/claude-agent-acp",
+      "@agentclientprotocol/claude-agent-acp@0.75.1",
     ]);
   });
 
@@ -419,7 +434,7 @@ describe("executeAcpSpawn: sandboxed bun auto-install on missing binary", () =>
     expect(result.isError).toBe(true);
     expect(result.content).toContain("claude-agent-acp is not on PATH");
     expect(result.content).toContain(
-      "bun add -g @agentclientprotocol/claude-agent-acp",
+      "bun add -g @agentclientprotocol/claude-agent-acp@0.75.1",
     );
     expect(result.content).toContain("auto-install failed");
     expect(result.content).toContain("EACCES");
@@ -458,6 +473,126 @@ describe("executeAcpSpawn — per-agent resume hint", () => {
   });
 });
 
+describe("executeAcpSpawn - model selection", () => {
+  test("threads the requested model into manager.spawn's options", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "opus" },
+      { ...makeContext(), toolUseId: "toolu_model" },
+    );
+
+    expect(result.isError).toBe(false);
+    expect(spawnMock.mock.calls[0][6]).toEqual({
+      parentToolUseId: "toolu_model",
+      model: "opus",
+    });
+    const payload = JSON.parse(result.content);
+    expect(payload.requestedModel).toBe("opus");
+    expect(payload.effectiveModel).toBe("opus");
+    expect(payload.message).toContain(
+      'The top-level ACP session reports "opus" as its effective model.',
+    );
+  });
+
+  test("reports the manager-normalized requested model", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "  opus  " },
+      makeContext(),
+    );
+
+    expect(spawnMock.mock.calls[0][6]).toEqual({
+      parentToolUseId: undefined,
+      model: "  opus  ",
+    });
+    expect(JSON.parse(result.content).requestedModel).toBe("opus");
+  });
+
+  test("a null model is treated as omitted", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: null },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    const options = spawnMock.mock.calls[0][6] as { model?: string };
+    expect(options.model).toBeUndefined();
+  });
+
+  test("a modelWarning from the spawn is relayed in the result message", async () => {
+    spawnMock.mockImplementationOnce(async () => ({
+      acpSessionId: "acp-session-test",
+      protocolSessionId: "proto-session-test",
+      requestedModel: "nope",
+      effectiveModel: "opus",
+      modelWarning: "Unknown model: nope",
+    }));
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "nope" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    expect(payload.message).toContain(
+      "The requested model was not applied: Unknown model: nope",
+    );
+    expect(payload.requestedModel).toBe("nope");
+    expect(payload.effectiveModel).toBe("opus");
+  });
+
+  test("the note relays a no-selector warning without calling it a refusal", async () => {
+    spawnMock.mockImplementationOnce(async () => ({
+      acpSessionId: "acp-session-test",
+      protocolSessionId: "proto-session-test",
+      requestedModel: "opus",
+      modelWarning:
+        'Agent "claude" does not support model selection, so the session is running on the agent\'s own model.',
+    }));
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "opus" },
+      makeContext(),
+    );
+
+    const payload = JSON.parse(result.content);
+    expect(payload.message).toContain("does not support model selection");
+    expect(payload.message).not.toContain("refused");
+  });
+
+  test("no model note when the spawn reports no warning", async () => {
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "opus" },
+      makeContext(),
+    );
+
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    expect(payload.message).not.toContain(
+      "The requested model was not applied",
+    );
+  });
+
+  test("reports when the adapter does not identify the effective model", async () => {
+    spawnMock.mockImplementationOnce(async () => ({
+      acpSessionId: "acp-session-test",
+      protocolSessionId: "proto-session-test",
+      requestedModel: "sonnet",
+    }));
+
+    const result = await executeAcpSpawn(
+      { agent: "claude", task: "do something", model: "sonnet" },
+      makeContext(),
+    );
+
+    const payload = JSON.parse(result.content);
+    expect(payload.requestedModel).toBe("sonnet");
+    expect(payload.effectiveModel).toBeNull();
+    expect(payload.message).toContain(
+      "The top-level ACP session did not report an effective model.",
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // executeAcpSpawn — CLAUDE_CODE_OAUTH_TOKEN env injection + preflight
 //

package/src/tools/acp/spawn.ts

@@ -37,6 +37,7 @@ export const acpSpawnInputSchema = z.looseObject({
   agent: nullAsOmitted(z.string()),
   task: nullAsOmitted(z.string()),
   cwd: nullAsOmitted(z.string()),
+  model: nullAsOmitted(z.string()),
 });
 
 /**
@@ -66,6 +67,7 @@ export async function executeAcpSpawn(
   }
   const agent = parsedInput.data.agent || "claude";
   const task = parsedInput.data.task;
+  const model = parsedInput.data.model;
 
   if (!task) {
     return { content: '"task" is required.', isError: true };
@@ -124,14 +126,20 @@ export async function executeAcpSpawn(
     // Recheck: the auto-install and the agent-env preparation above are both
     // awaits, and this is the point a long-lived subprocess starts.
     throwIfCancelled(context);
-    const { acpSessionId, protocolSessionId } = await manager.spawn(
+    const {
+      acpSessionId,
+      protocolSessionId,
+      requestedModel,
+      effectiveModel,
+      modelWarning,
+    } = await manager.spawn(
       agent,
       agentConfig,
       task,
       cwd,
       context.conversationId,
       sendToClient,
-      context.toolUseId,
+      { parentToolUseId: context.toolUseId, model },
       // The manager rechecks after its own protocol handshake and session
       // creation, so a turn stopped in that window tears the child process
       // down instead of handing it the task.
@@ -150,16 +158,26 @@ export async function executeAcpSpawn(
     const installNote = autoInstalledPackage
       ? ` Installed ${autoInstalledPackage} automatically.`
       : "";
+    // Relayed verbatim: the warning already distinguishes an adapter with no
+    // selector from one that refused the value.
+    const modelNote = modelWarning
+      ? ` The requested model was not applied: ${modelWarning}`
+      : "";
+    const effectiveModelNote = effectiveModel
+      ? ` The top-level ACP session reports "${effectiveModel}" as its effective model.`
+      : " The top-level ACP session did not report an effective model.";
     const payload = JSON.stringify({
       acpSessionId,
       protocolSessionId,
       agent,
       cwd,
+      requestedModel: requestedModel ?? null,
+      effectiveModel: effectiveModel ?? null,
       status: "running",
       message:
         `ACP agent "${agent}" spawned (session: ${protocolSessionId}). ` +
         `Results stream back via SSE. You will be notified when it completes.` +
-        `${installNote}${resumeHint}`,
+        `${installNote}${modelNote}${effectiveModelNote}${resumeHint}`,
     });
 
     return { content: payload, isError: false };

package/src/tools/acp/status.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Tests for the `acp_status` tool's projection of session state.
+ *
+ * The state the manager tracks feeds three surfaces with different budgets:
+ * the HTTP route, the SSE picker, and this tool, whose output is spent on
+ * LLM context. Only the fields an agent can act on belong here.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+
+import type { AcpSessionState } from "../../acp/types.js";
+import type { ToolContext } from "../types.js";
+
+const RUNNING_STATE: AcpSessionState = {
+  id: "acp-1",
+  agentId: "claude",
+  acpSessionId: "proto-1",
+  parentConversationId: "conv-1",
+  status: "running",
+  startedAt: 1234,
+  task: "refactor the parser",
+  model: "claude-opus-4-5",
+  availableModels: [
+    { value: "sonnet", label: "Sonnet" },
+    { value: "opus", label: "Opus", description: "Most capable" },
+  ],
+};
+
+let statusResult: AcpSessionState | AcpSessionState[] = RUNNING_STATE;
+
+const realAcpModule = await import("../../acp/index.js");
+mock.module("../../acp/index.js", () => ({
+  ...realAcpModule,
+  getAcpSessionManager: () => ({ getStatus: () => statusResult }),
+}));
+
+const { executeAcpStatus } = await import("./status.js");
+
+const context = {
+  conversationId: "conv-1",
+  workingDir: "/tmp",
+} as unknown as ToolContext;
+
+describe("executeAcpStatus", () => {
+  test("a single session reports its model but not the picker", async () => {
+    statusResult = RUNNING_STATE;
+
+    const result = await executeAcpStatus({ acp_session_id: "acp-1" }, context);
+
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    expect(payload).toEqual({
+      id: "acp-1",
+      agentId: "claude",
+      acpSessionId: "proto-1",
+      parentConversationId: "conv-1",
+      status: "running",
+      startedAt: 1234,
+      task: "refactor the parser",
+      model: "claude-opus-4-5",
+    });
+    expect(result.content).not.toContain("Most capable");
+  });
+
+  test("the listing drops the picker from every entry", async () => {
+    statusResult = [
+      RUNNING_STATE,
+      { ...RUNNING_STATE, id: "acp-2", model: "sonnet" },
+    ];
+
+    const result = await executeAcpStatus({}, context);
+
+    const payload = JSON.parse(result.content) as Array<
+      Record<string, unknown>
+    >;
+    expect(payload).toHaveLength(2);
+    expect(payload.map((entry) => entry.model)).toEqual([
+      "claude-opus-4-5",
+      "sonnet",
+    ]);
+    for (const entry of payload) {
+      expect(entry).not.toHaveProperty("availableModels");
+    }
+  });
+
+  test("an empty listing says so rather than rendering an empty array", async () => {
+    statusResult = [];
+
+    const result = await executeAcpStatus({}, context);
+
+    expect(result.content).toBe("No ACP sessions found.");
+    expect(result.isError).toBe(false);
+  });
+});

package/src/tools/acp/status.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { getAcpSessionManager } from "../../acp/index.js";
+import type { AcpSessionState } from "../../acp/types.js";
 import {
   invalidToolInputResult,
   nullAsOmitted,
@@ -16,6 +17,40 @@ export const acpStatusInputSchema = z.looseObject({
   acp_session_id: nullAsOmitted(z.string()),
 });
 
+/**
+ * The session fields worth spending LLM context on. An allowlist rather than
+ * an omission: `availableModels` is a picker for the human surfaces (HTTP and
+ * SSE) that says nothing the agent can act on, and a field added to
+ * `AcpSessionState` for those surfaces should not reach this one by default.
+ * `model` stays: which model a session is running on is answerable.
+ */
+function projectSession(state: AcpSessionState) {
+  return {
+    id: state.id,
+    agentId: state.agentId,
+    acpSessionId: state.acpSessionId,
+    parentConversationId: state.parentConversationId,
+    status: state.status,
+    startedAt: state.startedAt,
+    completedAt: state.completedAt,
+    error: state.error,
+    stopReason: state.stopReason,
+    task: state.task,
+    parentToolUseId: state.parentToolUseId,
+    authErrorCode: state.authErrorCode,
+    authErrorCredential: state.authErrorCredential,
+    latestUsage: state.latestUsage,
+    model: state.model,
+  };
+}
+
+/** Projects either shape `getStatus` answers with. */
+function projectStatus(status: AcpSessionState | AcpSessionState[]): unknown {
+  return Array.isArray(status)
+    ? status.map(projectSession)
+    : projectSession(status);
+}
+
 export async function executeAcpStatus(
   input: Record<string, unknown>,
   _context: ToolContext,
@@ -29,9 +64,8 @@ export async function executeAcpStatus(
 
   try {
     if (acpSessionId) {
-      const state = manager.getStatus(acpSessionId);
       return {
-        content: JSON.stringify(state),
+        content: JSON.stringify(projectStatus(manager.getStatus(acpSessionId))),
         isError: false,
       };
     }
@@ -42,7 +76,10 @@ export async function executeAcpStatus(
       return { content: "No ACP sessions found.", isError: false };
     }
 
-    return { content: JSON.stringify(allStates), isError: false };
+    return {
+      content: JSON.stringify(projectStatus(allStates)),
+      isError: false,
+    };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { content: msg, isError: true };

package/src/tools/app-control/skill-proxy-bridge.ts

@@ -5,6 +5,7 @@
  * the proxy resolver, which forwards the call to the connected client.
  */
 
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { throwIfCancelled } from "../shared/abort.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -32,7 +33,7 @@ export function forwardAppControlProxyTool(
   }
   if (!context.proxyToolResolver) {
     return Promise.resolve({
-      content: `Cannot execute ${toolName}: no proxy resolver available. This tool requires a connected client.`,
+      content: formatDesktopAppRequired("apps"),
       isError: true,
     });
   }

package/src/tools/browser/browser-execution.ts

@@ -262,7 +262,7 @@ export const EXTRACT_LINKS_EXPRESSION = `
 (() => {
   const anchors = Array.from(document.querySelectorAll('a[href]'));
   return anchors.slice(0, 200).map(a => ({
-    text: (a.textContent || '').trim().slice(0, 80),
+    text: Array.from((a.textContent || '').trim()).slice(0, 80).join(''),
     href: a.href,
   }));
 })()

package/src/tools/browser/cdp-client/accessibility-snapshot.ts

@@ -14,6 +14,8 @@
  * a later PR is a direct drop-in replacement.
  */
 
+import { safeStringSlice } from "../../../util/unicode.js";
+
 // ── Types ─────────────────────────────────────────────────────────────
 
 /**
@@ -288,7 +290,11 @@ function extractAttrs(node: RawAxNode): Record<string, string> {
     if (!PROPERTY_ALLOWLIST.has(name)) {
       continue;
     }
-    attrs[name] = stringifyAxValue(prop.value?.value).slice(0, MAX_VALUE_CHARS);
+    attrs[name] = safeStringSlice(
+      stringifyAxValue(prop.value?.value),
+      0,
+      MAX_VALUE_CHARS,
+    );
   }
   return attrs;
 }
@@ -346,12 +352,12 @@ export function transformAxTree(
     }
 
     const rawName = typeof node.name?.value === "string" ? node.name.value : "";
-    const name = rawName.trim().slice(0, MAX_NAME_CHARS);
+    const name = safeStringSlice(rawName.trim(), 0, MAX_NAME_CHARS);
 
     const rawValue = node.value?.value;
     const value =
       typeof rawValue === "string" && rawValue.length > 0
-        ? rawValue.slice(0, MAX_VALUE_CHARS)
+        ? safeStringSlice(rawValue, 0, MAX_VALUE_CHARS)
         : undefined;
 
     const attrs = extractAttrs(node);

package/src/tools/browser/cdp-client/cdp-inspect/discovery.ts

@@ -25,6 +25,7 @@
  * value.
  */
 
+import { safeStringSlice } from "../../../../util/unicode.js";
 import type { CdpWsTransport } from "./ws-transport.js";
 
 /**
@@ -336,7 +337,7 @@ function parseJsonText(text: string, endpoint: string): unknown {
   } catch (err) {
     throw new DevToolsDiscoveryError(
       "invalid_response",
-      `Expected JSON from ${endpoint} but got: ${text.slice(0, 200)}`,
+      `Expected JSON from ${endpoint} but got: ${safeStringSlice(text, 0, 200)}`,
       err,
     );
   }

package/src/tools/browser/cdp-client/extension-cdp-client.ts

@@ -1,5 +1,6 @@
 import type { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
 import { getLogger } from "../../../util/logger.js";
+import { safeStringSlice } from "../../../util/unicode.js";
 import type { CdpErrorCode } from "./errors.js";
 import { CdpError } from "./errors.js";
 import type { CdpClientKind, ScopedCdpClient, TabInfo } from "./types.js";
@@ -121,7 +122,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
         // and mask the extension path as the true failing hop.
         throw new CdpError(
           "cdp_error",
-          result.content.slice(0, 200) || `CDP error for ${method}`,
+          safeStringSlice(result.content, 0, 200) || `CDP error for ${method}`,
           {
             cdpMethod: method,
             cdpParams: params,
@@ -164,7 +165,7 @@ export class ExtensionCdpClient implements ScopedCdpClient {
     } catch (err) {
       throw new CdpError(
         "transport_error",
-        `Non-JSON content from host_browser_result: ${result.content.slice(0, 200)}`,
+        `Non-JSON content from host_browser_result: ${safeStringSlice(result.content, 0, 200)}`,
         {
           cdpMethod: method,
           cdpParams: params,

package/src/tools/browser/network-recorder.ts

@@ -7,6 +7,7 @@
 
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import type {
   ExtractedCredential,
   NetworkRecordedEntry,
@@ -457,7 +458,7 @@ export class NetworkRecorder {
 
         entry.response.body =
           body.length > MAX_BODY_SIZE
-            ? body.slice(0, MAX_BODY_SIZE) + "...[truncated]"
+            ? safeStringSlice(body, 0, MAX_BODY_SIZE) + "...[truncated]"
             : body;
       }
     } catch {

package/src/tools/capability-offer.test.ts

@@ -4,11 +4,26 @@ import {
   appendLoggedInBrowserOffer,
   CHROME_WEB_STORE_INSTALL_URL,
   DESKTOP_APP_DOWNLOAD_URL,
+  formatDesktopAppRequired,
   formatLoggedInBrowserOffer,
   isPhoneSurface,
   shouldOfferLoggedInBrowser,
 } from "./capability-offer.js";
 
+describe("formatDesktopAppRequired", () => {
+  test("offers a direct desktop-app download and retry step", () => {
+    const message = formatDesktopAppRequired("shell");
+
+    expect(message).toContain(
+      "The Vellum desktop app is needed to run commands on your computer",
+    );
+    expect(message).toContain(DESKTOP_APP_DOWNLOAD_URL);
+    expect(message).toContain("Open it, then retry.");
+    expect(message).not.toContain("client");
+    expect(message).not.toContain("daemon");
+  });
+});
+
 describe("isPhoneSurface", () => {
   test("is true for iOS transport and mobile client OS", () => {
     expect(isPhoneSurface({ transportInterface: "ios" })).toBe(true);
@@ -49,7 +64,9 @@ describe("shouldOfferLoggedInBrowser", () => {
     expect(shouldOfferLoggedInBrowser('Invalid browser_mode "bogus"')).toBe(
       false,
     );
-    expect(shouldOfferLoggedInBrowser("url must use http or https")).toBe(false);
+    expect(shouldOfferLoggedInBrowser("url must use http or https")).toBe(
+      false,
+    );
   });
 });
 
@@ -71,6 +88,7 @@ describe("formatLoggedInBrowserOffer", () => {
     });
     expect(offer).toContain("no in-app browser");
     expect(offer).toContain("Do not describe a browser panel");
+    expect(offer).toContain("Mac or Windows PC");
     expect(offer).toContain(DESKTOP_APP_DOWNLOAD_URL);
     expect(offer).toContain(CHROME_WEB_STORE_INSTALL_URL);
   });
@@ -78,7 +96,9 @@ describe("formatLoggedInBrowserOffer", () => {
 
 describe("appendLoggedInBrowserOffer", () => {
   test("appends the offer once", () => {
-    const once = appendLoggedInBrowserOffer("Error: Navigation failed: timeout");
+    const once = appendLoggedInBrowserOffer(
+      "Error: Navigation failed: timeout",
+    );
     expect(once).toContain("Error: Navigation failed: timeout");
     expect(once).toContain(DESKTOP_APP_DOWNLOAD_URL);
     const twice = appendLoggedInBrowserOffer(once);

package/src/tools/capability-offer.ts

@@ -7,7 +7,22 @@ export const DESKTOP_APP_DOWNLOAD_URL = "https://www.vellum.ai/downloads";
 export const CHROME_WEB_STORE_INSTALL_URL =
   "https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne";
 
-export const DESKTOP_APP_INSTALL_HINT = `Install the Vellum desktop app: ${DESKTOP_APP_DOWNLOAD_URL}`;
+export const DESKTOP_APP_INSTALL_HINT = `Download the Vellum desktop app: ${DESKTOP_APP_DOWNLOAD_URL}. Open it, then retry.`;
+
+export type DesktopAppCapability = "files" | "screen" | "shell" | "apps";
+
+const DESKTOP_APP_CAPABILITY_ACTION: Record<DesktopAppCapability, string> = {
+  files: "access files on your computer",
+  screen: "view or control your screen",
+  shell: "run commands on your computer",
+  apps: "control apps on your computer",
+};
+
+export function formatDesktopAppRequired(
+  capability: DesktopAppCapability,
+): string {
+  return `Error: The Vellum desktop app is needed to ${DESKTOP_APP_CAPABILITY_ACTION[capability]}. ${DESKTOP_APP_INSTALL_HINT}`;
+}
 
 /** User-facing install step for status userActions and command-failure hints. */
 export const CHROME_EXTENSION_INSTALL_HINT = `Install the Vellum Assistant Chrome extension from the Chrome Web Store: ${CHROME_WEB_STORE_INSTALL_URL}`;