@omercnet/paseo-shared-browser 0.3.1-next.72.1

package/index.client.tsx

@@ -0,0 +1,35 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { SharedBrowserPanel, contributeSharedBrowserClient } from "./client/browser";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "shared-browser",
+    title: "Shared Browser",
+    icon: "PanelsTopLeft",
+    context: "workspace",
+    locations: ["workspace", "explorer"],
+    Component: SharedBrowserPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-shared-browser",
+    title: "Open Shared Browser",
+    icon: "PanelsTopLeft",
+    keywords: ["browser", "shared", "remote"],
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel("shared-browser");
+    },
+  });
+  client.addCommandCenterItem({
+    id: "open-shared-browser-agent",
+    title: "Open Shared Browser",
+    icon: "PanelsTopLeft",
+    keywords: ["browser", "shared", "remote"],
+    context: "agent",
+    onSelect({ openPanel }) {
+      openPanel("shared-browser");
+    },
+  });
+
+  return contributeSharedBrowserClient(client);
+}

package/index.server.ts

@@ -0,0 +1,118 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  bindAgentTicket,
+  cleanupBrowserServer,
+  handleAcquireControl,
+  handleApplyDevicePreset,
+  handleAttachBrowser,
+  handleCaptureBrowser,
+  handleDetachBrowser,
+  handleListOpenBrowserWorkspaces,
+  handleNavigateBrowser,
+  handleReleaseControl,
+  handleResizeBrowser,
+  handleSendBrowserInput,
+  handleWorkspaceArchived,
+  issueAgentTicket,
+  revokeAgentBrowserAccess,
+} from "./server/browser";
+import {
+  acquireControlRpc,
+  applyDevicePresetRpc,
+  attachBrowserRpc,
+  captureBrowserRpc,
+  detachBrowserRpc,
+  listOpenBrowserWorkspacesRpc,
+  navigateBrowserRpc,
+  releaseControlRpc,
+  resizeBrowserRpc,
+  sendBrowserInputRpc,
+} from "./shared/browser";
+
+const TICKET_ENV = "PASEO_SHARED_BROWSER_TICKET";
+const MCP_SERVER_ID = "shared-browser";
+const TICKET_ISSUE_TIMEOUT_MS = 2_000;
+
+async function issueTicketWithinDeadline(ticket: string): Promise<boolean> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    await Promise.race([
+      issueAgentTicket(ticket),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Shared Browser ticket issuance timed out")),
+          TICKET_ISSUE_TIMEOUT_MS,
+        );
+        timer.unref();
+      }),
+    ]);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function paseoHome(): string {
+  return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+}
+
+function mcpBundlePath(): string {
+  return join(paseoHome(), "plugin-data", "shared-browser", "runtime", "shared-browser-mcp.cjs");
+}
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(attachBrowserRpc, handleAttachBrowser);
+  server.handle(detachBrowserRpc, handleDetachBrowser);
+  server.handle(captureBrowserRpc, handleCaptureBrowser);
+  server.handle(listOpenBrowserWorkspacesRpc, handleListOpenBrowserWorkspaces);
+  server.handle(acquireControlRpc, handleAcquireControl);
+  server.handle(releaseControlRpc, handleReleaseControl);
+  server.handle(navigateBrowserRpc, handleNavigateBrowser);
+  server.handle(resizeBrowserRpc, handleResizeBrowser);
+  server.handle(applyDevicePresetRpc, handleApplyDevicePreset);
+  server.handle(sendBrowserInputRpc, handleSendBrowserInput);
+  server.before("agent.create", async ({ request }) => {
+    if (request.config.internal || request.config.provider === "omp") return request;
+    const ticket = randomBytes(32).toString("base64url");
+    if (!(await issueTicketWithinDeadline(ticket))) return request;
+    return {
+      ...request,
+      env: { ...request.env, [TICKET_ENV]: ticket },
+      config: {
+        ...request.config,
+        mcpServers: {
+          ...request.config.mcpServers,
+          [MCP_SERVER_ID]: {
+            type: "stdio",
+            command: process.execPath,
+            args: [mcpBundlePath()],
+            env: {
+              PASEO_HOME: paseoHome(),
+              [TICKET_ENV]: ticket,
+            },
+          },
+        },
+      },
+    };
+  });
+
+  server.before("agent.session_open", async ({ request }) => {
+    if (request.reason !== "create") return request;
+    const ticket = request.env[TICKET_ENV];
+    if (!ticket || request.purpose !== "interactive" || !request.workspaceId) return request;
+    await bindAgentTicket(ticket, request.agentId, request.workspaceId);
+    const { [TICKET_ENV]: _ticket, ...environment } = request.env;
+    return { ...request, env: environment };
+  });
+
+  server.on("agent.archived", ({ agent }) => revokeAgentBrowserAccess(agent.id));
+
+  server.on("workspace.archived", ({ workspace }) => handleWorkspaceArchived(workspace.id));
+
+  return cleanupBrowserServer;
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@omercnet/paseo-shared-browser",
+  "version": "0.3.1-next.72.1",
+  "description": "One real Chromium session per Paseo workspace, shared live across every connected client.",
+  "keywords": [
+    "browser",
+    "chromium",
+    "coding-agents",
+    "paseo",
+    "paseo-plugin",
+    "remote-browser"
+  ],
+  "homepage": "https://github.com/omercnet/paseo-plugins/tree/main/paseo-shared-browser#readme",
+  "bugs": {
+    "url": "https://github.com/omercnet/paseo-plugins/issues"
+  },
+  "license": "MIT",
+  "author": "Omer Cohen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omercnet/paseo-plugins.git",
+    "directory": "paseo-shared-browser"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "index.client.tsx",
+    "index.server.ts",
+    "client",
+    "docs",
+    "scripts/prepare-dependencies.mjs",
+    "scripts/prepare-runtime.mjs",
+    "server",
+    "shared",
+    "paseo-plugin.json",
+    "tsconfig.json"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings .",
+    "format": "oxfmt . '!CHANGELOG.md'",
+    "format:check": "oxfmt --check . '!CHANGELOG.md'",
+    "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"
+  },
+  "dependencies": {
+    "@getpaseo/plugin": "0.8.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "agent-browser": "0.37.1",
+    "esbuild": "0.28.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.11",
+    "@types/node": "^22.0.0",
+    "@types/react": "~19.2.0",
+    "oxfmt": "0.66.0",
+    "oxlint": "1.81.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "typescript": "^7.0.0",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "npm@11.19.1",
+  "allowScripts": {
+    "agent-browser": true,
+    "esbuild@0.28.2": true
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "shared-browser",
+  "requirements": {
+    "paseo": "^0.8.0"
+  },
+  "build": [
+    ["node", "scripts/prepare-dependencies.mjs"],
+    ["npm", "run", "prepare:runtime"]
+  ]
+}

package/scripts/prepare-dependencies.mjs

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export function resolveDependencyRoot(packageName, from = import.meta.url) {
+  const require = createRequire(from);
+  return dirname(require.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",
+  });
+  return true;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  prepareDependencies();
+}

package/scripts/prepare-runtime.mjs

@@ -0,0 +1,168 @@
+import { resolveDependencyRoot } from "./prepare-dependencies.mjs";
+import { build } from "esbuild";
+import { execFile } from "node:child_process";
+import {
+  access,
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  readdir,
+  rename,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { arch, homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const execFileAsync = promisify(execFile);
+const expectedVersion = "0.37.1";
+const projectRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const paseoHome = process.env.PASEO_HOME || join(homedir(), ".paseo");
+const pluginDataRoot = join(paseoHome, "plugin-data", "shared-browser");
+const runtimeRoot = join(pluginDataRoot, "runtime");
+const stagingRoot = join(pluginDataRoot, `.runtime-${process.pid}`);
+const runtimeModules = join(stagingRoot, "node_modules");
+const packagedAgentBrowser = resolveDependencyRoot("agent-browser");
+const runtimeEntry = join(runtimeModules, ".bin", "agent-browser");
+const supervisorEntry = join(projectRoot, "server", "supervisor-entry.ts");
+const mcpEntry = join(projectRoot, "server", "mcp-entry.ts");
+
+async function requireExecutable(path, label) {
+  const absolutePath = resolve(path);
+  try {
+    await access(absolutePath, constants.X_OK);
+  } catch {
+    throw new Error(`${label} is missing or not executable: ${absolutePath}`);
+  }
+  return absolutePath;
+}
+
+async function validateAgentBrowser(path) {
+  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"}`);
+  }
+}
+async function bundleRuntimeEntries() {
+  await build({
+    entryPoints: {
+      supervisor: supervisorEntry,
+      "shared-browser-mcp": mcpEntry,
+    },
+    outdir: stagingRoot,
+    outExtension: { ".js": ".cjs" },
+    bundle: true,
+    platform: "node",
+    target: "node20",
+    format: "cjs",
+    logLevel: "silent",
+  });
+}
+
+async function applyPrivatePermissions(path) {
+  const metadata = await lstat(path);
+  if (metadata.isSymbolicLink()) return;
+  if (metadata.isDirectory()) {
+    await chmod(path, 0o700);
+    for (const entry of await readdir(path)) {
+      await applyPrivatePermissions(join(path, entry));
+    }
+    return;
+  }
+  await chmod(path, metadata.mode & 0o111 ? 0o700 : 0o600);
+}
+
+async function stageChromiumExecutable(executable) {
+  const chromiumRoot = join(stagingRoot, "chromium");
+  await mkdir(chromiumRoot, { recursive: true, mode: 0o700 });
+  await symlink(executable, join(chromiumRoot, "chrome"));
+}
+
+async function findLinuxArm64Chromium() {
+  if (platform() !== "linux" || arch() !== "arm64") return null;
+
+  const candidate = "/usr/bin/chromium";
+  try {
+    return await requireExecutable(candidate, "System Chromium executable");
+  } catch {
+    throw new Error(
+      `Linux ARM64 requires native Chromium at ${candidate}. ` +
+        "Install a non-Snap Chromium build or set " +
+        "PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE to its absolute path.",
+    );
+  }
+}
+
+async function installChromium() {
+  const override = process.env.PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE;
+  if (override) {
+    const executable = await requireExecutable(
+      override,
+      "PASEO_SHARED_BROWSER_CHROMIUM_EXECUTABLE",
+    );
+    await stageChromiumExecutable(executable);
+    return;
+  }
+
+  const systemChromium = await findLinuxArm64Chromium();
+  if (systemChromium) {
+    await stageChromiumExecutable(systemChromium);
+    console.log(`Using system Chromium at ${systemChromium}`);
+    return;
+  }
+
+  const installHome = join(stagingRoot, "install-home");
+  await mkdir(installHome, { recursive: true, mode: 0o700 });
+  await execFileAsync(runtimeEntry, ["install"], {
+    env: { ...process.env, HOME: installHome },
+    timeout: 180_000,
+  });
+
+  const browsersRoot = join(installHome, ".agent-browser", "browsers");
+  const releases = (await readdir(browsersRoot, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("chrome-"))
+    .map((entry) => entry.name)
+    .sort()
+    .reverse();
+  const chrome = releases[0] && join(browsersRoot, releases[0], "chrome");
+  if (!chrome) throw new Error("agent-browser install did not produce a Chromium release");
+  await requireExecutable(chrome, "Installed Chromium executable");
+  await cp(dirname(chrome), join(stagingRoot, "chromium"), { recursive: true, force: true });
+  await rm(installHome, { recursive: true, force: true });
+}
+
+await rm(stagingRoot, { recursive: true, force: true });
+await mkdir(join(runtimeModules, ".bin"), { recursive: true, mode: 0o700 });
+await chmod(pluginDataRoot, 0o700);
+await cp(packagedAgentBrowser, join(runtimeModules, "agent-browser"), {
+  recursive: true,
+  force: true,
+});
+await symlink("../agent-browser/bin/agent-browser.js", runtimeEntry);
+await chmod(runtimeEntry, 0o700);
+
+const binaryOverride = process.env.PASEO_SHARED_BROWSER_AGENT_BROWSER_BINARY;
+if (binaryOverride)
+  await validateAgentBrowser(
+    await requireExecutable(binaryOverride, "PASEO_SHARED_BROWSER_AGENT_BROWSER_BINARY"),
+  );
+await validateAgentBrowser(await requireExecutable(runtimeEntry, "Packaged agent-browser entry"));
+await installChromium();
+await bundleRuntimeEntries();
+
+await writeFile(
+  join(stagingRoot, "package.json"),
+  `${JSON.stringify({ private: true, type: "commonjs" }, null, 2)}\n`,
+  { mode: 0o600 },
+);
+await applyPrivatePermissions(stagingRoot);
+await rm(runtimeRoot, { recursive: true, force: true });
+await rename(stagingRoot, runtimeRoot);
+
+console.log(`Prepared immutable Shared Browser runtime assets in ${runtimeRoot}`);