Add opt-in browser tools for desktop tabs

* Add opt-in browser tools for desktop tabs Adds the daemon opt-in, desktop tab routing, MCP tools, and real browser automation surfaces for Paseo desktop browser tabs. * Fix browser tools CI expectations * Address browser tools review findings * Restrict browser file automation paths * Fix browser upload test on Windows * Harden browser navigation inputs * Make browser tools create usable tabs * Update browser MCP empty-state test * Fail browser tab creation when registration times out * Fix browser screenshots for agents * Hide disabled browser tools from agents * Address browser tools architecture review * Replace browser tools review tests * Wrap browser tab registration errors * Mock Expo Router in app unit tests * Handle invalid browser automation requests * Return browser failure on desktop disconnect * Update browser disconnect websocket test * Relax browser timeout polling test * Handle invalid browser responses * Return browser failure when send fails * Remove local diagnostics and fixture paths * Fix dev service home fallback * Use worktree home for dev services * Use managed daemon in desktop dev * fix(browser): keep agent tabs addressable Track agent-active browser targets separately from human-focused tabs and keep resident webviews alive for automation. Browser tool visibility now comes from registration while the broker reports disabled execution. * refactor(browser): register tools through catalog Move browser tool registration onto the shared Paseo tool catalog so the MCP server remains only the transport adapter. * fix(settings): translate browser tools host error
2026-06-30 22:33:18 +02:00
parent db03b1f3fd
commit 20385bdb50
71 changed files with 10908 additions and 115 deletions
@@ -87,6 +87,7 @@ import { polyfillCrypto } from "@/polyfills/crypto";
 import { queryClient } from "@/query/query-client";
 import {
  getHostRuntimeStore,
+  hasConfiguredLocalDaemonOverride,
  useHostRegistryLoaded,
  useHostMutations,
  useHostRuntimeClient,
@@ -313,6 +314,9 @@ async function shouldStartBuiltInDaemon(): Promise<boolean> {
  if (!shouldUseDesktopDaemon()) {
    return false;
  }
+  if (hasConfiguredLocalDaemonOverride()) {
+    return false;
+  }
  const settings = await loadDesktopSettings();
  return settings.daemon.manageBuiltInDaemon;
 }
@@ -0,0 +1,375 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { mountBrowserAutomationHandler } from "./handler";
+import type { DesktopHostBridge } from "@/desktop/host";
+import { useBrowserStore } from "@/stores/browser-store";
+import {
+  buildWorkspaceTabPersistenceKey,
+  useWorkspaceLayoutStore,
+} from "@/stores/workspace-layout-store";
+
+vi.mock("expo-router", () => ({
+  router: {
+    navigate: vi.fn(),
+  },
+}));
+
+vi.mock("@react-native-async-storage/async-storage", () => ({
+  default: {
+    getItem: vi.fn(async () => null),
+    setItem: vi.fn(async () => undefined),
+    removeItem: vi.fn(async () => undefined),
+  },
+}));
+
+type BrowserAutomationExecuteRequest = Extract<
+  SessionOutboundMessage,
+  { type: "browser.automation.execute.request" }
+>;
+type BrowserAutomationExecuteResponse = Extract<
+  SessionInboundMessage,
+  { type: "browser.automation.execute.response" }
+>;
+
+class FakeDaemonClient {
+  public sentResponses: BrowserAutomationExecuteResponse[] = [];
+  private handler: ((request: BrowserAutomationExecuteRequest) => void) | null = null;
+
+  public on(
+    type: "browser.automation.execute.request",
+    handler: (request: BrowserAutomationExecuteRequest) => void,
+  ): () => void {
+    expect(type).toBe("browser.automation.execute.request");
+    this.handler = handler;
+    return () => {
+      if (this.handler === handler) {
+        this.handler = null;
+      }
+    };
+  }
+
+  public sendBrowserAutomationExecuteResponse(response: BrowserAutomationExecuteResponse): void {
+    this.sentResponses.push(response);
+  }
+
+  public receive(nextRequest: BrowserAutomationExecuteRequest): void {
+    this.handler?.(nextRequest);
+  }
+}
+
+function browserAutomationRequest(): BrowserAutomationExecuteRequest {
+  return {
+    type: "browser.automation.execute.request",
+    requestId: "req-1",
+    command: { command: "list_tabs", args: {} },
+  };
+}
+
+function browserNewTabRequest(): BrowserAutomationExecuteRequest {
+  return {
+    type: "browser.automation.execute.request",
+    requestId: "req-new",
+    agentId: "agent-1",
+    workspaceId: "/repo",
+    command: { command: "new_tab", args: { workspaceId: "/repo", url: "https://example.com" } },
+  };
+}
+
+function emptyListTabsPayload(requestId = "req-new:list_tabs") {
+  return {
+    requestId,
+    ok: true as const,
+    result: {
+      command: "list_tabs" as const,
+      tabs: [],
+    },
+  };
+}
+
+function currentListTabsPayload(requestId = "req-new:list_tabs") {
+  return {
+    requestId,
+    ok: true as const,
+    result: {
+      command: "list_tabs" as const,
+      tabs: currentBrowserTabs(),
+    },
+  };
+}
+
+function flushPromises(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function waitForAsyncWork(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 20));
+}
+
+function currentBrowserTabs() {
+  return Object.values(useBrowserStore.getState().browsersById).map((browser) => ({
+    browserId: browser.browserId,
+    workspaceId: "/repo",
+    url: browser.url,
+    title: browser.title,
+    isActive: true,
+    isLoading: false,
+  }));
+}
+
+describe("mountBrowserAutomationHandler", () => {
+  beforeEach(() => {
+    useBrowserStore.setState({ browsersById: {} });
+    useWorkspaceLayoutStore.setState({ layoutByWorkspace: {} });
+  });
+
+  test("creates an unfocused workspace browser tab for browser_new_tab", async () => {
+    const client = new FakeDaemonClient();
+    const setWorkspaceActiveBrowser = vi.fn(async () => undefined);
+    const setAgentActiveBrowser = vi.fn(async () => undefined);
+    const registerWorkspaceBrowser = vi.fn(async () => undefined);
+    const ensureResidentBrowserWebview = vi.fn();
+    const executeAutomationCommand = vi.fn(async () => currentListTabsPayload());
+    const workspaceKey = buildWorkspaceTabPersistenceKey({
+      serverId: "server-1",
+      workspaceId: "/repo",
+    });
+    if (!workspaceKey) throw new Error("expected workspace key");
+    const focusedTabId = useWorkspaceLayoutStore
+      .getState()
+      .openTabFocused(workspaceKey, { kind: "draft", draftId: "human-draft" });
+    if (!focusedTabId) throw new Error("expected focused tab");
+    mountBrowserAutomationHandler({
+      client,
+      serverId: "server-1",
+      getHost: () =>
+        ({
+          browser: {
+            executeAutomationCommand,
+            registerWorkspaceBrowser,
+            setWorkspaceActiveBrowser,
+            setAgentActiveBrowser,
+          },
+        }) satisfies DesktopHostBridge,
+      ensureResidentBrowserWebview,
+    });
+
+    client.receive(browserNewTabRequest());
+    await flushPromises();
+
+    const payload = client.sentResponses[0]?.payload;
+    expect(payload?.ok).toBe(true);
+    if (!payload?.ok) throw new Error("expected success");
+    expect(payload.result.command).toBe("new_tab");
+    if (payload.result.command !== "new_tab") throw new Error("expected new_tab result");
+    expect(payload.result.url).toBe("https://example.com");
+    expect(useWorkspaceLayoutStore.getState().getWorkspaceTabs(workspaceKey)).toContainEqual(
+      expect.objectContaining({ target: { kind: "browser", browserId: payload.result.browserId } }),
+    );
+    const layout = useWorkspaceLayoutStore.getState().layoutByWorkspace[workspaceKey];
+    expect(layout?.root.kind).toBe("pane");
+    if (layout?.root.kind !== "pane") throw new Error("expected root pane");
+    expect(layout.root.pane.focusedTabId).toBe(focusedTabId);
+    expect(registerWorkspaceBrowser).toHaveBeenCalledWith({
+      browserId: payload.result.browserId,
+      workspaceId: "/repo",
+    });
+    expect(setAgentActiveBrowser).toHaveBeenCalledWith({
+      agentId: "agent-1",
+      browserId: payload.result.browserId,
+    });
+    expect(setWorkspaceActiveBrowser).not.toHaveBeenCalled();
+    expect(ensureResidentBrowserWebview).toHaveBeenCalledWith({
+      browserId: payload.result.browserId,
+      url: "https://example.com",
+    });
+    expect(executeAutomationCommand).toHaveBeenCalledTimes(1);
+  });
+
+  test("returns browser_timeout when the resident webview does not register", async () => {
+    const client = new FakeDaemonClient();
+    const ensureResidentBrowserWebview = vi.fn();
+    const executeAutomationCommand = vi.fn(async () => emptyListTabsPayload());
+    mountBrowserAutomationHandler({
+      client,
+      serverId: "server-1",
+      getHost: () => ({ browser: { executeAutomationCommand } }) satisfies DesktopHostBridge,
+      ensureResidentBrowserWebview,
+      registrationWaitTimeoutMs: 1,
+      registrationPollIntervalMs: 1,
+    });
+
+    client.receive(browserNewTabRequest());
+    await waitForAsyncWork();
+
+    expect(client.sentResponses[0]?.payload).toMatchObject({
+      requestId: "req-new",
+      ok: false,
+      error: {
+        code: "browser_timeout",
+        retryable: true,
+      },
+    });
+    expect(ensureResidentBrowserWebview).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://example.com" }),
+    );
+    expect(client.sentResponses[0]?.payload).not.toMatchObject({
+      ok: true,
+      result: { command: "new_tab" },
+    });
+  });
+
+  test("wraps browser_new_tab registration bridge errors in a response", async () => {
+    const client = new FakeDaemonClient();
+    const executeAutomationCommand = vi.fn(async () => {
+      throw new Error("IPC registration check failed");
+    });
+    mountBrowserAutomationHandler({
+      client,
+      serverId: "server-1",
+      getHost: () => ({ browser: { executeAutomationCommand } }) satisfies DesktopHostBridge,
+    });
+
+    client.receive(browserNewTabRequest());
+    await flushPromises();
+
+    expect(client.sentResponses[0]?.payload).toEqual({
+      requestId: "req-new",
+      ok: false,
+      error: {
+        code: "browser_unknown_error",
+        message: "IPC registration check failed",
+        retryable: false,
+      },
+    });
+  });
+
+  test("sends a success response from the desktop bridge", async () => {
+    const client = new FakeDaemonClient();
+    const executeAutomationCommand = vi.fn(async () => ({
+      requestId: "req-1",
+      ok: true as const,
+      result: { command: "list_tabs" as const, tabs: [] },
+    }));
+
+    mountBrowserAutomationHandler({
+      client,
+      getHost: () => ({ browser: { executeAutomationCommand } }) satisfies DesktopHostBridge,
+    });
+
+    client.receive(browserAutomationRequest());
+    await flushPromises();
+
+    expect(executeAutomationCommand).toHaveBeenCalledWith(browserAutomationRequest());
+    expect(client.sentResponses).toEqual([
+      {
+        type: "browser.automation.execute.response",
+        payload: {
+          requestId: "req-1",
+          ok: true,
+          result: { command: "list_tabs", tabs: [] },
+        },
+      },
+    ]);
+  });
+
+  test("missing bridge sends browser_unsupported", async () => {
+    const client = new FakeDaemonClient();
+    mountBrowserAutomationHandler({ client, getHost: () => null });
+
+    client.receive(browserAutomationRequest());
+    await flushPromises();
+
+    expect(client.sentResponses).toEqual([
+      {
+        type: "browser.automation.execute.response",
+        payload: {
+          requestId: "req-1",
+          ok: false,
+          error: {
+            code: "browser_unsupported",
+            message: "Desktop browser automation is not available in this app runtime.",
+            retryable: false,
+          },
+        },
+      },
+    ]);
+  });
+
+  test("typed bridge errors become failure responses", async () => {
+    const client = new FakeDaemonClient();
+    mountBrowserAutomationHandler({
+      client,
+      getHost: () => ({
+        browser: {
+          executeAutomationCommand: async () => {
+            throw {
+              code: "browser_tab_not_found",
+              message: "Browser tab browser-1 was not found.",
+              retryable: false,
+            };
+          },
+        },
+      }),
+    });
+
+    client.receive(browserAutomationRequest());
+    await flushPromises();
+
+    expect(client.sentResponses[0]?.payload).toEqual({
+      requestId: "req-1",
+      ok: false,
+      error: {
+        code: "browser_tab_not_found",
+        message: "Browser tab browser-1 was not found.",
+        retryable: false,
+      },
+    });
+  });
+
+  test("unimplemented preload IPC reports browser_unsupported", async () => {
+    const client = new FakeDaemonClient();
+    mountBrowserAutomationHandler({
+      client,
+      getHost: () => ({
+        browser: {
+          executeAutomationCommand: async () => {
+            throw new Error('No handler registered for "paseo:browser:execute-automation-command"');
+          },
+        },
+      }),
+    });
+
+    client.receive(browserAutomationRequest());
+    await flushPromises();
+
+    expect(client.sentResponses[0]?.payload).toEqual({
+      requestId: "req-1",
+      ok: false,
+      error: {
+        code: "browser_unsupported",
+        message: "Desktop browser automation is not implemented by this desktop build yet.",
+        retryable: false,
+      },
+    });
+  });
+
+  test("unsubscribe stops handling requests", async () => {
+    const client = new FakeDaemonClient();
+    const executeAutomationCommand = vi.fn(async () => ({
+      requestId: "req-1",
+      ok: true as const,
+      result: { command: "list_tabs" as const, tabs: [] },
+    }));
+    const unsubscribe = mountBrowserAutomationHandler({
+      client,
+      getHost: () => ({ browser: { executeAutomationCommand } }),
+    });
+
+    unsubscribe();
+    client.receive(browserAutomationRequest());
+    await flushPromises();
+
+    expect(executeAutomationCommand).not.toHaveBeenCalled();
+    expect(client.sentResponses).toEqual([]);
+  });
+});
@@ -0,0 +1,343 @@
+import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { getDesktopHost, type DesktopHostBridge } from "@/desktop/host";
+import { ensureResidentBrowserWebview as ensureResidentBrowserWebviewDefault } from "@/components/browser-webview-resident";
+import { createWorkspaceBrowser } from "@/stores/browser-store";
+import {
+  buildWorkspaceTabPersistenceKey,
+  useWorkspaceLayoutStore,
+} from "@/stores/workspace-layout-store";
+
+type BrowserAutomationExecuteRequest = Extract<
+  SessionOutboundMessage,
+  { type: "browser.automation.execute.request" }
+>;
+type BrowserAutomationExecuteResponse = Extract<
+  SessionInboundMessage,
+  { type: "browser.automation.execute.response" }
+>;
+type BrowserAutomationResponsePayload = BrowserAutomationExecuteResponse["payload"];
+type BrowserAutomationFailurePayload = Extract<BrowserAutomationResponsePayload, { ok: false }>;
+type BrowserAutomationErrorCode = BrowserAutomationFailurePayload["error"]["code"];
+
+interface BrowserAutomationClient {
+  on(
+    type: "browser.automation.execute.request",
+    handler: (message: BrowserAutomationExecuteRequest) => void,
+  ): () => void;
+  sendBrowserAutomationExecuteResponse(response: BrowserAutomationExecuteResponse): void;
+}
+
+export interface BrowserAutomationHandlerOptions {
+  client: BrowserAutomationClient;
+  serverId?: string;
+  getHost?: () => DesktopHostBridge | null;
+  ensureResidentBrowserWebview?: typeof ensureResidentBrowserWebviewDefault;
+  registrationWaitTimeoutMs?: number;
+  registrationPollIntervalMs?: number;
+}
+
+export function mountBrowserAutomationHandler(
+  options: BrowserAutomationHandlerOptions,
+): () => void {
+  const getHost = options.getHost ?? getDesktopHost;
+  return options.client.on("browser.automation.execute.request", (request) => {
+    void handleBrowserAutomationRequest({
+      client: options.client,
+      getHost,
+      request,
+      serverId: options.serverId,
+      ensureResidentBrowserWebview:
+        options.ensureResidentBrowserWebview ?? ensureResidentBrowserWebviewDefault,
+      ...(options.registrationWaitTimeoutMs !== undefined
+        ? { registrationWaitTimeoutMs: options.registrationWaitTimeoutMs }
+        : {}),
+      ...(options.registrationPollIntervalMs !== undefined
+        ? { registrationPollIntervalMs: options.registrationPollIntervalMs }
+        : {}),
+    });
+  });
+}
+
+export function mountBrowserAutomationDaemonClientHandler(
+  client: unknown,
+  options?: { serverId?: string },
+): () => void {
+  return mountBrowserAutomationHandler({
+    client: client as BrowserAutomationClient,
+    ...(options?.serverId ? { serverId: options.serverId } : {}),
+  });
+}
+
+async function handleBrowserAutomationRequest(params: {
+  client: BrowserAutomationHandlerOptions["client"];
+  getHost: () => DesktopHostBridge | null;
+  request: BrowserAutomationExecuteRequest;
+  serverId?: string;
+  ensureResidentBrowserWebview: typeof ensureResidentBrowserWebviewDefault;
+  registrationWaitTimeoutMs?: number;
+  registrationPollIntervalMs?: number;
+}): Promise<void> {
+  const {
+    client,
+    getHost,
+    request,
+    serverId,
+    ensureResidentBrowserWebview,
+    registrationWaitTimeoutMs,
+    registrationPollIntervalMs,
+  } = params;
+  const browserHost = getHost()?.browser;
+  const executeAutomationCommand = browserHost?.executeAutomationCommand;
+
+  if (request.command.command === "new_tab") {
+    try {
+      client.sendBrowserAutomationExecuteResponse({
+        type: "browser.automation.execute.response",
+        payload: await openBrowserTabForRequest({
+          request,
+          serverId,
+          browserHost,
+          ensureResidentBrowserWebview,
+          ...(registrationWaitTimeoutMs !== undefined ? { registrationWaitTimeoutMs } : {}),
+          ...(registrationPollIntervalMs !== undefined ? { registrationPollIntervalMs } : {}),
+        }),
+      });
+    } catch (error) {
+      client.sendBrowserAutomationExecuteResponse({
+        type: "browser.automation.execute.response",
+        payload: normalizeThrownBridgeError(request.requestId, error),
+      });
+    }
+    return;
+  }
+
+  await rememberAgentBrowserTarget({ request, browserHost });
+
+  if (!executeAutomationCommand) {
+    client.sendBrowserAutomationExecuteResponse({
+      type: "browser.automation.execute.response",
+      payload: browserAutomationFailure({
+        requestId: request.requestId,
+        code: "browser_unsupported",
+        message: "Desktop browser automation is not available in this app runtime.",
+      }),
+    });
+    return;
+  }
+
+  try {
+    const payload = await executeAutomationCommand(request);
+    client.sendBrowserAutomationExecuteResponse({
+      type: "browser.automation.execute.response",
+      payload: normalizeBridgePayload(request.requestId, payload),
+    });
+  } catch (error) {
+    client.sendBrowserAutomationExecuteResponse({
+      type: "browser.automation.execute.response",
+      payload: normalizeThrownBridgeError(request.requestId, error),
+    });
+  }
+}
+
+async function openBrowserTabForRequest(params: {
+  request: BrowserAutomationExecuteRequest;
+  serverId?: string;
+  browserHost: DesktopHostBridge["browser"] | undefined;
+  ensureResidentBrowserWebview: typeof ensureResidentBrowserWebviewDefault;
+  registrationWaitTimeoutMs?: number;
+  registrationPollIntervalMs?: number;
+}): Promise<BrowserAutomationResponsePayload> {
+  const {
+    request,
+    serverId,
+    browserHost,
+    ensureResidentBrowserWebview,
+    registrationWaitTimeoutMs,
+    registrationPollIntervalMs,
+  } = params;
+  const command = request.command as Extract<
+    BrowserAutomationExecuteRequest["command"],
+    { command: "new_tab" }
+  >;
+  const workspaceId = request.workspaceId ?? command.args.workspaceId;
+  if (!serverId || !workspaceId) {
+    return browserAutomationFailure({
+      requestId: request.requestId,
+      code: "browser_no_tab",
+      message: "Cannot create a browser tab without a workspace context.",
+    });
+  }
+
+  const url = command.args.url ?? "https://example.com";
+  const { browserId, url: normalizedUrl } = createWorkspaceBrowser({ initialUrl: url });
+  const workspaceKey = buildWorkspaceTabPersistenceKey({ serverId, workspaceId });
+  if (!workspaceKey) {
+    return browserAutomationFailure({
+      requestId: request.requestId,
+      code: "browser_no_tab",
+      message: "Cannot create a browser tab without a workspace context.",
+    });
+  }
+  useWorkspaceLayoutStore.getState().openTabInBackground(workspaceKey, {
+    kind: "browser",
+    browserId,
+  });
+
+  await browserHost?.registerWorkspaceBrowser?.({ browserId, workspaceId });
+  if (request.agentId) {
+    await browserHost?.setAgentActiveBrowser?.({ agentId: request.agentId, browserId });
+  }
+
+  if (browserHost?.executeAutomationCommand) {
+    ensureResidentBrowserWebview({ browserId, url: normalizedUrl });
+    const registered = await waitForBrowserRegistration({
+      request,
+      browserId,
+      workspaceId,
+      executeAutomationCommand: browserHost.executeAutomationCommand,
+      ...(registrationWaitTimeoutMs !== undefined ? { timeoutMs: registrationWaitTimeoutMs } : {}),
+      ...(registrationPollIntervalMs !== undefined
+        ? { pollIntervalMs: registrationPollIntervalMs }
+        : {}),
+    });
+    if (!registered) {
+      return browserAutomationFailure({
+        requestId: request.requestId,
+        code: "browser_timeout",
+        message: `Timed out waiting for browser tab ${browserId} to register with desktop automation. Try browser_new_tab again.`,
+        retryable: true,
+      });
+    }
+  }
+
+  return {
+    requestId: request.requestId,
+    ok: true,
+    result: { command: "new_tab", browserId, workspaceId, url: normalizedUrl },
+  };
+}
+
+async function waitForBrowserRegistration(params: {
+  request: BrowserAutomationExecuteRequest;
+  browserId: string;
+  workspaceId: string;
+  executeAutomationCommand: (
+    request: BrowserAutomationExecuteRequest,
+  ) => Promise<BrowserAutomationResponsePayload>;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+}): Promise<boolean> {
+  const deadline = Date.now() + (params.timeoutMs ?? 5_000);
+  while (Date.now() < deadline) {
+    const payload = await params.executeAutomationCommand({
+      type: "browser.automation.execute.request",
+      requestId: `${params.request.requestId}:list_tabs`,
+      agentId: params.request.agentId,
+      cwd: params.request.cwd,
+      workspaceId: params.workspaceId,
+      command: { command: "list_tabs", args: { workspaceId: params.workspaceId } },
+    });
+    if (payload.ok && payload.result.command === "list_tabs") {
+      if (payload.result.tabs.some((tab) => tab.browserId === params.browserId)) {
+        return true;
+      }
+    }
+    await delay(params.pollIntervalMs ?? 100);
+  }
+  return false;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function rememberAgentBrowserTarget(input: {
+  request: BrowserAutomationExecuteRequest;
+  browserHost: DesktopHostBridge["browser"] | undefined;
+}): Promise<void> {
+  if (!input.request.agentId) {
+    return;
+  }
+  const browserId = readRequestBrowserId(input.request);
+  if (!browserId) {
+    return;
+  }
+  await input.browserHost?.setAgentActiveBrowser?.({ agentId: input.request.agentId, browserId });
+}
+
+function readRequestBrowserId(request: BrowserAutomationExecuteRequest): string | null {
+  if (request.browserId) {
+    return request.browserId;
+  }
+  const args = request.command.args as { browserId?: unknown };
+  return typeof args.browserId === "string" && args.browserId.length > 0 ? args.browserId : null;
+}
+
+function normalizeBridgePayload(
+  requestId: string,
+  payload: BrowserAutomationResponsePayload,
+): BrowserAutomationResponsePayload {
+  return { ...payload, requestId } as BrowserAutomationResponsePayload;
+}
+
+function normalizeThrownBridgeError(
+  requestId: string,
+  error: unknown,
+): BrowserAutomationFailurePayload {
+  const typed = readTypedBrowserAutomationError(error);
+  if (typed) {
+    return browserAutomationFailure({ requestId, ...typed });
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("No handler registered")) {
+    return browserAutomationFailure({
+      requestId,
+      code: "browser_unsupported",
+      message: "Desktop browser automation is not implemented by this desktop build yet.",
+    });
+  }
+
+  return browserAutomationFailure({
+    requestId,
+    code: "browser_unknown_error",
+    message: message || "Desktop browser automation failed.",
+  });
+}
+
+function readTypedBrowserAutomationError(
+  value: unknown,
+): { code: BrowserAutomationErrorCode; message: string; retryable?: boolean } | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.code !== "string" || !record.code.startsWith("browser_")) {
+    return null;
+  }
+  if (typeof record.message !== "string" || record.message.length === 0) {
+    return null;
+  }
+  return {
+    code: record.code as BrowserAutomationErrorCode,
+    message: record.message,
+    ...(typeof record.retryable === "boolean" ? { retryable: record.retryable } : {}),
+  };
+}
+
+function browserAutomationFailure(params: {
+  requestId: string;
+  code: BrowserAutomationErrorCode;
+  message: string;
+  retryable?: boolean;
+}): BrowserAutomationFailurePayload {
+  return {
+    requestId: params.requestId,
+    ok: false,
+    error: {
+      code: params.code,
+      message: params.message,
+      retryable: params.retryable ?? false,
+    },
+  };
+}
@@ -25,6 +25,11 @@ import {
 } from "@/desktop/host";
 import { isDev } from "@/constants/platform";
 import { useBrowserStore, normalizeWorkspaceBrowserUrl } from "@/stores/browser-store";
+import {
+  prepareBrowserWebview,
+  releaseResidentBrowserWebview,
+  takeResidentBrowserWebview,
+} from "./browser-webview-resident";

 type ElectronWebview = HTMLElement & {
  canGoBack?: () => boolean;
@@ -404,16 +409,16 @@ export function BrowserPane({
      initialUrlRef.current,
      browserErrorLabelsRef.current,
    );
-    const webview = document.createElement("webview") as ElectronWebview;
+    const residentWebview = takeResidentBrowserWebview(browserId) as ElectronWebview | null;
+    const webview = residentWebview ?? (document.createElement("webview") as ElectronWebview);
    webviewRef.current = webview;
-    webview.setAttribute("partition", `persist:paseo-browser-${browserId}`);
-    webview.setAttribute("allowpopups", "true");
-    webview.setAttribute("spellcheck", "false");
-    webview.setAttribute("autosize", "on");
-    webview.setAttribute(
-      "src",
-      initialUnsafeNavigationMessage ? "about:blank" : initialUrlRef.current,
-    );
+    void getDesktopHost()?.browser?.registerWorkspaceBrowser?.({ browserId, workspaceId });
+    if (!residentWebview) {
+      prepareBrowserWebview(webview, {
+        browserId,
+        initialUrl: initialUnsafeNavigationMessage ? "about:blank" : initialUrlRef.current,
+      });
+    }
    webview.style.display = "flex";
    webview.style.flex = "1";
    webview.style.width = "100%";
@@ -528,7 +533,14 @@ export function BrowserPane({
      webview.removeEventListener("focus", handleWebviewFocus);
      webview.removeEventListener("mousedown", handleWebviewFocus);
      if (host.contains(webview)) {
-        host.removeChild(webview);
+        const browserStillExists = Boolean(
+          useBrowserStore.getState().browsersById[browserIdRef.current],
+        );
+        if (browserStillExists) {
+          releaseResidentBrowserWebview(browserIdRef.current, webview);
+        } else {
+          host.removeChild(webview);
+        }
      }
      if (webviewRef.current === webview) {
        webviewRef.current = null;
@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  clearResidentBrowserWebviewsForTests,
+  ensureResidentBrowserWebview,
+  releaseResidentBrowserWebview,
+  removeResidentBrowserWebview,
+  takeResidentBrowserWebview,
+} from "./browser-webview-resident";
+
+describe("resident browser webviews", () => {
+  afterEach(() => {
+    clearResidentBrowserWebviewsForTests();
+  });
+
+  it("keeps a browser webview mounted offscreen and reuses the same node", () => {
+    const host = document.createElement("div");
+    const webview = document.createElement("webview");
+    host.appendChild(webview);
+    document.body.appendChild(host);
+
+    releaseResidentBrowserWebview("browser-a", webview);
+
+    expect(host.children).toHaveLength(0);
+    expect(webview.isConnected).toBe(true);
+    expect(webview.style.width).toBe("1280px");
+    expect(webview.style.height).toBe("800px");
+
+    const reused = takeResidentBrowserWebview("browser-a");
+
+    expect(reused).toBe(webview);
+    expect(takeResidentBrowserWebview("browser-a")).toBeNull();
+  });
+
+  it("creates a resident webview for an agent-created unfocused tab", () => {
+    const webview = ensureResidentBrowserWebview({
+      browserId: "browser-agent",
+      url: "https://example.com",
+    });
+
+    expect(webview).not.toBeNull();
+    expect(webview?.isConnected).toBe(true);
+    expect(webview?.getAttribute("data-paseo-browser-id")).toBe("browser-agent");
+    expect(webview?.getAttribute("partition")).toBe("persist:paseo-browser-browser-agent");
+    expect((webview as HTMLUnknownElement & { src?: string })?.src).toContain(
+      "https://example.com",
+    );
+  });
+
+  it("removes a resident webview when its browser tab closes", () => {
+    const webview = ensureResidentBrowserWebview({
+      browserId: "browser-closed",
+      url: "https://example.com",
+    });
+
+    removeResidentBrowserWebview("browser-closed");
+
+    expect(webview?.isConnected).toBe(false);
+    expect(takeResidentBrowserWebview("browser-closed")).toBeNull();
+  });
+});
@@ -0,0 +1,153 @@
+const RESIDENT_BROWSER_HOST_ID = "paseo-browser-resident-webviews";
+const BROWSER_ID_ATTRIBUTE = "data-paseo-browser-id";
+const RESIDENT_VIEWPORT_WIDTH = 1280;
+const RESIDENT_VIEWPORT_HEIGHT = 800;
+
+const residentWebviewsByBrowserId = new Map<string, HTMLElement>();
+
+interface BrowserWebviewElement extends HTMLElement {
+  src: string;
+}
+
+function trimNonEmpty(value: string | null | undefined): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function readDocument(): Document | null {
+  return typeof document === "undefined" ? null : document;
+}
+
+function getResidentBrowserHost(ownerDocument: Document): HTMLElement {
+  const existing = ownerDocument.getElementById(RESIDENT_BROWSER_HOST_ID);
+  if (existing) {
+    return existing;
+  }
+
+  const host = ownerDocument.createElement("div");
+  host.id = RESIDENT_BROWSER_HOST_ID;
+  host.setAttribute("aria-hidden", "true");
+  host.style.position = "fixed";
+  host.style.left = "-20000px";
+  host.style.top = "0";
+  host.style.width = `${RESIDENT_VIEWPORT_WIDTH}px`;
+  host.style.height = `${RESIDENT_VIEWPORT_HEIGHT}px`;
+  host.style.overflow = "hidden";
+  host.style.opacity = "0";
+  host.style.pointerEvents = "none";
+  ownerDocument.body.appendChild(host);
+  return host;
+}
+
+function findBrowserWebview(browserId: string, ownerDocument: Document): HTMLElement | null {
+  for (const element of ownerDocument.querySelectorAll(`[${BROWSER_ID_ATTRIBUTE}]`)) {
+    if (element.getAttribute(BROWSER_ID_ATTRIBUTE) === browserId) {
+      return element as HTMLElement;
+    }
+  }
+  return null;
+}
+
+function applyResidentWebviewStyle(webview: HTMLElement): void {
+  webview.style.display = "block";
+  webview.style.width = `${RESIDENT_VIEWPORT_WIDTH}px`;
+  webview.style.height = `${RESIDENT_VIEWPORT_HEIGHT}px`;
+  webview.style.border = "0";
+  webview.style.background = "transparent";
+}
+
+export function prepareBrowserWebview(
+  webview: HTMLElement,
+  input: { browserId: string; initialUrl?: string | null },
+): void {
+  webview.setAttribute(BROWSER_ID_ATTRIBUTE, input.browserId);
+  webview.setAttribute("partition", `persist:paseo-browser-${input.browserId}`);
+  webview.setAttribute("allowpopups", "true");
+  webview.setAttribute("spellcheck", "false");
+  webview.setAttribute("autosize", "on");
+  if (input.initialUrl) {
+    (webview as BrowserWebviewElement).src = input.initialUrl;
+  }
+}
+
+export function ensureResidentBrowserWebview(input: {
+  browserId: string;
+  url: string;
+}): HTMLElement | null {
+  const browserId = trimNonEmpty(input.browserId);
+  if (!browserId) {
+    return null;
+  }
+  const ownerDocument = readDocument();
+  if (!ownerDocument) {
+    return null;
+  }
+
+  const resident = residentWebviewsByBrowserId.get(browserId) ?? null;
+  if (resident?.isConnected) {
+    return resident;
+  }
+
+  const existing = findBrowserWebview(browserId, ownerDocument);
+  if (existing) {
+    return existing;
+  }
+
+  const webview = ownerDocument.createElement("webview") as BrowserWebviewElement;
+  prepareBrowserWebview(webview, { browserId, initialUrl: input.url });
+  releaseResidentBrowserWebview(browserId, webview);
+  return webview;
+}
+
+export function takeResidentBrowserWebview(browserId: string): HTMLElement | null {
+  const normalizedBrowserId = trimNonEmpty(browserId);
+  if (!normalizedBrowserId) {
+    return null;
+  }
+
+  const webview = residentWebviewsByBrowserId.get(normalizedBrowserId) ?? null;
+  if (!webview) {
+    return null;
+  }
+
+  residentWebviewsByBrowserId.delete(normalizedBrowserId);
+  return webview;
+}
+
+export function releaseResidentBrowserWebview(browserId: string, webview: HTMLElement): void {
+  const normalizedBrowserId = trimNonEmpty(browserId);
+  if (!normalizedBrowserId) {
+    webview.remove();
+    return;
+  }
+  const ownerDocument = readDocument();
+  if (!ownerDocument) {
+    return;
+  }
+
+  residentWebviewsByBrowserId.set(normalizedBrowserId, webview);
+  applyResidentWebviewStyle(webview);
+  getResidentBrowserHost(ownerDocument).appendChild(webview);
+}
+
+export function removeResidentBrowserWebview(browserId: string): void {
+  const normalizedBrowserId = trimNonEmpty(browserId);
+  if (!normalizedBrowserId) {
+    return;
+  }
+
+  const resident = residentWebviewsByBrowserId.get(normalizedBrowserId) ?? null;
+  residentWebviewsByBrowserId.delete(normalizedBrowserId);
+  resident?.remove();
+}
+
+export function clearResidentBrowserWebviewsForTests(): void {
+  for (const webview of residentWebviewsByBrowserId.values()) {
+    webview.remove();
+  }
+  residentWebviewsByBrowserId.clear();
+  readDocument()?.getElementById(RESIDENT_BROWSER_HOST_ID)?.remove();
+}
@@ -1,5 +1,15 @@
 import { Platform } from "react-native";
 import { getElectronHost } from "@/desktop/electron/host";
+import type { SessionInboundMessage, SessionOutboundMessage } from "@getpaseo/protocol/messages";
+
+type BrowserAutomationExecuteRequest = Extract<
+  SessionOutboundMessage,
+  { type: "browser.automation.execute.request" }
+>;
+type BrowserAutomationExecuteResponse = Extract<
+  SessionInboundMessage,
+  { type: "browser.automation.execute.response" }
+>;

 export type DesktopNotificationPermission = "granted" | "denied" | "default";

@@ -117,9 +127,17 @@ export interface DesktopBrowserNewTabRequestEvent {
 }

 export interface DesktopBrowserBridge {
-  setWorkspaceActiveBrowser?: (browserId: string | null) => Promise<void>;
+  registerWorkspaceBrowser?: (input: { browserId: string; workspaceId: string }) => Promise<void>;
+  setWorkspaceActiveBrowser?: (input: {
+    workspaceId: string;
+    browserId: string | null;
+  }) => Promise<void>;
+  setAgentActiveBrowser?: (input: { agentId: string; browserId: string | null }) => Promise<void>;
  openDevTools?: (browserId: string) => Promise<unknown>;
  clearPartition?: (browserId: string) => Promise<void>;
+  executeAutomationCommand?: (
+    request: BrowserAutomationExecuteRequest,
+  ) => Promise<BrowserAutomationExecuteResponse["payload"]>;
 }

 export interface DesktopInvokeBridge {
@@ -1,4 +1,8 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.hoisted(() => {
+  Object.defineProperty(globalThis, "__DEV__", { value: false, configurable: true });
+});
 import type {
  DaemonClient,
  ConnectionState,
@@ -16,6 +20,10 @@ import {
  type HostRuntimeStorage,
 } from "./host-runtime";

+vi.mock("@/browser-automation/handler", () => ({
+  mountBrowserAutomationDaemonClientHandler: vi.fn(() => () => undefined),
+}));
+
 class FakeDaemonClient {
  private state: ConnectionState = { status: "idle" };
  private listeners = new Set<(status: ConnectionState) => void>();
@@ -342,6 +350,18 @@ function onceHostListMatches(store: HostRuntimeStore, predicate: () => boolean):
  });
 }

+class BrowserClientLifecycle {
+  public active: Array<{ serverId: string; connectionId: string }> = [];
+
+  mount(input: { host: HostProfile; connection: HostConnection }): () => void {
+    const entry = { serverId: input.host.serverId, connectionId: input.connection.id };
+    this.active.push(entry);
+    return () => {
+      this.active = this.active.filter((current) => current !== entry);
+    };
+  }
+}
+
 describe("HostRuntimeController", () => {
  it("replaces the active relay client when re-pairing changes the daemon public key", async () => {
    const oldRelay: HostConnection = {
@@ -458,6 +478,39 @@ describe("HostRuntimeController", () => {
    expect(controller.getSnapshot().connectionStatus).toBe("online");
  });

+  it("keeps browser client lifecycle tied to the active host runtime client", async () => {
+    const host = makeHost({ preferredConnectionId: "direct:lan:6767" });
+    const fakeClient = makeConnectedProbeClient(12);
+    const lifecycle = new BrowserClientLifecycle();
+    const controller = new HostRuntimeController({
+      host,
+      deps: {
+        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
+        connectToDaemon: async ({ host: hostProfile, connection }) => ({
+          client: makeConnectedProbeClient(10) as unknown as DaemonClient,
+          serverId: hostProfile.serverId,
+          hostname: connection.id,
+        }),
+        getClientId: async () => "cid_runtime_stable",
+        mountClientHandlers: (input) => lifecycle.mount(input),
+      },
+    });
+
+    await controller.start({
+      autoProbe: false,
+      initialConnection: {
+        connectionId: "direct:lan:6767",
+        existingClient: fakeClient as unknown as DaemonClient,
+      },
+    });
+
+    expect(lifecycle.active).toEqual([{ serverId: "srv_test", connectionId: "direct:lan:6767" }]);
+
+    await controller.stop();
+
+    expect(lifecycle.active).toEqual([]);
+  });
+
  it("adopts the first successful probe on startup", async () => {
    const host = makeHost({ preferredConnectionId: "direct:lan:6767" });
    const clients: FakeDaemonClient[] = [];
@@ -1431,7 +1484,7 @@ describe("HostRuntimeStore", () => {
        entries: [
          makeFetchAgentsEntry({
            id: "agent-recent",
-            cwd: "/Users/moboudra/dev/paseo",
+            cwd: "/workspaces/paseo",
            updatedAt: "2026-03-04T12:00:00.000Z",
            title: "Recent agent",
          }),
@@ -1444,7 +1497,7 @@ describe("HostRuntimeStore", () => {
        entries: [
          makeFetchAgentsEntry({
            id: "agent-stale-attention",
-            cwd: "/Users/moboudra/dev/paseo-pr67-review",
+            cwd: "/workspaces/paseo-pr67-review",
            updatedAt: "2026-02-20T08:00:00.000Z",
            title: "Needs triage",
            requiresAttention: true,
@@ -1612,7 +1665,7 @@ describe("HostRuntimeStore", () => {
    useSessionStore.getState().setAgents(host.serverId, () => {
      const stale = makeFetchAgentsEntry({
        id: "agent-archived",
-        cwd: "/Users/moboudra/dev/paseo",
+        cwd: "/workspaces/paseo",
        updatedAt: "2026-03-30T15:29:00.000Z",
        archivedAt: null,
        title: "Stale active copy",
@@ -37,6 +37,8 @@ import {
  buildLocalDaemonTransportUrl,
  createDesktopLocalDaemonTransportFactory,
 } from "@/desktop/daemon/desktop-daemon-transport";
+import { getDesktopHost } from "@/desktop/host";
+import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
 import { replaceFetchedAgentDirectory } from "@/utils/agent-directory-sync";
 import { useSessionStore } from "@/stores/session-store";
 import {
@@ -45,6 +47,7 @@ import {
 } from "@/workspace/legacy-daemon-workspaces";
 import { invalidateCheckoutGitQueriesForServer } from "@/git/query-keys";
 import { queryClient } from "@/query/query-client";
+import { mountBrowserAutomationDaemonClientHandler } from "@/browser-automation/handler";

 export type HostRuntimeConnectionStatus = "idle" | "connecting" | "online" | "offline" | "error";
 export type HostRegistryStatus = "loading" | "ready";
@@ -138,6 +141,11 @@ export interface HostRuntimeControllerDeps {
  }>;
  getClientId: () => Promise<string>;
  readInitialConnectionHint?: () => InitialDaemonConnectionHint | null;
+  mountClientHandlers?: (input: {
+    client: DaemonClient;
+    host: HostProfile;
+    connection: HostConnection;
+  }) => () => void;
 }

 export interface HostRuntimeStorage {
@@ -514,6 +522,12 @@ function probeIntervalForConnection(
 }

 function createDefaultDeps(): HostRuntimeControllerDeps {
+  const desktopBrowserAutomationAvailable =
+    typeof getDesktopHost()?.browser?.executeAutomationCommand === "function";
+  const browserAutomationCapabilities = desktopBrowserAutomationAvailable
+    ? { [CLIENT_CAPS.desktopBrowserAutomation]: true }
+    : undefined;
+
  return {
    createClient: ({ host, connection, clientId, runtimeGeneration }) => {
      const localTransportFactory = createDesktopLocalDaemonTransportFactory();
@@ -523,6 +537,7 @@ function createDefaultDeps(): HostRuntimeControllerDeps {
        clientType: "mobile" as const,
        appVersion: resolveAppVersion() ?? undefined,
        runtimeGeneration,
+        ...(browserAutomationCapabilities ? { capabilities: browserAutomationCapabilities } : {}),
      };
      if (connection.type === "directSocket" || connection.type === "directPipe") {
        return new DaemonClient({
@@ -560,8 +575,15 @@ function createDefaultDeps(): HostRuntimeControllerDeps {
      connectToDaemon(connection, {
        ...(host.serverId ? { serverId: host.serverId } : {}),
        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(browserAutomationCapabilities ? { capabilities: browserAutomationCapabilities } : {}),
      }),
    getClientId: () => getOrCreateClientId(),
+    mountClientHandlers: ({ client, host }) => {
+      if (!browserAutomationCapabilities) {
+        return () => {};
+      }
+      return mountBrowserAutomationDaemonClientHandler(client, { serverId: host.serverId });
+    },
  };
 }

@@ -574,6 +596,7 @@ export class HostRuntimeController {
  private listeners = new Set<() => void>();
  private activeClient: DaemonClient | null = null;
  private unsubscribeClientStatus: (() => void) | null = null;
+  private unsubscribeClientHandlers: (() => void) | null = null;
  private probeIntervalHandle: ReturnType<typeof setInterval> | null = null;
  private started = false;
  private connectionFirstSeenAt = new Map<string, number>();
@@ -656,6 +679,10 @@ export class HostRuntimeController {
      this.unsubscribeClientStatus();
      this.unsubscribeClientStatus = null;
    }
+    if (this.unsubscribeClientHandlers) {
+      this.unsubscribeClientHandlers();
+      this.unsubscribeClientHandlers = null;
+    }
    if (this.activeClient) {
      const prev = this.activeClient;
      this.activeClient = null;
@@ -1133,6 +1160,10 @@ export class HostRuntimeController {
      this.unsubscribeClientStatus();
      this.unsubscribeClientStatus = null;
    }
+    if (this.unsubscribeClientHandlers) {
+      this.unsubscribeClientHandlers();
+      this.unsubscribeClientHandlers = null;
+    }
    if (this.activeClient) {
      const previousClient = this.activeClient;
      this.activeClient = null;
@@ -1206,6 +1237,8 @@ export class HostRuntimeController {
    }

    this.activeClient = client;
+    this.unsubscribeClientHandlers =
+      this.deps.mountClientHandlers?.({ client, host: this.host, connection }) ?? null;
    this.applyConnectionEvent({
      type: "select_connection",
      connectionId: connection.id,
@@ -0,0 +1,70 @@
+import React, { useCallback } from "react";
+import { Text, View } from "react-native";
+import { useMutation } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { Switch } from "@/components/ui/switch";
+import { useDaemonConfig } from "@/hooks/use-daemon-config";
+import { useHostRuntimeIsConnected } from "@/runtime/host-runtime";
+import { settingsStyles } from "@/styles/settings";
+import {
+  createBrowserToolsPatch,
+  getBrowserToolsCardState,
+  getBrowserToolsMutationViewState,
+} from "./browser-tools-config";
+
+export function BrowserToolsOptInCard({ serverId }: { serverId: string }) {
+  const { t } = useTranslation();
+  const isConnected = useHostRuntimeIsConnected(serverId);
+  const { config, patchConfig } = useDaemonConfig(serverId);
+  const state = getBrowserToolsCardState({ isConnected, config });
+  const mutation = useMutation({
+    mutationFn: async (next: boolean) => {
+      const result = await patchConfig(createBrowserToolsPatch(next));
+      if (!result) {
+        throw new Error(t("workspace.terminal.hostDisconnected"));
+      }
+      return result;
+    },
+  });
+  const mutationView = getBrowserToolsMutationViewState({
+    isPending: mutation.isPending,
+    error: mutation.error,
+  });
+
+  const handleValueChange = useCallback(
+    (next: boolean) => {
+      mutation.mutate(next);
+    },
+    [mutation],
+  );
+
+  if (!state.isVisible) return null;
+
+  return (
+    <View style={settingsStyles.card} testID="host-page-browser-tools-card">
+      <View style={settingsStyles.row}>
+        <View style={settingsStyles.rowContent}>
+          <Text style={settingsStyles.rowTitle}>{state.title}</Text>
+          <Text style={settingsStyles.rowHint}>{state.warning}</Text>
+          {mutationView.loadingText ? (
+            <Text style={settingsStyles.rowHint} testID="host-page-browser-tools-loading">
+              {mutationView.loadingText}
+            </Text>
+          ) : null}
+          {mutationView.errorText ? (
+            <Text style={settingsStyles.rowError} testID="host-page-browser-tools-error">
+              {mutationView.errorText}
+            </Text>
+          ) : null}
+        </View>
+        <Switch
+          value={state.isEnabled}
+          onValueChange={handleValueChange}
+          disabled={mutationView.isSwitchDisabled}
+          accessibilityLabel="Enable browser tools"
+          testID="host-page-browser-tools-switch"
+        />
+      </View>
+    </View>
+  );
+}
@@ -0,0 +1,70 @@
+import type { MutableDaemonConfig } from "@getpaseo/protocol/messages";
+import { describe, expect, it } from "vitest";
+import {
+  BROWSER_TOOLS_WARNING,
+  createBrowserToolsPatch,
+  getBrowserToolsCardState,
+  getBrowserToolsMutationViewState,
+} from "./browser-tools-config";
+
+function makeConfig(browserToolsEnabled = false): MutableDaemonConfig {
+  return {
+    mcp: { injectIntoAgents: false },
+    browserTools: { enabled: browserToolsEnabled },
+    providers: {},
+    metadataGeneration: { providers: [] },
+    autoArchiveAfterMerge: false,
+    enableTerminalAgentHooks: false,
+    appendSystemPrompt: "",
+  };
+}
+
+describe("browser tools opt-in config", () => {
+  it("shows the card with the logged-in browser state warning when connected", () => {
+    expect(getBrowserToolsCardState({ isConnected: true, config: makeConfig(false) })).toEqual({
+      isVisible: true,
+      isEnabled: false,
+      title: "Browser tools",
+      warning: BROWSER_TOOLS_WARNING,
+    });
+  });
+
+  it("reads enabled state from daemon config", () => {
+    expect(getBrowserToolsCardState({ isConnected: true, config: makeConfig(true) })).toMatchObject(
+      {
+        isEnabled: true,
+      },
+    );
+  });
+
+  it("hides the card when the host is disconnected", () => {
+    expect(
+      getBrowserToolsCardState({ isConnected: false, config: makeConfig(true) }),
+    ).toMatchObject({
+      isVisible: false,
+    });
+  });
+
+  it("writes daemon.browserTools.enabled when toggled", () => {
+    expect(createBrowserToolsPatch(true)).toEqual({ browserTools: { enabled: true } });
+    expect(createBrowserToolsPatch(false)).toEqual({ browserTools: { enabled: false } });
+  });
+
+  it("shows loading and disables the toggle while browser tool settings save", () => {
+    expect(getBrowserToolsMutationViewState({ isPending: true, error: null })).toEqual({
+      isSwitchDisabled: true,
+      loadingText: "Updating browser tools…",
+      errorText: null,
+    });
+  });
+
+  it("shows the save error when browser tool settings fail", () => {
+    expect(
+      getBrowserToolsMutationViewState({ isPending: false, error: new Error("Disk full") }),
+    ).toEqual({
+      isSwitchDisabled: false,
+      loadingText: null,
+      errorText: "Disk full",
+    });
+  });
+});
@@ -0,0 +1,49 @@
+import type { MutableDaemonConfig } from "@getpaseo/protocol/messages";
+
+export const BROWSER_TOOLS_TITLE = "Browser tools";
+export const BROWSER_TOOLS_WARNING =
+  "Allow agents to access and control Paseo desktop browser tabs, including logged-in browser state. Only enable this for agents you trust.";
+
+export interface BrowserToolsCardState {
+  isVisible: boolean;
+  isEnabled: boolean;
+  title: string;
+  warning: string;
+}
+
+export interface BrowserToolsMutationViewState {
+  isSwitchDisabled: boolean;
+  loadingText: string | null;
+  errorText: string | null;
+}
+
+export function getBrowserToolsCardState(input: {
+  isConnected: boolean;
+  config: MutableDaemonConfig | null;
+}): BrowserToolsCardState {
+  return {
+    isVisible: input.isConnected,
+    isEnabled: input.config?.browserTools.enabled === true,
+    title: BROWSER_TOOLS_TITLE,
+    warning: BROWSER_TOOLS_WARNING,
+  };
+}
+
+export function createBrowserToolsPatch(enabled: boolean): Partial<MutableDaemonConfig> {
+  return { browserTools: { enabled } };
+}
+
+export function getBrowserToolsMutationViewState(input: {
+  isPending: boolean;
+  error: unknown;
+}): BrowserToolsMutationViewState {
+  return {
+    isSwitchDisabled: input.isPending,
+    loadingText: input.isPending ? "Updating browser tools…" : null,
+    errorText: input.error ? toErrorMessage(input.error) : null,
+  };
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
@@ -61,6 +61,7 @@ import { formatLatency } from "@/utils/latency";
 import { ICON_SIZE } from "@/styles/theme";
 import type { Theme } from "@/styles/theme";
 import { getProviderIcon } from "@/components/provider-icons";
+import { BrowserToolsOptInCard } from "./browser-tools-card";

 const ThemedArrowUp = withUnistyles(ArrowUp);
 const ThemedArrowDown = withUnistyles(ArrowDown);
@@ -262,6 +263,7 @@ export function HostAgentsPage({ serverId }: { serverId: string }) {
      {isConnected ? (
        <SettingsSection title={t("settings.hostSections.agents")}>
          <InjectPaseoToolsCard serverId={serverId} />
+          <BrowserToolsOptInCard serverId={serverId} />
          <AppendSystemPromptCard serverId={serverId} />
        </SettingsSection>
      ) : (
@@ -220,6 +220,7 @@ const disabledCodexEntry: ProviderSnapshotEntry = {
 function makeConfig(providers: MutableDaemonConfig["providers"] = {}): MutableDaemonConfig {
  return {
    mcp: { injectIntoAgents: false },
+    browserTools: { enabled: false },
    providers,
    metadataGeneration: { providers: [] },
    autoArchiveAfterMerge: false,
@@ -105,6 +105,7 @@ import type { CheckoutStatusPayload } from "@/git/use-status-query";
 import { confirmDialog } from "@/utils/confirm-dialog";
 import { useArchiveAgent } from "@/hooks/use-archive-agent";
 import { useStableEvent } from "@/hooks/use-stable-event";
+import { removeResidentBrowserWebview } from "@/components/browser-webview-resident";
 import { createWorkspaceBrowser, useBrowserStore } from "@/stores/browser-store";
 import { getDesktopHost } from "@/desktop/host";
 import { buildProviderCommand } from "@/utils/provider-command-templates";
@@ -304,19 +305,22 @@ function decodeSegment(value: string): string {
 function useSyncWorkspaceActiveBrowser(input: {
  workspaceLayout: WorkspaceLayout | null;
  isRouteFocused: boolean;
+  workspaceId: string;
 }) {
  const focusedBrowserId = useMemo(
    () => getFocusedBrowserId(input.workspaceLayout),
    [input.workspaceLayout],
  );
-  const desktopActiveBrowserId = input.isRouteFocused ? focusedBrowserId : null;

  useEffect(() => {
    if (!getIsElectron()) {
      return;
    }
-    void getDesktopHost()?.browser?.setWorkspaceActiveBrowser?.(desktopActiveBrowserId);
-  }, [desktopActiveBrowserId]);
+    void getDesktopHost()?.browser?.setWorkspaceActiveBrowser?.({
+      workspaceId: input.workspaceId,
+      browserId: focusedBrowserId,
+    });
+  }, [focusedBrowserId, input.workspaceId]);
 }

 function getFallbackTabOptionLabel(
@@ -1876,7 +1880,11 @@ function WorkspaceScreenContent({
    () => (workspaceLayout ? collectAllTabs(workspaceLayout.root) : EMPTY_UI_TABS),
    [workspaceLayout],
  );
-  useSyncWorkspaceActiveBrowser({ workspaceLayout, isRouteFocused });
+  useSyncWorkspaceActiveBrowser({
+    workspaceLayout,
+    isRouteFocused,
+    workspaceId: normalizedWorkspaceId,
+  });
  const openWorkspaceTabInBackground = useWorkspaceLayoutStore(
    (state) => state.openTabInBackground,
  );
@@ -1921,6 +1929,7 @@ function WorkspaceScreenContent({
      if (input.target?.kind === "browser") {
        const { browserId } = input.target;
        useBrowserStore.getState().removeBrowser(browserId);
+        removeResidentBrowserWebview(browserId);
        void getDesktopHost()?.browser?.clearPartition?.(browserId);
      }
      closeWorkspaceTab(persistenceKey, normalizedTabId);
@@ -63,4 +63,9 @@ export const settingsStyles = StyleSheet.create((theme) => ({
    fontSize: theme.fontSize.xs,
    marginTop: theme.spacing[1],
  },
+  rowError: {
+    color: theme.colors.statusDanger,
+    fontSize: theme.fontSize.xs,
+    marginTop: theme.spacing[1],
+  },
 }));
@@ -25,7 +25,7 @@ describe("assistant image metadata", () => {
    setAssistantImageMetadata(
      {
        source: "/tmp/paseo-codex-screenshot.png",
-        workspaceRoot: "/Users/moboudra/dev/paseo",
+        workspaceRoot: "/workspaces/paseo",
        serverId: "server-1",
      },
      { width: 1200, height: 800 },
@@ -5,28 +5,28 @@ describe("buildAbsoluteExplorerPath", () => {
  it("builds a POSIX absolute path from a relative explorer path", () => {
    expect(
      buildAbsoluteExplorerPath({
-        workspaceRoot: "/Users/moboudra/dev/paseo",
+        workspaceRoot: "/workspaces/paseo",
        entryPath: "packages/app/src/components/file-explorer-pane.tsx",
      }),
-    ).toBe("/Users/moboudra/dev/paseo/packages/app/src/components/file-explorer-pane.tsx");
+    ).toBe("/workspaces/paseo/packages/app/src/components/file-explorer-pane.tsx");
  });

  it("returns workspace root when entry path points to explorer root", () => {
    expect(
      buildAbsoluteExplorerPath({
-        workspaceRoot: "/Users/moboudra/dev/paseo",
+        workspaceRoot: "/workspaces/paseo",
        entryPath: ".",
      }),
-    ).toBe("/Users/moboudra/dev/paseo");
+    ).toBe("/workspaces/paseo");
  });

  it("trims trailing separators from workspace root before joining", () => {
    expect(
      buildAbsoluteExplorerPath({
-        workspaceRoot: "/Users/moboudra/dev/paseo/",
+        workspaceRoot: "/workspaces/paseo/",
        entryPath: "README.md",
      }),
-    ).toBe("/Users/moboudra/dev/paseo/README.md");
+    ).toBe("/workspaces/paseo/README.md");
  });

  it("builds a Windows absolute path with backslash separators", () => {
@@ -41,7 +41,7 @@ describe("buildAbsoluteExplorerPath", () => {
  it("passes through an already-absolute entry path", () => {
    expect(
      buildAbsoluteExplorerPath({
-        workspaceRoot: "/Users/moboudra/dev/paseo",
+        workspaceRoot: "/workspaces/paseo",
        entryPath: "/tmp/another/location.txt",
      }),
    ).toBe("/tmp/another/location.txt");
@@ -45,8 +45,8 @@ describe("workspace route parsing", () => {
  });

  it("decodes non-canonical base64url workspace IDs used by older links", () => {
-    expect(decodeWorkspaceIdFromPathSegment("L1VzZXJzL21vYm91ZHJhL2Rldi9wYXNlby")).toBe(
-      "/Users/moboudra/dev/paseo",
+    expect(decodeWorkspaceIdFromPathSegment("L2hvbWUvdXNlci9kZXYvcGFzZW8")).toBe(
+      "/home/user/dev/paseo",
    );
  });

@@ -97,6 +97,7 @@ export class DaemonConnectionTestError extends Error {
 export async function buildClientConfig(
  connection: HostConnection,
  serverId?: string,
+  options?: { capabilities?: DaemonClientConfig["capabilities"] },
  deps: Pick<
    DaemonConnectionDependencies<DaemonProbeClient>,
    "getClientId" | "resolveAppVersion" | "createLocalTransportFactory" | "buildLocalTransportUrl"
@@ -110,6 +111,7 @@ export async function buildClientConfig(
    appVersion: deps.resolveAppVersion() ?? undefined,
    suppressSendErrors: true,
    reconnect: { enabled: false },
+    ...(options?.capabilities ? { capabilities: options.capabilities } : {}),
    ...((connection.type === "directSocket" || connection.type === "directPipe") &&
    localTransportFactory
      ? { transportFactory: localTransportFactory }
@@ -221,6 +223,7 @@ export function connectAndProbe(
 interface ProbeOptions {
  serverId?: string;
  timeoutMs?: number;
+  capabilities?: DaemonClientConfig["capabilities"];
 }

 function resolveTimeout(connection: HostConnection, options?: ProbeOptions): number {
@@ -242,6 +245,6 @@ export async function connectToDaemon(
  options?: ProbeOptions,
  deps: DaemonConnectionDependencies<DaemonProbeClient> = defaultDaemonConnectionDependencies,
 ): Promise<{ client: DaemonProbeClient; serverId: string; hostname: string | null }> {
-  const config = await buildClientConfig(connection, options?.serverId, deps);
+  const config = await buildClientConfig(connection, options?.serverId, options, deps);
  return connectAndProbe(config, resolveTimeout(connection, options), deps);
 }