@omercnet/paseo-shared-browser 0.4.2 → 1.0.0

package/README.md

@@ -72,24 +72,10 @@ paseo plugin install npm:@omercnet/paseo-shared-browser
 paseo plugin ls
 ```
 
-Or install from Git:
-
-```bash
-paseo plugin add omercnet/paseo-plugins:paseo-shared-browser
-paseo plugin ls
-```
-
-Installation runs `npm ci --include=dev` and `npm run prepare:runtime` on the daemon host. The
-preparation step installs the pinned browser runtime and builds both `supervisor.cjs` and
+When Paseo acquires the npm package, it runs the `npm run prepare:runtime` build hook automatically. The
+hook installs the pinned browser runtime and builds both `supervisor.cjs` and
 `shared-browser-mcp.cjs` under
-`$PASEO_HOME/plugin-data/shared-browser/runtime`. For a local monorepo checkout:
-
-```bash
-cd paseo-plugins/paseo-shared-browser
-npm ci --include=dev
-npm run prepare:runtime
-paseo plugin install "$PWD"
-```
+`$PASEO_HOME/plugin-data/shared-browser/runtime`.
 
 The build requires Node.js 24 or newer and npm on the daemon host. On Linux x64, macOS, and
 Windows, runtime preparation installs and stages the platform's Chrome for Testing distribution. On
@@ -162,9 +148,9 @@ User-supplied `AGENT_BROWSER_*` variables are deliberately ignored.
   isolation boundary between local OS users.
 - `agent-browser` IPC metadata and workspace profile directories are owner-only on POSIX systems.
   The plugin rejects a non-loopback CDP endpoint.
-- Viewer and control tokens coordinate clients already paired to the same Paseo daemon. Paseo v0.8
-  plugin RPC callbacks expose no authenticated caller identity, so these human-viewer tokens are a
-  workflow safeguard, not an authorization boundary. The stdio MCP adapter separately uses an
+- Viewer and control tokens coordinate clients already paired to the same Paseo daemon. Plugin RPC
+  callbacks expose no authenticated caller identity, so these human-viewer tokens are a workflow
+  safeguard, not an authorization boundary. The stdio MCP adapter separately uses an
   opaque, workspace-bound credential.
 - Downloads, uploads, clipboard synchronization, media permissions, extensions, native passkeys,
   and platform authenticators are not exposed by this plugin.
@@ -175,23 +161,20 @@ User-supplied `AGENT_BROWSER_*` variables are deliberately ignored.
 ## Develop
 
 ```bash
-npm ci
-npm run typecheck
-npm run lint
-npm run format:check
-npm run test:unit
-npm run prepare:runtime
-paseo plugin install "$PWD"
-paseo plugin reload shared-browser
+bun install
+bun run typecheck
+bun run lint
+bun run format:check
+bun run test:unit
+bun run prepare:runtime
 ```
 
-`npm run test:smoke` launches the configured real Chromium runtime and exercises two viewers,
+`bun run test:smoke` launches the configured real Chromium runtime and exercises two viewers,
 control handoff, reconnect, stale-frame rejection, viewport changes, device emulation, profile
 persistence, and archive teardown.
 
 Release Please maintains the version, changelog, component tag, and GitHub release from
 Conventional Commits in the monorepo.
 
-Both the Paseo daemon and app must satisfy `^0.8.0 || ^0.9.0-beta.1`, which supports Paseo 0.8
-and the Paseo 0.9 beta line. The client surface uses React Native primitives and works in desktop,
-web, iOS, and Android Paseo clients.
+Both the Paseo daemon and app must satisfy `^0.9.0`. The client surface uses React Native primitives
+and works in desktop, web, iOS, and Android Paseo clients.

package/client/browser.tsx

@@ -1,46 +1,46 @@
-import { useMutation, useQuery } from "@tanstack/react-query";
 import {
   type PluginClientContext,
   type PluginWorkspacePanelProps,
   useRpc,
 } from "@getpaseo/plugin/client";
 import { Icon, Modal, ScrollView, TextInput } from "@getpaseo/plugin/client/react-native";
-import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   ActivityIndicator,
+  type GestureResponderEvent,
   Image,
+  type LayoutChangeEvent,
   PanResponder,
   Pressable,
+  type StyleProp,
   StyleSheet,
   Text,
-  View,
-  type GestureResponderEvent,
-  type LayoutChangeEvent,
-  type StyleProp,
   type TextInputProps,
   type TextStyle,
+  View,
   type ViewStyle,
 } from "react-native";
 import {
-  DEVICE_PRESETS,
-  MAX_VIEWPORT,
-  MIN_VIEWPORT,
   acquireControlRpc,
   applyDevicePresetRpc,
   attachBrowserRpc,
+  type BrowserFrame,
+  type BrowserInputEvent,
+  type BrowserState,
   captureBrowserRpc,
+  DEVICE_PRESETS,
+  type DevicePresetId,
   detachBrowserRpc,
+  didBrowserRuntimeRestart,
+  isBrowserStateCurrent,
   listOpenBrowserWorkspacesRpc,
+  MAX_VIEWPORT,
+  MIN_VIEWPORT,
   navigateBrowserRpc,
   releaseControlRpc,
   resizeBrowserRpc,
   sendBrowserInputRpc,
-  didBrowserRuntimeRestart,
-  isBrowserStateCurrent,
-  type BrowserFrame,
-  type BrowserInputEvent,
-  type BrowserState,
-  type DevicePresetId,
 } from "../shared/browser";
 
 const SPACE = {
@@ -72,6 +72,7 @@ const CAPTURE_INTERVAL_READY = 250;
 const CAPTURE_INTERVAL_WAITING = 1_500;
 const MAX_VIEWER_LABEL_LENGTH = 64;
 const PILL_PRESENCE_POLL_MS = 2_000;
+const AGENT_DIRECTORY_PAGE_LIMIT = 200;
 const MAX_URL_LENGTH = 8_192;
 const MAX_TEXT_LENGTH = 4_000;
 const BYTES_PER_KIBIBYTE = 1_024;
@@ -803,18 +804,33 @@ function CanvasPlaceholder({
   );
 }
 
+interface AgentDirectoryPage {
+  entries: Array<{ agent: { id: string; workspaceId?: string | undefined } }>;
+  pageInfo: { hasMore: boolean; nextCursor: string | null };
+}
+
+type AgentDirectoryUpdate =
+  | { kind: "remove"; agentId: string }
+  | { kind: "upsert"; agent: { id: string; workspaceId?: string | undefined } };
+type AgentPlacement = { id: string; workspaceId: string };
+
 export function contributeSharedBrowserClient(client: PluginClientContext) {
-  const agents = new Map<string, { id: string; workspaceId: string }>();
+  const agents = new Map<string, AgentPlacement>();
   const pills = new Map<string, { workspaceId: string; remove: () => void }>();
+  const lifetime = new AbortController();
   let openWorkspaceIds = new Set<string>();
   let refreshing = false;
   let stopped = false;
+  let directoryGeneration = 0;
+  let pendingDirectory: { generation: number; updates: AgentDirectoryUpdate[] } | null = null;
+  let unsubscribeDirectory: (() => void) | null = null;
+  let releaseDirectory: (() => Promise<void>) | null = null;
 
   const removePill = (agentId: string) => {
     pills.get(agentId)?.remove();
     pills.delete(agentId);
   };
-  const syncPill = (agent: { id: string; workspaceId: string }) => {
+  const syncPill = (agent: AgentPlacement) => {
     const current = pills.get(agent.id);
     if (!openWorkspaceIds.has(agent.workspaceId)) {
       removePill(agent.id);
@@ -858,32 +874,94 @@ export function contributeSharedBrowserClient(client: PluginClientContext) {
       refreshing = false;
     }
   };
-
-  const unsubscribe = client.paseo.agents.subscribe((update) => {
+  const applyUpdate = (target: Map<string, AgentPlacement>, update: AgentDirectoryUpdate) => {
+    if (update.kind === "remove") {
+      target.delete(update.agentId);
+      return;
+    }
+    const { id, workspaceId } = update.agent;
+    if (workspaceId) target.set(id, { id, workspaceId });
+    else target.delete(id);
+  };
+  const applyLiveUpdate = (update: AgentDirectoryUpdate) => {
+    if (stopped) return;
+    pendingDirectory?.updates.push(update);
+    applyUpdate(agents, update);
     if (update.kind === "remove") {
-      agents.delete(update.agentId);
       removePill(update.agentId);
       return;
     }
     const { id, workspaceId } = update.agent;
     if (!workspaceId) {
-      agents.delete(id);
       removePill(id);
       return;
     }
-    const agent = { id, workspaceId };
-    agents.set(id, agent);
-    syncPill(agent);
+    syncPill({ id, workspaceId });
     void refreshPresence();
-  });
-  void client.paseo.agents
-    .list()
-    .then(async ({ entries }) => {
-      for (const { agent } of entries) {
-        if (agent.workspaceId)
-          agents.set(agent.id, { id: agent.id, workspaceId: agent.workspaceId });
+  };
+  const replaceAgents = (next: Map<string, AgentPlacement>) => {
+    for (const agentId of agents.keys()) {
+      if (!next.has(agentId)) removePill(agentId);
+    }
+    agents.clear();
+    for (const [agentId, agent] of next) agents.set(agentId, agent);
+    syncAllPills();
+  };
+  const followSnapshot = async (snapshot: AgentDirectoryPage) => {
+    if (stopped) return;
+    const generation = ++directoryGeneration;
+    const transaction = { generation, updates: [] as AgentDirectoryUpdate[] };
+    pendingDirectory = transaction;
+    const next = new Map<string, AgentPlacement>();
+    for (const { agent } of snapshot.entries) {
+      if (agent.workspaceId) next.set(agent.id, { id: agent.id, workspaceId: agent.workspaceId });
+    }
+
+    try {
+      let cursor = snapshot.pageInfo.hasMore ? snapshot.pageInfo.nextCursor : null;
+      while (cursor) {
+        const page = await client.paseo.agents.list({
+          scope: "active",
+          page: { limit: AGENT_DIRECTORY_PAGE_LIMIT, cursor },
+          signal: lifetime.signal,
+        });
+        if (stopped || pendingDirectory?.generation !== generation) return;
+        for (const { agent } of page.entries) {
+          if (agent.workspaceId)
+            next.set(agent.id, { id: agent.id, workspaceId: agent.workspaceId });
+        }
+        cursor = page.pageInfo.hasMore ? page.pageInfo.nextCursor : null;
       }
+      if (stopped || pendingDirectory?.generation !== generation) return;
+      for (const update of transaction.updates) applyUpdate(next, update);
+      pendingDirectory = null;
+      replaceAgents(next);
       await refreshPresence();
+    } catch {
+      if (!stopped && pendingDirectory?.generation === generation) pendingDirectory = null;
+    }
+  };
+
+  void client.paseo.agents
+    .list({
+      scope: "active",
+      page: { limit: AGENT_DIRECTORY_PAGE_LIMIT },
+      subscribe: {},
+      signal: lifetime.signal,
+    })
+    .then(({ subscription }) => {
+      if (stopped) {
+        void subscription.release().catch(() => undefined);
+        return undefined;
+      }
+      releaseDirectory = subscription.release;
+      unsubscribeDirectory = subscription.subscribe({
+        snapshot: (snapshot) => void followSnapshot(snapshot),
+        update: (message) => {
+          if (message.type === "agent_update") applyLiveUpdate(message.payload);
+        },
+      });
+      return undefined;
     })
     .catch(() => undefined);
   const presenceTimer = setInterval(() => void refreshPresence(), PILL_PRESENCE_POLL_MS);
@@ -891,8 +969,12 @@ export function contributeSharedBrowserClient(client: PluginClientContext) {
   return () => {
     if (stopped) return;
     stopped = true;
+    directoryGeneration += 1;
+    pendingDirectory = null;
     clearInterval(presenceTimer);
-    unsubscribe();
+    unsubscribeDirectory?.();
+    void releaseDirectory?.().catch(() => undefined);
+    lifetime.abort();
     for (const { remove } of pills.values()) remove();
     pills.clear();
     agents.clear();

package/index.client.tsx

@@ -1,5 +1,5 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
-import { SharedBrowserPanel, contributeSharedBrowserClient } from "./client/browser";
+import { contributeSharedBrowserClient, SharedBrowserPanel } from "./client/browser";
 
 export default function contribute(client: PluginClientContext) {
   client.addWorkspacePanel({

package/index.server.ts

@@ -1,7 +1,7 @@
-import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
 import {
   bindAgentTicket,
   cleanupBrowserServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-shared-browser",
-  "version": "0.4.2",
+  "version": "1.0.0",
   "description": "One real Chromium session per Paseo workspace, shared live across every connected client.",
   "keywords": [
     "browser",
@@ -38,37 +38,35 @@
     "access": "public"
   },
   "scripts": {
+    "check": "biome check .",
+    "check:write": "biome check --write .",
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint --deny-warnings .",
-    "format": "oxfmt --ignore-path .formatignore .",
-    "format:check": "oxfmt --check --ignore-path .formatignore .",
     "prepare:runtime": "node scripts/prepare-runtime.mjs",
-    "test:unit": "node --test scripts/prepare-dependencies.test.mjs && vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts",
+    "test": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts",
+    "test:unit": "vitest run tests/contracts.test.ts tests/lease.test.ts tests/runtime-lifecycle.test.ts tests/agent-access.test.ts tests/composer-pills.test.ts",
     "test:smoke": "vitest run tests/browser.smoke.test.ts --testTimeout=30000"
   },
   "dependencies": {
-    "@getpaseo/plugin": "0.8.0",
+    "@getpaseo/plugin": "0.9.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "agent-browser": "0.37.1",
     "esbuild": "0.28.2",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@getpaseo/plugin": "0.9.0-beta.1",
-    "@tanstack/react-query": "^5.90.11",
-    "@types/node": "^22.0.0",
-    "@types/react": "~19.2.0",
-    "oxfmt": "0.66.0",
-    "oxlint": "1.81.0",
+    "@biomejs/biome": "^2.5.10",
+    "@tanstack/react-query": "^5.102.3",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.18",
     "react": "19.1.0",
     "react-native": "0.81.5",
-    "typescript": "^7.0.0",
+    "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=24"
   },
-  "packageManager": "npm@11.19.1",
+  "packageManager": "bun@1.4.2",
   "allowScripts": {
     "agent-browser": true,
     "esbuild@0.28.2": true

package/paseo-plugin.json

@@ -1,10 +1,6 @@
 {
   "id": "shared-browser",
-  "requirements": {
-    "paseo": "^0.8.0 || ^0.9.0-beta.1"
-  },
-  "build": [
-    ["node", "scripts/prepare-dependencies.mjs"],
-    ["npm", "run", "prepare:runtime"]
-  ]
+  "description": "One real Chromium session per Paseo workspace, shared live across every connected client.",
+  "requirements": { "paseo": "^0.9.0" },
+  "build": [["node", "scripts/prepare-dependencies.mjs"], ["npm", "run", "prepare:runtime"]]
 }

package/scripts/prepare-dependencies.mjs

@@ -1,21 +1,58 @@
-import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 
+function loadRootCatalog(root) {
+  for (let directory = root; ; directory = dirname(directory)) {
+    const manifestPath = join(directory, "package.json");
+    if (existsSync(manifestPath)) {
+      const catalog = JSON.parse(readFileSync(manifestPath, "utf8")).catalog;
+      if (catalog) return catalog;
+    }
+    if (directory === dirname(directory)) return null;
+  }
+}
+
+function stageManifest(root, catalog, install) {
+  const manifestPath = join(root, "package.json");
+  const source = readFileSync(manifestPath, "utf8");
+  const manifest = JSON.parse(source);
+
+  for (const [name, spec] of Object.entries(manifest.dependencies)) {
+    if (spec !== "catalog:") continue;
+    if (typeof catalog[name] !== "string") throw new Error(`Missing catalog entry for ${name}`);
+    manifest.dependencies[name] = catalog[name];
+  }
+  delete manifest.devDependencies;
+
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  try {
+    install();
+  } finally {
+    writeFileSync(manifestPath, source);
+  }
+}
+
 export function resolveDependencyRoot(packageName, from = import.meta.url) {
-  const require = createRequire(from);
-  return dirname(require.resolve(`${packageName}/package.json`));
+  return dirname(createRequire(from).resolve(`${packageName}/package.json`));
 }
-export function prepareDependencies(root = projectRoot, execute = execFileSync) {
-  if (!existsSync(join(root, "package-lock.json"))) return false;
 
-  execute(process.platform === "win32" ? "npm.cmd" : "npm", ["ci", "--include=dev"], {
-    cwd: root,
-    stdio: "inherit",
+export function prepareDependencies(root = projectRoot, execute = execFileSync) {
+  const catalog = loadRootCatalog(root);
+  if (!catalog) return false;
+  stageManifest(root, catalog, () => {
+    execute(
+      process.platform === "win32" ? "npm.cmd" : "npm",
+      ["install", "--omit=dev", "--ignore-scripts", "--no-package-lock", "--workspaces=false"],
+      {
+        cwd: root,
+        stdio: "inherit",
+      },
+    );
   });
   return true;
 }

package/scripts/prepare-runtime.mjs

@@ -1,6 +1,5 @@
-import { resolveDependencyRoot } from "./prepare-dependencies.mjs";
-import { build } from "esbuild";
 import { execFile } from "node:child_process";
+import { constants } from "node:fs";
 import {
   access,
   chmod,
@@ -13,11 +12,19 @@ import {
   symlink,
   writeFile,
 } from "node:fs/promises";
-import { constants } from "node:fs";
+import { createRequire } from "node:module";
 import { arch, homedir, platform, userInfo } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { build } from "esbuild";
+
+const require = createRequire(import.meta.url);
+
+function resolveDependencyRoot(packageName) {
+  const packageJsonPath = require.resolve(`${packageName}/package.json`);
+  return dirname(packageJsonPath);
+}
 
 const execFileAsync = promisify(execFile);
 const expectedVersion = "0.37.1";
@@ -54,7 +61,9 @@ async function requireExecutable(path, label) {
 }
 
 async function validateAgentBrowser(path) {
-  const { stdout } = await execFileAsync(path, ["--version"], { encoding: "utf8" });
+  const { stdout } = await execFileAsync(path, ["--version"], {
+    encoding: "utf8",
+  });
   const version = stdout.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)?.[0];
   if (version !== expectedVersion) {
     throw new Error(`Expected agent-browser ${expectedVersion}, received ${version ?? "unknown"}`);
@@ -185,7 +194,10 @@ async function installChromium() {
   if (!releaseDir) throw new Error("agent-browser install did not produce a Chromium release");
   const chrome = installedChromiumExecutable(releaseDir);
   await requireExecutable(chrome, "Installed Chromium executable");
-  await cp(releaseDir, join(stagingRoot, "chromium"), { recursive: true, force: true });
+  await cp(releaseDir, join(stagingRoot, "chromium"), {
+    recursive: true,
+    force: true,
+  });
   if (hostPlatform === "darwin") {
     // chrome can't be a symlink to the .app's real binary here: macOS dyld
     // resolves @executable_path from the invoked path's own directory, so a

package/server/agent-browser-runtime.ts

@@ -3,14 +3,14 @@ import { chmod, mkdir, readFile, rm } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { promisify } from "node:util";
 import {
+  attachToTarget,
   CdpConnection,
-  CdpSession,
+  type CdpEvent,
+  type CdpSession,
+  type CdpTarget,
   CdpUnavailableError,
   CdpUnknownOutcomeError,
-  attachToTarget,
   listPageTargets,
-  type CdpEvent,
-  type CdpTarget,
 } from "./cdp";
 
 const execFileAsync = promisify(execFile);
@@ -93,6 +93,7 @@ export interface AgentBrowserRuntimeOptions {
   ipcDirectory: string;
   session: string;
   initialUrl?: string;
+  headed?: boolean;
   timeoutMs?: number;
 }
 
@@ -164,9 +165,7 @@ function parseJsonOutput(stdout: string): unknown {
   for (const line of lines) {
     try {
       return JSON.parse(line);
-    } catch {
-      continue;
-    }
+    } catch {}
   }
   throw new AgentBrowserIncompatibleError("agent-browser returned invalid JSON");
 }
@@ -191,6 +190,7 @@ export class AgentBrowserRuntime {
   readonly ipcDirectory: string;
   readonly session: string;
   private readonly initialUrl: string;
+  private readonly headed: boolean;
   private readonly timeoutMs: number;
   private readonly environment: NodeJS.ProcessEnv;
   private connection: CdpConnection | null = null;
@@ -214,6 +214,7 @@ export class AgentBrowserRuntime {
       throw new AgentBrowserIncompatibleError("agent-browser session name is invalid");
     }
     this.session = options.session;
+    this.headed = options.headed ?? false;
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.environment = runtimeEnvironment(this.ipcDirectory);
     this.initialUrl = options.initialUrl ?? "about:blank";
@@ -238,6 +239,7 @@ export class AgentBrowserRuntime {
       this.profilePath,
       "--executable-path",
       this.executablePath,
+      ...(this.headed ? ["--headed"] : []),
       ...(chromiumArguments ? ["--args", chromiumArguments] : []),
       "--json",
       "open",
@@ -508,9 +510,7 @@ export class AgentBrowserRuntime {
 
   async mouseMove(x: number, y: number): Promise<void> {
     this.assertPoint(x, y);
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchMouseEvent",
       {
         type: "mouseMoved",
@@ -530,9 +530,7 @@ export class AgentBrowserRuntime {
     clickCount = 1,
   ): Promise<void> {
     this.assertPoint(x, y);
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchMouseEvent",
       {
         type: "mousePressed",
@@ -549,9 +547,7 @@ export class AgentBrowserRuntime {
 
   async mouseUp(x: number, y: number, button: MouseButton = "left", clickCount = 1): Promise<void> {
     this.assertPoint(x, y);
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchMouseEvent",
       {
         type: "mouseReleased",
@@ -568,9 +564,7 @@ export class AgentBrowserRuntime {
 
   async wheel(x: number, y: number, deltaX: number, deltaY: number): Promise<void> {
     this.assertPoint(x, y);
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchMouseEvent",
       {
         type: "mouseWheel",
@@ -590,9 +584,7 @@ export class AgentBrowserRuntime {
   }
 
   async keyDown(key: string, code = key): Promise<void> {
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchKeyEvent",
       {
         type: "keyDown",
@@ -606,9 +598,11 @@ export class AgentBrowserRuntime {
   }
 
   async keyUp(key: string, code = key): Promise<void> {
-    await (
-      await this.requirePage()
-    ).send("Input.dispatchKeyEvent", { type: "keyUp", key, code }, { mutation: true });
+    await (await this.requirePage()).send(
+      "Input.dispatchKeyEvent",
+      { type: "keyUp", key, code },
+      { mutation: true },
+    );
     this.heldKeys.delete(key);
   }
 
@@ -617,9 +611,7 @@ export class AgentBrowserRuntime {
     points: Array<{ x: number; y: number; id?: number }>,
   ): Promise<void> {
     for (const point of points) this.assertPoint(point.x, point.y);
-    await (
-      await this.requirePage()
-    ).send(
+    await (await this.requirePage()).send(
       "Input.dispatchTouchEvent",
       {
         type,
@@ -681,9 +673,10 @@ export class AgentBrowserRuntime {
     if (!force) {
       try {
         await this.invoke(["--session", this.session, "--json", "close"]);
-      } catch (error) {
+      } catch {
         this.stopping = false;
-        throw error;
+        await this.shutdown(true);
+        return;
       }
     } else {
       const pid = await this.daemonPid();

package/server/browser-policy.ts

@@ -1,20 +1,20 @@
-import type { RpcInput } from "@getpaseo/plugin";
 import { randomBytes } from "node:crypto";
+import type { RpcInput } from "@getpaseo/plugin";
 import {
-  DEVICE_PRESETS,
+  type applyDevicePresetRpc,
+  type BrowserFrame,
+  type BrowserInputEvent,
+  type BrowserState,
   DEFAULT_VIEWPORT,
+  DEVICE_PRESETS,
+  type DevicePresetId,
   FRAME_MAX_BYTES,
   MAX_VIEWPORT,
   MIN_VIEWPORT,
   mapDisplayedPoint,
-  applyDevicePresetRpc,
-  navigateBrowserRpc,
-  resizeBrowserRpc,
-  sendBrowserInputRpc,
-  type BrowserFrame,
-  type BrowserInputEvent,
-  type BrowserState,
-  type DevicePresetId,
+  type navigateBrowserRpc,
+  type resizeBrowserRpc,
+  type sendBrowserInputRpc,
   type Viewport,
 } from "../shared/browser";
 import type { JsonValue } from "./runtime-protocol";

package/server/browser.ts

@@ -1,11 +1,11 @@
-import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
-import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import {
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type {
   acquireControlRpc,
   applyDevicePresetRpc,
   attachBrowserRpc,
@@ -18,15 +18,15 @@ import {
   sendBrowserInputRpc,
 } from "../shared/browser";
 import type { JsonValue } from "./runtime-protocol";
-import { SupervisorClient } from "./supervisor-client";
 import { resolveSupervisorPaths } from "./supervisor";
+import { SupervisorClient } from "./supervisor-client";
 
-export { SessionManager, normalizeBrowserUrl } from "./browser-policy";
 export type {
   BrowserRuntimeClient,
   SessionManagerOptions,
   WorkspaceValidator,
 } from "./browser-policy";
+export { normalizeBrowserUrl, SessionManager } from "./browser-policy";
 
 type AttachInput = RpcInput<typeof attachBrowserRpc>;
 type AttachOutput = RpcOutput<typeof attachBrowserRpc>;

package/server/cdp.ts

@@ -102,7 +102,11 @@ export class CdpConnection extends EventEmitter {
   async send<T = unknown>(
     method: string,
     params: Record<string, unknown> = {},
-    options: { sessionId?: string; mutation?: boolean; timeoutMs?: number } = {},
+    options: {
+      sessionId?: string;
+      mutation?: boolean;
+      timeoutMs?: number;
+    } = {},
   ): Promise<T> {
     if (!this.isOpen) throw new CdpUnavailableError("CDP connection is closed");
     const id = this.nextId++;
@@ -173,7 +177,10 @@ export class CdpConnection extends EventEmitter {
         return;
       }
       if (message.method) {
-        const event: CdpEvent = { method: message.method, params: message.params ?? {} };
+        const event: CdpEvent = {
+          method: message.method,
+          params: message.params ?? {},
+        };
         if (message.sessionId) event.sessionId = message.sessionId;
         this.emit("event", event);
         this.emit(message.method, event.params, event.sessionId);
@@ -220,7 +227,10 @@ export class CdpSession extends EventEmitter {
     params: Record<string, unknown> = {},
     options: { mutation?: boolean; timeoutMs?: number } = {},
   ): Promise<T> {
-    return this.connection.send<T>(method, params, { ...options, sessionId: this.sessionId });
+    return this.connection.send<T>(method, params, {
+      ...options,
+      sessionId: this.sessionId,
+    });
   }
 
   detach(): Promise<void> {

package/server/mcp-entry.ts

@@ -1,11 +1,11 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import type { JsonValue } from "./runtime-protocol";
-import { AgentSupervisorClient } from "./supervisor-client";
 import { resolveSupervisorPaths } from "./supervisor";
+import { AgentSupervisorClient } from "./supervisor-client";
 
 const TICKET_ENV = "PASEO_SHARED_BROWSER_TICKET";
 const MIN_VIEWPORT = { width: 320, height: 480 } as const;
@@ -71,7 +71,9 @@ function asObject(value: JsonValue): Record<string, JsonValue> {
 }
 
 function textResult(value: JsonValue) {
-  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
+  };
 }
 
 async function main(): Promise<void> {
@@ -83,7 +85,10 @@ async function main(): Promise<void> {
   });
   await client.open();
 
-  const server = new McpServer({ name: "paseo-shared-browser", version: "0.2.2" });
+  const server = new McpServer({
+    name: "paseo-shared-browser",
+    version: "0.2.2",
+  });
 
   server.registerTool(
     "shared_browser_status",
@@ -100,7 +105,9 @@ async function main(): Promise<void> {
     {
       description:
         "Capture the current shared browser frame and state. Capture before sending input.",
-      inputSchema: z.object({ quality: z.enum(["low", "medium", "high"]).default("medium") }),
+      inputSchema: z.object({
+        quality: z.enum(["low", "medium", "high"]).default("medium"),
+      }),
       annotations: { readOnlyHint: true, idempotentHint: true },
     },
     async ({ quality }) => {
@@ -113,7 +120,11 @@ async function main(): Promise<void> {
       if (frame && typeof frame === "object" && !Array.isArray(frame)) {
         const image = frame as Record<string, JsonValue>;
         if (typeof image.dataBase64 === "string" && typeof image.mimeType === "string")
-          content.push({ type: "image", data: image.dataBase64, mimeType: image.mimeType });
+          content.push({
+            type: "image",
+            data: image.dataBase64,
+            mimeType: image.mimeType,
+          });
       }
       return { content };
     },
@@ -125,7 +136,11 @@ async function main(): Promise<void> {
       description:
         "Acquire browser control if no human or other viewer currently holds it. Forced takeover is unavailable.",
       inputSchema: z.object({}),
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
     },
     async () => textResult(await client.request("acquire-control", {})),
   );
@@ -135,7 +150,11 @@ async function main(): Promise<void> {
     {
       description: "Release this agent's browser control lease.",
       inputSchema: z.object({}),
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
     },
     async () => textResult(await client.request("release-control", {})),
   );
@@ -145,16 +164,27 @@ async function main(): Promise<void> {
       description: "Navigate the shared browser using the agent's current observed state.",
       inputSchema: z.object({
         action: z.discriminatedUnion("kind", [
-          z.object({ kind: z.literal("goto"), url: z.string().trim().min(1).max(8_192) }),
+          z.object({
+            kind: z.literal("goto"),
+            url: z.string().trim().min(1).max(8_192),
+          }),
           z.object({ kind: z.literal("back") }),
           z.object({ kind: z.literal("forward") }),
           z.object({ kind: z.literal("reload") }),
         ]),
       }),
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
     },
     async ({ action }) =>
-      textResult(await client.request("navigate", { action: action as unknown as JsonValue })),
+      textResult(
+        await client.request("navigate", {
+          action: action as unknown as JsonValue,
+        }),
+      ),
   );
 
   server.registerTool(
@@ -163,7 +193,11 @@ async function main(): Promise<void> {
       description:
         "Send one input event using the exact frame returned by the latest capture. Stale frames are rejected.",
       inputSchema: z.object({ event: inputEventSchema }),
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
     },
     async ({ event }) =>
       textResult(await client.request("input", { event: event as unknown as JsonValue })),
@@ -177,10 +211,18 @@ async function main(): Promise<void> {
         width: z.number().int().min(MIN_VIEWPORT.width).max(MAX_VIEWPORT.width),
         height: z.number().int().min(MIN_VIEWPORT.height).max(MAX_VIEWPORT.height),
       }),
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+      },
     },
     async (viewport) =>
-      textResult(await client.request("viewport", { viewport: viewport as unknown as JsonValue })),
+      textResult(
+        await client.request("viewport", {
+          viewport: viewport as unknown as JsonValue,
+        }),
+      ),
   );
 
   const transport = new StdioServerTransport();

package/server/runtime-owner.ts

@@ -11,12 +11,18 @@ interface OwnedRuntime {
   runtimeId: string;
   runtime: AgentBrowserRuntime;
 }
+interface RuntimeOwnerOptions {
+  initialUrl?: string;
+  headed?: boolean;
+}
 
 function paseoHome(): string {
   return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
 }
 
-export async function createRuntimeOwner(): Promise<RuntimeOwner<OwnedRuntime>> {
+export async function createRuntimeOwner(
+  options: RuntimeOwnerOptions = {},
+): Promise<RuntimeOwner<OwnedRuntime>> {
   const root = join(paseoHome(), "plugin-data", "shared-browser");
   const ipcDirectory =
     process.platform === "win32"
@@ -46,7 +52,8 @@ export async function createRuntimeOwner(): Promise<RuntimeOwner<OwnedRuntime>>
         profilePath: join(root, "profiles", hash),
         ipcDirectory,
         session: `ws-${hash.slice(0, 16)}`,
-        initialUrl: DEFAULT_BROWSER_URL,
+        initialUrl: options.initialUrl ?? DEFAULT_BROWSER_URL,
+        headed: options.headed ?? false,
       });
       await runtime.launch();
       return { runtimeId: randomUUID(), runtime };

package/server/runtime-protocol.ts

@@ -41,7 +41,11 @@ export type AgentBrowserOperation =
 export type RuntimeRequest =
   | (AdminRequestBase & { method: "bridge.claim"; takeover?: boolean })
   | (AdminRequestBase & { method: "bridge.heartbeat"; epoch: number })
-  | (AdminRequestBase & { method: "workspace.ensure"; epoch: number; workspaceId: string })
+  | (AdminRequestBase & {
+      method: "workspace.ensure";
+      epoch: number;
+      workspaceId: string;
+    })
   | (AdminRequestBase & {
       method: "workspace.request";
       epoch: number;
@@ -49,14 +53,22 @@ export type RuntimeRequest =
       operation: string;
       input: JsonValue;
     })
-  | (AdminRequestBase & { method: "workspace.archive"; epoch: number; workspaceId: string })
+  | (AdminRequestBase & {
+      method: "workspace.archive";
+      epoch: number;
+      workspaceId: string;
+    })
   | (AdminRequestBase & {
       method: "browser.request";
       epoch: number;
       operation: string;
       input: JsonValue;
     })
-  | (AdminRequestBase & { method: "ticket.issue"; epoch: number; ticket: string })
+  | (AdminRequestBase & {
+      method: "ticket.issue";
+      epoch: number;
+      ticket: string;
+    })
   | (AdminRequestBase & {
       method: "ticket.bind";
       epoch: number;
@@ -64,7 +76,11 @@ export type RuntimeRequest =
       agentId: string;
       workspaceId: string;
     })
-  | (AdminRequestBase & { method: "agent.revoke"; epoch: number; agentId: string })
+  | (AdminRequestBase & {
+      method: "agent.revoke";
+      epoch: number;
+      agentId: string;
+    })
   | (RuntimeRequestBase & {
       method: "agent.request";
       ticket: string;
@@ -76,7 +92,11 @@ export type RuntimeResult = BridgeLease | RuntimeDescriptor | JsonValue | { arch
 
 export type RuntimeResponse =
   | { id: string; ok: true; result: RuntimeResult }
-  | { id: string; ok: false; error: { code: RuntimeErrorCode; message: string } };
+  | {
+      id: string;
+      ok: false;
+      error: { code: RuntimeErrorCode; message: string };
+    };
 
 export type RuntimeErrorCode =
   | "AUTHENTICATION_FAILED"
@@ -145,7 +165,14 @@ export function parseRuntimeRequest(value: unknown): RuntimeRequest {
     };
   const epoch = requireInteger(value, "epoch");
   if (method === "bridge.heartbeat")
-    return { id, version: RUNTIME_PROTOCOL_VERSION, method, token, bridgeId, epoch };
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+    };
   if (method === "workspace.ensure" || method === "workspace.archive")
     return {
       id,

package/server/supervisor-client.ts

@@ -1,14 +1,14 @@
+import { randomUUID } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { createConnection, type Socket } from "node:net";
-import { randomUUID } from "node:crypto";
 import {
-  RUNTIME_PROTOCOL_VERSION,
-  RuntimeProtocolError,
-  isRuntimeResponse,
   type AgentBrowserOperation,
   type BridgeLease,
+  isRuntimeResponse,
   type JsonValue,
+  RUNTIME_PROTOCOL_VERSION,
   type RuntimeDescriptor,
+  RuntimeProtocolError,
   type RuntimeRequest,
   type RuntimeResponse,
   type RuntimeResult,

package/server/supervisor.ts

@@ -7,15 +7,15 @@ import type { BrowserFrame, BrowserInputEvent, BrowserState, Viewport } from "..
 import { SessionManager } from "./browser-policy";
 import { CdpUnknownOutcomeError } from "./cdp";
 import {
+  type BridgeLease,
   DEFAULT_BRIDGE_HEARTBEAT_MS,
   DEFAULT_BRIDGE_TIMEOUT_MS,
   DEFAULT_ORPHAN_GRACE_MS,
-  RUNTIME_PROTOCOL_VERSION,
-  RuntimeProtocolError,
-  parseRuntimeRequest,
-  type BridgeLease,
   type JsonValue,
+  parseRuntimeRequest,
+  RUNTIME_PROTOCOL_VERSION,
   type RuntimeDescriptor,
+  RuntimeProtocolError,
   type RuntimeRequest,
   type RuntimeResponse,
   type RuntimeResult,

package/shared/browser.ts

@@ -206,7 +206,10 @@ export const navigateBrowserRpc = defineRpc({
     controlToken: opaqueTokenSchema,
     expected: expectedStateSchema,
     action: z.discriminatedUnion("kind", [
-      z.object({ kind: z.literal("goto"), url: z.string().trim().min(1).max(8_192) }),
+      z.object({
+        kind: z.literal("goto"),
+        url: z.string().trim().min(1).max(8_192),
+      }),
       z.object({ kind: z.literal("back") }),
       z.object({ kind: z.literal("forward") }),
       z.object({ kind: z.literal("reload") }),