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

package/docs/desktop-browser-cli.md

@@ -0,0 +1,33 @@
+# Virtual desktop browser CLI
+
+`assistant browser --virtual-desktop` uses the browser CLI's shared operation handlers against the Chrome process owned by `DesktopSessionManager`. It requires a platform-hosted container, the `assistant-desktop` flag, completed automatic desktop installation and an identified guardian conversation. Availability is checked before starting or reusing control and after asynchronous startup; loss of the flag or installation readiness cancels active control. The first eligible browser command waits for the shared installation job, starts Chrome, and executes the original action exactly once. Cancellation and feature revocation stop the pending action while shared installation can finish for other viewers. Browser CLI requests allow ten minutes, with an eight-minute setup wait limit. Eligible web conversations receive browser guidance in the bash tool description, including the configured shell timeout; native clients retain their existing tool description. Opening the picture-in-picture panel also starts setup and shows progress automatically; failed installs retain a retry action. The persistent profile remains `data/desktop-profile`; no data migration or extension installation is required.
+
+Automatic browser selection in platform-hosted web conversations uses the streamed Chrome when the desktop flag is enabled and the actor is an identified guardian. The macOS and Windows apps keep their existing browser selection and fallback behavior; they use the streamed desktop only with explicit `--virtual-desktop`. Their shared renderer reports a `web` transport, so selection also reads the active turn's frozen `clientOs`; it does not change transport identity or host capability checks. Explicit `--virtual-desktop`, `--browser-mode`, `--target-client-id` and active-tab requests override the default. Existing personal-browser sessions and tab pins remain on their selected browser. Tab commands use the same streamed-browser default as page commands. `--browser-mode local` selects assistant-side Playwright, not the user's Chrome.
+
+The legacy `--desktop` option remains an alias. The deployment flag key `assistant-desktop`, API paths, sync tags and persistent profile path are unchanged for compatibility. The shared `isVirtualDesktopEnabled` gate rejects self-hosted assistants, including local Docker, for setup, streaming and control.
+
+```mermaid
+flowchart LR
+  CLI[assistant browser --virtual-desktop] --> IPC[Existing browser IPC routes]
+  IPC --> Lease[DesktopAutomationLease conversation and actor lease]
+  Lease --> Shared[Shared browser operation handlers]
+  Shared --> CDP[Scoped desktop CDP client]
+  CDP --> Chrome[Managed Chrome on display :99]
+  Chrome --> Stream[Existing desktop stream]
+```
+
+Chrome and its dock launcher share the managed profile and loopback debug port. For Chrome reopened from the dock, the profile singleton lock identifies a candidate PID, validated against the installed executable, profile and loopback debug arguments. Discovery checks `/proc` socket ownership against that browser PID, refuses redirects and validates the returned browser WebSocket endpoint. The connection stays within the container. No CDP endpoint or token is exposed to the renderer.
+
+The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, cancellation, errors and idle expiry release control. Only `tabs close` closes a Chrome tab.
+
+`assistant browser --virtual-desktop screenshot --output /tmp/desktop-page.jpg` captures a color page image through CDP `Page.captureScreenshot`. It excludes the browser toolbar and desktop dock. `snapshot` returns semantic page structure. Agents should use these interfaces and let the manager start the desktop, including when older memory notes describe manual Xvnc, `xdotool` or scratch XWD conversion scripts.
+
+Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs. They are never personal extension tab IDs. Initial attachment selects an existing HTTP(S) page or opens a blank tab. Use `tabs list` and `tabs select --tab-id <id>` to choose explicitly. Navigation, tab selection, document replacement and release clear the desktop snapshot map. Personal-browser snapshots use a separate namespace.
+
+CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation.
+
+The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
+
+`--use-active-tab` and personal browser targeting are rejected with `--virtual-desktop`. Download waiting is unsupported. Browser operations are bounded to two minutes and share the desktop lease's action budget and idle expiry.
+
+Validation: focused client tests exercise shared snapshot/click behavior, namespace isolation, stale references, target changes, cancellation and uncertain-input cleanup. Lease tests cover browser ownership, cancellation and cleanup independently of native input. The Linux smoke script exercises real Chrome, the CLI and visible pointer feedback.

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.12.1
+  version: 0.12.2
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -4146,6 +4146,8 @@ paths:
                 conversationId:
                   type: string
                   minLength: 1
+                desktop:
+                  type: boolean
               required:
                 - operation
       responses:
@@ -4181,7 +4183,7 @@ paths:
     post:
       operationId: browser_tabs_post
       summary: Manage browser tabs
-      description: List, create, select, or close browser tabs via the Chrome extension backend.
+      description: List, create, select, or close browser tabs in the Chrome extension or streamed desktop browser.
       tags:
         - browser
       requestBody:
@@ -4205,6 +4207,10 @@ paths:
                 conversationId:
                   type: string
                   minLength: 1
+                desktop:
+                  type: boolean
+                browserMode:
+                  type: string
                 tabId:
                   type: number
                 url:
@@ -11916,7 +11922,7 @@ paths:
   /v1/desktop/setup:
     get:
       operationId: desktop_setup_get
-      summary: Get desktop setup status
+      summary: Get virtual desktop setup status
       tags:
         - desktop
       responses:
@@ -11946,7 +11952,7 @@ paths:
                 additionalProperties: false
     post:
       operationId: desktop_setup_post
-      summary: Install desktop components
+      summary: Install virtual desktop components
       tags:
         - desktop
       responses:
@@ -18426,7 +18432,7 @@ paths:
     get:
       operationId: internal_mcp_list_get
       summary: List MCP servers with health status
-      description: Returns configured MCP servers with live health-check results (connected, needs auth, error).
+      description: Returns configured MCP servers with recorded runtime status without opening new connections.
       tags:
         - internal
       responses:
@@ -26544,6 +26550,12 @@ paths:
                   target:
                     type: string
                     description: Absolute path that was removed on the assistant host. Useful for audit logs and confirmation toasts.
+                  warnings:
+                    description: Stable keys for non-fatal cleanup limitations that should be localized at the presentation edge.
+                    type: array
+                    items:
+                      type: string
+                      const: plugin.uninstall.mcp_oauth_credentials_unchecked
                 required:
                   - name
                   - target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-staging.2",
+  "version": "0.12.2-staging.3",
   "license": "MIT",
   "type": "module",
   "exports": {

package/scripts/smoke-desktop-browser-cli.ts

@@ -0,0 +1,279 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { IpcFrameReader, writeMessage } from "@vellumai/ipc-server-utils";
+import { Command } from "commander";
+import sharp from "sharp";
+
+import { executeBrowserOperation } from "../src/browser/operations.js";
+import type { BrowserOperation } from "../src/browser/types.js";
+import { registerBrowserCommand } from "../src/cli/commands/browser.js";
+import { DesktopAutomationLease } from "../src/desktop/desktop-automation-lease.js";
+import {
+  desktopChromePath,
+  desktopDependencyInstaller,
+} from "../src/desktop/desktop-dependencies.js";
+import { DesktopSessionManager } from "../src/desktop/desktop-session-manager.js";
+import { getAssistantSocketPath } from "../src/ipc/socket-path.js";
+
+if (
+  process.platform !== "linux" ||
+  !process.argv[2] ||
+  !process.env.ASSISTANT_IPC_SOCKET_DIR
+) {
+  throw new Error(
+    "Run in disposable Linux with desktop packages, a temporary ASSISTANT_IPC_SOCKET_DIR and a Chrome executable argument or --install for a cold install.",
+  );
+}
+const coldInstall = process.argv[2] === "--install";
+const executable = coldInstall ? desktopChromePath() : process.argv[2];
+if (coldInstall) {
+  assert.equal(desktopDependencyInstaller.getStatus().state, "required");
+  assert.equal(Bun.which("Xtigervnc"), null);
+}
+const directory = await mkdtemp(join(tmpdir(), "desktop-browser-cli-"));
+const manager = new DesktopSessionManager({
+  resolveChromePath: async () => executable,
+  profileDir: join(directory, "profile"),
+  panelConfigDir: join(directory, "panel"),
+  renderWallpaper: async () => null,
+});
+const control = new DesktopAutomationLease({
+  enabled: () => true,
+  ready: () =>
+    !coldInstall || desktopDependencyInstaller.getStatus().state === "ready",
+  ensureReady: (signal) => desktopDependencyInstaller.ensureReady(signal),
+  manager: () => manager,
+});
+const context = {
+  workingDir: directory,
+  conversationId: "conv-smoke",
+  sourceActorPrincipalId: "user-123",
+  trustClass: "guardian" as const,
+};
+let submissions = 0;
+let navigations = 0;
+const page = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 0,
+  fetch(request) {
+    if (new URL(request.url).pathname === "/save") {
+      submissions++;
+      return Response.json({ ok: true });
+    }
+    if (new URL(request.url).pathname === "/") {
+      navigations++;
+    }
+    return new Response(
+      `<!doctype html><html><head><title>Desktop browser CLI</title><style>body{font:24px sans-serif;padding:70px;background:#f3f4f8}input,button{font:inherit;padding:12px;margin:16px}#result{color:#5140bd}#colors{position:fixed;left:0;top:0;display:flex}#colors span{width:100px;height:50px}</style></head><body><div id="colors"><span style="background:#ff0000"></span><span style="background:#00ff00"></span><span style="background:#0000ff"></span></div><h1>Streamed desktop browser</h1><label>Example text<input id="text"></label><button id="save" onclick="fetch('/save');document.getElementById('result').textContent='Saved '+document.getElementById('text').value">Save</button><p id="result"></p><button id="open-dialog" onclick="document.querySelector('dialog').showModal()">Open dialog</button><dialog style="background:white"><button id="inside" onclick="this.textContent='Modal clicked'">Inside dialog</button></dialog></body></html>`,
+      {
+        headers: {
+          "content-type": "text/html",
+          "content-security-policy":
+            "require-trusted-types-for 'script'; trusted-types 'none'",
+        },
+      },
+    );
+  },
+});
+await mkdir(process.env.ASSISTANT_IPC_SOCKET_DIR, { recursive: true });
+let setupNotifications = 0;
+const ipc = createServer((socket) => {
+  const reader = new IpcFrameReader((request) => {
+    void (async () => {
+      try {
+        if (request.method === "/events/publish") {
+          setupNotifications++;
+          writeMessage(socket, { id: request.id, result: { ok: true } });
+          return;
+        }
+        const body = (
+          request.params as {
+            body: {
+              operation: BrowserOperation;
+              input: Record<string, unknown>;
+              desktop: boolean;
+            };
+          }
+        ).body;
+        assert.equal(request.method, "browser_execute");
+        assert.equal(body.desktop, true);
+        const result = await control.runBrowser(
+          context,
+          async (signal) => {
+            const cdpClient = await manager.browser.client(
+              context.conversationId,
+              signal,
+            );
+            return executeBrowserOperation(body.operation, body.input, {
+              ...context,
+              signal,
+              cdpClient,
+            });
+          },
+          body.operation === "detach",
+        );
+        const screenshots = (result.contentBlocks ?? []).flatMap((block) =>
+          block.type === "image" && block.source.type === "base64"
+            ? [{ mediaType: block.source.media_type, data: block.source.data }]
+            : [],
+        );
+        writeMessage(socket, {
+          id: request.id,
+          result: { ...result, screenshots },
+        });
+      } catch (error) {
+        writeMessage(socket, { id: request.id, error: String(error) });
+      }
+    })();
+  });
+  socket.on("data", (chunk) => reader.push(chunk));
+});
+await new Promise<void>((resolve, reject) => {
+  ipc.once("error", reject);
+  ipc.listen(getAssistantSocketPath(), resolve);
+});
+async function cli(...args: string[]) {
+  const program = new Command();
+  program.exitOverride();
+  registerBrowserCommand(program);
+  const chunks: string[] = [];
+  const original = process.stdout.write;
+  process.stdout.write = ((chunk: unknown) => {
+    chunks.push(String(chunk));
+    return true;
+  }) as typeof original;
+  try {
+    await program.parseAsync([
+      "bun",
+      "assistant",
+      "browser",
+      "--virtual-desktop",
+      "--json",
+      ...args,
+    ]);
+  } finally {
+    process.stdout.write = original;
+  }
+  const result = JSON.parse(chunks.join("")) as {
+    ok: boolean;
+    content: string;
+    error?: string;
+  };
+  assert.equal(result.ok, true, JSON.stringify(result));
+  return result.content;
+}
+function ref(snapshot: string, name: string): string {
+  const line = snapshot
+    .split("\n")
+    .find((value) => value.includes(name) && /\be\d+\b/.test(value));
+  assert(line, `Missing ${name}: ${snapshot}`);
+  return /\be\d+\b/.exec(line)![0];
+}
+try {
+  await cli(
+    "navigate",
+    "--url",
+    `http://127.0.0.1:${page.port}`,
+    "--allow-private-network",
+  );
+  assert.equal(navigations, 1);
+  if (coldInstall) {
+    assert.equal(desktopDependencyInstaller.getStatus().state, "ready");
+    assert(
+      setupNotifications >= 3,
+      "Installation progress must reach the viewer",
+    );
+    console.error(
+      "PASS: one CLI navigate installed desktop and Chrome from scratch, then loaded the requested page once",
+    );
+  }
+  const snapshot = await cli("snapshot");
+  await cli(
+    "type",
+    "--element-id",
+    ref(snapshot, "Example text"),
+    "--text",
+    "Hello café 世界",
+    "--clear-first",
+  );
+  await cli("click", "--element-id", ref(snapshot, "Save"));
+  const saved = await cli("extract");
+  assert.match(saved, /Saved Hello café 世界/);
+  assert.equal(submissions, 1);
+  const screenshotPath = join(tmpdir(), "desktop-browser-cli-page.jpg");
+  await cli("screenshot", "--output", screenshotPath);
+  const { data: pixels, info } = await sharp(screenshotPath)
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  for (let channel = 0; channel < 3; channel++) {
+    const offset = (25 * info.width + 50 + channel * 100) * info.channels;
+    for (let component = 0; component < 3; component++) {
+      const expected = component === channel ? 255 : 0;
+      assert(
+        Math.abs(pixels[offset + component] - expected) < 10,
+        `Incorrect screenshot color for swatch ${channel}, channel ${component}`,
+      );
+    }
+  }
+  async function assertCursorPainted(expected: boolean) {
+    await control.runBrowser(context, async (signal) => {
+      const cdp = await manager.browser.client(context.conversationId, signal);
+      const screenshot = await cdp.send<{ data: string }>(
+        "Page.captureScreenshot",
+        { format: "png" },
+      );
+      const { data, info } = await sharp(Buffer.from(screenshot.data, "base64"))
+        .removeAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+      let purple = 0;
+      for (let i = 0; i < data.length; i += info.channels) {
+        if (
+          Math.abs(data[i]! - 112) < 5 &&
+          Math.abs(data[i + 1]! - 87) < 5 &&
+          Math.abs(data[i + 2]! - 255) < 5
+        ) {
+          purple++;
+        }
+      }
+      assert.equal(purple > 40, expected, `Cursor pixels: ${purple}`);
+      return { content: "verified", isError: false };
+    });
+  }
+  await assertCursorPainted(true);
+  await cli("click", "--selector", "#open-dialog");
+  await assertCursorPainted(true);
+  await cli("hover", "--selector", "#inside");
+  await assertCursorPainted(true);
+  await cli("click", "--selector", "#inside");
+  assert.match(await cli("extract"), /Modal clicked/);
+  for (const key of ["Enter", "Space"]) {
+    await cli("press-key", "--key", "Escape");
+    await cli("press-key", "--key", key, "--selector", "#open-dialog");
+    await assertCursorPainted(true);
+  }
+  await cli(
+    "navigate",
+    "--url",
+    `http://127.0.0.1:${page.port}/next`,
+    "--allow-private-network",
+  );
+  await assertCursorPainted(true);
+  await cli("detach");
+  await assertCursorPainted(false);
+  await cli("detach");
+  console.log(
+    "PASS: real browser CLI over IPC, shared AX snapshot, Unicode typing, one click submission, RGB page screenshot, cursor pixels above dialogs and after navigation, detach cleanup",
+  );
+} finally {
+  await cli("detach");
+  await manager.destroy();
+  await new Promise<void>((resolve) => ipc.close(() => resolve()));
+  page.stop(true);
+  await rm(directory, { recursive: true, force: true });
+}

package/src/__tests__/config-schema.test.ts

@@ -1021,7 +1021,7 @@ describe("AssistantConfigSchema", () => {
           maxSilenceMs: 35000,
           longOpMs: 15000,
           minGapMs: 6000,
-          generationTimeoutMs: 1500,
+          generationTimeoutMs: 5000,
         },
       },
     });

package/src/__tests__/config-sounds-sync.test.ts

@@ -5,6 +5,7 @@ import { SYNC_TAGS } from "../daemon/message-types/sync.js";
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";
 import {
   publishConfigChanged,
+  publishMcpChanged,
   publishSchedulesChanged,
   publishSoundsConfigUpdated,
 } from "../runtime/sync/resource-sync-events.js";
@@ -94,4 +95,26 @@ describe("config and sounds sync events", () => {
       subscription.dispose();
     }
   });
+
+  test("MCP changes emit a sync tag without a client origin", async () => {
+    const received: AssistantEventEnvelope[] = [];
+    const subscription = assistantEventHub.subscribe({
+      type: "process",
+      callback: (event) => {
+        received.push(event);
+      },
+    });
+
+    try {
+      publishMcpChanged();
+      await waitFor(() => received.length === 1);
+
+      expect(received[0].message).toEqual({
+        type: "sync_changed",
+        tags: [SYNC_TAGS.mcpList],
+      });
+    } finally {
+      subscription.dispose();
+    }
+  });
 });

package/src/__tests__/conversation-error.test.ts

@@ -1490,6 +1490,7 @@ describe("classifyConversationError", () => {
       "subagent_aborted",
       "signal_cancel",
       "voice_session_aborted",
+      "voice_progress_narration_timeout",
     ];
 
     for (const kind of taggedKinds) {
@@ -1727,7 +1728,9 @@ describe("ConnectionResolutionError classification", () => {
     expect(result.userMessage).toContain("qwen/qwen3-8b");
     expect(result.userMessage).toContain("Vellum GPU route");
     expect(result.userMessage).toContain('profile "steer"');
-    expect(result.userMessage).toContain("was not sent through another provider");
+    expect(result.userMessage).toContain(
+      "was not sent through another provider",
+    );
   });
 
   it("classifies missing_credential naming the connection and fix", () => {

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -607,7 +607,9 @@ describe("injectChannelCapabilityContext", () => {
         "ui_show, ui_update, and ui_dismiss persist conversation content",
       );
       expect(text).not.toContain("Only use ui_show/ui_update");
-      expect(text).not.toContain("Do NOT use ui_show, ui_update, or app_create");
+      expect(text).not.toContain(
+        "Do NOT use ui_show, ui_update, or app_create",
+      );
       expect(text).not.toContain(
         "Present information as well-formatted text instead of dynamic UI.",
       );
@@ -898,12 +900,12 @@ describe("trust-gating via channel capabilities", () => {
 
     const result = injectChannelCapabilityContext(message, caps);
 
-    // macOS clients now get osascript guidance injected
+    // macOS clients get app-scripting guidance injected
     expect(result).not.toBe(message);
     const injected = (result.content[0] as { type: "text"; text: string }).text;
     expect(injected).toContain("client_os: macos");
-    expect(injected).toContain("osascript");
-    expect(injected).toContain("host_bash");
+    expect(injected).toContain("drive apps with the computer-use skill");
+    expect(injected).toContain("`host_bash` is for shell commands");
     // No channel constraints — full desktop capabilities
     expect(injected).not.toContain("CHANNEL CONSTRAINTS");
   });

package/src/__tests__/external-plugin-loader.test.ts

@@ -39,6 +39,20 @@ function writePackageJson(dir: string, pkg: Record<string, unknown>): void {
   writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2));
 }
 
+function writePluginJson(dir: string, manifest: Record<string, unknown>): void {
+  writeFileSync(
+    join(dir, "plugin.json"),
+    JSON.stringify(
+      {
+        $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        ...manifest,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
 function writeSurfaceFile(dir: string, relPath: string, body: string): void {
   const parts = relPath.split("/");
   parts.pop();
@@ -104,6 +118,31 @@ describe("loadExternalPlugin — manifest", () => {
     expect(registered).toBeDefined();
     expect(registered?.manifest.version).toBe("0.0.0");
   });
+
+  test("loads a standard plugin.json when package.json is absent", async () => {
+    const dir = freshPluginDir("standard-only");
+    writePluginJson(dir, { name: "standard-only", version: "2.1.0" });
+
+    await loadExternalPlugin(dir);
+
+    const registered = getRegisteredPlugins().find(
+      (plugin) => plugin.manifest.name === "standard-only",
+    );
+    expect(registered?.manifest.version).toBe("2.1.0");
+  });
+
+  test("keeps package.json authoritative when plugin.json is also present", async () => {
+    const dir = freshPluginDir("mixed-manifests");
+    writePackageJson(dir, { name: "legacy-name", version: "1.2.3" });
+    writeFileSync(join(dir, "plugin.json"), "{ foreign and malformed }");
+
+    await loadExternalPlugin(dir);
+
+    const registered = getRegisteredPlugins().find(
+      (plugin) => plugin.manifest.name === "mixed-manifests",
+    );
+    expect(registered?.manifest.version).toBe("1.2.3");
+  });
 });
 
 describe("credentialKeyPatterns manifest field", () => {
@@ -277,6 +316,19 @@ describe("loadExternalPlugin — plugin-api peerDependency", () => {
   test("malformed package.json is logged and skipped (registry untouched)", async () => {
     const dir = freshPluginDir("malformed-pkg");
     writeFileSync(join(dir, "package.json"), "{ this is not json");
+    writePluginJson(dir, { name: "valid-standard-fallback" });
+
+    await loadExternalPlugin(dir);
+
+    expect(registeredNames()).toHaveLength(0);
+  });
+
+  test("malformed selected plugin.json is logged and skipped", async () => {
+    const dir = freshPluginDir("malformed-standard");
+    writeFileSync(
+      join(dir, "plugin.json"),
+      JSON.stringify({ name: "missing-schema" }),
+    );
 
     await loadExternalPlugin(dir);
 

package/src/__tests__/headless-browser-mode.test.ts

@@ -41,6 +41,16 @@ function makeFakeCdp(
     dispose() {
       _cdpDisposed = true;
     },
+    setCdpSessionId() {},
+    async listTabs() {
+      return [];
+    },
+    async selectTab(tabId: number) {
+      return { tabId };
+    },
+    async closeTab(tabId: number) {
+      return { tabId, closed: true };
+    },
   };
 }
 
@@ -142,6 +152,8 @@ mock.module("../tools/network/url-safety.js", () => ({
 
 import {
   executeBrowserClick,
+  executeBrowserClose,
+  executeBrowserDetach,
   executeBrowserNavigate,
   executeBrowserScreenshot,
   executeBrowserSnapshot,
@@ -687,6 +699,42 @@ describe("browser_mode wiring through tool execution", () => {
 
   // ── Per-conversation sticky backend kind ─────────────────────────
 
+  for (const release of [executeBrowserDetach, executeBrowserClose]) {
+    test.each(["local", "extension", "cdp-inspect"])(
+      `${release.name} on desktop preserves the normal %s session's backend`,
+      async (mode) => {
+        const first = await executeBrowserSnapshot({ browser_mode: mode }, ctx);
+        expect(first.isError).toBe(false);
+
+        factoryModeCalls.length = 0;
+        const desktop = await release(
+          {},
+          {
+            ...ctx,
+            cdpClient: makeFakeCdp(
+              "cdp-inspect",
+              `desktop-browser:${ctx.conversationId}`,
+            ),
+          },
+        );
+        expect(desktop.isError).toBe(false);
+        expect(factoryModeCalls).toEqual([]);
+
+        const resumed = await executeBrowserSnapshot({}, ctx);
+        expect(resumed.isError).toBe(false);
+        expect(factoryModeCalls).toEqual([mode]);
+      },
+    );
+
+    test(`${release.name} on the normal browser still resets automatic selection`, async () => {
+      await executeBrowserSnapshot({ browser_mode: "extension" }, ctx);
+      expect((await release({}, ctx)).isError).toBe(false);
+      factoryModeCalls.length = 0;
+      expect((await executeBrowserSnapshot({}, ctx)).isError).toBe(false);
+      expect(factoryModeCalls).toEqual(["auto"]);
+    });
+  }
+
   test("auto-mode call after an explicit pin sticks to the pinned kind", async () => {
     const first = await executeBrowserNavigate(
       { url: "https://example.com", browser_mode: "local" },