@vellumai/assistant 0.12.0 → 0.12.1-dev.202609141913.5e16607

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/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}`;

package/src/tools/computer-use/definitions.ts

@@ -8,6 +8,7 @@
  */
 
 import { RiskLevel } from "../../permissions/types.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -31,7 +32,7 @@ function proxyExecute(toolName: string) {
   ): Promise<ToolExecutionResult> => {
     if (!context.proxyToolResolver) {
       return {
-        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires a connected desktop client.`,
+        content: formatDesktopAppRequired("screen"),
         isError: true,
       };
     }
@@ -456,7 +457,8 @@ export const computerUseObserveTool = {
         type: "integer",
         minimum: 1,
         maximum: 4294967295,
-        description: "macOS only: capture this native CGWindowID instead of the desktop, including only its accessibility tree. Obtain a current native window ID first; do not guess or use a browser tab ID. Applies to this observation only, not subsequent actions. Requires a desktop helper with window-capture support. Screenshot coordinates are window-relative; use accessibility element IDs for later actions, not desktop scaling.",
+        description:
+          "macOS only: capture this native CGWindowID instead of the desktop, including only its accessibility tree. Obtain a current native window ID first; do not guess or use a browser tab ID. Applies to this observation only, not subsequent actions. Requires a desktop helper with window-capture support. Screenshot coordinates are window-relative; use accessibility element IDs for later actions, not desktop scaling.",
       },
       target_client_id: {
         type: "string",

package/src/tools/computer-use/skill-proxy-bridge.ts

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

package/src/tools/credentials/metadata-store.ts

@@ -20,6 +20,7 @@ import {
 } from "@vellumai/credential-storage";
 import type { CredentialRecord } from "@vellumai/service-contracts/credential-rpc";
 
+import { createCesHttpRecordBackendIfConfigured } from "../../security/ces-http-record-backend.js";
 import type { CredentialRecordBackend } from "../../security/ces-rpc-record-backend.js";
 import { getLogger } from "../../util/logger.js";
 import type { CredentialInjectionTemplate } from "./policy-types.js";
@@ -55,6 +56,11 @@ const CES_MEMORY_PATH = "ces-in-memory-credential-metadata";
 let _store: StaticCredentialMetadataStore | undefined;
 let _overridePath: string | null = null;
 let _recordBackend: CredentialRecordBackend | undefined;
+/**
+ * Test override for the CES HTTP listing fallback. `undefined` uses the
+ * production factory. `null` disables HTTP fallback.
+ */
+let _httpRecordBackendOverride: CredentialRecordBackend | null | undefined;
 let _cesRecordsLoaded = false;
 let _cesLoad: Promise<void> | undefined;
 let _cesLoadGeneration = 0;
@@ -255,6 +261,93 @@ export function listCredentialMetadata(): CredentialMetadata[] {
   return getStore().list() as CredentialMetadata[];
 }
 
+export type CredentialRecordListResult = {
+  records: CredentialMetadata[];
+  unreachable: boolean;
+};
+
+type ListedCredentialRecords = Array<{
+  account: string;
+  record: CredentialRecord;
+}>;
+
+function backendIsAvailable(backend: CredentialRecordBackend): boolean {
+  try {
+    return backend.isAvailable();
+  } catch {
+    return false;
+  }
+}
+
+async function listFromRecordBackend(
+  backend: CredentialRecordBackend,
+): Promise<ListedCredentialRecords | null> {
+  if (!backendIsAvailable(backend)) {
+    return null;
+  }
+  return backend.list();
+}
+
+function resolveHttpRecordBackend(): CredentialRecordBackend | null {
+  if (_httpRecordBackendOverride !== undefined) {
+    return _httpRecordBackendOverride;
+  }
+  return createCesHttpRecordBackendIfConfigured();
+}
+
+async function listFromHttpFallback(): Promise<ListedCredentialRecords | null> {
+  const httpBackend = resolveHttpRecordBackend();
+  if (!httpBackend) {
+    return null;
+  }
+  return listFromRecordBackend(httpBackend);
+}
+
+/**
+ * Live catalog from the credential record backend. Does not read the
+ * daemon in-process cache, so an outage cannot be mistaken for an empty
+ * vault. `unreachable` is true when the backend is missing, down, or
+ * the list RPC fails, and CES HTTP failover is also unavailable.
+ *
+ * When the attached backend is CES RPC (or none is attached), listing
+ * fails over to CES HTTP in containerized deployments so a down RPC
+ * socket does not hide a healthy vault sidecar. A successful empty
+ * catalog (`[]`) does not fall through to HTTP.
+ *
+ * The file-backed test store is the catalog when a test override path is set.
+ */
+export async function listCredentialRecordsLive(): Promise<CredentialRecordListResult> {
+  if (_overridePath) {
+    return {
+      records: getStore().list() as CredentialMetadata[],
+      unreachable: false,
+    };
+  }
+  if (_recordBackend) {
+    const remote = await listFromRecordBackend(_recordBackend);
+    if (remote !== null) {
+      return {
+        records: remote.map((entry) => entry.record as CredentialMetadata),
+        unreachable: false,
+      };
+    }
+    if (_recordBackend.name !== "ces-rpc") {
+      return { records: [], unreachable: true };
+    }
+  }
+  const httpRemote = await listFromHttpFallback();
+  if (httpRemote !== null) {
+    log.warn(
+      "CES RPC credential record list unavailable. Failing over to CES HTTP.",
+    );
+    return {
+      records: httpRemote.map((entry) => entry.record as CredentialMetadata),
+      unreachable: false,
+    };
+  }
+  return { records: [], unreachable: true };
+}
+
 /**
  * Delete metadata for a credential.
  */
@@ -287,3 +380,10 @@ export function _setMetadataPath(path: string | null): void {
     }
   }
 }
+
+/** @internal Test-only: override the CES HTTP listing fallback. */
+export function _setHttpRecordBackendForTests(
+  backend: CredentialRecordBackend | null | undefined,
+): void {
+  _httpRecordBackendOverride = backend;
+}

package/src/tools/host-filesystem/edit.test.ts

@@ -71,8 +71,9 @@ describe("host_file_edit cross-client guards", () => {
     );
     expect(result.isError).toBe(true);
     expect(result.content).toContain(
-      "no client with host_file capability is connected",
+      "The Vellum desktop app is needed to access files on your computer",
     );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
   });
 
   test("returns 'specified client disconnected' error when targetClientId set but proxy unavailable on web", async () => {

package/src/tools/host-filesystem/edit.ts

@@ -4,7 +4,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
-import { desktopClientName } from "../client-os.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatEditDiff } from "../shared/filesystem/format-diff.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
@@ -115,7 +115,7 @@ export const hostFileEditTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
+        content: formatDesktopAppRequired("files"),
         isError: true,
       };
     }

package/src/tools/host-filesystem/read.test.ts

@@ -67,8 +67,9 @@ describe("host_file_read cross-client guards", () => {
     );
     expect(result.isError).toBe(true);
     expect(result.content).toContain(
-      "no client with host_file capability is connected",
+      "The Vellum desktop app is needed to access files on your computer",
     );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
   });
 
   test("returns 'specified client disconnected' error when targetClientId set but proxy unavailable on web", async () => {

package/src/tools/host-filesystem/read.ts

@@ -6,7 +6,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
-import { desktopClientName } from "../client-os.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import {
   AUDIO_EXTENSIONS,
   readAudioFile,
@@ -121,7 +121,7 @@ export const hostFileReadTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
+        content: formatDesktopAppRequired("files"),
         isError: true,
       };
     }

package/src/tools/host-filesystem/transfer.test.ts

@@ -335,8 +335,9 @@ describe("host_file_transfer cross-client guards", () => {
 
     expect(result.isError).toBe(true);
     expect(result.content).toContain(
-      "no client with host_file capability is connected",
+      "The Vellum desktop app is needed to access files on your computer",
     );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
     expect(toSandboxCalls.length).toBe(0);
   });
 

package/src/tools/host-filesystem/transfer.ts

@@ -6,7 +6,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
-import { desktopClientName } from "../client-os.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { declareDaemonActivityField } from "../schema-transforms.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
 import type {
@@ -126,7 +126,7 @@ export const hostFileTransferTool = {
       !HostTransferProxy.instance.isAvailable()
     ) {
       return {
-        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
+        content: formatDesktopAppRequired("files"),
         isError: true,
       };
     }

package/src/tools/host-filesystem/write.test.ts

@@ -67,8 +67,9 @@ describe("host_file_write cross-client guards", () => {
     );
     expect(result.isError).toBe(true);
     expect(result.content).toContain(
-      "no client with host_file capability is connected",
+      "The Vellum desktop app is needed to access files on your computer",
     );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
   });
 
   test("returns 'specified client disconnected' error when targetClientId set but proxy unavailable on web", async () => {

package/src/tools/host-filesystem/write.ts

@@ -4,7 +4,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
-import { desktopClientName } from "../client-os.js";
+import { formatDesktopAppRequired } from "../capability-offer.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
@@ -90,7 +90,7 @@ export const hostFileWriteTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
+        content: formatDesktopAppRequired("files"),
         isError: true,
       };
     }

package/src/tools/host-terminal/host-shell.test.ts

@@ -170,6 +170,22 @@ afterEach(() => {
   mockProxyAvailable = false;
 });
 
+describe("host_bash unavailable desktop-app recovery", () => {
+  test("offers the desktop app download when a web turn has no host connection", async () => {
+    const result = await hostShellTool.execute(
+      { command: "pwd" },
+      makeContext({ transportInterface: "web" }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      "The Vellum desktop app is needed to run commands on your computer",
+    );
+    expect(result.content).toContain("https://www.vellum.ai/downloads");
+    expect(result.content).toContain("Open it, then retry.");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Proxy path — background: true
 // ---------------------------------------------------------------------------