@jackwener/opencli 1.5.6 → 1.5.8

package/docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md

@@ -0,0 +1,208 @@
+# Daemon Lifecycle Redesign
+
+## Problem
+
+OpenCLI's daemon auto-exits after 5 minutes of idle time. During typical development
+cycles (write code → test → modify → test again), coding intervals frequently exceed
+5 minutes. Each restart incurs 2-4 seconds of overhead (process spawn + Extension
+WebSocket reconnection), creating a noticeable and frustrating delay.
+
+The current design treats the daemon as a disposable process, but the actual cost
+profile doesn't justify this:
+
+| Cost of staying alive | Cost of restarting |
+|-----------------------|--------------------|
+| ~12 MB memory, 0% CPU | 2-4 seconds delay per restart |
+
+The restart cost far outweighs the idle cost.
+
+## Solution
+
+Replace the aggressive 5-minute fixed timeout with a long-lived daemon model. The
+daemon stays running for hours, exits only when truly abandoned, and reconnects to
+the Chrome Extension faster when needed.
+
+Four changes:
+
+1. Extend idle timeout from 5 minutes to 4 hours (configurable)
+2. Require dual idle condition: both no CLI requests AND no Extension connection
+3. Reduce Extension WebSocket reconnect backoff cap from 60s to 5s
+4. Add `opencli daemon status/stop/restart` commands
+
+## Design
+
+### Timeout Strategy
+
+**Current behavior:** A single idle timer resets on each HTTP request. After 5
+minutes without a request, the daemon calls `process.exit(0)`.
+
+**New behavior:** The daemon tracks two activity signals independently:
+
+- **CLI activity:** timestamp of the last HTTP request from any CLI invocation
+- **Extension activity:** whether a WebSocket connection from the Chrome Extension
+  is currently open
+
+The exit countdown starts only when BOTH conditions are met simultaneously:
+
+- No CLI request for `IDLE_TIMEOUT` duration
+- No Extension WebSocket connection
+
+If either signal is active, the daemon stays alive. This means:
+
+- A connected Extension keeps the daemon alive indefinitely (user has Chrome open,
+  likely still working)
+- Recent CLI activity keeps the daemon alive even if Extension temporarily
+  disconnects (Chrome restarting, Extension updating)
+
+**Timeout value:** 4 hours by default, configurable via `OPENCLI_DAEMON_TIMEOUT`
+environment variable. Value in milliseconds. Set to `0` to disable timeout entirely.
+
+```typescript
+const DEFAULT_IDLE_TIMEOUT = 4 * 60 * 60 * 1000; // 4 hours
+const IDLE_TIMEOUT = Number(process.env.OPENCLI_DAEMON_TIMEOUT ?? DEFAULT_IDLE_TIMEOUT);
+```
+
+**Timer implementation:**
+
+```
+resetIdleTimer():
+  clear existing timer
+  if Extension is connected:
+    do not start timer (Extension connection keeps daemon alive)
+    return
+  start timer with IDLE_TIMEOUT duration
+  on timeout: process.exit(0)
+
+On CLI HTTP request:
+  update lastRequestTime
+  resetIdleTimer()
+
+On Extension WebSocket connect:
+  clear timer (Extension keeps daemon alive)
+
+On Extension WebSocket disconnect:
+  elapsed = now - lastRequestTime
+  if elapsed >= IDLE_TIMEOUT:
+    process.exit(0)  // CLI has been idle long enough already
+  else:
+    start timer with (IDLE_TIMEOUT - elapsed)  // count remaining time
+```
+
+### Extension Fast Reconnect
+
+**Current behavior:** When the Extension loses its WebSocket connection to the
+daemon, it reconnects with exponential backoff: 2s → 4s → 8s → 16s → 32s → 60s
+(capped). In the worst case, the Extension waits up to 60 seconds before attempting
+reconnection.
+
+**New behavior:** Cap the backoff at 5 seconds instead of 60 seconds.
+
+```typescript
+// extension/src/background.ts
+const WS_RECONNECT_MAX_DELAY = 5000; // was 60000
+```
+
+Rationale: with a 4-hour daemon timeout, the daemon is almost always running. Long
+backoff intervals are unnecessary and only increase reconnection latency. A 5-second
+cap means the Extension reconnects within 5 seconds of the daemon becoming available.
+
+### Daemon Management Commands
+
+Add three new CLI commands for daemon lifecycle management:
+
+**`opencli daemon status`**
+
+Queries the daemon's `/status` endpoint (new) and displays:
+
+```
+Daemon: running (PID 12345)
+Uptime: 2h 15m
+Extension: connected
+Last CLI request: 8 min ago
+Memory: 12.3 MB
+Port: 19825
+```
+
+If daemon is not running:
+
+```
+Daemon: not running
+```
+
+**`opencli daemon stop`**
+
+Sends a `POST /shutdown` request to the daemon, which triggers a graceful shutdown:
+reject pending requests with a shutdown message, close WebSocket connections, close
+HTTP server, then exit.
+
+**`opencli daemon restart`**
+
+Equivalent to `stop` followed by spawning a new daemon. Useful when the daemon gets
+into a bad state.
+
+**Daemon-side endpoints:**
+
+- `GET /status` — returns JSON with PID, uptime, extension connection state, last
+  request time, memory usage
+- `POST /shutdown` — initiates graceful shutdown
+
+Both endpoints require the same `X-OpenCLI` header as existing endpoints for CSRF
+protection.
+
+### CLI Connection Experience
+
+**Current behavior:** When daemon is running but Extension is not connected, the CLI
+silently polls every 300ms and eventually times out with a generic error.
+
+**New behavior:** Show a progress indicator and actionable message:
+
+```
+⏳ Waiting for Chrome extension to connect...
+   Make sure Chrome is open and the OpenCLI extension is enabled.
+```
+
+Poll interval reduced from 300ms to 200ms for slightly faster detection.
+
+If the daemon is not running at all (connection refused), the CLI spawns it as before
+and shows:
+
+```
+⏳ Starting daemon...
+```
+
+## Files Changed
+
+| File | Change | Estimated LOC |
+|------|--------|---------------|
+| `src/daemon.ts` | Dual-condition idle timeout, `/status` endpoint, `/shutdown` endpoint | ~40 |
+| `extension/src/background.ts` | `WS_RECONNECT_MAX_DELAY` 60000 → 5000 | 1 |
+| `src/browser/daemon-client.ts` | Better connection-waiting UX, 200ms poll interval | ~20 |
+| `src/commands/daemon.ts` (new) | `status`, `stop`, `restart` subcommands | ~80 |
+| `src/constants.ts` | `DEFAULT_IDLE_TIMEOUT` constant | 2 |
+
+**Total: ~143 lines of new/changed code.**
+
+## Backward Compatibility
+
+- No breaking changes to CLI commands or Extension protocol
+- Existing `OPENCLI_DAEMON_PORT` environment variable continues to work
+- The only observable behavior change: daemon stays alive longer
+- New `daemon` subcommands are additive
+
+## Testing
+
+- Unit test: idle timer starts only when both CLI and Extension are idle
+- Unit test: idle timer is cleared when Extension connects
+- Unit test: `/status` returns correct state
+- Unit test: `/shutdown` triggers graceful exit
+- Integration test: daemon survives 10+ minutes without CLI requests while Extension
+  is connected
+- Integration test: daemon exits after configured timeout when fully idle
+- Integration test: `opencli daemon status/stop/restart` work correctly
+
+## Out of Scope
+
+- OS-level daemon management (launchd/systemd) — can be added later if needed
+- Daemon auto-update mechanism
+- Multi-daemon coordination
+- Persistent daemon state across restarts

package/docs/zh/guide/browser-bridge.md

@@ -22,3 +22,15 @@ OpenCLI 通过轻量级 **Browser Bridge** Chrome 扩展 + 微守护进程连接
 ```bash
 opencli doctor            # 检查扩展 + 守护进程连接
 ```
+
+## Daemon 生命周期
+
+Daemon 在首次运行浏览器命令时自动启动，默认保持 **4 小时**。仅当 CLI 空闲超时**且** Chrome 扩展未连接时才会退出。
+
+```bash
+opencli daemon status    # 查看 daemon 状态（PID、运行时长、扩展连接、内存）
+opencli daemon stop      # 优雅关停
+opencli daemon restart   # 重启
+```
+
+通过 `OPENCLI_DAEMON_TIMEOUT` 环境变量覆盖超时时间（毫秒）。设为 `0` 则永不超时。

package/extension/dist/background.js

@@ -3,14 +3,67 @@ const DAEMON_HOST = "localhost";
 const DAEMON_WS_URL = `ws://${DAEMON_HOST}:${DAEMON_PORT}/ext`;
 const DAEMON_PING_URL = `http://${DAEMON_HOST}:${DAEMON_PORT}/ping`;
 const WS_RECONNECT_BASE_DELAY = 2e3;
-const WS_RECONNECT_MAX_DELAY = 6e4;
+const WS_RECONNECT_MAX_DELAY = 5e3;
 
 const attached = /* @__PURE__ */ new Set();
 const BLANK_PAGE$1 = "data:text/html,<html></html>";
+const FOREIGN_EXTENSION_URL_PREFIX = "chrome-extension://";
+const ATTACH_RECOVERY_DELAY_MS = 120;
 function isDebuggableUrl$1(url) {
   if (!url) return true;
   return url.startsWith("http://") || url.startsWith("https://") || url === BLANK_PAGE$1;
 }
+async function removeForeignExtensionEmbeds(tabId) {
+  const tab = await chrome.tabs.get(tabId);
+  if (!tab.url || !tab.url.startsWith("http://") && !tab.url.startsWith("https://")) {
+    return { removed: 0 };
+  }
+  if (!chrome.scripting?.executeScript) return { removed: 0 };
+  try {
+    const [result] = await chrome.scripting.executeScript({
+      target: { tabId },
+      args: [`${FOREIGN_EXTENSION_URL_PREFIX}${chrome.runtime.id}/`],
+      func: (ownExtensionPrefix) => {
+        const extensionPrefix = "chrome-extension://";
+        const selectors = ["iframe", "frame", "embed", "object"];
+        const visitedRoots = /* @__PURE__ */ new Set();
+        const roots = [document];
+        let removed = 0;
+        while (roots.length > 0) {
+          const root = roots.pop();
+          if (!root || visitedRoots.has(root)) continue;
+          visitedRoots.add(root);
+          for (const selector of selectors) {
+            const nodes = root.querySelectorAll(selector);
+            for (const node of nodes) {
+              const src = node.getAttribute("src") || node.getAttribute("data") || "";
+              if (!src.startsWith(extensionPrefix) || src.startsWith(ownExtensionPrefix)) continue;
+              node.remove();
+              removed++;
+            }
+          }
+          const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+          let current = walker.nextNode();
+          while (current) {
+            const element = current;
+            if (element.shadowRoot) roots.push(element.shadowRoot);
+            current = walker.nextNode();
+          }
+        }
+        return { removed };
+      }
+    });
+    return result?.result ?? { removed: 0 };
+  } catch {
+    return { removed: 0 };
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function tryAttach(tabId) {
+  await chrome.debugger.attach({ tabId }, "1.3");
+}
 async function ensureAttached(tabId) {
   try {
     const tab = await chrome.tabs.get(tabId);
@@ -35,17 +88,28 @@ async function ensureAttached(tabId) {
     }
   }
   try {
-    await chrome.debugger.attach({ tabId }, "1.3");
+    await tryAttach(tabId);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     const hint = msg.includes("chrome-extension://") ? ". Tip: another Chrome extension may be interfering — try disabling other extensions" : "";
-    if (msg.includes("Another debugger is already attached")) {
+    if (msg.includes("chrome-extension://")) {
+      const recoveryCleanup = await removeForeignExtensionEmbeds(tabId);
+      if (recoveryCleanup.removed > 0) {
+        console.warn(`[opencli] Removed ${recoveryCleanup.removed} foreign extension frame(s) after attach failure on tab ${tabId}`);
+      }
+      await delay(ATTACH_RECOVERY_DELAY_MS);
+      try {
+        await tryAttach(tabId);
+      } catch {
+        throw new Error(`attach failed: ${msg}${hint}`);
+      }
+    } else if (msg.includes("Another debugger is already attached")) {
       try {
         await chrome.debugger.detach({ tabId });
       } catch {
       }
       try {
-        await chrome.debugger.attach({ tabId }, "1.3");
+        await tryAttach(tabId);
       } catch {
         throw new Error(`attach failed: ${msg}${hint}`);
       }
@@ -58,6 +122,11 @@ async function ensureAttached(tabId) {
     await chrome.debugger.sendCommand({ tabId }, "Runtime.enable");
   } catch {
   }
+  try {
+    await chrome.debugger.sendCommand({ tabId }, "Debugger.enable");
+    await chrome.debugger.sendCommand({ tabId }, "Debugger.setBreakpointsActive", { active: false });
+  } catch {
+  }
 }
 async function evaluate(tabId, expression) {
   await ensureAttached(tabId);
@@ -102,6 +171,23 @@ async function screenshot(tabId, options = {}) {
     }
   }
 }
+async function setFileInputFiles(tabId, files, selector) {
+  await ensureAttached(tabId);
+  await chrome.debugger.sendCommand({ tabId }, "DOM.enable");
+  const doc = await chrome.debugger.sendCommand({ tabId }, "DOM.getDocument");
+  const query = selector || 'input[type="file"]';
+  const result = await chrome.debugger.sendCommand({ tabId }, "DOM.querySelector", {
+    nodeId: doc.root.nodeId,
+    selector: query
+  });
+  if (!result.nodeId) {
+    throw new Error(`No element found matching selector: ${query}`);
+  }
+  await chrome.debugger.sendCommand({ tabId }, "DOM.setFileInputFiles", {
+    files,
+    nodeId: result.nodeId
+  });
+}
 async function detach(tabId) {
   if (!attached.has(tabId)) return;
   attached.delete(tabId);
@@ -215,6 +301,11 @@ function resetWindowIdleTimer(workspace) {
   session.idleTimer = setTimeout(async () => {
     const current = automationSessions.get(workspace);
     if (!current) return;
+    if (!current.owned) {
+      console.log(`[opencli] Borrowed workspace ${workspace} detached from window ${current.windowId} (idle timeout)`);
+      automationSessions.delete(workspace);
+      return;
+    }
     try {
       await chrome.windows.remove(current.windowId);
       console.log(`[opencli] Automation window ${current.windowId} (${workspace}) closed (idle timeout)`);
@@ -243,7 +334,9 @@ async function getAutomationWindow(workspace) {
   const session = {
     windowId: win.id,
     idleTimer: null,
-    idleDeadlineAt: Date.now() + WINDOW_IDLE_TIMEOUT
+    idleDeadlineAt: Date.now() + WINDOW_IDLE_TIMEOUT,
+    owned: true,
+    preferredTabId: null
   };
   automationSessions.set(workspace, session);
   console.log(`[opencli] Created automation window ${session.windowId} (${workspace})`);
@@ -306,6 +399,10 @@ async function handleCommand(cmd) {
         return await handleCloseWindow(cmd, workspace);
       case "sessions":
         return await handleSessions(cmd);
+      case "set-file-input":
+        return await handleSetFileInput(cmd, workspace);
+      case "bind-current":
+        return await handleBindCurrent(cmd, workspace);
       default:
         return { id: cmd.id, ok: false, error: `Unknown action: ${cmd.action}` };
     }
@@ -341,14 +438,91 @@ function normalizeUrlForComparison(url) {
 function isTargetUrl(currentUrl, targetUrl) {
   return normalizeUrlForComparison(currentUrl) === normalizeUrlForComparison(targetUrl);
 }
+function matchesDomain(url, domain) {
+  if (!url) return false;
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`);
+  } catch {
+    return false;
+  }
+}
+function matchesBindCriteria(tab, cmd) {
+  if (!tab.id || !isDebuggableUrl(tab.url)) return false;
+  if (cmd.matchDomain && !matchesDomain(tab.url, cmd.matchDomain)) return false;
+  if (cmd.matchPathPrefix) {
+    try {
+      const parsed = new URL(tab.url);
+      if (!parsed.pathname.startsWith(cmd.matchPathPrefix)) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function isNotebooklmWorkspace(workspace) {
+  return workspace === "site:notebooklm";
+}
+function classifyNotebooklmUrl(url) {
+  if (!url) return "other";
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname !== "notebooklm.google.com") return "other";
+    return parsed.pathname.startsWith("/notebook/") ? "notebook" : "home";
+  } catch {
+    return "other";
+  }
+}
+function scoreWorkspaceTab(workspace, tab) {
+  if (!tab.id || !isDebuggableUrl(tab.url)) return -1;
+  if (isNotebooklmWorkspace(workspace)) {
+    const kind = classifyNotebooklmUrl(tab.url);
+    if (kind === "other") return -1;
+    if (kind === "notebook") return tab.active ? 400 : 300;
+    return tab.active ? 200 : 100;
+  }
+  return -1;
+}
+function setWorkspaceSession(workspace, session) {
+  const existing = automationSessions.get(workspace);
+  if (existing?.idleTimer) clearTimeout(existing.idleTimer);
+  automationSessions.set(workspace, {
+    ...session,
+    idleTimer: null,
+    idleDeadlineAt: Date.now() + WINDOW_IDLE_TIMEOUT
+  });
+}
+async function maybeBindWorkspaceToExistingTab(workspace) {
+  if (!isNotebooklmWorkspace(workspace)) return null;
+  const tabs = await chrome.tabs.query({});
+  let bestTab = null;
+  let bestScore = -1;
+  for (const tab of tabs) {
+    const score = scoreWorkspaceTab(workspace, tab);
+    if (score > bestScore) {
+      bestScore = score;
+      bestTab = tab;
+    }
+  }
+  if (!bestTab?.id || bestScore < 0) return null;
+  setWorkspaceSession(workspace, {
+    windowId: bestTab.windowId,
+    owned: false,
+    preferredTabId: bestTab.id
+  });
+  console.log(`[opencli] Workspace ${workspace} bound to existing tab ${bestTab.id} in window ${bestTab.windowId}`);
+  resetWindowIdleTimer(workspace);
+  return bestTab.id;
+}
 async function resolveTabId(tabId, workspace) {
   if (tabId !== void 0) {
     try {
       const tab = await chrome.tabs.get(tabId);
       const session = automationSessions.get(workspace);
-      if (isDebuggableUrl(tab.url) && session && tab.windowId === session.windowId) return tabId;
-      if (session && tab.windowId !== session.windowId) {
-        console.warn(`[opencli] Tab ${tabId} belongs to window ${tab.windowId}, not automation window ${session.windowId}, re-resolving`);
+      const matchesSession = session ? session.preferredTabId !== null ? session.preferredTabId === tabId : tab.windowId === session.windowId : false;
+      if (isDebuggableUrl(tab.url) && matchesSession) return tabId;
+      if (session && !matchesSession) {
+        console.warn(`[opencli] Tab ${tabId} is not bound to workspace ${workspace}, re-resolving`);
       } else if (!isDebuggableUrl(tab.url)) {
         console.warn(`[opencli] Tab ${tabId} URL is not debuggable (${tab.url}), re-resolving`);
       }
@@ -356,6 +530,18 @@ async function resolveTabId(tabId, workspace) {
       console.warn(`[opencli] Tab ${tabId} no longer exists, re-resolving`);
     }
   }
+  const adoptedTabId = await maybeBindWorkspaceToExistingTab(workspace);
+  if (adoptedTabId !== null) return adoptedTabId;
+  const existingSession = automationSessions.get(workspace);
+  if (existingSession && existingSession.preferredTabId !== null) {
+    try {
+      const preferredTabId = existingSession.preferredTabId;
+      const preferredTab = await chrome.tabs.get(preferredTabId);
+      if (isDebuggableUrl(preferredTab.url)) return preferredTab.id;
+    } catch {
+      automationSessions.delete(workspace);
+    }
+  }
   const windowId = await getAutomationWindow(workspace);
   const tabs = await chrome.tabs.query({ windowId });
   const debuggableTab = tabs.find((t) => t.id && isDebuggableUrl(t.url));
@@ -378,6 +564,14 @@ async function resolveTabId(tabId, workspace) {
 async function listAutomationTabs(workspace) {
   const session = automationSessions.get(workspace);
   if (!session) return [];
+  if (session.preferredTabId !== null) {
+    try {
+      return [await chrome.tabs.get(session.preferredTabId)];
+    } catch {
+      automationSessions.delete(workspace);
+      return [];
+    }
+  }
   try {
     return await chrome.tabs.query({ windowId: session.windowId });
   } catch {
@@ -559,15 +753,29 @@ async function handleScreenshot(cmd, workspace) {
 async function handleCloseWindow(cmd, workspace) {
   const session = automationSessions.get(workspace);
   if (session) {
-    try {
-      await chrome.windows.remove(session.windowId);
-    } catch {
+    if (session.owned) {
+      try {
+        await chrome.windows.remove(session.windowId);
+      } catch {
+      }
     }
     if (session.idleTimer) clearTimeout(session.idleTimer);
     automationSessions.delete(workspace);
   }
   return { id: cmd.id, ok: true, data: { closed: true } };
 }
+async function handleSetFileInput(cmd, workspace) {
+  if (!cmd.files || !Array.isArray(cmd.files) || cmd.files.length === 0) {
+    return { id: cmd.id, ok: false, error: "Missing or empty files array" };
+  }
+  const tabId = await resolveTabId(cmd.tabId, workspace);
+  try {
+    await setFileInputFiles(tabId, cmd.files, cmd.selector);
+    return { id: cmd.id, ok: true, data: { count: cmd.files.length } };
+  } catch (err) {
+    return { id: cmd.id, ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
 async function handleSessions(cmd) {
   const now = Date.now();
   const data = await Promise.all([...automationSessions.entries()].map(async ([workspace, session]) => ({
@@ -578,3 +786,34 @@ async function handleSessions(cmd) {
   })));
   return { id: cmd.id, ok: true, data };
 }
+async function handleBindCurrent(cmd, workspace) {
+  const activeTabs = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
+  const fallbackTabs = await chrome.tabs.query({ lastFocusedWindow: true });
+  const allTabs = await chrome.tabs.query({});
+  const boundTab = activeTabs.find((tab) => matchesBindCriteria(tab, cmd)) ?? fallbackTabs.find((tab) => matchesBindCriteria(tab, cmd)) ?? allTabs.find((tab) => matchesBindCriteria(tab, cmd));
+  if (!boundTab?.id) {
+    return {
+      id: cmd.id,
+      ok: false,
+      error: cmd.matchDomain || cmd.matchPathPrefix ? `No visible tab matching ${cmd.matchDomain ?? "domain"}${cmd.matchPathPrefix ? ` ${cmd.matchPathPrefix}` : ""}` : "No active debuggable tab found"
+    };
+  }
+  setWorkspaceSession(workspace, {
+    windowId: boundTab.windowId,
+    owned: false,
+    preferredTabId: boundTab.id
+  });
+  resetWindowIdleTimer(workspace);
+  console.log(`[opencli] Workspace ${workspace} explicitly bound to tab ${boundTab.id} (${boundTab.url})`);
+  return {
+    id: cmd.id,
+    ok: true,
+    data: {
+      tabId: boundTab.id,
+      windowId: boundTab.windowId,
+      url: boundTab.url,
+      title: boundTab.title,
+      workspace
+    }
+  };
+}

package/extension/manifest.json

@@ -5,6 +5,7 @@
   "description": "Browser automation bridge for the OpenCLI CLI tool. Executes commands in isolated Chrome windows via a local daemon.",
   "permissions": [
     "debugger",
+    "scripting",
     "tabs",
     "cookies",
     "activeTab",
@@ -35,4 +36,4 @@
     "extension_pages": "script-src 'self'; object-src 'self'"
   },
   "homepage_url": "https://github.com/jackwener/opencli"
-}
+}