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

package/src/cli/lib/list-installed-plugins.ts

@@ -17,6 +17,10 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  LEGACY_PLUGIN_MANIFEST,
+  readPluginManifest,
+} from "../../util/plugin-manifest.js";
 import { parsePluginIcon } from "./plugin-artifact.js";
 import { readValidatedPluginIcon } from "./plugin-icon-file.js";
 
@@ -51,10 +55,13 @@ export interface InstalledPluginInfo {
   readonly name: string;
   /** Absolute path to the plugin directory. */
   readonly target: string;
-  /** Parsed `package.json` content, when present and parseable. */
+  /**
+   * Metadata from the selected manifest. The API exposes this field as
+   * `packageJson`.
+   */
   readonly packageJson: PluginPackageMetadata | null;
   /**
-   * Non-fatal issues with this entry (missing `package.json`, malformed
+   * Non-fatal issues with this entry (missing or malformed selected manifest,
    * JSON, unexpected type, etc.). Empty when the entry parses cleanly.
    */
   readonly issues: readonly string[];
@@ -143,51 +150,30 @@ function readPluginEntry(
   name: string,
 ): InstalledPluginInfo {
   const target = join(pluginsDir, name);
-  const pkgJsonPath = join(target, "package.json");
   const issues: string[] = [];
 
   // Icon validation is independent of package.json parsing, so resolve it
   // once and attach to every return below (including error paths).
   const iconFields = pluginIconFields(target);
 
-  if (!existsSync(pkgJsonPath)) {
-    issues.push("missing package.json");
-    return { name, target, packageJson: null, issues, ...iconFields };
-  }
-
-  let raw: string;
-  try {
-    raw = readFileSync(pkgJsonPath, "utf8");
-  } catch (err) {
-    issues.push(
-      `package.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return { name, target, packageJson: null, issues, ...iconFields };
-  }
-
-  let parsed: unknown;
+  let manifest: ReturnType<typeof readPluginManifest>;
   try {
-    parsed = JSON.parse(raw);
+    manifest = readPluginManifest(target);
   } catch (err) {
-    issues.push(
-      `package.json invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
-    );
+    issues.push(err instanceof Error ? err.message : String(err));
     return { name, target, packageJson: null, issues, ...iconFields };
   }
-
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    issues.push("package.json is not an object");
-    return { name, target, packageJson: null, issues, ...iconFields };
-  }
-
-  const meta = parsed as Record<string, unknown>;
-  const icon = parsePluginIcon(meta);
+  const meta = manifest.raw;
+  const icon =
+    manifest.source === LEGACY_PLUGIN_MANIFEST
+      ? parsePluginIcon(meta)
+      : undefined;
   const packageJson: PluginPackageMetadata = {
-    name: typeof meta.name === "string" ? meta.name : undefined,
-    version: typeof meta.version === "string" ? meta.version : undefined,
-    description:
-      typeof meta.description === "string" ? meta.description : undefined,
+    name: manifest.name,
+    version: manifest.version,
+    description: manifest.description,
     peerDependencies:
+      manifest.source === LEGACY_PLUGIN_MANIFEST &&
       typeof meta.peerDependencies === "object" &&
       meta.peerDependencies !== null &&
       !Array.isArray(meta.peerDependencies)

package/src/cli/lib/plugin-details.ts

@@ -33,6 +33,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
+import { readPluginManifest } from "../../util/plugin-manifest.js";
 import type { FetchLike } from "./fetch-like.js";
 import { sanitizePluginName } from "./install-from-github.js";
 import {
@@ -230,22 +231,34 @@ interface LocalPlugin {
   readonly readme: string | null;
 }
 
-/** Read an installed copy's `package.json` + README off disk, if present. */
+/** Read an installed copy's selected manifest and README off disk, if present. */
 function readLocalPlugin(pluginsDir: string, name: string): LocalPlugin {
   const target = join(pluginsDir, name);
   if (!existsSync(target)) {
     return { installed: false, manifest: emptyManifest(), readme: null };
   }
 
-  const pkgPath = join(target, "package.json");
   let manifest = emptyManifest();
-  if (existsSync(pkgPath)) {
-    try {
-      manifest = parseManifest(readFileSync(pkgPath, "utf8"));
-    } catch {
-      // A malformed local manifest degrades to empty fields — the entry is
-      // still "installed", we just have nothing extra to surface from it.
+  try {
+    const packagePath = join(target, "package.json");
+    if (existsSync(packagePath)) {
+      // Detail metadata is intentionally lenient. An installed legacy package
+      // may omit the loader-required name while still carrying useful fields.
+      manifest = parseManifest(readFileSync(packagePath, "utf8"));
+    } else {
+      const selected = readPluginManifest(target);
+      manifest = {
+        version: selected.version ?? null,
+        description: selected.description ?? null,
+        homepage: selected.homepage ?? null,
+        license: normalizeLicense(selected.license),
+        artifact: null,
+        icon: null,
+      };
     }
+  } catch {
+    // A malformed local manifest degrades to empty fields. The entry is still
+    // installed, but it has no manifest metadata to surface.
   }
 
   return { installed: true, manifest, readme: readLocalReadme(target) };

package/src/cli/lib/uninstall-plugin.ts

@@ -15,10 +15,13 @@ import { existsSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { runShutdownHook } from "../../hooks/hook-loader.js";
+import { MESSAGE_KEYS, t } from "../../i18n/index.js";
 import { isPluginDisabled } from "../../plugins/disabled-state.js";
+import { PLUGIN_MCP_MANIFEST } from "../../plugins/mcp-servers.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import {
   InvalidPluginNameError,
+  readInstallMeta,
   sanitizePluginName,
 } from "./install-from-github.js";
 
@@ -40,11 +43,27 @@ export interface UninstallPluginOptions {
   readonly workspacePluginsDir?: string;
 }
 
+export const PLUGIN_UNINSTALL_WARNING_KEYS = {
+  MCP_OAUTH_CREDENTIALS_UNCHECKED:
+    MESSAGE_KEYS.PLUGIN_MCP_OAUTH_CREDENTIALS_UNCHECKED,
+} as const;
+
+export type PluginUninstallWarningKey =
+  (typeof PLUGIN_UNINSTALL_WARNING_KEYS)[keyof typeof PLUGIN_UNINSTALL_WARNING_KEYS];
+
+export function resolvePluginUninstallWarning(
+  key: PluginUninstallWarningKey,
+): string {
+  return t(key);
+}
+
 /** Result of a successful uninstall. */
 export interface UninstallPluginResult {
   readonly name: string;
   /** Absolute path that was removed. */
   readonly target: string;
+  /** Stable keys for non-fatal cleanup limitations. */
+  readonly warnings?: PluginUninstallWarningKey[];
 }
 
 /**
@@ -87,6 +106,41 @@ export async function uninstallPlugin(
     throw new PluginNotInstalledError(name, target);
   }
 
+  const hasCurrentMcpManifest = existsSync(join(target, PLUGIN_MCP_MANIFEST));
+  const recordedFiles = readInstallMeta(target)?.fingerprint?.files;
+  const hasRecordedMcpManifest =
+    recordedFiles !== undefined &&
+    Object.hasOwn(recordedFiles, PLUGIN_MCP_MANIFEST);
+  const warnings: PluginUninstallWarningKey[] = [];
+  const { deletePluginMcpOAuthCredentials } =
+    await import("../../mcp/mcp-oauth-provider.js");
+  let credentialsReachable = true;
+  let cleanup:
+    | Awaited<ReturnType<typeof deletePluginMcpOAuthCredentials>>
+    | undefined;
+  try {
+    cleanup = await deletePluginMcpOAuthCredentials(name);
+    credentialsReachable = !cleanup.unreachable;
+  } catch {
+    credentialsReachable = false;
+  }
+  if (cleanup && !cleanup.unreachable && !cleanup.ok) {
+    throw new Error(
+      `Plugin "${name}" was not removed because its MCP OAuth credentials could not be deleted.`,
+    );
+  }
+
+  if (!credentialsReachable) {
+    if (hasCurrentMcpManifest || hasRecordedMcpManifest) {
+      throw new Error(
+        `Plugin "${name}" was not removed because credential storage is unavailable and its MCP OAuth credentials could not be checked.`,
+      );
+    }
+    warnings.push(
+      PLUGIN_UNINSTALL_WARNING_KEYS.MCP_OAUTH_CREDENTIALS_UNCHECKED,
+    );
+  }
+
   // Skip the shutdown hook when the plugin is disabled. A `.disabled` plugin
   // is never loaded — no hooks, tools, or init — so its shutdown was never
   // paired with an init. Running it on uninstall would be the first and only
@@ -98,7 +152,11 @@ export async function uninstallPlugin(
   }
 
   rmSync(target, { recursive: true, force: true });
-  return { name, target };
+  return {
+    name,
+    target,
+    ...(warnings.length > 0 && { warnings }),
+  };
 }
 
 export { InvalidPluginNameError };

package/src/config/__tests__/plugin-resident-skill-discovery.test.ts

@@ -94,6 +94,27 @@ describe("discoverPluginResidentSkills (via loadSkillCatalog)", () => {
     expect(skill!.owner).toEqual({ kind: "plugin", id: "demo-matched" });
   });
 
+  test("surfaces a skill from a standard-only plugin", () => {
+    const pluginDir = join(getWorkspacePluginsDir(), "standard-plugin");
+    const skillDir = join(pluginDir, "skills", "qa-standard-skill");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      join(pluginDir, "plugin.json"),
+      JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        name: "standard-plugin",
+      }),
+    );
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      "---\nname: qa-standard-skill\ndescription: Standard skill.\n---\n\nBody.\n",
+    );
+
+    const skill = skillById("qa-standard-skill");
+
+    expect(skill?.owner).toEqual({ kind: "plugin", id: "standard-plugin" });
+  });
+
   test("skips a plugin directory that has no package.json", () => {
     writePlugin(
       "no-manifest",

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

@@ -125,5 +125,5 @@ Default to the conversation's current working directory when spawning an agent.
 
 - The spawned agent runs autonomously with its own tools, file editing, and terminal access.
 - Results are streamed back and injected into the conversation when the agent completes.
-- Use `acp_status` to check on running agents and `acp_abort` to stop them.
+- Use `acp_status` to inspect running and idle agents. Use `acp_steer` to attempt follow-up work on an idle session; do not replace it with a new `acp_spawn`.
 - The `cwd` parameter controls where the agent works - set it to the project root the user wants the agent to operate in.

package/src/config/bundled-skills/acp/TOOLS.json

@@ -33,7 +33,7 @@
     },
     {
       "name": "acp_status",
-      "description": "Get the status of a specific ACP session or list all ACP sessions. Only use this when the user explicitly asks about ACP session status - do NOT poll automatically, as you will be notified when sessions complete.",
+      "description": "Get the status of a specific ACP session or list recent ACP sessions. Cleanly completed sessions with durable resume metadata are returned as idle; use `acp_steer` to attempt follow-up work on them instead of starting over with `acp_spawn`. Only use this when the user explicitly asks about ACP session status - do NOT poll automatically, as you will be notified when sessions complete.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -41,7 +41,7 @@
         "properties": {
           "acp_session_id": {
             "type": "string",
-            "description": "Optional ACP session ID to query. If omitted, returns all ACP sessions."
+            "description": "Optional ACP session ID to query. If omitted, returns recent ACP sessions, including active and resumable idle sessions."
           }
         },
         "required": []

package/src/config/bundled-skills/computer-use/SKILL.md

@@ -37,6 +37,36 @@ The tree is walked to a limited depth to keep steps fast, and says when it was
 cut off. If the element you need is not in it, call `computer_use_observe` with
 `full_tree: true`.
 
+## Scripting apps (macOS)
+
+Reach for `computer_use_run_applescript` first when an app can be driven by
+script. It does not take the cursor.
+
+**Try the app's own scripting dictionary before anything else.** Ask it for the
+state you want, not for the clicks that would produce that state. Finder, Mail,
+Music, Notes, Safari, Terminal and many third-party apps have one, and where
+there is a dictionary the whole task is usually a sentence with no window to
+open, no tree to read and nothing to click:
+
+```applescript
+tell application "Finder"
+  set target of front window to desktop
+  set current view of front window to list view
+  set sort column of list view options of front window to name column
+end tell
+```
+
+**System Events menu clicking is the fallback**, for apps with no dictionary
+entry for what you need: `click menu item "Split Clip" of menu "Modify" of menu
+bar 1` inside `tell application "System Events" to tell process "iMovie"`. It is
+UI automation in a script's clothes: it still depends on the menu sitting where
+you expect and on the app being frontmost. A menu item that needs a selection or
+a playhead position does nothing when that context is missing, so set it up
+first, and read `enabled of menu item` when unsure.
+
+Click and type for everything a script cannot reach. `host_bash` is for shell
+commands, not for driving apps.
+
 ## Typing is not sending
 
 Pressing enter in a chat, email or form usually sends or submits it, and that

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -269,7 +269,7 @@
     },
     {
       "name": "computer_use_run_applescript",
-      "description": "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt foreground activity. Never use 'do shell script' inside AppleScript (blocked for security).",
+      "description": "Run an AppleScript on the Mac. Try the target app's own scripting dictionary first, asking it for the state you want rather than for the clicks that would produce it; fall back to System Events menu clicking for apps with no dictionary entry for what you need. Prefer this over click and type when the app supports it; it does not move the cursor. The result is the script's return value, and the accessibility tree may not change even when the script worked. Never use 'do shell script' inside AppleScript (blocked for security).",
       "category": "computer-use",
       "risk": "medium",
       "input_schema": {
@@ -281,7 +281,7 @@
           },
           "reasoning": {
             "type": "string",
-            "description": "Explanation of what this script does and why AppleScript is better than UI interaction for this step"
+            "description": "What this script does"
           },
           "target_client_id": {
             "type": "string",

package/src/config/bundled-skills/screen-annotation/SKILL.md

@@ -8,11 +8,11 @@ metadata:
     display-name: "Screen Annotation"
     category: "system"
     activation-hints:
-      - "User asks where something is, how to do it, or to be walked through it, in an app they share on a call"
+      - "User asks where a control is, or to be walked through doing something themselves, in an app they share"
       - "User wants to be shown, not have it done for them"
       - "The answer is a place on the user's screen"
     avoid-when:
-      - "User wants the assistant to do the thing rather than be shown it (use computer-use)"
+      - "User asks the assistant to do it (click, type, edit), even on a call: use computer-use"
       - "Nothing is being shared, so there is no surface to point at"
 ---
 

package/src/config/feature-flag-registry.json

@@ -540,8 +540,8 @@
       "id": "assistant-desktop",
       "scope": "assistant",
       "key": "assistant-desktop",
-      "label": "Assistant Desktop",
-      "description": "Streams an interactive desktop from a containerized assistant pod to the web client over /v1/desktop/stream. Off: no desktop affordance is rendered. On: the chat header offers a desktop panel that views and controls the pod's display.",
+      "label": "Virtual desktop",
+      "description": "Streams an interactive virtual desktop from a platform-hosted, containerized assistant over /v1/desktop/stream. Requires platform hosting; self-hosted assistants are excluded. Off: the virtual desktop is hidden. On: the chat header offers its viewer and controls.",
       "defaultEnabled": false
     }
   ]

package/src/config/schemas/__tests__/voice.test.ts

@@ -9,7 +9,7 @@ const PROGRESS_DEFAULTS = {
   maxSilenceMs: 35_000,
   longOpMs: 15_000,
   minGapMs: 6_000,
-  generationTimeoutMs: 1_500,
+  generationTimeoutMs: 5_000,
 };
 
 const FRONT_MODEL_DEFAULTS = {
@@ -75,7 +75,7 @@ describe("VoiceFrontModelConfigSchema", () => {
     expect(parsed.progress.maxSilenceMs).toBe(35_000);
     expect(parsed.progress.longOpMs).toBe(15_000);
     expect(parsed.progress.minGapMs).toBe(6_000);
-    expect(parsed.progress.generationTimeoutMs).toBe(1_500);
+    expect(parsed.progress.generationTimeoutMs).toBe(5_000);
   });
 
   test("a stale maxPerTurn key is stripped, not rejected", () => {

package/src/config/schemas/mcp.ts

@@ -55,9 +55,7 @@ const McpSseTransportSchema = z
       .optional()
       .describe("Custom HTTP headers sent with SSE requests"),
   })
-  .describe(
-    "SSE transport: connects to an MCP server over Server-Sent Events",
-  );
+  .describe("SSE transport: connects to an MCP server over Server-Sent Events");
 
 const McpStreamableHttpTransportSchema = z
   .object({
@@ -114,10 +112,14 @@ export type McpConfig = z.infer<typeof McpConfigSchema>;
  */
 export type McpServerSource = "workspace" | "plugin";
 
-/** A server config with its origin resolved. */
-export interface ResolvedMcpServerConfig extends McpServerConfig {
-  readonly source: McpServerSource;
-}
+/** A server config with its runtime-only origin and credential identity. */
+export type ResolvedMcpServerConfig =
+  | (McpServerConfig & { readonly source: "workspace" })
+  | (McpServerConfig & {
+      readonly source: "plugin";
+      readonly pluginName: string;
+      readonly serverKey: string;
+    });
 
 /** The MCP config the daemon runs: both origins, every server attributed. */
 export interface ResolvedMcpConfig {

package/src/config/schemas/monitoring.ts

@@ -75,6 +75,15 @@ export const MonitoringConfigSchema = z
       .describe(
         "Minimum interval between file-descriptor warnings while usage stays over the threshold, in milliseconds. Crossing the threshold always warns immediately; this only throttles the repeats.",
       ),
+    mountWatchIntervalMs: z
+      .number({ error: "monitoring.mountWatchIntervalMs must be a number" })
+      .int("monitoring.mountWatchIntervalMs must be an integer")
+      .min(1_000, "monitoring.mountWatchIntervalMs must be at least 1000ms")
+      .max(60_000, "monitoring.mountWatchIntervalMs must be <= 60000ms")
+      .default(10_000)
+      .describe(
+        "How often the monitor diffs the assistant container's mount table (/proc/self/mountinfo plus statfs of /workspace and /data), in milliseconds. Logs only when the watched mounts change. Default 10 seconds so a virtiofs bind drop is timestamped without a line per poll.",
+      ),
     pluginSourceScanIntervalMs: z
       .number({
         error: "monitoring.pluginSourceScanIntervalMs must be a number",

package/src/config/schemas/voice.ts

@@ -74,9 +74,9 @@ export const VoiceProgressConfigSchema = z
       .positive(
         "voice.frontModel.progress.generationTimeoutMs must be a positive integer",
       )
-      .default(1_500)
+      .default(5_000)
       .describe(
-        "Budget (ms) for LLM-generated progress text. Not latency-critical: it speaks into dead air",
+        "Budget (ms) for LLM-generated progress text. Not latency-critical: it speaks into dead air, so the budget is set to cover the narrator's real roundtrip rather than to be tight. A budget that only sometimes covers that roundtrip thins narration out rather than speeding it up, and it thins out exactly where the updates matter most, since the slow beats are the ones with the longest silence behind them (see endpointDecisionTimeoutMs for the same failure mode). Kept under progress.minGapMs so an update that spends the whole budget still lands before the next one is due",
       ),
   })
   // The heartbeat is checked when the idle tick finds the turn silent, so a

package/src/config/skills.ts

@@ -39,6 +39,10 @@ import {
   getWorkspacePluginsDir,
   getWorkspaceSkillsDir,
 } from "../util/platform.js";
+import {
+  hasPluginManifest,
+  readPluginManifest,
+} from "../util/plugin-manifest.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
 import { isAssistantFeatureFlagEnabled } from "./assistant-feature-flags.js";
 import { getConfig } from "./loader.js";
@@ -734,8 +738,7 @@ function discoverSkillDirectories(skillsDir: string): string[] {
 }
 
 /**
- * Whether `pluginDir` carries a plugin manifest the runtime can load: a
- * parseable `package.json` with a non-empty string `name`. This mirrors the
+ * Whether `pluginDir` carries a plugin manifest the runtime can load. This mirrors the
  * external plugin loader (`buildPluginFromDir`), which builds a plugin from
  * any such directory and derives the plugin's identity from `package.json`
  * `name` — it imposes no match between that `name` and the directory name.
@@ -745,31 +748,20 @@ function discoverSkillDirectories(skillsDir: string): string[] {
  * requiring the two to match would silently drop the resident skills of every
  * such plugin even though the runtime loads its hooks and tools fine.
  *
- * The caller is responsible for the missing-`package.json` case (it emits a
+ * The caller is responsible for the missing-manifest case (it emits a
  * diagnostic warning); this function only judges a manifest that is present.
  */
 function hasLoadablePluginManifest(pluginDir: string): boolean {
-  const manifestPath = join(pluginDir, "package.json");
-  if (!existsSync(manifestPath)) {
-    return false;
-  }
-  let parsed: unknown;
   try {
-    parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    readPluginManifest(pluginDir);
+    return true;
   } catch (err) {
     log.warn(
-      { err, manifestPath },
-      "Skipping plugin dir with unparseable package.json for resident skills",
+      { err, pluginDir },
+      "Skipping plugin dir with an invalid manifest for resident skills",
     );
     return false;
   }
-  return (
-    typeof parsed === "object" &&
-    parsed !== null &&
-    "name" in parsed &&
-    typeof (parsed as { name: unknown }).name === "string" &&
-    (parsed as { name: string }).name.length > 0
-  );
 }
 
 /**
@@ -885,15 +877,15 @@ function discoverInstalledPluginResidentSkills(): SkillSummary[] {
     }
     const pluginDir = join(pluginsDir, entry.name);
 
-    // A directory under `plugins/` with no `package.json` is not a plugin the
+    // A directory under `plugins/` with no supported manifest is not a plugin the
     // runtime can load, so its skills are never surfaced. This is an easy
     // footgun — a plugin dropped in without its manifest looks installed but
     // silently contributes nothing — so warn loudly with the path rather than
     // skipping in silence, to make the misconfiguration diagnosable.
-    if (!existsSync(join(pluginDir, "package.json"))) {
+    if (!hasPluginManifest(pluginDir)) {
       log.warn(
         { pluginDir },
-        "Plugin directory is missing package.json — skipping; its skills will not be available. Add a package.json with a `name`.",
+        "Plugin directory is missing package.json and plugin.json; its skills will not be available.",
       );
       continue;
     }

package/src/daemon/__tests__/conversation-tool-setup-exclude.test.ts

@@ -6,6 +6,7 @@
 
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
 import * as configLoader from "../../config/loader.js";
 import type { AssistantConfig } from "../../config/schema.js";
 import * as disabledState from "../../plugins/disabled-state.js";
@@ -245,3 +246,49 @@ describe("createResolveToolsCallback — config.tools.exclude", () => {
     expect(ctx.allowedToolNames?.has("bash")).toBe(false);
   });
 });
+
+test("managed browser guidance follows each turn without changing native or shared tool definitions", () => {
+  const platform = process.env.IS_PLATFORM;
+  const containerized = process.env.IS_CONTAINERIZED;
+  process.env.IS_PLATFORM = "true";
+  process.env.IS_CONTAINERIZED = "true";
+  setOverridesForTesting({ "assistant-desktop": true });
+  const bash = def("bash");
+  const ctx = makeCtx({
+    conversationId: "conv-browser-guidance",
+    transportInterface: "web",
+    currentTurnClientOs: "web",
+    trustContext: { trustClass: "guardian" } as Conversation["trustContext"],
+    getTurnActorPrincipalId: () => "user-123",
+  });
+  const resolve = createResolveToolsCallback([bash], ctx)!;
+  try {
+    expect(
+      resolve([]).find((tool) => tool.name === "bash")?.description,
+    ).toContain("assistant browser navigate");
+    expect(bash.description).toBe("bash");
+    for (const clientOs of ["macos", "windows", "linux"] as const) {
+      ctx.currentTurnClientOs = clientOs;
+      expect(
+        resolve([]).find((tool) => tool.name === "bash")?.description,
+      ).toBe("bash");
+    }
+    ctx.currentTurnClientOs = "web";
+    setOverridesForTesting({ "assistant-desktop": false });
+    expect(resolve([]).find((tool) => tool.name === "bash")?.description).toBe(
+      "bash",
+    );
+  } finally {
+    setOverridesForTesting({});
+    if (platform === undefined) {
+      delete process.env.IS_PLATFORM;
+    } else {
+      process.env.IS_PLATFORM = platform;
+    }
+    if (containerized === undefined) {
+      delete process.env.IS_CONTAINERIZED;
+    } else {
+      process.env.IS_CONTAINERIZED = containerized;
+    }
+  }
+});

package/src/daemon/__tests__/plugin-mcp-reconcile.test.ts

@@ -41,6 +41,7 @@ mock.module("../../mcp/mcp-header-store.js", () => ({
 }));
 
 mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({}),
   invalidateConfigCache: () => {},
 }));
 

package/src/daemon/conversation-client-surface.ts

@@ -0,0 +1,26 @@
+import { type ClientOs, parseClientOs } from "../channels/types.js";
+import type { Conversation } from "./conversation.js";
+
+/**
+ * Host OS of the client driving this turn. The Electron renderer reports
+ * `interface: "web"` and carries the real OS in `clientOs`, so this prefers
+ * the frozen per-turn value and only falls back to a desktop transport.
+ */
+export function resolveTurnClientOs(ctx: Conversation): {
+  clientOs: ClientOs | undefined;
+  transportInterface: Conversation["transportInterface"];
+} {
+  const pin = ctx.toolContextPin;
+  const transportInterface = pin
+    ? pin.transportInterface
+    : ctx.transportInterface;
+  const clientOs = pin
+    ? pin.clientOs
+    : (parseClientOs(ctx.currentTurnClientOs ?? ctx.clientOs) ??
+      (transportInterface === "macos" ||
+      transportInterface === "windows" ||
+      transportInterface === "linux"
+        ? transportInterface
+        : undefined));
+  return { clientOs, transportInterface };
+}

package/src/daemon/conversation-runtime-assembly.ts

@@ -854,7 +854,7 @@ export function buildChannelCapabilityBlock(
   if (clientOs === "macos") {
     lines.push("");
     lines.push(
-      "On macOS, prefer osascript/CLI via `host_bash` over computer use tools, which take over the user's cursor. Use foreground computer use only when no scripting alternative exists or the user explicitly asks.",
+      "On macOS, drive apps with the computer-use skill; `host_bash` is for shell commands.",
     );
   }