@omercnet/paseo-shared-browser 0.4.2-next.129.1 → 0.4.2-next.145.1

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
@@ -175,23 +161,21 @@ 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.8.0 <0.10.0`, which supports Paseo 0.8
+and Paseo 0.9. The client surface uses React Native primitives and works in desktop, web, iOS,
+and Android Paseo clients.

package/client/browser.tsx

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-shared-browser",
-  "version": "0.4.2-next.129.1",
+  "version": "0.4.2-next.145.1",
   "description": "One real Chromium session per Paseo workspace, shared live across every connected client.",
   "keywords": [
     "browser",
@@ -38,40 +38,35 @@
     "access": "public"
   },
   "scripts": {
+    "check": "biome check .",
+    "check:write": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "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:smoke": "vitest run tests/browser.smoke.test.ts --testTimeout=30000",
-    "check": "biome check --error-on-warnings .",
-    "check:write": "biome check --write .",
-    "test": "run-s test:ci:*",
-    "test:ci:unit": "npm run test:unit",
-    "build": "node ../.github/scripts/build-plugin.mjs"
+    "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": {
-    "@biomejs/biome": "^2.5.14",
-    "@getpaseo/plugin": "0.9.0-beta.1",
-    "@getpaseo/server": "0.9.0-beta.1",
-    "@tanstack/react-query": "^5.90.11",
-    "@types/node": "^22.0.0",
-    "@types/react": "~19.2.0",
-    "npm-run-all2": "^9.0.3",
+    "@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,7 +1,7 @@
 {
   "id": "shared-browser",
   "requirements": {
-    "paseo": "^0.8.0 || ^0.9.0-beta.1"
+    "paseo": ">=0.9.0 <0.10.0"
   },
   "build": [["node", "scripts/prepare-dependencies.mjs"], ["npm", "run", "prepare:runtime"]]
 }

package/scripts/prepare-dependencies.mjs

@@ -1,21 +1,58 @@
 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

@@ -12,12 +12,19 @@ import {
   symlink,
   writeFile,
 } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { arch, homedir, platform, userInfo } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { build } from "esbuild";
-import { resolveDependencyRoot } from "./prepare-dependencies.mjs";
+
+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

@@ -93,6 +93,7 @@ export interface AgentBrowserRuntimeOptions {
   ipcDirectory: string;
   session: string;
   initialUrl?: string;
+  headed?: boolean;
   timeoutMs?: number;
 }
 
@@ -189,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;
@@ -212,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";
@@ -236,6 +239,7 @@ export class AgentBrowserRuntime {
       this.profilePath,
       "--executable-path",
       this.executablePath,
+      ...(this.headed ? ["--headed"] : []),
       ...(chromiumArguments ? ["--args", chromiumArguments] : []),
       "--json",
       "open",
@@ -669,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/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

@@ -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/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") }),