@different-ai/opencode-browser 2.0.2 → 2.1.0

package/README.md

@@ -41,7 +41,9 @@ Then load the extension in Chrome:
 | Tool | Description |
 |------|-------------|
 | `browser_status` | Check if browser is available or locked |
-| `browser_kill_session` | Take over from another OpenCode session |
+| `browser_kill_session` | Request other session release + take over (no kill) |
+| `browser_release` | Release lock and stop server |
+| `browser_force_kill_session` | (Last resort) kill other OpenCode process |
 | `browser_navigate` | Navigate to a URL |
 | `browser_click` | Click an element by CSS selector |
 | `browser_type` | Type text into an input field |
@@ -57,7 +59,9 @@ Then load the extension in Chrome:
 Only one OpenCode session can use the browser at a time. This prevents conflicts when you have multiple terminals open.
 
 - `browser_status` - Check who has the lock
-- `browser_kill_session` - Kill the other session and take over
+- `browser_kill_session` - Request the other session to release (no kill)
+- `browser_release` - Release lock/server for this session
+- `browser_force_kill_session` - (Last resort) kill the other OpenCode process and take over
 
 In your prompts, you can say:
 - "If browser is locked, kill the session and proceed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@different-ai/opencode-browser",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Browser automation plugin for OpenCode. Control your real Chrome browser with existing logins and cookies.",
   "type": "module",
   "bin": {

package/src/plugin.ts

@@ -1,18 +1,16 @@
 /**
  * OpenCode Browser Plugin
  *
- * A simple plugin that provides browser automation tools.
- * Connects to Chrome extension via WebSocket.
+ * OpenCode Plugin (this) <--WebSocket:19222--> Chrome Extension
  *
- * Architecture:
- *   OpenCode Plugin (this) <--WebSocket:19222--> Chrome Extension
- *
- * Lock file ensures only one OpenCode session uses browser at a time.
+ * Notes
+ * - Uses a lock file so only one OpenCode session owns the browser.
+ * - Supports a *soft takeover* (SIGUSR1) so we don't have to kill OpenCode.
  */
 
 import type { Plugin } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
-import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -21,7 +19,9 @@ const BASE_DIR = join(homedir(), ".opencode-browser");
 const LOCK_FILE = join(BASE_DIR, "lock.json");
 const SCREENSHOTS_DIR = join(BASE_DIR, "screenshots");
 
-// Ensure directories exist
+// If a session hasn't used the browser in this long, allow soft takeover by default.
+const LOCK_TTL_MS = 2 * 60 * 60 * 1000; // 2 hours
+
 mkdirSync(BASE_DIR, { recursive: true });
 mkdirSync(SCREENSHOTS_DIR, { recursive: true });
 
@@ -33,20 +33,19 @@ let isConnected = false;
 let server: ReturnType<typeof Bun.serve> | null = null;
 let pendingRequests = new Map<number, { resolve: (v: any) => void; reject: (e: Error) => void }>();
 let requestId = 0;
-let hasLock = false;
-let serverFailed = false;
-
-// ============================================================================
-// Lock File Management
-// ============================================================================
 
 interface LockInfo {
   pid: number;
   sessionId: string;
   startedAt: string;
+  lastUsedAt: string;
   cwd: string;
 }
 
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
 function readLock(): LockInfo | null {
   try {
     if (!existsSync(LOCK_FILE)) return null;
@@ -59,14 +58,40 @@ function readLock(): LockInfo | null {
 function writeLock(): void {
   writeFileSync(
     LOCK_FILE,
-    JSON.stringify({
-      pid,
-      sessionId,
-      startedAt: new Date().toISOString(),
-      cwd: process.cwd(),
-    } satisfies LockInfo)
+    JSON.stringify(
+      {
+        pid,
+        sessionId,
+        startedAt: nowIso(),
+        lastUsedAt: nowIso(),
+        cwd: process.cwd(),
+      } satisfies LockInfo,
+      null,
+      2
+    ) + "\n"
   );
-  hasLock = true;
+}
+
+function touchLock(): void {
+  const lock = readLock();
+  if (!lock) return;
+  if (lock.sessionId !== sessionId) return;
+
+  try {
+    writeFileSync(
+      LOCK_FILE,
+      JSON.stringify(
+        {
+          ...lock,
+          lastUsedAt: nowIso(),
+        } satisfies LockInfo,
+        null,
+        2
+      ) + "\n"
+    );
+  } catch {
+    // Ignore
+  }
 }
 
 function releaseLock(): void {
@@ -75,8 +100,9 @@ function releaseLock(): void {
     if (lock && lock.sessionId === sessionId) {
       unlinkSync(LOCK_FILE);
     }
-  } catch {}
-  hasLock = false;
+  } catch {
+    // Ignore
+  }
 }
 
 function isProcessAlive(targetPid: number): boolean {
@@ -88,78 +114,49 @@ function isProcessAlive(targetPid: number): boolean {
   }
 }
 
-function tryAcquireLock(): { success: boolean; error?: string; lock?: LockInfo } {
-  const existingLock = readLock();
-
-  if (!existingLock) {
-    writeLock();
-    return { success: true };
-  }
-
-  if (existingLock.sessionId === sessionId) {
-    return { success: true };
-  }
-
-  if (!isProcessAlive(existingLock.pid)) {
-    // Stale lock, take it
-    writeLock();
-    return { success: true };
-  }
-
-  return {
-    success: false,
-    error: `Browser locked by another session (PID ${existingLock.pid})`,
-    lock: existingLock,
-  };
+function lockAgeMs(lock: LockInfo): number {
+  const ts = lock.lastUsedAt || lock.startedAt;
+  const n = Date.parse(ts);
+  if (Number.isNaN(n)) return Number.POSITIVE_INFINITY;
+  return Date.now() - n;
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+function isLockExpired(lock: LockInfo): boolean {
+  return lockAgeMs(lock) > LOCK_TTL_MS;
 }
 
-async function killSession(targetPid: number): Promise<{ success: boolean; error?: string }> {
+function isPortFree(port: number): boolean {
   try {
-    process.kill(targetPid, "SIGTERM");
-    // Wait for process to die
-    let attempts = 0;
-    while (isProcessAlive(targetPid) && attempts < 10) {
-      await sleep(100);
-      attempts++;
-    }
-    if (isProcessAlive(targetPid)) {
-      process.kill(targetPid, "SIGKILL");
-    }
-    // Remove lock and acquire
-    try { unlinkSync(LOCK_FILE); } catch {}
-    writeLock();
-    return { success: true };
+    // If we can connect, something is already listening.
+    const testSocket = Bun.connect({ port, timeout: 300 });
+    testSocket.end();
+    return false;
   } catch (e) {
-    return { success: false, error: e instanceof Error ? e.message : String(e) };
+    if ((e as any).code === "ECONNREFUSED") return true;
+    return false;
   }
 }
 
-// ============================================================================
-// WebSocket Server
-// ============================================================================
+function stopBrowserServer(): void {
+  try {
+    (ws as any)?.close?.();
+  } catch {
+    // Ignore
+  }
+  ws = null;
+  isConnected = false;
 
-function checkPortAvailable(): boolean {
   try {
-    const testSocket = Bun.connect({ port: WS_PORT, timeout: 1000 });
-    testSocket.end();
-    return true;
-  } catch (e) {
-    if ((e as any).code === "ECONNREFUSED") {
-      return false;
-    }
-    return true;
+    server?.stop();
+  } catch {
+    // Ignore
   }
+  server = null;
 }
 
 function startServer(): boolean {
-  if (server) {
-    console.error(`[browser-plugin] Server already running`);
-    return true;
-  }
+  if (server) return true;
+  if (!isPortFree(WS_PORT)) return false;
 
   try {
     server = Bun.serve({
@@ -179,7 +176,7 @@ function startServer(): boolean {
           ws = null;
           isConnected = false;
         },
-        message(wsClient, data) {
+        message(_wsClient, data) {
           try {
             const message = JSON.parse(data.toString());
             handleMessage(message);
@@ -189,8 +186,8 @@ function startServer(): boolean {
         },
       },
     });
+
     console.error(`[browser-plugin] WebSocket server listening on port ${WS_PORT}`);
-    serverFailed = false;
     return true;
   } catch (e) {
     console.error(`[browser-plugin] Failed to start server:`, e);
@@ -198,19 +195,74 @@ function startServer(): boolean {
   }
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForExtensionConnection(timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (isConnected) return true;
+    await sleep(100);
+  }
+  return isConnected;
+}
+
+async function requestSessionRelease(targetPid: number, opts?: { timeoutMs?: number }): Promise<{ success: boolean; error?: string }> {
+  const timeoutMs = opts?.timeoutMs ?? 3000;
+
+  try {
+    // SIGUSR1 is treated as "release browser lock + stop server".
+    // This does NOT terminate OpenCode.
+    process.kill(targetPid, "SIGUSR1");
+  } catch (e) {
+    return { success: false, error: e instanceof Error ? e.message : String(e) };
+  }
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const lock = readLock();
+    const lockCleared = !lock || lock.pid !== targetPid;
+    const portCleared = isPortFree(WS_PORT);
+
+    if (lockCleared && portCleared) return { success: true };
+    await sleep(100);
+  }
+
+  return {
+    success: false,
+    error: `Timed out waiting for PID ${targetPid} to release browser`,
+  };
+}
+
+async function forceKillSession(targetPid: number): Promise<{ success: boolean; error?: string }> {
+  try {
+    process.kill(targetPid, "SIGTERM");
+    let attempts = 0;
+    while (isProcessAlive(targetPid) && attempts < 20) {
+      await sleep(100);
+      attempts++;
+    }
+    if (isProcessAlive(targetPid)) {
+      process.kill(targetPid, "SIGKILL");
+    }
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
 function handleMessage(message: { type: string; id?: number; result?: any; error?: any }): void {
   if (message.type === "tool_response" && message.id !== undefined) {
     const pending = pendingRequests.get(message.id);
-    if (pending) {
-      pendingRequests.delete(message.id);
-      if (message.error) {
-        pending.reject(new Error(message.error.content || String(message.error)));
-      } else {
-        pending.resolve(message.result?.content);
-      }
+    if (!pending) return;
+
+    pendingRequests.delete(message.id);
+    if (message.error) {
+      pending.reject(new Error(message.error.content || String(message.error)));
+    } else {
+      pending.resolve(message.result?.content);
     }
-  } else if (message.type === "pong") {
-    // Heartbeat response, ignore
   }
 }
 
@@ -222,15 +274,85 @@ function sendToChrome(message: any): boolean {
   return false;
 }
 
-async function executeCommand(tool: string, args: Record<string, any>): Promise<any> {
-  // Check lock and start server if needed
-  const lockResult = tryAcquireLock();
-  if (!lockResult.success) {
-    throw new Error(
-      `${lockResult.error}. Use browser_kill_session to take over, or browser_status to see details.`
+async function performTakeover(): Promise<string> {
+  const lock = readLock();
+
+  if (!lock) {
+    writeLock();
+  } else if (lock.sessionId === sessionId) {
+    // Already ours.
+  } else if (!isProcessAlive(lock.pid)) {
+    // Dead PID -> stale.
+    console.error(`[browser-plugin] Cleaning stale lock from dead PID ${lock.pid}`);
+    writeLock();
+  } else {
+    const ageMinutes = Math.round(lockAgeMs(lock) / 60000);
+    console.error(
+      `[browser-plugin] Requesting release from PID ${lock.pid} (last used ${ageMinutes}m ago)...`
     );
+    const released = await requestSessionRelease(lock.pid, { timeoutMs: 4000 });
+    if (!released.success) {
+      throw new Error(
+        `Failed to takeover without killing OpenCode: ${released.error}. ` +
+          `Try again, or use browser_force_kill_session as last resort.`
+      );
+    }
+    console.error(`[browser-plugin] Previous session released gracefully.`);
+    writeLock();
   }
 
+  touchLock();
+
+  if (!server) {
+    if (!startServer()) {
+      throw new Error("Failed to start WebSocket server after takeover.");
+    }
+  }
+
+  const ok = await waitForExtensionConnection(3000);
+  if (!ok) {
+    throw new Error("Took over lock but Chrome extension did not connect.");
+  }
+
+  return "Browser now connected to this session.";
+}
+
+async function ensureLockAndServer(): Promise<void> {
+  const existingLock = readLock();
+
+  if (!existingLock) {
+    writeLock();
+  } else if (existingLock.sessionId === sessionId) {
+    // Already ours.
+  } else if (!isProcessAlive(existingLock.pid)) {
+    // Stale lock (dead PID).
+    console.error(`[browser-plugin] Cleaning stale lock from dead PID ${existingLock.pid}`);
+    writeLock();
+  } else {
+    // Another session holds the lock - attempt automatic soft takeover
+    const ageMinutes = Math.round(lockAgeMs(existingLock) / 60000);
+    console.error(
+      `[browser-plugin] Browser locked by PID ${existingLock.pid} (last used ${ageMinutes}m ago). Attempting auto-takeover...`
+    );
+
+    const released = await requestSessionRelease(existingLock.pid, { timeoutMs: 4000 });
+    if (released.success) {
+      console.error(`[browser-plugin] Auto-takeover succeeded. Previous session released gracefully.`);
+      writeLock();
+    } else {
+      // Soft takeover failed - provide helpful error
+      const expired = isLockExpired(existingLock);
+      const why = expired ? "expired" : "active";
+      throw new Error(
+        `Browser locked by another session (PID ${existingLock.pid}, ${why}). ` +
+          `Auto-takeover failed: ${released.error}. ` +
+          `Use browser_force_kill_session as last resort, or browser_status for details.`
+      );
+    }
+  }
+
+  touchLock();
+
   if (!server) {
     if (!startServer()) {
       throw new Error("Failed to start WebSocket server. Port may be in use.");
@@ -238,12 +360,20 @@ async function executeCommand(tool: string, args: Record<string, any>): Promise<
   }
 
   if (!isConnected) {
-    throw new Error(
-      "Chrome extension not connected. Make sure Chrome is running with the OpenCode Browser extension enabled."
-    );
+    const ok = await waitForExtensionConnection(3000);
+    if (!ok) {
+      throw new Error(
+        "Chrome extension not connected. Make sure Chrome is running with the OpenCode Browser extension enabled."
+      );
+    }
   }
+}
+
+async function executeCommand(toolName: string, args: Record<string, any>): Promise<any> {
+  await ensureLockAndServer();
 
   const id = ++requestId;
+  touchLock();
 
   return new Promise((resolve, reject) => {
     pendingRequests.set(id, { resolve, reject });
@@ -251,33 +381,38 @@ async function executeCommand(tool: string, args: Record<string, any>): Promise<
     sendToChrome({
       type: "tool_request",
       id,
-      tool,
+      tool: toolName,
       args,
     });
 
-    // Timeout after 60 seconds
     setTimeout(() => {
-      if (pendingRequests.has(id)) {
-        pendingRequests.delete(id);
-        reject(new Error("Tool execution timed out after 60 seconds"));
-      }
+      if (!pendingRequests.has(id)) return;
+      pendingRequests.delete(id);
+      reject(new Error("Tool execution timed out after 60 seconds"));
     }, 60000);
   });
 }
 
 // ============================================================================
-// Cleanup on exit
+// Cleanup / Signals
 // ============================================================================
 
+// Soft release: do NOT exit the OpenCode process.
+process.on("SIGUSR1", () => {
+  console.error(`[browser-plugin] SIGUSR1: releasing lock + stopping server`);
+  releaseLock();
+  stopBrowserServer();
+});
+
 process.on("SIGTERM", () => {
   releaseLock();
-  server?.stop();
+  stopBrowserServer();
   process.exit(0);
 });
 
 process.on("SIGINT", () => {
   releaseLock();
-  server?.stop();
+  stopBrowserServer();
   process.exit(0);
 });
 
@@ -289,38 +424,9 @@ process.on("exit", () => {
 // Plugin Export
 // ============================================================================
 
-export const BrowserPlugin: Plugin = async (ctx) => {
+export const BrowserPlugin: Plugin = async (_ctx) => {
   console.error(`[browser-plugin] Initializing (session ${sessionId})`);
 
-  // Check port availability on load, don't try to acquire lock yet
-  checkPortAvailable();
-
-  // Check lock status and set appropriate state
-  const lock = readLock();
-  if (!lock) {
-    // No lock - just check if we can start server
-    console.error(`[browser-plugin] No lock file, checking port...`);
-    if (!startServer()) {
-      serverFailed = true;
-    }
-  } else if (lock.sessionId === sessionId) {
-    // We own the lock - start server
-    console.error(`[browser-plugin] Already have lock, starting server...`);
-    if (!startServer()) {
-      serverFailed = true;
-    }
-  } else if (!isProcessAlive(lock.pid)) {
-    // Stale lock - take it and start server
-    console.error(`[browser-plugin] Stale lock from dead PID ${lock.pid}, taking over...`);
-    writeLock();
-    if (!startServer()) {
-      serverFailed = true;
-    }
-  } else {
-    // Another session has the lock
-    console.error(`[browser-plugin] Lock held by PID ${lock.pid}, tools will fail until lock is released`);
-  }
-
   return {
     tool: {
       browser_status: tool({
@@ -335,33 +441,77 @@ export const BrowserPlugin: Plugin = async (ctx) => {
           }
 
           if (lock.sessionId === sessionId) {
-            return `Browser connected (this session)\nPID: ${pid}\nStarted: ${lock.startedAt}\nExtension: ${isConnected ? "connected" : "not connected"}`;
+            return (
+              `Browser connected (this session)\n` +
+              `PID: ${pid}\n` +
+              `Started: ${lock.startedAt}\n` +
+              `Last used: ${lock.lastUsedAt}\n` +
+              `Extension: ${isConnected ? "connected" : "not connected"}`
+            );
           }
 
-          if (!isProcessAlive(lock.pid)) {
-            return `Browser available (stale lock from dead PID ${lock.pid} will be auto-cleaned)`;
+          const alive = isProcessAlive(lock.pid);
+          const ageMinutes = Math.round(lockAgeMs(lock) / 60000);
+          const expired = isLockExpired(lock);
+
+          if (!alive) {
+            return `Browser available (stale lock from dead PID ${lock.pid} will be auto-cleaned on next command)`;
+          }
+
+          return (
+            `Browser locked by another session\n` +
+            `PID: ${lock.pid}\n` +
+            `Session: ${lock.sessionId}\n` +
+            `Started: ${lock.startedAt}\n` +
+            `Last used: ${lock.lastUsedAt} (~${ageMinutes}m ago)${expired ? " [expired]" : ""}\n` +
+            `Working directory: ${lock.cwd}\n\n` +
+            `Use browser_takeover to request release (no kill), or browser_force_kill_session as last resort.`
+          );
+        },
+      }),
+
+      browser_release: tool({
+        description: "Release browser lock and stop the server for this session.",
+        args: {},
+        async execute() {
+          const lock = readLock();
+          if (lock && lock.sessionId !== sessionId) {
+            throw new Error("This session does not own the browser lock.");
           }
 
-          return `Browser locked by another session\nPID: ${lock.pid}\nSession: ${lock.sessionId}\nStarted: ${lock.startedAt}\nWorking directory: ${lock.cwd}\n\nUse browser_kill_session to take over.`;
+          releaseLock();
+          stopBrowserServer();
+          return "Released browser lock for this session.";
+        },
+      }),
+
+      browser_takeover: tool({
+        description:
+          "Request the session holding the browser lock to release it (no process kill), then take over.",
+        args: {},
+        async execute() {
+          return await performTakeover();
         },
       }),
 
       browser_kill_session: tool({
         description:
-          "Kill the session that currently holds the browser lock and take over. Use when browser_status shows another session has the lock.",
+          "(Deprecated name) Soft takeover without killing OpenCode. Prefer browser_takeover.",
+        args: {},
+        async execute() {
+          // Keep backward compatibility: old callers use this.
+          return await performTakeover();
+        },
+      }),
+
+      browser_force_kill_session: tool({
+        description: "Force kill the session holding the browser lock (last resort).",
         args: {},
         async execute() {
           const lock = readLock();
 
           if (!lock) {
-            // No lock, just acquire
             writeLock();
-            // Start server if needed
-            if (!server) {
-              if (!startServer()) {
-                throw new Error("Failed to start WebSocket server after acquiring lock.");
-              }
-            }
             return "No active session. Browser now connected to this session.";
           }
 
@@ -370,29 +520,36 @@ export const BrowserPlugin: Plugin = async (ctx) => {
           }
 
           if (!isProcessAlive(lock.pid)) {
-            // Stale lock
             writeLock();
-            // Start server if needed
-            if (!server) {
-              if (!startServer()) {
-                throw new Error("Failed to start WebSocket server after cleaning stale lock.");
-              }
-            }
             return `Cleaned stale lock (PID ${lock.pid} was dead). Browser now connected to this session.`;
           }
 
-          // Kill other session and wait for port to be free
-          const result = await killSession(lock.pid);
-          if (result.success) {
-            if (!server) {
-              if (!startServer()) {
-                throw new Error("Failed to start WebSocket server after killing other session.");
-              }
+          const result = await forceKillSession(lock.pid);
+          if (!result.success) {
+            throw new Error(`Failed to force kill session: ${result.error}`);
+          }
+
+          // Best-effort cleanup; then take lock.
+          try {
+            unlinkSync(LOCK_FILE);
+          } catch {
+            // Ignore
+          }
+
+          writeLock();
+
+          if (!server) {
+            if (!startServer()) {
+              throw new Error("Failed to start WebSocket server after force kill.");
             }
-            return `Killed session ${lock.sessionId} (PID ${lock.pid}). Browser now connected to this session.`;
-          } else {
-            throw new Error(`Failed to kill session: ${result.error}`);
           }
+
+          const ok = await waitForExtensionConnection(3000);
+          if (!ok) {
+            throw new Error("Force-killed lock holder but Chrome extension did not connect.");
+          }
+
+          return `Force-killed session ${lock.sessionId} (PID ${lock.pid}). Browser now connected to this session.`;
         },
       }),
 
@@ -439,10 +596,10 @@ export const BrowserPlugin: Plugin = async (ctx) => {
             tool.schema.string({ description: "Optional name for screenshot file (without extension)" })
           ),
         },
-        async execute(args) {
+        async execute(args: { tabId?: number; name?: string }) {
           const result = await executeCommand("screenshot", args);
 
-          if (result && result.startsWith("data:image")) {
+          if (result && typeof result === "string" && result.startsWith("data:image")) {
             const base64Data = result.replace(/^data:image\/\w+;base64,/, "");
             const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
             const filename = args.name ? `${args.name}.png` : `screenshot-${timestamp}.png`;