@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

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

@@ -25,16 +25,55 @@ desktop client and is never handled locally by the assistant.
 
 ## Observations
 
-Every computer-use step returns the accessibility tree. A screenshot comes with
-a desktop's first look, with window-scoped observations, or when you call
-`computer_use_observe` with `include_screenshot: true`. Ask for one whenever the
-tree is not enough to act on: a canvas, a game, a custom-drawn view, few or
+Every computer-use step returns the accessibility tree. Every action also
+returns a screenshot taken after it ran (one at the end of a
+`computer_use_sequence`), so check it to see what your action did. An
+observation comes with a screenshot on a desktop's first look, when it is
+window-scoped, or when you pass `include_screenshot: true`. Ask for one whenever
+the tree is not enough to act on: a canvas, a game, a custom-drawn view, few or
 unlabeled controls, or a layout question.
 
 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
+cannot be taken back. Send only when the user asked you to send, post or
+submit. When they asked you to type, write or draft something, type it and stop
+before pressing enter; tell them it is ready to send.
+
 ## Batching known steps (macOS)
 
 When you already know the next few actions and none depends on seeing the

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

@@ -17,7 +17,7 @@
           },
           "include_screenshot": {
             "type": "boolean",
-            "description": "Force a screenshot with this observation. The accessibility tree is returned every step; ask for pixels whenever the tree is not enough to act on, such as a canvas, a game, a custom-drawn view, a window with few or unlabeled controls, or a question about layout."
+            "description": "Force a screenshot with this observation. The accessibility tree is returned every step and actions always return a screenshot of their result; ask for pixels on an observation whenever the tree is not enough to act on, such as a canvas, a game, a custom-drawn view, a window with few or unlabeled controls, or a question about layout."
           },
           "full_tree": {
             "type": "boolean",
@@ -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

@@ -175,7 +175,7 @@
       "scope": "client",
       "key": "teleport",
       "label": "Teleport",
-      "description": "Enable teleport UI in General settings for moving assistants between hosting environments",
+      "description": "Enable the local-to-platform teleport UI in General settings. Platform-to-local teleport is GA and not gated by this flag",
       "defaultEnabled": false
     },
     {
@@ -474,6 +474,14 @@
       "description": "Gates the seeded Figma OAuth provider. When off, the provider is hidden from GET /v1/oauth/providers, its get-by-id route, and the connect/update routes, so it cannot be listed or connected from the CLI, gateway, or web integrations list. The row is still seeded into oauth_providers on startup, and existing connections keep injecting credentials; only its visibility changes.",
       "defaultEnabled": false
     },
+    {
+      "id": "quickbooks-oauth",
+      "scope": "assistant",
+      "key": "quickbooks-oauth",
+      "label": "QuickBooks Integration",
+      "description": "Gates the seeded QuickBooks OAuth provider. When off, the provider is hidden from GET /v1/oauth/providers, its get-by-id route, and the connect/update routes, so it cannot be listed or connected from the CLI, gateway, or web integrations list. The row is still seeded into oauth_providers on startup, and existing connections keep injecting credentials; only its visibility changes.",
+      "defaultEnabled": false
+    },
     {
       "id": "shopify-oauth",
       "scope": "assistant",
@@ -532,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/loader.ts

@@ -183,6 +183,7 @@ export function getDeploymentContextDefaults(): Record<string, unknown> {
       "shopify-oauth": managed,
       "stripe-link-oauth": managed,
       "figma-oauth": managed,
+      "quickbooks-oauth": managed,
       "eventbrite-oauth": managed,
       "calendly-oauth": managed,
     },

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/services.ts

@@ -157,6 +157,13 @@ export const FigmaOAuthServiceSchema = BaseServiceSchema.extend({
 });
 export type FigmaOAuthService = z.infer<typeof FigmaOAuthServiceSchema>;
 
+export const QuickBooksOAuthServiceSchema = BaseServiceSchema.extend({
+  mode: ServiceModeSchema.default("your-own"),
+});
+export type QuickBooksOAuthService = z.infer<
+  typeof QuickBooksOAuthServiceSchema
+>;
+
 export const EventbriteOAuthServiceSchema = BaseServiceSchema.extend({
   mode: ServiceModeSchema.default("your-own"),
 });
@@ -228,6 +235,9 @@ export const ServicesSchema = z.object({
   "figma-oauth": FigmaOAuthServiceSchema.default(
     FigmaOAuthServiceSchema.parse({}),
   ),
+  "quickbooks-oauth": QuickBooksOAuthServiceSchema.default(
+    QuickBooksOAuthServiceSchema.parse({}),
+  ),
   "eventbrite-oauth": EventbriteOAuthServiceSchema.default(
     EventbriteOAuthServiceSchema.parse({}),
   ),

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

@@ -819,10 +819,15 @@ export function applySightFrameRetention(
  * `null` on the happy path (desktop, full capabilities, no special context)
  * where no block is injected. Split from {@link injectChannelCapabilityContext}
  * so callers can capture the exact injected text for metadata persistence.
+ *
+ * Live vs clientless guidance belongs here, not in tool schemas. Tool
+ * definitions stay identical so the tools cache prefix can reuse; this block
+ * sits later in the system prompt and can describe the current turn.
  */
 export function buildChannelCapabilityBlock(
   caps: ChannelCapabilities,
   clientOs: string | undefined = caps.clientOS,
+  isNonInteractive = false,
 ): string | null {
   // Happy path: desktop with full capabilities and no special context — skip injection.
   if (
@@ -849,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.",
     );
   }
 
@@ -874,18 +879,24 @@ export function buildChannelCapabilityBlock(
       "- Do NOT reference the dashboard UI, settings panels, or visual preference pickers.",
     );
     if (!caps.supportsDynamicUi) {
-      if (caps.channel === "slack") {
+      if (isNonInteractive) {
         lines.push(
-          '- Do NOT use app_create. Only use ui_show/ui_update for card surfaces with template: "task_progress"; present all other information as text.',
+          "- ui_show, ui_update, and ui_dismiss persist conversation content for the next capable client that opens this conversation. Do not claim a surface is visible now or wait for an action.",
         );
       } else {
+        if (caps.channel === "slack") {
+          lines.push(
+            '- Do NOT use app_create. Only use ui_show/ui_update for card surfaces with template: "task_progress"; present all other information as text.',
+          );
+        } else {
+          lines.push(
+            "- Do NOT use ui_show, ui_update, or app_create. This channel cannot render them.",
+          );
+        }
         lines.push(
-          "- Do NOT use ui_show, ui_update, or app_create — this channel cannot render them.",
+          "- Present information as well-formatted text instead of dynamic UI.",
         );
       }
-      lines.push(
-        "- Present information as well-formatted text instead of dynamic UI.",
-      );
     }
     if (caps.channel === "whatsapp") {
       lines.push(
@@ -2853,6 +2864,7 @@ export async function applyRuntimeInjections(
       const channelCapabilityBlock = buildChannelCapabilityBlock(
         channelCapabilities,
         clientOs,
+        options.isNonInteractive === true,
       );
       if (channelCapabilityBlock !== null) {
         channelCapabilitiesCaptured = channelCapabilityBlock;

package/src/daemon/conversation-surfaces.ts

@@ -3180,7 +3180,7 @@ export async function surfaceProxyResolver(
           : typeof input.answer === "string"
             ? input.answer
             : "Task complete";
-      hostCuProxy.reset();
+      hostCuProxy.endTask(ctx.conversationId);
       return { content: summary, isError: false };
     }
 
@@ -3346,6 +3346,11 @@ export async function surfaceProxyResolver(
 
   if (toolName === "ui_show" || toolName === "ui_update") {
     const caps = ctx.channelCapabilities;
+    // Live non-dynamic channels reject unsupported surfaces. Clientless turns
+    // skip this gate so surfaces persist for a later capable client.
+    // `canShowInteractiveUi` fails closed on clientless turns because
+    // standalone surfaces have nobody to answer them, so it is not the
+    // predicate here.
     if (
       caps &&
       !ctx.hasNoClient &&

package/src/daemon/conversation-tool-setup.ts

@@ -7,10 +7,9 @@
  */
 
 import type { AssistantEvent } from "../api/index.js";
+import { shouldUseVirtualDesktopBrowser } from "../browser/virtual-desktop-target.js";
 import {
-  type ClientOs,
   type HostProxyCapability,
-  parseClientOs,
   supportsHostProxy,
 } from "../channels/types.js";
 import { getIsPlatform } from "../config/env-registry.js";
@@ -62,10 +61,7 @@ import {
   type ToolContext,
   type ToolExecutionResult,
 } from "../tools/types.js";
-import {
-  injectActivationMomentParam,
-  projectUiToolsForChannel,
-} from "../tools/ui-surface/channel-variants.js";
+import { injectActivationMomentParam } from "../tools/ui-surface/channel-variants.js";
 import { loadWorkspaceTools } from "../tools/workspace-tools/loader.js";
 import {
   resolveUsageAttribution,
@@ -77,6 +73,7 @@ import {
   conversationSupportsGuardianQuestionCards,
 } from "./channel-ui-capability.js";
 import type { Conversation } from "./conversation.js";
+import { resolveTurnClientOs } from "./conversation-client-surface.js";
 import { projectSkillTools } from "./conversation-skill-tools.js";
 import {
   restoreSurfaceStateEntry,
@@ -745,30 +742,6 @@ export const ALLOWLIST_ONLY_TOOL_NAMES = new Set<string>([
   "delete_memory_page",
 ]);
 
-/**
- * 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.
- */
-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 };
-}
-
 /**
  * Windows parity gate: skill tools may declare `supported_client_os`; drop
  * them when the turn's client OS (or pinned OS for wakes) is not listed.
@@ -1147,19 +1120,40 @@ export function createResolveToolsCallback(
         : currentWorkspaceDefs
     ).filter((d) => !readOnlyHidesFromWire(d.name));
     const excluded = new Set(getConfig().tools.exclude);
-    // Swap UI surface tools for channel-appropriate variants (e.g. Slack's
-    // task_progress-only ui_show). Mirrors the pin handling in
-    // `isToolActiveForContext`: execution-gate-mode wakes pin channel
-    // capabilities to undefined, which resolves to the unprojected defs.
-    const channelForUiTools = ctx.toolContextPin
-      ? undefined
-      : ctx.channelCapabilities?.channel;
-    let allBaseDefs = projectUiToolsForChannel(
-      [...scopedCoreDefs, ...scopedWorkspaceDefs, ...scopedMcpDefs].filter(
-        (d) => !excluded.has(d.name),
-      ),
-      channelForUiTools,
-    );
+    // UI definitions stay identical across channel and background turns.
+    // Channel renderers enforce their supported surface subset at execution,
+    // while background calls persist the full surface content for the next
+    // capable client that opens the conversation. Skill tools stay off this
+    // list (`skill_execute` dispatch) and are a separate disclosure path.
+    let allBaseDefs = [
+      ...scopedCoreDefs,
+      ...scopedWorkspaceDefs,
+      ...scopedMcpDefs,
+    ].filter((d) => !excluded.has(d.name));
+    if (
+      ctx.transportInterface === "web" &&
+      shouldUseVirtualDesktopBrowser(
+        undefined,
+        {},
+        {
+          workingDir: ctx.workingDir,
+          conversationId: ctx.conversationId,
+          trustClass: ctx.trustContext?.trustClass ?? "unknown",
+          transportInterface: ctx.transportInterface,
+          clientOs: resolveTurnClientOs(ctx).clientOs,
+          sourceActorPrincipalId: ctx.getTurnActorPrincipalId?.(),
+        },
+      )
+    ) {
+      allBaseDefs = allBaseDefs.map((definition) =>
+        definition.name === "bash"
+          ? {
+              ...definition,
+              description: `${definition.description} For browser tasks, use assistant browser navigate --url <url> directly. It installs the virtual desktop if needed, starts Chrome, and completes the action in one call. Use timeout_seconds: ${getConfig().timeouts.shellMaxTimeoutSec} for first use; setup progress is visible in the Virtual desktop panel. Use assistant browser --help for other browser actions. Use this managed path even if saved notes describe manual setup. Do not install packages or launch Chrome, X servers, or screenshot scripts yourself.`,
+            }
+          : definition,
+      );
+    }
     // Activation-rail conversations carry the optional `activation_moment`
     // telemetry param on ui_show. The marker is written before the first
     // tool resolution (see `applyBootstrapTemplate` in system-prompt.ts), so