@different-ai/opencode-browser 4.3.2 → 4.5.0

package/.opencode/skill/browser-automation/SKILL.md

@@ -21,9 +21,15 @@ metadata:
 3. Navigate with `browser_navigate` if needed
 4. Wait for UI using `browser_query` with `timeoutMs`
 5. Discover candidates using `browser_query` with `mode=list`
-6. Click or type using `index`
+6. Click, type, or select using `index`
 7. Confirm using `browser_query` or `browser_snapshot`
 
+## Selecting options
+
+- Use `browser_select` for native `<select>` elements
+- Prefer `value` or `label`; use `optionIndex` when needed
+- Example: `browser_select({ selector: "select", value: "plugin" })`
+
 ## Query modes
 
 - `text`: read visible text from a matched element

package/README.md

@@ -1,6 +1,6 @@
 # OpenCode Browser
 
-Browser automation plugin for [OpenCode](https://github.com/opencode-ai/opencode).
+Browser automation plugin for [OpenCode](https://opencode.ai).
 
 Control your real Chromium browser (Chrome/Brave/Arc/Edge) using your existing profile (logins, cookies, bookmarks). No DevTools Protocol, no security prompts.
 
@@ -34,11 +34,15 @@ The installer will:
 
 1. Copy the extension to `~/.opencode-browser/extension/`
 2. Walk you through loading + pinning it in `chrome://extensions`
-3. Ask for the extension ID and install a **Native Messaging Host manifest**
+3. Resolve a fixed extension ID (no copy/paste) and install a **Native Messaging Host manifest**
 4. Update your `opencode.json` or `opencode.jsonc` to load the plugin
 
+To override the extension ID, pass `--extension-id <id>` or set `OPENCODE_BROWSER_EXTENSION_ID`.
+
 ### Configure OpenCode
 
+> Note: if you run the installer you'll be prompted to include this automatically. If you said "yes", you can skip this part.
+
 Your `opencode.json` or `opencode.jsonc` should contain:
 
 ```json
@@ -48,6 +52,12 @@ Your `opencode.json` or `opencode.jsonc` should contain:
 }
 ```
 
+### Update
+
+```bash
+bunx @different-ai/opencode-browser@latest update
+```
+
 ## How it works
 
 ```
@@ -58,26 +68,80 @@ OpenCode Plugin <-> Local Broker (unix socket) <-> Native Host <-> Chrome Extens
 - The plugin talks to the broker over a local unix socket.
 - The broker forwards tool requests to the extension and enforces tab ownership.
 
+## Agent Browser mode (alpha)
+
+This branch adds an alternate backend powered by `agent-browser` (Playwright). It runs headless and does **not** reuse your existing Chrome profile.
+
+### Enable locally
+
+1. Install `agent-browser` and Chromium:
+
+```bash
+npm install -g agent-browser
+agent-browser install
+```
+
+2. Set the backend mode:
+
+```bash
+export OPENCODE_BROWSER_BACKEND=agent
+```
+
+Optional overrides:
+- `OPENCODE_BROWSER_AGENT_SESSION` (custom session name)
+- `OPENCODE_BROWSER_AGENT_SOCKET` (unix socket path)
+- `OPENCODE_BROWSER_AGENT_AUTOSTART=0` (disable auto-start)
+- `OPENCODE_BROWSER_AGENT_DAEMON` (explicit daemon path)
+
+### Tailnet/remote host
+
+On the host (e.g., `home-server.taild435d7.ts.net`), run the TCP gateway:
+
+```bash
+OPENCODE_BROWSER_AGENT_GATEWAY_PORT=9833 node bin/agent-gateway.cjs
+```
+
+On the client:
+
+```bash
+export OPENCODE_BROWSER_BACKEND=agent
+export OPENCODE_BROWSER_AGENT_HOST=home-server.taild435d7.ts.net
+export OPENCODE_BROWSER_AGENT_PORT=9833
+```
+
 ## Per-tab ownership
 
 - 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.
-- Use `browser_status` to inspect claims if needed.
+- Each session tracks a default tab; tools without `tabId` route to it.
+- `browser_open_tab` always works; if another session owns the active tab, the new tab opens in the background.
+- Claims expire after inactivity (`OPENCODE_BROWSER_CLAIM_TTL_MS`, default 5 minutes).
+- Use `browser_status` or `browser_list_claims` to inspect claims if needed.
 
 ## Available tools
 
 Core primitives:
 - `browser_status`
 - `browser_get_tabs`
+- `browser_list_claims`
+- `browser_claim_tab`
+- `browser_release_tab`
 - `browser_open_tab`
 - `browser_navigate`
 - `browser_query` (modes: `text`, `value`, `list`, `exists`, `page_text`; optional `timeoutMs`/`pollMs`)
-- `browser_click`
-- `browser_type`
-- `browser_select`
-- `browser_scroll`
+- `browser_click` (optional `timeoutMs`/`pollMs`)
+- `browser_type` (optional `timeoutMs`/`pollMs`)
+- `browser_select` (optional `timeoutMs`/`pollMs`)
+- `browser_scroll` (optional `timeoutMs`/`pollMs`)
 - `browser_wait`
 
+Selector helpers (usable in `selector`):
+- `label:Mailing Address: City`
+- `aria:Principal Address: City`
+- `placeholder:Search`, `name:email`, `role:button`, `text:Submit`
+- `css:label:has(input)` to force CSS
+
+Selector-based tools wait up to 2000ms by default; set `timeoutMs: 0` to disable.
+
 Diagnostics:
 - `browser_snapshot`
 - `browser_screenshot`
@@ -95,11 +159,11 @@ Diagnostics:
 
 **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`
+- If you loaded a custom extension ID, rerun with `--extension-id <id>`
 
 **Tab ownership errors**
-- Use `browser_status` to see current claims
-- Close the other OpenCode session to release ownership
+- Use `browser_status` or `browser_list_claims` to see current claims
+- Use `browser_release_tab` or close the other OpenCode session to release ownership
 
 ## Uninstall
 

package/bin/agent-gateway.cjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+"use strict";
+
+const net = require("net");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+
+const session =
+  (process.env.OPENCODE_BROWSER_AGENT_SESSION || process.env.AGENT_BROWSER_SESSION || "default").trim();
+const socketPath =
+  process.env.OPENCODE_BROWSER_AGENT_SOCKET || path.join(os.tmpdir(), `agent-browser-${session}.sock`);
+
+function getPortForSession(name) {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = (hash << 5) - hash + name.charCodeAt(i);
+    hash |= 0;
+  }
+  return 49152 + (Math.abs(hash) % 16383);
+}
+
+const host = process.env.OPENCODE_BROWSER_AGENT_GATEWAY_HOST || process.env.OPENCODE_BROWSER_AGENT_HOST || "0.0.0.0";
+const port =
+  Number(process.env.OPENCODE_BROWSER_AGENT_GATEWAY_PORT || process.env.OPENCODE_BROWSER_AGENT_PORT) ||
+  getPortForSession(session);
+
+function resolveDaemonPath() {
+  const override = process.env.OPENCODE_BROWSER_AGENT_DAEMON;
+  if (override) return override;
+  try {
+    return require.resolve("agent-browser/dist/daemon.js");
+  } catch {
+    return null;
+  }
+}
+
+function shouldAutoStart() {
+  const autoStart = (process.env.OPENCODE_BROWSER_AGENT_AUTOSTART || "").toLowerCase();
+  return !["0", "false", "no"].includes(autoStart);
+}
+
+function startDaemon() {
+  if (!shouldAutoStart()) return;
+  const daemonPath = resolveDaemonPath();
+  if (!daemonPath) {
+    console.error("[agent-gateway] agent-browser dependency not found.");
+    return;
+  }
+  try {
+    const child = spawn(process.execPath, [daemonPath], {
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        AGENT_BROWSER_SESSION: session,
+        AGENT_BROWSER_DAEMON: "1",
+      },
+    });
+    child.unref();
+  } catch (err) {
+    console.error("[agent-gateway] Failed to start daemon:", err?.message || err);
+  }
+}
+
+async function sleep(ms) {
+  return await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function connectAgentSocket() {
+  return await new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    socket.once("connect", () => resolve(socket));
+    socket.once("error", (err) => reject(err));
+  });
+}
+
+async function createAgentConnection() {
+  try {
+    return await connectAgentSocket();
+  } catch {
+    startDaemon();
+    for (let attempt = 0; attempt < 20; attempt++) {
+      await sleep(100);
+      try {
+        return await connectAgentSocket();
+      } catch {}
+    }
+    throw new Error(`Could not connect to agent-browser socket at ${socketPath}`);
+  }
+}
+
+const server = net.createServer(async (client) => {
+  let upstream = null;
+  try {
+    upstream = await createAgentConnection();
+  } catch (err) {
+    client.end();
+    console.error("[agent-gateway] Connection failed:", err?.message || err);
+    return;
+  }
+
+  client.pipe(upstream);
+  upstream.pipe(client);
+
+  const close = () => {
+    try {
+      client.destroy();
+    } catch {}
+    try {
+      upstream.destroy();
+    } catch {}
+  };
+
+  client.on("error", close);
+  upstream.on("error", close);
+  client.on("close", close);
+  upstream.on("close", close);
+});
+
+server.on("error", (err) => {
+  console.error("[agent-gateway] Server error:", err?.message || err);
+  process.exit(1);
+});
+
+server.listen(port, host, () => {
+  console.log(`[agent-gateway] Listening on ${host}:${port}`);
+  console.log(`[agent-gateway] Proxying to ${socketPath}`);
+});

package/bin/broker.cjs

@@ -11,6 +11,20 @@ const SOCKET_PATH = path.join(BASE_DIR, "broker.sock");
 
 fs.mkdirSync(BASE_DIR, { recursive: true });
 
+const DEFAULT_LEASE_TTL_MS = 5 * 60 * 1000;
+const LEASE_TTL_MS = (() => {
+  const raw = process.env.OPENCODE_BROWSER_CLAIM_TTL_MS;
+  const value = Number(raw);
+  if (Number.isFinite(value) && value >= 0) return value;
+  return DEFAULT_LEASE_TTL_MS;
+})();
+const LEASE_SWEEP_MS =
+  LEASE_TTL_MS > 0 ? Math.min(Math.max(10000, Math.floor(LEASE_TTL_MS / 2)), 60000) : 0;
+
+function nowMs() {
+  return Date.now();
+}
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -39,7 +53,7 @@ function writeJsonLine(socket, msg) {
 }
 
 function wantsTab(toolName) {
-  return !["get_tabs", "get_active_tab"].includes(toolName);
+  return !["get_tabs", "get_active_tab", "open_tab"].includes(toolName);
 }
 
 // --- State ---
@@ -49,22 +63,78 @@ const extPending = new Map(); // extId -> { pluginSocket, pluginRequestId, sessi
 
 const clients = new Set();
 
-// Tab ownership: tabId -> { sessionId, claimedAt }
+// Tab ownership: tabId -> { sessionId, claimedAt, lastSeenAt }
 const claims = new Map();
+// Session state: sessionId -> { defaultTabId, lastSeenAt }
+const sessionState = new Map();
 
 function listClaims() {
   const out = [];
   for (const [tabId, info] of claims.entries()) {
-    out.push({ tabId, ...info });
+    out.push({
+      tabId,
+      sessionId: info.sessionId,
+      claimedAt: info.claimedAt,
+      lastSeenAt: new Date(info.lastSeenAt).toISOString(),
+    });
   }
   out.sort((a, b) => a.tabId - b.tabId);
   return out;
 }
 
+function sessionHasClaims(sessionId) {
+  for (const info of claims.values()) {
+    if (info.sessionId === sessionId) return true;
+  }
+  return false;
+}
+
+function getSessionState(sessionId) {
+  if (!sessionId) return null;
+  let state = sessionState.get(sessionId);
+  if (!state) {
+    state = { defaultTabId: null, lastSeenAt: nowMs() };
+    sessionState.set(sessionId, state);
+  }
+  return state;
+}
+
+function touchSession(sessionId) {
+  const state = getSessionState(sessionId);
+  if (!state) return null;
+  state.lastSeenAt = nowMs();
+  return state;
+}
+
+function setDefaultTab(sessionId, tabId) {
+  const state = getSessionState(sessionId);
+  if (!state) return;
+  state.defaultTabId = tabId;
+  state.lastSeenAt = nowMs();
+}
+
+function clearDefaultTab(sessionId, tabId) {
+  const state = sessionState.get(sessionId);
+  if (!state) return;
+  if (tabId === undefined || state.defaultTabId === tabId) {
+    state.defaultTabId = null;
+  }
+  state.lastSeenAt = nowMs();
+}
+
+function releaseClaim(tabId) {
+  const info = claims.get(tabId);
+  if (!info) return;
+  claims.delete(tabId);
+  clearDefaultTab(info.sessionId, tabId);
+}
+
 function releaseClaimsForSession(sessionId) {
   for (const [tabId, info] of claims.entries()) {
     if (info.sessionId === sessionId) claims.delete(tabId);
   }
+  clearDefaultTab(sessionId);
+  sessionState.delete(sessionId);
 }
 
 function checkClaim(tabId, sessionId) {
@@ -75,7 +145,37 @@ function checkClaim(tabId, sessionId) {
 }
 
 function setClaim(tabId, sessionId) {
-  claims.set(tabId, { sessionId, claimedAt: nowIso() });
+  const existing = claims.get(tabId);
+  claims.set(tabId, {
+    sessionId,
+    claimedAt: existing ? existing.claimedAt : nowIso(),
+    lastSeenAt: nowMs(),
+  });
+}
+
+function touchClaim(tabId, sessionId) {
+  const existing = claims.get(tabId);
+  if (existing && existing.sessionId !== sessionId) return;
+  if (existing) {
+    existing.lastSeenAt = nowMs();
+  } else {
+    setClaim(tabId, sessionId);
+  }
+}
+
+function cleanupStaleClaims() {
+  if (!LEASE_TTL_MS) return;
+  const now = nowMs();
+  for (const [tabId, info] of claims.entries()) {
+    if (now - info.lastSeenAt > LEASE_TTL_MS) {
+      releaseClaim(tabId);
+    }
+  }
+  for (const [sessionId, state] of sessionState.entries()) {
+    if (!sessionHasClaims(sessionId) && now - state.lastSeenAt > LEASE_TTL_MS) {
+      sessionState.delete(sessionId);
+    }
+  }
 }
 
 function ensureHost() {
@@ -117,25 +217,47 @@ async function handleTool(pluginSocket, req) {
   const { tool, args = {}, sessionId } = req;
   if (!tool) throw new Error("Missing tool");
 
+  if (sessionId) touchSession(sessionId);
+
   let tabId = args.tabId;
+  const toolArgs = { ...args };
+
+  if (tool === "open_tab" && toolArgs.active !== false) {
+    const activeTabId = await resolveActiveTab(sessionId);
+    const claimCheck = checkClaim(activeTabId, sessionId);
+    if (!claimCheck.ok) {
+      toolArgs.active = false;
+    }
+  }
 
   if (wantsTab(tool)) {
     if (typeof tabId !== "number") {
-      tabId = await resolveActiveTab(sessionId);
+      const state = getSessionState(sessionId);
+      const defaultTabId = state && Number.isFinite(state.defaultTabId) ? state.defaultTabId : null;
+      if (Number.isFinite(defaultTabId)) {
+        tabId = defaultTabId;
+      } else {
+        const activeTabId = await resolveActiveTab(sessionId);
+        const claimCheck = checkClaim(activeTabId, sessionId);
+        if (!claimCheck.ok) {
+          throw new Error(`${claimCheck.error}. No default tab for session; open a new tab or claim one.`);
+        }
+        tabId = activeTabId;
+        setDefaultTab(sessionId, tabId);
+      }
     }
 
     const claimCheck = checkClaim(tabId, sessionId);
     if (!claimCheck.ok) throw new Error(claimCheck.error);
   }
 
-  const res = await callExtension(tool, { ...args, tabId }, sessionId);
+  const res = await callExtension(tool, { ...toolArgs, 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);
+    touchClaim(usedTabId, sessionId);
+    setDefaultTab(sessionId, usedTabId);
   }
 
   return res;
@@ -145,6 +267,7 @@ function handleClientMessage(socket, client, msg) {
   if (msg && msg.type === "hello") {
     client.role = msg.role || "unknown";
     client.sessionId = msg.sessionId;
+    if (client.sessionId) touchSession(client.sessionId);
     if (client.role === "native-host") {
       host = { socket };
       // allow host to see current state
@@ -174,6 +297,7 @@ function handleClientMessage(socket, client, msg) {
   if (msg && msg.type === "request" && typeof msg.id === "number") {
     const requestId = msg.id;
     const sessionId = msg.sessionId || client.sessionId;
+    if (sessionId) touchSession(sessionId);
 
     const replyOk = (data) => writeJsonLine(socket, { type: "response", id: requestId, ok: true, data });
     const replyErr = (err) =>
@@ -182,7 +306,21 @@ function handleClientMessage(socket, client, msg) {
     (async () => {
       try {
         if (msg.op === "status") {
-          replyOk({ broker: true, hostConnected: !!host && !!host.socket && !host.socket.destroyed, claims: listClaims() });
+          const state = sessionId ? sessionState.get(sessionId) : null;
+          const sessionInfo = state
+            ? {
+                sessionId,
+                defaultTabId: state.defaultTabId,
+                lastSeenAt: new Date(state.lastSeenAt).toISOString(),
+              }
+            : null;
+          replyOk({
+            broker: true,
+            hostConnected: !!host && !!host.socket && !host.socket.destroyed,
+            claims: listClaims(),
+            leaseTtlMs: LEASE_TTL_MS,
+            session: sessionInfo,
+          });
           return;
         }
 
@@ -199,7 +337,11 @@ function handleClientMessage(socket, client, msg) {
           if (existing && existing.sessionId !== sessionId && !force) {
             throw new Error(`Tab ${tabId} is owned by another OpenCode session (${existing.sessionId})`);
           }
+          if (existing && existing.sessionId !== sessionId && force) {
+            clearDefaultTab(existing.sessionId, tabId);
+          }
           setClaim(tabId, sessionId);
+          setDefaultTab(sessionId, tabId);
           replyOk({ ok: true, tabId, sessionId });
           return;
         }
@@ -215,7 +357,7 @@ function handleClientMessage(socket, client, msg) {
           if (existing.sessionId !== sessionId) {
             throw new Error(`Tab ${tabId} is owned by another OpenCode session (${existing.sessionId})`);
           }
-          claims.delete(tabId);
+          releaseClaim(tabId);
           replyOk({ ok: true, tabId, released: true });
           return;
         }
@@ -287,4 +429,9 @@ function start() {
   });
 }
 
+if (LEASE_TTL_MS > 0 && LEASE_SWEEP_MS > 0) {
+  const timer = setInterval(cleanupStaleClaims, LEASE_SWEEP_MS);
+  if (typeof timer.unref === "function") timer.unref();
+}
+
 start();