@different-ai/opencode-browser 3.0.0 → 4.0.0

package/README.md

@@ -1,14 +1,16 @@
 # OpenCode Browser
 
-Browser automation MCP server for [OpenCode](https://github.com/opencode-ai/opencode).
+Browser automation plugin for [OpenCode](https://github.com/opencode-ai/opencode).
 
-Control your real Chrome browser with existing logins, cookies, and bookmarks. No DevTools Protocol, no security prompts.
+Control your real Chromium browser (Chrome/Brave/Arc/Edge) using your existing profile (logins, cookies, bookmarks). No DevTools Protocol, no security prompts.
 
-## Why?
+## Why this architecture
 
-Chrome 136+ blocks `--remote-debugging-port` on your default profile for security reasons. DevTools-based automation (like Playwright) triggers a security prompt every time.
+This version is optimized for reliability and predictable multi-session behavior:
 
-OpenCode Browser uses a simple WebSocket connection between an MCP server and a Chrome extension. Your automation works with your existing browser session - no prompts, no separate profiles.
+- **No WebSocket port** → no port conflicts
+- **Chrome Native Messaging** between extension and a local host process
+- A local **broker** multiplexes multiple OpenCode plugin sessions and enforces **per-tab ownership**
 
 ## Installation
 
@@ -17,111 +19,66 @@ npx @different-ai/opencode-browser install
 ```
 
 The installer will:
+
 1. Copy the extension to `~/.opencode-browser/extension/`
-2. Guide you to load the extension in Chrome
-3. Update your `opencode.json` with MCP server config
+2. Walk you through loading + pinning it in `chrome://extensions`
+3. Ask for the extension ID and install a **Native Messaging Host manifest**
+4. Update your `opencode.json` to load the plugin
 
-## Configuration
+### Configure OpenCode
 
-Add to your `opencode.json`:
+Your `opencode.json` should contain:
 
 ```json
 {
-  "mcp": {
-    "browser": {
-      "type": "local",
-      "command": ["bunx", "@different-ai/opencode-browser", "serve"]
-    }
-  }
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@different-ai/opencode-browser"]
 }
 ```
 
-Then load the extension in Chrome:
-1. Go to `chrome://extensions`
-2. Enable "Developer mode"
-3. Click "Load unpacked" and select `~/.opencode-browser/extension/`
-
-## Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `browser_status` | Check if browser extension is connected |
-| `browser_navigate` | Navigate to a URL |
-| `browser_click` | Click an element by CSS selector |
-| `browser_type` | Type text into an input field |
-| `browser_screenshot` | Capture the page (returns base64, optionally saves to file) |
-| `browser_snapshot` | Get accessibility tree with selectors + all page links |
-| `browser_get_tabs` | List all open tabs |
-| `browser_scroll` | Scroll page or element into view |
-| `browser_wait` | Wait for a duration |
-| `browser_execute` | Run JavaScript in page context |
-
-### Screenshot Tool
-
-The `browser_screenshot` tool returns base64 image data by default, allowing AI to view images directly:
-
-```javascript
-// Returns base64 image (AI can view it)
-browser_screenshot()
-
-// Save to current working directory
-browser_screenshot({ save: true })
-
-// Save to specific path
-browser_screenshot({ path: "my-screenshot.png" })
-```
-
-## Architecture
+## How it works
 
 ```
-OpenCode <──STDIO──> MCP Server <──WebSocket:19222──> Chrome Extension
-                          │                                   │
-                          └── @modelcontextprotocol/sdk       └── chrome.tabs, chrome.scripting
+OpenCode Plugin <-> Local Broker (unix socket) <-> Native Host <-> Chrome Extension
 ```
 
-**Two components:**
-1. MCP Server (runs as separate process, manages WebSocket server)
-2. Chrome extension (connects to server, executes browser commands)
+- The extension connects to the native host.
+- The plugin talks to the broker over a local unix socket.
+- The broker forwards tool requests to the extension and enforces tab ownership.
 
-**Benefits of MCP architecture:**
-- No session conflicts between OpenCode instances
-- Server runs independently of OpenCode process
-- Clean separation of concerns
-- Standard MCP protocol
+## Per-tab ownership
 
-## Upgrading from v2.x (Plugin)
+- First time a session touches a tab, the broker **auto-claims** it for that session.
+- Other sessions attempting to use the same tab will get an error.
 
-v3.0 migrates from plugin to MCP architecture:
+Tools:
 
-1. Run `npx @different-ai/opencode-browser install`
-2. Replace plugin config with MCP config in `opencode.json`:
+- `browser_claim_tab({ tabId })`
+- `browser_release_tab({ tabId })`
+- `browser_list_claims()`
 
-```diff
-- "plugin": ["@different-ai/opencode-browser"]
-+ "mcp": {
-+   "browser": {
-+     "type": "local",
-+     "command": ["bunx", "@different-ai/opencode-browser", "serve"]
-+   }
-+ }
-```
+## Available tools
 
-3. Restart OpenCode
+- `browser_status`
+- `browser_get_tabs`
+- `browser_navigate`
+- `browser_click`
+- `browser_type`
+- `browser_screenshot`
+- `browser_snapshot`
+- `browser_scroll`
+- `browser_wait`
+- `browser_execute`
 
 ## Troubleshooting
 
-**"Chrome extension not connected"**
-- Make sure Chrome is running
-- Check that the extension is loaded and enabled
-- Click the extension icon to see connection status
-
-**"Failed to start WebSocket server"**
-- Port 19222 may be in use
-- Run `lsof -i :19222` to check what's using it
+**Extension says native host not available**
+- Re-run `npx @different-ai/opencode-browser install`
+- Confirm the extension ID you pasted matches the loaded extension in `chrome://extensions`
 
-**"browser_execute fails on some sites"**
-- Sites with strict CSP block JavaScript execution
-- Use `browser_snapshot` to get page data instead
+**Tab ownership errors**
+- Use `browser_list_claims()` to see who owns a tab
+- Use `browser_claim_tab({ tabId, force: true })` to take over intentionally
 
 ## Uninstall
 
@@ -129,18 +86,4 @@ v3.0 migrates from plugin to MCP architecture:
 npx @different-ai/opencode-browser uninstall
 ```
 
-Then remove the extension from Chrome and delete `~/.opencode-browser/` if desired.
-
-## Platform Support
-
-- macOS ✓
-- Linux ✓  
-- Windows (not yet supported)
-
-## License
-
-MIT
-
-## Credits
-
-Inspired by [Claude in Chrome](https://www.anthropic.com/news/claude-in-chrome) by Anthropic.
+Then remove the unpacked extension in `chrome://extensions` and remove the plugin from `opencode.json`.

package/bin/broker.cjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+"use strict";
+
+const net = require("net");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const BASE_DIR = path.join(os.homedir(), ".opencode-browser");
+const SOCKET_PATH = path.join(BASE_DIR, "broker.sock");
+
+fs.mkdirSync(BASE_DIR, { recursive: true });
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function createJsonLineParser(onMessage) {
+  let buffer = "";
+  return (chunk) => {
+    buffer += chunk.toString("utf8");
+    while (true) {
+      const idx = buffer.indexOf("\n");
+      if (idx === -1) return;
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+      if (!line.trim()) continue;
+      try {
+        onMessage(JSON.parse(line));
+      } catch {
+        // ignore
+      }
+    }
+  };
+}
+
+function writeJsonLine(socket, msg) {
+  socket.write(JSON.stringify(msg) + "\n");
+}
+
+function wantsTab(toolName) {
+  return !["get_tabs", "get_active_tab"].includes(toolName);
+}
+
+// --- State ---
+let host = null; // { socket }
+let nextExtId = 0;
+const extPending = new Map(); // extId -> { pluginSocket, pluginRequestId, sessionId }
+
+const clients = new Set();
+
+// Tab ownership: tabId -> { sessionId, claimedAt }
+const claims = new Map();
+
+function listClaims() {
+  const out = [];
+  for (const [tabId, info] of claims.entries()) {
+    out.push({ tabId, ...info });
+  }
+  out.sort((a, b) => a.tabId - b.tabId);
+  return out;
+}
+
+function releaseClaimsForSession(sessionId) {
+  for (const [tabId, info] of claims.entries()) {
+    if (info.sessionId === sessionId) claims.delete(tabId);
+  }
+}
+
+function checkClaim(tabId, sessionId) {
+  const existing = claims.get(tabId);
+  if (!existing) return { ok: true };
+  if (existing.sessionId === sessionId) return { ok: true };
+  return { ok: false, error: `Tab ${tabId} is owned by another OpenCode session (${existing.sessionId})` };
+}
+
+function setClaim(tabId, sessionId) {
+  claims.set(tabId, { sessionId, claimedAt: nowIso() });
+}
+
+function ensureHost() {
+  if (host && host.socket && !host.socket.destroyed) return;
+  throw new Error("Chrome extension is not connected (native host offline)");
+}
+
+function callExtension(tool, args, sessionId) {
+  ensureHost();
+  const extId = ++nextExtId;
+
+  return new Promise((resolve, reject) => {
+    extPending.set(extId, { resolve, reject, sessionId });
+    writeJsonLine(host.socket, {
+      type: "to_extension",
+      message: { type: "tool_request", id: extId, tool, args },
+    });
+
+    const timeout = setTimeout(() => {
+      if (!extPending.has(extId)) return;
+      extPending.delete(extId);
+      reject(new Error("Timed out waiting for extension"));
+    }, 60000);
+
+    // attach timeout to resolver
+    const pending = extPending.get(extId);
+    if (pending) pending.timeout = timeout;
+  });
+}
+
+async function resolveActiveTab(sessionId) {
+  const res = await callExtension("get_active_tab", {}, sessionId);
+  const tabId = res && typeof res.tabId === "number" ? res.tabId : undefined;
+  if (!tabId) throw new Error("Could not determine active tab");
+  return tabId;
+}
+
+async function handleTool(pluginSocket, req) {
+  const { tool, args = {}, sessionId } = req;
+  if (!tool) throw new Error("Missing tool");
+
+  let tabId = args.tabId;
+
+  if (wantsTab(tool)) {
+    if (typeof tabId !== "number") {
+      tabId = await resolveActiveTab(sessionId);
+    }
+
+    const claimCheck = checkClaim(tabId, sessionId);
+    if (!claimCheck.ok) throw new Error(claimCheck.error);
+  }
+
+  const res = await callExtension(tool, { ...args, tabId }, sessionId);
+
+  const usedTabId =
+    res && typeof res.tabId === "number" ? res.tabId : typeof tabId === "number" ? tabId : undefined;
+  if (typeof usedTabId === "number") {
+    // Auto-claim on first touch
+    const existing = claims.get(usedTabId);
+    if (!existing) setClaim(usedTabId, sessionId);
+  }
+
+  return res;
+}
+
+function handleClientMessage(socket, client, msg) {
+  if (msg && msg.type === "hello") {
+    client.role = msg.role || "unknown";
+    client.sessionId = msg.sessionId;
+    if (client.role === "native-host") {
+      host = { socket };
+      // allow host to see current state
+      writeJsonLine(socket, { type: "host_ready", claims: listClaims() });
+    }
+    return;
+  }
+
+  if (msg && msg.type === "from_extension") {
+    const message = msg.message;
+    if (message && message.type === "tool_response" && typeof message.id === "number") {
+      const pending = extPending.get(message.id);
+      if (!pending) return;
+      extPending.delete(message.id);
+      if (pending.timeout) clearTimeout(pending.timeout);
+
+      if (message.error) {
+        pending.reject(new Error(message.error.content || String(message.error)));
+      } else {
+        // Forward full result payload so callers can read tabId
+        pending.resolve(message.result);
+      }
+    }
+    return;
+  }
+
+  if (msg && msg.type === "request" && typeof msg.id === "number") {
+    const requestId = msg.id;
+    const sessionId = msg.sessionId || client.sessionId;
+
+    const replyOk = (data) => writeJsonLine(socket, { type: "response", id: requestId, ok: true, data });
+    const replyErr = (err) =>
+      writeJsonLine(socket, { type: "response", id: requestId, ok: false, error: err.message || String(err) });
+
+    (async () => {
+      try {
+        if (msg.op === "status") {
+          replyOk({ broker: true, hostConnected: !!host && !!host.socket && !host.socket.destroyed, claims: listClaims() });
+          return;
+        }
+
+        if (msg.op === "list_claims") {
+          replyOk({ claims: listClaims() });
+          return;
+        }
+
+        if (msg.op === "claim_tab") {
+          const tabId = msg.tabId;
+          const force = !!msg.force;
+          if (typeof tabId !== "number") throw new Error("tabId is required");
+          const existing = claims.get(tabId);
+          if (existing && existing.sessionId !== sessionId && !force) {
+            throw new Error(`Tab ${tabId} is owned by another OpenCode session (${existing.sessionId})`);
+          }
+          setClaim(tabId, sessionId);
+          replyOk({ ok: true, tabId, sessionId });
+          return;
+        }
+
+        if (msg.op === "release_tab") {
+          const tabId = msg.tabId;
+          if (typeof tabId !== "number") throw new Error("tabId is required");
+          const existing = claims.get(tabId);
+          if (!existing) {
+            replyOk({ ok: true, tabId, released: false });
+            return;
+          }
+          if (existing.sessionId !== sessionId) {
+            throw new Error(`Tab ${tabId} is owned by another OpenCode session (${existing.sessionId})`);
+          }
+          claims.delete(tabId);
+          replyOk({ ok: true, tabId, released: true });
+          return;
+        }
+
+        if (msg.op === "tool") {
+          const result = await handleTool(socket, { tool: msg.tool, args: msg.args || {}, sessionId });
+          replyOk(result);
+          return;
+        }
+
+        throw new Error(`Unknown op: ${msg.op}`);
+      } catch (e) {
+        replyErr(e);
+      }
+    })();
+
+    return;
+  }
+}
+
+function start() {
+  try {
+    if (fs.existsSync(SOCKET_PATH)) fs.unlinkSync(SOCKET_PATH);
+  } catch {
+    // ignore
+  }
+
+  const server = net.createServer((socket) => {
+    socket.setNoDelay(true);
+
+    const client = { role: "unknown", sessionId: null };
+    clients.add(client);
+
+    socket.on(
+      "data",
+      createJsonLineParser((msg) => handleClientMessage(socket, client, msg))
+    );
+
+    socket.on("close", () => {
+      clients.delete(client);
+      if (client.role === "native-host" && host && host.socket === socket) {
+        host = null;
+        // fail pending extension requests
+        for (const [extId, pending] of extPending.entries()) {
+          extPending.delete(extId);
+          if (pending.timeout) clearTimeout(pending.timeout);
+          pending.reject(new Error("Native host disconnected"));
+        }
+      }
+      if (client.sessionId) releaseClaimsForSession(client.sessionId);
+    });
+
+    socket.on("error", () => {
+      // close handler will clean up
+    });
+  });
+
+  server.listen(SOCKET_PATH, () => {
+    // Make socket group-readable; ignore errors
+    try {
+      fs.chmodSync(SOCKET_PATH, 0o600);
+    } catch {}
+    console.error(`[browser-broker] listening on ${SOCKET_PATH}`);
+  });
+
+  server.on("error", (err) => {
+    console.error("[browser-broker] server error", err);
+    process.exit(1);
+  });
+}
+
+start();