@jackwener/opencli 1.6.8 → 1.6.10

package/dist/src/browser/bridge.js

@@ -6,8 +6,9 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Page } from './page.js';
-import { fetchDaemonStatus, isExtensionConnected } from './daemon-client.js';
+import { getDaemonHealth } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { BrowserConnectError } from '../errors.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
@@ -52,25 +53,22 @@ export class BrowserBridge {
     async _ensureDaemon(timeoutSeconds) {
         const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
         const timeoutMs = effectiveSeconds * 1000;
-        // Single status check instead of two separate fetchDaemonStatus() calls
-        const status = await fetchDaemonStatus();
-        // Fast path: extension already connected
-        if (status?.extensionConnected)
+        const health = await getDaemonHealth();
+        // Fast path: everything ready
+        if (health.state === 'ready')
             return;
         // Daemon running but no extension — wait for extension with progress
-        if (status !== null) {
+        if (health.state === 'no-extension') {
             if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
                 process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
                 process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
             }
-            const deadline = Date.now() + timeoutMs;
-            while (Date.now() < deadline) {
-                await new Promise(resolve => setTimeout(resolve, 200));
-                if (await isExtensionConnected())
-                    return;
-            }
-            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
-                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+            if (await this._pollUntilReady(timeoutMs))
+                return;
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
+                '  Then run: opencli doctor', 'extension-not-connected');
         }
         // No daemon — spawn one
         const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -91,19 +89,27 @@ export class BrowserBridge {
             env: { ...process.env },
         });
         this._daemonProc.unref();
-        // Wait for daemon + extension with faster polling
+        // Wait for daemon + extension
+        if (await this._pollUntilReady(timeoutMs))
+            return;
+        const finalHealth = await getDaemonHealth();
+        if (finalHealth.state === 'no-extension') {
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
+                '  Then run: opencli doctor', 'extension-not-connected');
+        }
+        throw new BrowserConnectError('Failed to start opencli daemon', `Try running manually:\n  node ${daemonPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
+    }
+    /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
+    async _pollUntilReady(timeoutMs) {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             await new Promise(resolve => setTimeout(resolve, 200));
-            if (await isExtensionConnected())
-                return;
-        }
-        if ((await fetchDaemonStatus()) !== null) {
-            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
-                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+            const h = await getDaemonHealth();
+            if (h.state === 'ready')
+                return true;
         }
-        throw new Error('Failed to start opencli daemon. Try running manually:\n' +
-            `  node ${daemonPath}\n` +
-            `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
+        return false;
     }
 }

package/dist/src/browser/daemon-client.d.ts

@@ -7,6 +7,9 @@ import type { BrowserSessionInfo } from '../types.js';
 export interface DaemonCommand {
     id: string;
     action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp';
+    /** Target page identity (targetId). Cross-layer contract — preferred over tabId. */
+    page?: string;
+    /** @deprecated Legacy tab ID — use `page` (targetId) instead. */
     tabId?: number;
     code?: string;
     workspace?: string;
@@ -35,6 +38,8 @@ export interface DaemonResult {
     ok: boolean;
     data?: unknown;
     error?: string;
+    /** Page identity (targetId) — present on page-scoped command responses */
+    page?: string;
 }
 export interface DaemonStatus {
     ok: boolean;
@@ -50,23 +55,38 @@ export interface DaemonStatus {
 export declare function fetchDaemonStatus(opts?: {
     timeout?: number;
 }): Promise<DaemonStatus | null>;
+export type DaemonHealth = {
+    state: 'stopped';
+    status: null;
+} | {
+    state: 'no-extension';
+    status: DaemonStatus;
+} | {
+    state: 'ready';
+    status: DaemonStatus;
+};
+/**
+ * Unified daemon health check — single entry point for all status queries.
+ * Replaces isDaemonRunning(), isExtensionConnected(), and checkDaemonStatus().
+ */
+export declare function getDaemonHealth(opts?: {
+    timeout?: number;
+}): Promise<DaemonHealth>;
 export declare function requestDaemonShutdown(opts?: {
     timeout?: number;
 }): Promise<boolean>;
 /**
- * Check if daemon is running.
+ * Send a command to the daemon and return the result data.
  */
-export declare function isDaemonRunning(): Promise<boolean>;
-/**
- * Check if daemon is running AND the extension is connected.
- */
-export declare function isExtensionConnected(): Promise<boolean>;
+export declare function sendCommand(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<unknown>;
 /**
- * Send a command to the daemon and wait for a result.
- * Retries up to 4 times: network errors retry at 500ms,
- * transient extension errors retry at 1500ms.
+ * Like sendCommand, but returns both data and page identity (targetId).
+ * Use this for page-scoped commands where the caller needs the page identity.
  */
-export declare function sendCommand(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<unknown>;
+export declare function sendCommandFull(action: DaemonCommand['action'], params?: Omit<DaemonCommand, 'id' | 'action'>): Promise<{
+    data: unknown;
+    page?: string;
+}>;
 export declare function listSessions(): Promise<BrowserSessionInfo[]>;
 export declare function bindCurrentTab(workspace: string, opts?: {
     matchDomain?: string;

package/dist/src/browser/daemon-client.js

@@ -5,7 +5,7 @@
  */
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { sleep } from '../utils.js';
-import { isTransientBrowserError } from './errors.js';
+import { classifyBrowserError } from './errors.js';
 const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const OPENCLI_HEADERS = { 'X-OpenCLI': '1' };
@@ -39,6 +39,18 @@ export async function fetchDaemonStatus(opts) {
         return null;
     }
 }
+/**
+ * Unified daemon health check — single entry point for all status queries.
+ * Replaces isDaemonRunning(), isExtensionConnected(), and checkDaemonStatus().
+ */
+export async function getDaemonHealth(opts) {
+    const status = await fetchDaemonStatus(opts);
+    if (!status)
+        return { state: 'stopped', status: null };
+    if (!status.extensionConnected)
+        return { state: 'no-extension', status };
+    return { state: 'ready', status };
+}
 export async function requestDaemonShutdown(opts) {
     try {
         const res = await requestDaemon('/shutdown', { method: 'POST', timeout: opts?.timeout ?? 5000 });
@@ -49,27 +61,17 @@ export async function requestDaemonShutdown(opts) {
     }
 }
 /**
- * Check if daemon is running.
- */
-export async function isDaemonRunning() {
-    return (await fetchDaemonStatus()) !== null;
-}
-/**
- * Check if daemon is running AND the extension is connected.
- */
-export async function isExtensionConnected() {
-    const status = await fetchDaemonStatus();
-    return !!status?.extensionConnected;
-}
-/**
- * Send a command to the daemon and wait for a result.
- * Retries up to 4 times: network errors retry at 500ms,
- * transient extension errors retry at 1500ms.
+ * Internal: send a command to the daemon with retry logic.
+ * Returns the raw DaemonResult. All retry policy lives here — callers
+ * (sendCommand, sendCommandFull) only shape the return value.
+ *
+ * Retries up to 4 times:
+ * - Network errors (TypeError, AbortError): retry at 500ms
+ * - Transient browser errors: retry at the delay suggested by classifyBrowserError()
  */
-export async function sendCommand(action, params = {}) {
+async function sendCommandRaw(action, params) {
     const maxRetries = 4;
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        // Generate a fresh ID per attempt to avoid daemon-side duplicate detection
         const id = generateId();
         const command = { id, action, ...params };
         try {
@@ -81,29 +83,42 @@ export async function sendCommand(action, params = {}) {
             });
             const result = (await res.json());
             if (!result.ok) {
-                // Check if error is a transient extension issue worth retrying
-                if (isTransientBrowserError(new Error(result.error ?? '')) && attempt < maxRetries) {
-                    // Longer delay for extension recovery (service worker restart)
-                    await sleep(1500);
+                const advice = classifyBrowserError(new Error(result.error ?? ''));
+                if (advice.retryable && attempt < maxRetries) {
+                    await sleep(advice.delayMs);
                     continue;
                 }
                 throw new Error(result.error ?? 'Daemon command failed');
             }
-            return result.data;
+            return result;
         }
         catch (err) {
-            const isRetryable = err instanceof TypeError // fetch network error
+            const isNetworkError = err instanceof TypeError
                 || (err instanceof Error && err.name === 'AbortError');
-            if (isRetryable && attempt < maxRetries) {
+            if (isNetworkError && attempt < maxRetries) {
                 await sleep(500);
                 continue;
             }
             throw err;
         }
     }
-    // Unreachable — the loop always returns or throws
     throw new Error('sendCommand: max retries exhausted');
 }
+/**
+ * Send a command to the daemon and return the result data.
+ */
+export async function sendCommand(action, params = {}) {
+    const result = await sendCommandRaw(action, params);
+    return result.data;
+}
+/**
+ * Like sendCommand, but returns both data and page identity (targetId).
+ * Use this for page-scoped commands where the caller needs the page identity.
+ */
+export async function sendCommandFull(action, params = {}) {
+    const result = await sendCommandRaw(action, params);
+    return { data: result.data, page: result.page };
+}
 export async function listSessions() {
     const result = await sendCommand('sessions');
     return Array.isArray(result) ? result : [];

package/dist/src/browser/daemon-client.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchDaemonStatus, isDaemonRunning, isExtensionConnected, requestDaemonShutdown, } from './daemon-client.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, } from './daemon-client.js';
 describe('daemon-client', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
@@ -42,36 +42,43 @@ describe('daemon-client', () => {
             headers: expect.objectContaining({ 'X-OpenCLI': '1' }),
         }));
     });
-    it('isDaemonRunning reflects shared status availability', async () => {
+    it('getDaemonHealth returns stopped when daemon is not reachable', async () => {
+        vi.mocked(fetch).mockRejectedValue(new Error('ECONNREFUSED'));
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'stopped', status: null });
+    });
+    it('getDaemonHealth returns no-extension when daemon is running but extension disconnected', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            extensionConnected: false,
+            pending: 0,
+            lastCliRequestTime: Date.now(),
+            memoryMB: 16,
+            port: 19825,
+        };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
-            json: () => Promise.resolve({
-                ok: true,
-                pid: 123,
-                uptime: 10,
-                extensionConnected: false,
-                pending: 0,
-                lastCliRequestTime: Date.now(),
-                memoryMB: 16,
-                port: 19825,
-            }),
+            json: () => Promise.resolve(status),
         });
-        await expect(isDaemonRunning()).resolves.toBe(true);
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'no-extension', status });
     });
-    it('isExtensionConnected reflects shared status payload', async () => {
+    it('getDaemonHealth returns ready when daemon and extension are both connected', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            extensionConnected: true,
+            extensionVersion: '1.2.3',
+            pending: 0,
+            lastCliRequestTime: Date.now(),
+            memoryMB: 32,
+            port: 19825,
+        };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
-            json: () => Promise.resolve({
-                ok: true,
-                pid: 123,
-                uptime: 10,
-                extensionConnected: false,
-                pending: 0,
-                lastCliRequestTime: Date.now(),
-                memoryMB: 16,
-                port: 19825,
-            }),
+            json: () => Promise.resolve(status),
         });
-        await expect(isExtensionConnected()).resolves.toBe(false);
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'ready', status });
     });
 });

package/dist/src/browser/dom-helpers.test.js

@@ -24,11 +24,12 @@ describe('waitForCaptureJs', () => {
     });
     it('resolves "captured" when __opencli_xhr is populated before deadline', async () => {
         const g = globalThis;
-        g.__opencli_xhr = [];
+        const captured = [];
+        g.__opencli_xhr = captured;
         g.window = g; // stub window for Node eval
         const code = waitForCaptureJs(1000);
         const promise = eval(code);
-        g.__opencli_xhr.push({ data: 'test' });
+        captured.push({ data: 'test' });
         await expect(promise).resolves.toBe('captured');
         delete g.__opencli_xhr;
         delete g.window;

package/dist/src/browser/errors.d.ts

@@ -6,7 +6,32 @@
  */
 import { BrowserConnectError, type BrowserConnectKind } from '../errors.js';
 /**
- * Check if an error message indicates a transient browser error worth retrying.
+ * Unified browser error classification.
+ *
+ * All transient error detection lives here — daemon-client, pipeline executor,
+ * and page retry logic all use this single system instead of maintaining
+ * separate pattern lists.
+ */
+/** Error category — determines which layer should retry. */
+export type BrowserErrorKind = 'extension-transient' | 'target-navigation' | 'non-retryable';
+/** How the caller should handle the error. */
+export interface RetryAdvice {
+    /** Error category — callers use this to decide whether *they* should retry. */
+    kind: BrowserErrorKind;
+    /** Whether the error is transient and worth retrying. */
+    retryable: boolean;
+    /** Suggested delay before retry (ms). */
+    delayMs: number;
+}
+/**
+ * Classify a browser error and return retry advice.
+ *
+ * Single source of truth for "is this error transient?" across all layers.
+ */
+export declare function classifyBrowserError(err: unknown): RetryAdvice;
+/**
+ * Check if an error is a transient browser error worth retrying.
+ * Convenience wrapper around classifyBrowserError().
  */
 export declare function isTransientBrowserError(err: unknown): boolean;
 export type ConnectFailureKind = BrowserConnectKind;

package/dist/src/browser/errors.js

@@ -7,24 +7,57 @@
 import { BrowserConnectError } from '../errors.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 /**
- * Transient browser error patterns — shared across daemon-client, pipeline executor,
- * and page retry logic. These errors indicate temporary conditions (extension restart,
- * service worker cycle, tab navigation) that are worth retrying.
+ * Extension/daemon transient patterns — service worker restarts, attach races,
+ * tab closure, daemon hiccups. These warrant a longer retry delay (~1500ms)
+ * because the extension needs time to recover.
  */
-const TRANSIENT_ERROR_PATTERNS = [
+const EXTENSION_TRANSIENT_PATTERNS = [
     'Extension disconnected',
     'Extension not connected',
     'attach failed',
     'no longer exists',
     'CDP connection',
     'Daemon command failed',
+    'No window with id',
 ];
 /**
- * Check if an error message indicates a transient browser error worth retrying.
+ * CDP target navigation patterns — SPA client-side redirects can invalidate the
+ * CDP target after chrome.tabs reports 'complete'. These warrant a shorter retry
+ * delay (~200ms) because the new document is usually available quickly.
+ */
+const TARGET_NAVIGATION_PATTERNS = [
+    'Inspected target navigated or closed',
+];
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Classify a browser error and return retry advice.
+ *
+ * Single source of truth for "is this error transient?" across all layers.
+ */
+export function classifyBrowserError(err) {
+    const msg = errorMessage(err);
+    // Extension/daemon transient errors — longer recovery time
+    if (EXTENSION_TRANSIENT_PATTERNS.some(p => msg.includes(p))) {
+        return { kind: 'extension-transient', retryable: true, delayMs: 1500 };
+    }
+    // CDP target navigation errors — shorter recovery time
+    if (TARGET_NAVIGATION_PATTERNS.some(p => msg.includes(p))) {
+        return { kind: 'target-navigation', retryable: true, delayMs: 200 };
+    }
+    // CDP protocol error with target context (e.g., -32000 "target closed")
+    if (msg.includes('-32000') && msg.toLowerCase().includes('target')) {
+        return { kind: 'target-navigation', retryable: true, delayMs: 200 };
+    }
+    return { kind: 'non-retryable', retryable: false, delayMs: 0 };
+}
+/**
+ * Check if an error is a transient browser error worth retrying.
+ * Convenience wrapper around classifyBrowserError().
  */
 export function isTransientBrowserError(err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return TRANSIENT_ERROR_PATTERNS.some(pattern => msg.includes(pattern));
+    return classifyBrowserError(err).retryable;
 }
 export function formatBrowserConnectError(kind, detail) {
     switch (kind) {

package/dist/src/browser/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/errors.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { classifyBrowserError, isTransientBrowserError } from './errors.js';
+describe('classifyBrowserError', () => {
+    it('classifies extension transient errors with 1500ms delay', () => {
+        for (const msg of [
+            'Extension disconnected',
+            'Extension not connected',
+            'attach failed',
+            'no longer exists',
+            'CDP connection reset',
+            'Daemon command failed',
+            'No window with id: 123',
+        ]) {
+            const advice = classifyBrowserError(new Error(msg));
+            expect(advice.kind, `expected "${msg}" → extension-transient`).toBe('extension-transient');
+            expect(advice.retryable).toBe(true);
+            expect(advice.delayMs).toBe(1500);
+        }
+    });
+    it('classifies CDP target navigation errors with 200ms delay', () => {
+        const advice = classifyBrowserError(new Error('Inspected target navigated or closed'));
+        expect(advice.kind).toBe('target-navigation');
+        expect(advice.retryable).toBe(true);
+        expect(advice.delayMs).toBe(200);
+    });
+    it('classifies CDP -32000 target errors with 200ms delay', () => {
+        const advice = classifyBrowserError(new Error('{"code":-32000,"message":"Target closed"}'));
+        expect(advice.kind).toBe('target-navigation');
+        expect(advice.retryable).toBe(true);
+        expect(advice.delayMs).toBe(200);
+    });
+    it('returns non-retryable for unrelated errors', () => {
+        for (const msg of ['Permission denied', 'malformed exec payload', 'SyntaxError']) {
+            const advice = classifyBrowserError(new Error(msg));
+            expect(advice.kind).toBe('non-retryable');
+            expect(advice.retryable).toBe(false);
+        }
+    });
+    it('handles non-Error values', () => {
+        expect(classifyBrowserError('Extension disconnected').kind).toBe('extension-transient');
+        expect(classifyBrowserError(42).kind).toBe('non-retryable');
+    });
+});
+describe('isTransientBrowserError (convenience wrapper)', () => {
+    it('returns true for transient errors', () => {
+        expect(isTransientBrowserError(new Error('No window with id: 123'))).toBe(true);
+    });
+    it('returns false for non-transient errors', () => {
+        expect(isTransientBrowserError(new Error('Permission denied'))).toBe(false);
+    });
+});

package/dist/src/browser/index.d.ts

@@ -7,7 +7,8 @@
 export { Page } from './page.js';
 export { BrowserBridge } from './bridge.js';
 export { CDPBridge } from './cdp.js';
-export { isDaemonRunning } from './daemon-client.js';
+export { getDaemonHealth } from './daemon-client.js';
+export type { DaemonHealth } from './daemon-client.js';
 export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 export { generateStealthJs } from './stealth.js';
 export type { DomSnapshotOptions } from './dom-snapshot.js';

package/dist/src/browser/index.js

@@ -7,6 +7,6 @@
 export { Page } from './page.js';
 export { BrowserBridge } from './bridge.js';
 export { CDPBridge } from './cdp.js';
-export { isDaemonRunning } from './daemon-client.js';
+export { getDaemonHealth } from './daemon-client.js';
 export { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 export { generateStealthJs } from './stealth.js';

package/dist/src/browser/page.d.ts

@@ -4,30 +4,31 @@
  * All browser operations are ultimately 'exec' (JS evaluation via CDP)
  * plus a few native Chrome Extension APIs (tabs, cookies, navigate).
  *
- * IMPORTANT: After goto(), we remember the tabId returned by the navigate
- * action and pass it to all subsequent commands. This avoids the issue
- * where resolveTabId() in the extension picks a chrome:// or
- * chrome-extension:// tab that can't be debugged.
+ * IMPORTANT: After goto(), we remember the page identity (targetId) returned
+ * by the navigate action and pass it to all subsequent commands. This ensures
+ * page-scoped operations target the correct page without guessing.
  */
 import type { BrowserCookie, ScreenshotOptions } from '../types.js';
 import { BasePage } from './base-page.js';
-export declare function isRetryableSettleError(err: unknown): boolean;
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
 export declare class Page extends BasePage {
     private readonly workspace;
     constructor(workspace?: string);
-    /** Active tab ID, set after navigate and used in all subsequent commands */
-    private _tabId;
+    /** Active page identity (targetId), set after navigate and used in all subsequent commands */
+    private _page;
     /** Helper: spread workspace into command params */
     private _wsOpt;
-    /** Helper: spread workspace + tabId into command params */
+    /** Helper: spread workspace + page identity into command params */
     private _cmdOpts;
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
     }): Promise<void>;
+    /** Get the active page identity (targetId) */
+    getActivePage(): string | undefined;
+    /** @deprecated Use getActivePage() instead */
     getActiveTabId(): number | undefined;
     evaluate(js: string): Promise<unknown>;
     getCookies(opts?: {