@agentrhq/webcmd 0.1.2 → 0.2.1

package/dist/src/browser/bridge.js

@@ -2,7 +2,7 @@
  * Browser session manager — auto-spawns daemon and provides IPage.
  */
 import { Page } from './page.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
@@ -26,11 +26,13 @@ export class BrowserBridge {
             throw new Error('Session is closed');
         this._state = 'connecting';
         try {
-            const contextId = opts.contextId ?? resolveProfileContextId();
-            await this._ensureDaemon(opts.timeout, contextId);
+            const routing = opts.contextId || opts.preferredContextId
+                ? { contextId: opts.contextId, preferredContextId: opts.preferredContextId }
+                : profileRouteParams(resolveProfileSelection());
+            await this._ensureDaemon(opts.timeout, routing.contextId);
             if (!opts.session?.trim())
                 throw new Error('Browser session is required');
-            this._page = new Page(opts.session.trim(), opts.idleTimeout, contextId, opts.windowMode, opts.surface, opts.siteSession);
+            this._page = new Page(opts.session.trim(), opts.idleTimeout, routing.contextId, opts.windowMode, opts.surface, opts.siteSession, routing.preferredContextId);
             this._state = 'connected';
             return this._page;
         }

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

@@ -26,6 +26,7 @@ export declare class CDPBridge implements IBrowserFactory {
         session?: string;
         cdpEndpoint?: string;
         contextId?: string;
+        preferredContextId?: string;
         idleTimeout?: number;
         windowMode?: 'foreground' | 'background';
         surface?: 'browser' | 'adapter';

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

@@ -5,6 +5,7 @@
  */
 import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, type BrowserProfileStatus, type DaemonHealth, type DaemonStatus } from './daemon-transport.js';
 import type { BrowserRuntimeCommand, BrowserRuntimeResult } from './protocol.js';
+export declare function setDaemonCommandTimeoutSeconds(seconds: number | null): void;
 export type DaemonCommand = BrowserRuntimeCommand;
 export type DaemonResult = BrowserRuntimeResult;
 export declare class BrowserCommandError extends Error {
@@ -27,6 +28,7 @@ export declare function sendCommandFull(action: DaemonCommand['action'], params?
 }>;
 export declare function bindTab(session: string, opts?: {
     contextId?: string;
+    preferredContextId?: string;
     page?: string;
     index?: number;
 }): Promise<unknown>;

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

@@ -5,8 +5,9 @@
  */
 import { sleep } from '../utils.js';
 import { BrowserConnectError } from '../errors.js';
+import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
 import { classifyBrowserError } from './errors.js';
-import { resolveProfileContextId } from './profile.js';
+import { profileRouteParams, resolveProfileSelection } from './profile.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
 import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
 import { isPreDispatchError } from './bridge-readiness.js';
@@ -15,6 +16,51 @@ let _idCounter = 0;
 function generateId() {
     return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
 }
+const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+const RUNTIME_OP_TIMEOUT_MARGIN_MS = 15_000;
+const HTTP_TIMEOUT_MARGIN_MS = 10_000;
+const TRANSPORT_MAX_ATTEMPTS = 4;
+let _userCommandTimeoutSeconds = null;
+export function setDaemonCommandTimeoutSeconds(seconds) {
+    _userCommandTimeoutSeconds = typeof seconds === 'number' && seconds > 0 ? Math.ceil(seconds) : null;
+}
+function effectiveCommandTimeoutSeconds(params) {
+    const base = _userCommandTimeoutSeconds ?? DEFAULT_COMMAND_TIMEOUT_SECONDS;
+    if (typeof params.timeoutMs === 'number' && params.timeoutMs > 0) {
+        return Math.max(base, Math.ceil((params.timeoutMs + RUNTIME_OP_TIMEOUT_MARGIN_MS) / 1000));
+    }
+    return base;
+}
+const UNKNOWN_OUTCOME_CODES = new Set([
+    COMMAND_RESULT_UNKNOWN_CODE,
+    'command_lost',
+    'result_evicted',
+]);
+const PRE_CONNECT_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+]);
+function isPreConnectFetchError(err) {
+    const queue = [err];
+    const seen = new Set();
+    while (queue.length) {
+        const current = queue.pop();
+        if (!current || typeof current !== 'object' || seen.has(current))
+            continue;
+        seen.add(current);
+        const { code, cause, errors } = current;
+        if (typeof code === 'string' && PRE_CONNECT_ERROR_CODES.has(code))
+            return true;
+        if (cause)
+            queue.push(cause);
+        if (Array.isArray(errors))
+            queue.push(...errors);
+    }
+    return false;
+}
 export class BrowserCommandError extends Error {
     code;
     hint;
@@ -30,58 +76,80 @@ export { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, };
  * Internal: send a command to the daemon and return the raw `DaemonResult`.
  *
  * Retry policy is explicit:
- * - pre-dispatch bridge/profile errors: run the full daemon/runtime ensure
- *   path, then resend with a fresh transport id;
- * - local TypeError before dispatch: same full ensure path, because the daemon
- *   may be stopped/stale and needs spawn/replacement, not just polling;
- * - `command_result_unknown` and AbortError: never retry automatically.
+ * - pre-dispatch bridge/profile errors and pre-connect fetch failures run the
+ *   full daemon/runtime ensure path, then resend the same command id;
+ * - executor-transient errors that happened before page code ran get one new
+ *   logical attempt with a fresh id;
+ * - `command_result_unknown`, duplicate pending ids from old daemons,
+ *   post-connect drops, and AbortError are never retried automatically.
  */
 async function sendCommandRaw(action, params) {
-    const maxAttempts = 4;
-    let dispatchRecoveryUsed = false;
-    let duplicateIdRetryUsed = false;
-    let transientRetryUsed = false;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        const id = generateId();
-        const rawWindowMode = process.env.WEBCMD_WINDOW;
-        const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
-            ? rawWindowMode
-            : undefined;
-        const contextId = params.contextId ?? resolveProfileContextId();
-        const windowMode = params.windowMode ?? envWindowMode;
-        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowMode && { windowMode }) };
+    const timeoutSeconds = effectiveCommandTimeoutSeconds(params);
+    const deadlineAt = Date.now() + timeoutSeconds * 1000;
+    const rawWindowMode = process.env.WEBCMD_WINDOW;
+    const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
+        ? rawWindowMode
+        : undefined;
+    const routing = params.contextId || params.preferredContextId
+        ? { contextId: params.contextId, preferredContextId: params.preferredContextId }
+        : profileRouteParams(resolveProfileSelection());
+    const contextId = routing.contextId;
+    const preferredContextId = routing.preferredContextId;
+    const windowMode = params.windowMode ?? envWindowMode;
+    let id = generateId();
+    let ensureUsed = false;
+    let semanticRetryUsed = false;
+    const ensureBridge = async () => {
+        const remainingSeconds = Math.ceil((deadlineAt - Date.now()) / 1000);
+        await ensureBrowserBridgeReady({
+            timeoutSeconds: Math.max(1, Math.min(DEFAULT_BROWSER_CONNECT_TIMEOUT, remainingSeconds)),
+            contextId,
+            verbose: false,
+        });
+    };
+    for (let attempt = 1; attempt <= TRANSPORT_MAX_ATTEMPTS; attempt++) {
+        if (attempt > 1 && Date.now() >= deadlineAt) {
+            throw new BrowserCommandError('Browser command deadline exhausted across transport retries.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+        }
+        const remainingMs = Math.max(1000, deadlineAt - Date.now());
+        const command = {
+            id,
+            action,
+            ...params,
+            timeout: timeoutSeconds,
+            deadlineAt,
+            ...(contextId && { contextId }),
+            ...(preferredContextId && { preferredContextId }),
+            ...(windowMode && { windowMode }),
+        };
         try {
             const res = await requestDaemon('/command', {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(command),
-                timeout: 30000,
+                timeout: remainingMs + HTTP_TIMEOUT_MARGIN_MS,
             });
             const result = (await res.json());
             if (result.ok)
                 return result;
-            if (result.errorCode === 'command_result_unknown') {
+            if (result.errorCode && UNKNOWN_OUTCOME_CODES.has(result.errorCode)) {
                 throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
             }
-            if (!dispatchRecoveryUsed && isPreDispatchError(result.errorCode)) {
-                dispatchRecoveryUsed = true;
-                await ensureBrowserBridgeReady({
-                    timeoutSeconds: DEFAULT_BROWSER_CONNECT_TIMEOUT,
-                    contextId,
-                    verbose: false,
-                });
-                continue;
-            }
             const isDuplicateCommandId = res.status === 409
                 && !result.errorCode
                 && (result.error ?? '').includes('Duplicate command id');
-            if (isDuplicateCommandId && !duplicateIdRetryUsed) {
-                duplicateIdRetryUsed = true;
+            if (isDuplicateCommandId) {
+                throw new BrowserCommandError('Daemon already has this command id pending; the command may already be running.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
+            }
+            if (isPreDispatchError(result.errorCode) && !ensureUsed) {
+                ensureUsed = true;
+                await ensureBridge();
                 continue;
             }
-            const advice = classifyBrowserError(new Error(result.error ?? ''));
-            if (advice.retryable && !transientRetryUsed) {
-                transientRetryUsed = true;
+            const advice = classifyBrowserError(new BrowserCommandError(result.error ?? '', result.errorCode));
+            if (advice.kind === 'extension-transient' && !semanticRetryUsed) {
+                semanticRetryUsed = true;
+                id = generateId();
                 await sleep(advice.delayMs);
                 continue;
             }
@@ -91,24 +159,13 @@ async function sendCommandRaw(action, params) {
             if (err instanceof BrowserCommandError || err instanceof BrowserConnectError)
                 throw err;
             if (err instanceof Error && err.name === 'AbortError') {
-                throw new BrowserCommandError('Browser command timed out client-side; the page may still have applied it.', 'command_result_unknown', 'Inspect the page state before retrying. Idempotent reads are safe to retry; non-idempotent writes may have already happened.');
-            }
-            if (!dispatchRecoveryUsed && err instanceof TypeError) {
-                dispatchRecoveryUsed = true;
-                await ensureBrowserBridgeReady({
-                    timeoutSeconds: DEFAULT_BROWSER_CONNECT_TIMEOUT,
-                    contextId,
-                    verbose: false,
-                });
-                continue;
+                throw new BrowserCommandError('Browser command timed out client-side; the page may still have applied it.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
             }
-            if (err instanceof Error) {
-                const advice = classifyBrowserError(err);
-                if (advice.retryable && !transientRetryUsed) {
-                    transientRetryUsed = true;
-                    await sleep(advice.delayMs);
+            if (err instanceof TypeError) {
+                await ensureBridge();
+                if (isPreConnectFetchError(err))
                     continue;
-                }
+                throw new BrowserCommandError('Connection to the daemon was lost mid-command; it may have already been applied.', COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT);
             }
             throw err;
         }

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

@@ -1,11 +1,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, } from './daemon-client.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown, sendCommand, setDaemonCommandTimeoutSeconds, } from './daemon-client.js';
 import * as daemonLifecycle from './daemon-lifecycle.js';
 describe('daemon-client', () => {
     beforeEach(() => {
         vi.stubGlobal('fetch', vi.fn());
     });
     afterEach(() => {
+        if (typeof setDaemonCommandTimeoutSeconds === 'function') {
+            setDaemonCommandTimeoutSeconds(null);
+        }
         vi.restoreAllMocks();
         vi.unstubAllEnvs();
     });
@@ -19,7 +22,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         const fetchMock = vi.mocked(fetch);
         fetchMock.mockResolvedValue({
@@ -57,7 +60,7 @@ describe('daemon-client', () => {
             runtimeName: 'fake',
             pending: 0,
             memoryMB: 16,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -75,7 +78,7 @@ describe('daemon-client', () => {
             runtimeVersion: '1.2.3',
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -97,7 +100,7 @@ describe('daemon-client', () => {
             ],
             pending: 0,
             memoryMB: 32,
-            port: 19825,
+            port: 9777,
         };
         vi.mocked(fetch).mockResolvedValue({
             ok: true,
@@ -116,32 +119,12 @@ describe('daemon-client', () => {
                 runtimeName: 'fake',
                 pending: 0,
                 memoryMB: 1,
-                port: 19825,
+                port: 9777,
             }),
         });
         await fetchDaemonStatus({ contextId: 'work' });
         expect(vi.mocked(fetch).mock.calls[0][0]).toMatch(/\/status\?contextId=work$/);
     });
-    it('rejects WEBCMD_DAEMON_PORT so CLI and extension cannot split bridge ports', async () => {
-        vi.resetModules();
-        vi.stubEnv('WEBCMD_DAEMON_PORT', '19999');
-        vi.mocked(fetch).mockResolvedValue({
-            ok: true,
-            json: () => Promise.resolve({
-                ok: true,
-                pid: 1,
-                uptime: 0,
-                runtimeConnected: true,
-                runtimeName: 'fake',
-                pending: 0,
-                memoryMB: 1,
-                port: 19825,
-            }),
-        });
-        const freshClient = await import('./daemon-client.js');
-        await expect(freshClient.fetchDaemonStatus()).rejects.toThrow('WEBCMD_DAEMON_PORT is no longer supported');
-        expect(vi.mocked(fetch)).not.toHaveBeenCalled();
-    });
     it('sendCommand includes the current pid in generated command ids', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -159,7 +142,7 @@ describe('daemon-client', () => {
         expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
         expect(ids[0]).not.toBe(ids[1]);
     });
-    it('sendCommand forwards WEBCMD_PROFILE as command contextId', async () => {
+    it('sendCommand forwards WEBCMD_PROFILE as a hard contextId requirement', async () => {
         vi.stubEnv('WEBCMD_PROFILE', 'work');
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -169,6 +152,29 @@ describe('daemon-client', () => {
         await sendCommand('exec', { code: '1 + 1' });
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.contextId).toBe('work');
+        expect(body.preferredContextId).toBeUndefined();
+    });
+    it('sendCommand forwards the config default as preferredContextId', async () => {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-dc-profile-'));
+        fs.writeFileSync(path.join(configDir, 'browser-profiles.json'), JSON.stringify({ version: 1, aliases: {}, defaultContextId: 'profile-default' }));
+        vi.stubEnv('WEBCMD_CONFIG_DIR', configDir);
+        vi.stubEnv('WEBCMD_PROFILE', '');
+        try {
+            vi.mocked(fetch).mockResolvedValue({
+                status: 200,
+                json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+            });
+            await sendCommand('exec', { code: '1 + 1' });
+            const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+            expect(body.contextId).toBeUndefined();
+            expect(body.preferredContextId).toBe('profile-default');
+        }
+        finally {
+            fs.rmSync(configDir, { recursive: true, force: true });
+        }
     });
     it('sendCommand uses explicit windowMode before WEBCMD_WINDOW env fallback', async () => {
         vi.stubEnv('WEBCMD_WINDOW', 'foreground');
@@ -180,27 +186,19 @@ describe('daemon-client', () => {
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.windowMode).toBe('background');
     });
-    it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
+    it('sendCommand treats duplicate pending ids from an old daemon as unknown instead of minting a new id', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
         const fetchMock = vi.mocked(fetch);
-        fetchMock
-            .mockResolvedValueOnce({
+        fetchMock.mockResolvedValueOnce({
             ok: false,
             status: 409,
             json: () => Promise.resolve({ ok: false, error: 'Duplicate command id already pending; retry' }),
-        })
-            .mockResolvedValueOnce({
-            ok: true,
-            status: 200,
-            json: () => Promise.resolve({ id: 'server', ok: true, data: 42 }),
         });
-        await expect(sendCommand('exec', { code: '6 * 7' })).resolves.toBe(42);
-        expect(fetchMock).toHaveBeenCalledTimes(2);
-        const ids = fetchMock.mock.calls.map(([, init]) => {
-            const body = JSON.parse(String(init?.body));
-            return body.id;
+        await expect(sendCommand('exec', { code: '6 * 7' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
         });
-        expect(ids[0]).not.toBe(ids[1]);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
     });
     it('sendCommand does not retry command_result_unknown even when the message looks transient', async () => {
         const fetchMock = vi.mocked(fetch);
@@ -222,7 +220,7 @@ describe('daemon-client', () => {
         });
         expect(fetchMock).toHaveBeenCalledTimes(1);
     });
-    it('sendCommand runs full bridge ensure on a pre-dispatch failure, then resends with a fresh id', async () => {
+    it('sendCommand runs full bridge ensure on a pre-dispatch failure, then resends with the same id', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_321);
         const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
             health: {
@@ -235,7 +233,7 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
@@ -260,9 +258,9 @@ describe('daemon-client', () => {
         expect(ensureSpy).toHaveBeenCalledWith(expect.objectContaining({ contextId: 'work', verbose: false }));
         const ids = fetchMock.mock.calls.map(([, init]) => JSON.parse(String(init?.body)).id);
         expect(ids).toHaveLength(2);
-        expect(ids[0]).not.toBe(ids[1]);
+        expect(ids[0]).toBe(ids[1]);
     });
-    it('sendCommand runs full bridge ensure on a local TypeError before resending', async () => {
+    it('sendCommand runs full bridge ensure on a pre-connect TypeError before resending', async () => {
         const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
             health: {
                 state: 'ready',
@@ -274,14 +272,16 @@ describe('daemon-client', () => {
                     runtimeName: 'fake',
                     pending: 0,
                     memoryMB: 0,
-                    port: 19825,
+                    port: 9777,
                 },
             },
             spawnedProcess: null,
         });
+        const refused = new TypeError('fetch failed');
+        refused.cause = Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:9777'), { code: 'ECONNREFUSED' });
         const fetchMock = vi.mocked(fetch);
         fetchMock
-            .mockRejectedValueOnce(new TypeError('fetch failed'))
+            .mockRejectedValueOnce(refused)
             .mockResolvedValueOnce({
             ok: true,
             status: 200,
@@ -291,6 +291,33 @@ describe('daemon-client', () => {
         expect(ensureSpy).toHaveBeenCalledWith(expect.objectContaining({ verbose: false }));
         expect(fetchMock).toHaveBeenCalledTimes(2);
     });
+    it('sendCommand does not resend a post-connect TypeError because the command may have been dispatched', async () => {
+        const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady').mockResolvedValue({
+            health: {
+                state: 'ready',
+                status: {
+                    ok: true,
+                    pid: 1,
+                    uptime: 1,
+                    runtimeConnected: true,
+                    runtimeName: 'fake',
+                    pending: 0,
+                    memoryMB: 0,
+                    port: 9777,
+                },
+            },
+            spawnedProcess: null,
+        });
+        const reset = new TypeError('fetch failed');
+        reset.cause = Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' });
+        vi.mocked(fetch).mockRejectedValueOnce(reset);
+        await expect(sendCommand('navigate', { url: 'https://example.com' })).rejects.toMatchObject({
+            name: 'BrowserCommandError',
+            code: 'command_result_unknown',
+        });
+        expect(ensureSpy).toHaveBeenCalledTimes(1);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
     it('sendCommand does NOT wait when the bridge reports profile_required', async () => {
         const ensureSpy = vi.spyOn(daemonLifecycle, 'ensureBrowserBridgeReady');
         const fetchMock = vi.mocked(fetch);
@@ -323,4 +350,65 @@ describe('daemon-client', () => {
         expect(ensureSpy).not.toHaveBeenCalled();
         expect(fetch).toHaveBeenCalledTimes(1);
     });
+    it('sendCommand plumbs the default command timeout and absolute deadline into the request body', async () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 1 }),
+        });
+        await expect(sendCommand('exec', { code: '1' })).resolves.toBe(1);
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(120);
+        expect(body.deadlineAt).toBe(1_763_000_120_000);
+    });
+    it('sendCommand extends the daemon deadline past a runtime-side timeoutMs', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: { downloaded: true } }),
+        });
+        await sendCommand('wait-download', { timeoutMs: 240_000 });
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(255);
+    });
+    it('setDaemonCommandTimeoutSeconds raises the transport deadline for a user timeout', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 1 }),
+        });
+        setDaemonCommandTimeoutSeconds(300);
+        await sendCommand('exec', { code: '1' });
+        const body = JSON.parse(String(fetchMock.mock.calls[0][1]?.body));
+        expect(body.timeout).toBe(300);
+    });
+    it('client HTTP abort fires only after the daemon timeout margin', async () => {
+        vi.useFakeTimers();
+        try {
+            const fetchMock = vi.mocked(fetch);
+            let aborted = false;
+            fetchMock.mockImplementationOnce((_url, init) => new Promise((_, reject) => {
+                init?.signal?.addEventListener('abort', () => {
+                    aborted = true;
+                    reject(Object.assign(new Error('This operation was aborted'), { name: 'AbortError' }));
+                });
+            }));
+            const pending = sendCommand('exec', { code: '1' }).catch((err) => err);
+            await vi.advanceTimersByTimeAsync(120_000 + 9_999);
+            expect(aborted).toBe(false);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(aborted).toBe(true);
+            await expect(pending).resolves.toMatchObject({
+                name: 'BrowserCommandError',
+                code: 'command_result_unknown',
+            });
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
 });

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

@@ -1,20 +1,8 @@
-import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT, unsupportedDaemonPortEnvMessage } from '../constants.js';
+import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
 const DAEMON_PORT = DEFAULT_DAEMON_PORT;
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const WEBCMD_HEADERS = { [DAEMON_HEADER_NAME]: '1' };
-class UnsupportedDaemonPortEnvError extends Error {
-    constructor(value) {
-        super(unsupportedDaemonPortEnvMessage(value));
-        this.name = 'UnsupportedDaemonPortEnvError';
-    }
-}
-function assertSupportedDaemonPortEnv() {
-    const value = process.env.WEBCMD_DAEMON_PORT;
-    if (value !== undefined && value !== '')
-        throw new UnsupportedDaemonPortEnvError(value);
-}
 export async function requestDaemon(pathname, init) {
-    assertSupportedDaemonPortEnv();
     const { timeout = 2000, headers, ...rest } = init ?? {};
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
@@ -37,9 +25,7 @@ export async function fetchDaemonStatus(opts) {
             return null;
         return await res.json();
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return null;
     }
 }
@@ -60,9 +46,7 @@ export async function requestDaemonShutdown(opts) {
         const res = await requestDaemon('/shutdown', { method: 'POST', timeout: opts?.timeout ?? 5000 });
         return res.ok;
     }
-    catch (err) {
-        if (err instanceof UnsupportedDaemonPortEnvError)
-            throw err;
+    catch {
         return false;
     }
 }

package/dist/src/browser/errors.js

@@ -34,12 +34,23 @@ const TARGET_NAVIGATION_PATTERNS = [
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+const ERROR_CODE_ADVICE = {
+    attach_failed: { kind: 'extension-transient', retryable: true, delayMs: 1500 },
+    tab_gone: { kind: 'extension-transient', retryable: true, delayMs: 1500 },
+    target_navigated: { kind: 'target-navigation', retryable: true, delayMs: 200 },
+    detached_mid_command: { kind: 'non-retryable', retryable: false, delayMs: 0 },
+    cdp_timeout: { kind: 'non-retryable', retryable: false, delayMs: 0 },
+};
 /**
  * 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 code = err && typeof err === 'object' ? err.code : undefined;
+    if (typeof code === 'string' && ERROR_CODE_ADVICE[code]) {
+        return ERROR_CODE_ADVICE[code];
+    }
     const msg = errorMessage(err);
     // Runtime/daemon transient errors — longer recovery time
     if (EXTENSION_TRANSIENT_PATTERNS.some(p => msg.includes(p))) {

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

@@ -19,8 +19,9 @@ export declare class Page extends BasePage {
     private readonly windowMode?;
     private readonly surface;
     private readonly siteSession?;
+    readonly preferredContextId?: string | undefined;
     private readonly _idleTimeout;
-    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined);
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined, preferredContextId?: string | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;