@godscene/web 1.7.11

package/dist/lib/web-page.js

@@ -0,0 +1,322 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    commonWebActionsForWebPage: ()=>commonWebActionsForWebPage,
+    getKeyCommands: ()=>getKeyCommands,
+    AbstractWebPage: ()=>AbstractWebPage
+});
+const external_node_assert_namespaceObject = require("node:assert");
+var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
+const core_namespaceObject = require("@godscene/core");
+const device_namespaceObject = require("@godscene/core/device");
+const utils_namespaceObject = require("@godscene/core/utils");
+const logger_namespaceObject = require("@godscene/shared/logger");
+const us_keyboard_layout_namespaceObject = require("@godscene/shared/us-keyboard-layout");
+const debug = (0, logger_namespaceObject.getDebug)('web:page');
+const navigateParamSchema = core_namespaceObject.z.object({
+    url: core_namespaceObject.z.string().describe('The URL to navigate to. Must start with https://, file://, or a similar protocol.')
+});
+function normalizeKeyInputs(value) {
+    const inputs = Array.isArray(value) ? value : [
+        value
+    ];
+    const result = [];
+    for (const input of inputs){
+        if ('string' != typeof input) {
+            result.push(input);
+            continue;
+        }
+        const trimmed = input.trim();
+        if (!trimmed) {
+            result.push(input);
+            continue;
+        }
+        let normalized = trimmed;
+        if (normalized.length > 1 && normalized.includes('+')) normalized = normalized.replace(/\s*\+\s*/g, ' ');
+        if (/\s/.test(normalized)) normalized = normalized.replace(/\s+/g, ' ');
+        const transformed = (0, us_keyboard_layout_namespaceObject.transformHotkeyInput)(normalized);
+        if (1 === transformed.length && '' === transformed[0] && '' !== trimmed) {
+            result.push(input);
+            continue;
+        }
+        if (0 === transformed.length) {
+            result.push(input);
+            continue;
+        }
+        result.push(...transformed);
+    }
+    return result;
+}
+function getKeyCommands(value) {
+    const keys = normalizeKeyInputs(value);
+    return keys.reduce((acc, k)=>{
+        const includeMeta = keys.includes('Meta') || keys.includes('Control');
+        if (includeMeta && ('a' === k || 'A' === k)) return acc.concat([
+            {
+                key: k,
+                command: 'SelectAll'
+            }
+        ]);
+        if (includeMeta && ('c' === k || 'C' === k)) return acc.concat([
+            {
+                key: k,
+                command: 'Copy'
+            }
+        ]);
+        if (includeMeta && ('v' === k || 'V' === k)) return acc.concat([
+            {
+                key: k,
+                command: 'Paste'
+            }
+        ]);
+        return acc.concat([
+            {
+                key: k
+            }
+        ]);
+    }, []);
+}
+class AbstractWebPage extends device_namespaceObject.AbstractInterface {
+    get mouse() {
+        return {
+            click: async (x, y, options)=>{},
+            wheel: async (deltaX, deltaY)=>{},
+            move: async (x, y)=>{},
+            drag: async (from, to)=>{}
+        };
+    }
+    get keyboard() {
+        return {
+            type: async (text)=>{},
+            press: async (action)=>{}
+        };
+    }
+    async clearInput(element) {}
+}
+const commonWebActionsForWebPage = (page, includeTouchEvents = false)=>[
+        (0, device_namespaceObject.defineActionTap)(async (param)=>{
+            const element = param.locate;
+            external_node_assert_default()(element, 'Element not found, cannot tap');
+            await page.mouse.click(element.center[0], element.center[1], {
+                button: 'left'
+            });
+        }),
+        (0, device_namespaceObject.defineActionRightClick)(async (param)=>{
+            const element = param.locate;
+            external_node_assert_default()(element, 'Element not found, cannot right click');
+            await page.mouse.click(element.center[0], element.center[1], {
+                button: 'right'
+            });
+        }),
+        (0, device_namespaceObject.defineActionDoubleClick)(async (param)=>{
+            const element = param.locate;
+            external_node_assert_default()(element, 'Element not found, cannot double click');
+            await page.mouse.click(element.center[0], element.center[1], {
+                button: 'left',
+                count: 2
+            });
+        }),
+        (0, device_namespaceObject.defineActionHover)(async (param)=>{
+            const element = param.locate;
+            external_node_assert_default()(element, 'Element not found, cannot hover');
+            await page.mouse.move(element.center[0], element.center[1]);
+        }),
+        (0, device_namespaceObject.defineActionInput)(async (param)=>{
+            const element = param.locate;
+            if (element && 'typeOnly' !== param.mode) await page.clearInput(element);
+            else if (element && 'typeOnly' === param.mode) {
+                await page.mouse.click(element.center[0], element.center[1], {
+                    button: 'left'
+                });
+                await page.keyboard.press([
+                    {
+                        key: 'End'
+                    }
+                ]);
+            }
+            if ('clear' === param.mode) return;
+            if (!param || !param.value) return;
+            await page.keyboard.type(param.value);
+            await page.flushPendingVisualUpdate?.();
+        }),
+        (0, device_namespaceObject.defineActionKeyboardPress)(async (param)=>{
+            const element = param.locate;
+            if (element) await page.mouse.click(element.center[0], element.center[1], {
+                button: 'left'
+            });
+            const keys = getKeyCommands(param.keyName);
+            await page.keyboard.press(keys);
+            await page.flushPendingVisualUpdate?.();
+        }),
+        (0, device_namespaceObject.defineActionCursorMove)(async (param)=>{
+            const arrowKey = 'left' === param.direction ? 'ArrowLeft' : 'ArrowRight';
+            const times = param.times ?? 1;
+            for(let i = 0; i < times; i++){
+                await page.keyboard.press([
+                    {
+                        key: arrowKey
+                    }
+                ]);
+                await (0, utils_namespaceObject.sleep)(100);
+            }
+        }),
+        (0, device_namespaceObject.defineActionScroll)(async (param)=>{
+            const element = param.locate;
+            const startingPoint = element ? {
+                left: element.center[0],
+                top: element.center[1]
+            } : void 0;
+            const scrollToEventName = param?.scrollType;
+            if ('scrollToTop' === scrollToEventName) await page.scrollUntilTop(startingPoint);
+            else if ('scrollToBottom' === scrollToEventName) await page.scrollUntilBottom(startingPoint);
+            else if ('scrollToRight' === scrollToEventName) await page.scrollUntilRight(startingPoint);
+            else if ('scrollToLeft' === scrollToEventName) await page.scrollUntilLeft(startingPoint);
+            else if ('singleAction' !== scrollToEventName && scrollToEventName) throw new Error(`Unknown scroll event type: ${scrollToEventName}, param: ${JSON.stringify(param)}`);
+            else {
+                if (param?.direction !== 'down' && param && param.direction) if ('up' === param.direction) await page.scrollUp(param.distance || void 0, startingPoint);
+                else if ('left' === param.direction) await page.scrollLeft(param.distance || void 0, startingPoint);
+                else if ('right' === param.direction) await page.scrollRight(param.distance || void 0, startingPoint);
+                else throw new Error(`Unknown scroll direction: ${param.direction}`);
+                else await page.scrollDown(param?.distance || void 0, startingPoint);
+                await (0, utils_namespaceObject.sleep)(500);
+            }
+        }),
+        (0, device_namespaceObject.defineActionDragAndDrop)(async (param)=>{
+            const from = param.from;
+            const to = param.to;
+            external_node_assert_default()(from, 'missing "from" param for drag and drop');
+            external_node_assert_default()(to, 'missing "to" param for drag and drop');
+            await page.mouse.drag({
+                x: from.center[0],
+                y: from.center[1]
+            }, {
+                x: to.center[0],
+                y: to.center[1]
+            });
+        }),
+        (0, device_namespaceObject.defineActionLongPress)(async (param)=>{
+            const element = param.locate;
+            external_node_assert_default()(element, 'Element not found, cannot long press');
+            const duration = param?.duration;
+            await page.longPress(element.center[0], element.center[1], duration);
+        }),
+        (0, device_namespaceObject.defineActionPinch)(async (param)=>{
+            const { centerX, centerY, startDistance, endDistance, duration } = (0, device_namespaceObject.normalizePinchParam)(param, await page.size());
+            await page.pinch(centerX, centerY, startDistance, endDistance, duration);
+        }),
+        ...includeTouchEvents ? [
+            (0, device_namespaceObject.defineActionSwipe)(async (param)=>{
+                const { width, height } = await page.size();
+                const { start, end } = param;
+                const startPoint = start ? {
+                    x: start.center[0],
+                    y: start.center[1]
+                } : {
+                    x: width / 2,
+                    y: height / 2
+                };
+                let endPoint;
+                if (end) endPoint = {
+                    x: end.center[0],
+                    y: end.center[1]
+                };
+                else if (param.distance) {
+                    const direction = param.direction;
+                    if (!direction) throw new Error('direction is required for swipe gesture');
+                    endPoint = {
+                        x: startPoint.x + ('right' === direction ? param.distance : 'left' === direction ? -param.distance : 0),
+                        y: startPoint.y + ('down' === direction ? param.distance : 'up' === direction ? -param.distance : 0)
+                    };
+                } else throw new Error('Either end or distance must be specified for swipe gesture');
+                endPoint.x = Math.max(0, Math.min(endPoint.x, width));
+                endPoint.y = Math.max(0, Math.min(endPoint.y, height));
+                const duration = param.duration;
+                debug(`swipe from ${startPoint.x}, ${startPoint.y} to ${endPoint.x}, ${endPoint.y} with duration ${duration}ms, repeat is set to ${param.repeat}`);
+                let repeat = 'number' == typeof param.repeat ? param.repeat : 1;
+                if (0 === repeat) repeat = 10;
+                for(let i = 0; i < repeat; i++)await page.swipe(startPoint, endPoint, duration);
+            })
+        ] : [],
+        (0, device_namespaceObject.defineActionClearInput)(async (param)=>{
+            await page.clearInput(param.locate);
+        }),
+        (0, device_namespaceObject.defineAction)({
+            name: 'Navigate',
+            description: 'Navigate the browser to a specified URL. Opens the URL in the current tab.',
+            paramSchema: navigateParamSchema,
+            sample: {
+                url: 'https://www.example.com'
+            },
+            call: async (param)=>{
+                if (!page.navigate) throw new Error('Navigate operation is not supported on this page type');
+                await page.navigate(param.url);
+            }
+        }),
+        (0, device_namespaceObject.defineAction)({
+            name: 'Reload',
+            description: 'Reload the current page',
+            call: async ()=>{
+                if (!page.reload) throw new Error('Reload operation is not supported on this page type');
+                await page.reload();
+            }
+        }),
+        (0, device_namespaceObject.defineAction)({
+            name: 'GoBack',
+            description: 'Navigate back in browser history',
+            call: async ()=>{
+                if (!page.goBack) throw new Error('GoBack operation is not supported on this page type');
+                await page.goBack();
+            }
+        }),
+        (0, device_namespaceObject.defineAction)({
+            name: 'GoForward',
+            description: 'Navigate forward in browser history',
+            call: async ()=>{
+                if (!page.goForward) throw new Error('GoForward operation is not supported on this page type');
+                await page.goForward();
+            }
+        })
+    ];
+exports.AbstractWebPage = __webpack_exports__.AbstractWebPage;
+exports.commonWebActionsForWebPage = __webpack_exports__.commonWebActionsForWebPage;
+exports.getKeyCommands = __webpack_exports__.getKeyCommands;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "AbstractWebPage",
+    "commonWebActionsForWebPage",
+    "getKeyCommands"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types/bin.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';

package/dist/types/bridge-mode/agent-cli-side.d.ts

@@ -0,0 +1,49 @@
+import { Agent, type AgentOpt } from '@godscene/core/agent';
+import { type BridgeConnectTabOptions } from './common';
+import type { ExtensionBridgePageBrowserSide } from './page-browser-side';
+interface ChromeExtensionPageCliSide extends ExtensionBridgePageBrowserSide {
+    showStatusMessage: (message: string) => Promise<void>;
+}
+export declare const getBridgePageInCliSide: (options?: {
+    host?: string;
+    port?: number;
+    timeout?: number | false;
+    closeConflictServer?: boolean;
+}) => ChromeExtensionPageCliSide;
+export declare class AgentOverChromeBridge extends Agent<ChromeExtensionPageCliSide> {
+    private destroyAfterDisconnectFlag?;
+    constructor(opts?: AgentOpt & {
+        /**
+         * Enable remote access to the bridge server.
+         * - false (default): Only localhost can connect (most secure)
+         * - true: Allow remote machines to connect (binds to 0.0.0.0)
+         */
+        allowRemoteAccess?: boolean;
+        /**
+         * Custom host to bind the bridge server to.
+         * Overrides allowRemoteAccess if specified.
+         */
+        host?: string;
+        /**
+         * Custom port for the bridge server.
+         * @default 3766
+         */
+        port?: number;
+        closeNewTabsAfterDisconnect?: boolean;
+        serverListeningTimeout?: number | false;
+        closeConflictServer?: boolean;
+    });
+    setDestroyOptionsAfterConnect(): Promise<void>;
+    connectNewTabWithUrl(url: string, options?: BridgeConnectTabOptions): Promise<void>;
+    getBrowserTabList(): Promise<{
+        id: string;
+        title: string;
+        url: string;
+        currentActiveTab: boolean;
+    }[]>;
+    setActiveTabId(tabId: string): Promise<void>;
+    connectCurrentTab(options?: BridgeConnectTabOptions): Promise<void>;
+    aiAct(prompt: string, options?: any): Promise<string | undefined>;
+    destroy(closeNewTabsAfterDisconnect?: boolean): Promise<void>;
+}
+export {};

package/dist/types/bridge-mode/browser.d.ts

@@ -0,0 +1,2 @@
+import { ExtensionBridgePageBrowserSide } from '../bridge-mode/page-browser-side';
+export { ExtensionBridgePageBrowserSide };

package/dist/types/bridge-mode/common.d.ts

@@ -0,0 +1,74 @@
+export declare const DefaultBridgeServerHost = "127.0.0.1";
+export declare const DefaultBridgeServerPort = 3766;
+export declare const DefaultLocalEndpoint = "http://127.0.0.1:3766";
+export declare const BridgeCallTimeout = 30000;
+/**
+ * Get the server host based on configuration options.
+ * Priority: explicit host > allowRemoteAccess > default (127.0.0.1)
+ */
+export declare function getBridgeServerHost(options?: {
+    host?: string;
+    allowRemoteAccess?: boolean;
+}): string;
+export declare enum BridgeEvent {
+    Call = "bridge-call",
+    CallResponse = "bridge-call-response",
+    UpdateAgentStatus = "bridge-update-agent-status",
+    Message = "bridge-message",
+    Connected = "bridge-connected",
+    Refused = "bridge-refused",
+    ConnectNewTabWithUrl = "connectNewTabWithUrl",
+    ConnectCurrentTab = "connectCurrentTab",
+    GetBrowserTabList = "getBrowserTabList",
+    SetDestroyOptions = "setDestroyOptions",
+    SetActiveTabId = "setActiveTabId"
+}
+export declare const BridgeSignalKill = "MIDSCENE_BRIDGE_SIGNAL_KILL";
+export interface BridgeConnectTabOptions {
+    /**
+     * If true, the page will always track the active tab.
+     * @default true
+     */
+    forceSameTabNavigation?: boolean;
+    /**
+     * Custom timeout for connecting to the tab in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+export declare enum MouseEvent {
+    PREFIX = "mouse.",
+    Click = "mouse.click",
+    Wheel = "mouse.wheel",
+    Move = "mouse.move",
+    Drag = "mouse.drag"
+}
+export declare enum KeyboardEvent {
+    PREFIX = "keyboard.",
+    Type = "keyboard.type",
+    Press = "keyboard.press"
+}
+export declare const BridgePageType = "page-over-chrome-extension-bridge";
+export declare const BridgeErrorCodeNoClientConnected = "no-client-connected";
+export interface BridgeCall {
+    method: string;
+    args: any[];
+    response: any;
+    callTime: number;
+    responseTime: number;
+    callback: (error: Error | undefined, response: any) => void;
+    error?: Error;
+}
+export interface BridgeCallRequest {
+    id: string;
+    method: string;
+    args: any[];
+}
+export interface BridgeCallResponse {
+    id: string;
+    response: any;
+    error?: any;
+}
+export interface BridgeConnectedEventPayload {
+    version: string;
+}

package/dist/types/bridge-mode/index.d.ts

@@ -0,0 +1,4 @@
+import { AgentOverChromeBridge } from './agent-cli-side';
+export { AgentOverChromeBridge };
+export { overrideAIConfig } from '@godscene/shared/env';
+export { killRunningServer } from './io-server';

package/dist/types/bridge-mode/io-client.d.ts

@@ -0,0 +1,10 @@
+export declare class BridgeClient {
+    endpoint: string;
+    onBridgeCall: (method: string, args: any[]) => Promise<any>;
+    onDisconnect?: (() => void) | undefined;
+    private socket;
+    serverVersion: string | null;
+    constructor(endpoint: string, onBridgeCall: (method: string, args: any[]) => Promise<any>, onDisconnect?: (() => void) | undefined);
+    connect(): Promise<unknown>;
+    disconnect(): void;
+}

package/dist/types/bridge-mode/io-server.d.ts

@@ -0,0 +1,27 @@
+import { type BridgeCall } from './common';
+export declare const killRunningServer: (port?: number, host?: string) => Promise<void>;
+export declare class BridgeServer {
+    host: string;
+    port: number;
+    onConnect?: (() => void) | undefined;
+    onDisconnect?: ((reason: string) => void) | undefined;
+    closeConflictServer?: boolean | undefined;
+    private callId;
+    private io;
+    private socket;
+    private listeningTimeoutId;
+    private listeningTimerFlag;
+    private connectionTipTimer;
+    calls: Record<string, BridgeCall>;
+    private connectionLost;
+    private connectionLostReason;
+    constructor(host: string, port: number, onConnect?: (() => void) | undefined, onDisconnect?: ((reason: string) => void) | undefined, closeConflictServer?: boolean | undefined);
+    listen(opts?: {
+        timeout?: number | false;
+    }): Promise<void>;
+    private connectionLostErrorMsg;
+    private triggerCallResponseCallback;
+    private emitCall;
+    call<T = any>(method: string, args: any[], timeout?: number): Promise<T>;
+    close(): Promise<void | undefined>;
+}

package/dist/types/bridge-mode/page-browser-side.d.ts

@@ -0,0 +1,21 @@
+import ChromeExtensionProxyPage from '../chrome-extension/page';
+import type { ChromePageDestroyOptions } from '../web-page';
+import { type BridgeConnectTabOptions } from './common';
+import { BridgeClient } from './io-client';
+export declare class ExtensionBridgePageBrowserSide extends ChromeExtensionProxyPage {
+    serverEndpoint?: string | undefined;
+    onDisconnect: () => void;
+    onLogMessage: (message: string, type: 'log' | 'status') => void;
+    onConnectionRequest?: (() => Promise<boolean>) | undefined;
+    bridgeClient: BridgeClient | null;
+    private destroyOptions?;
+    private newlyCreatedTabIds;
+    private confirmationPromise;
+    constructor(serverEndpoint?: string | undefined, onDisconnect?: () => void, onLogMessage?: (message: string, type: 'log' | 'status') => void, forceSameTabNavigation?: boolean, onConnectionRequest?: (() => Promise<boolean>) | undefined);
+    private setupBridgeClient;
+    connect(): Promise<void>;
+    connectNewTabWithUrl(url: string, options?: BridgeConnectTabOptions): Promise<void>;
+    connectCurrentTab(options?: BridgeConnectTabOptions): Promise<void>;
+    setDestroyOptions(options: ChromePageDestroyOptions): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/types/cdp-proxy-constants.d.ts

@@ -0,0 +1,4 @@
+export declare const PROXY_ENDPOINT_FILE: string;
+export declare const PROXY_PID_FILE: string;
+export declare const PROXY_UPSTREAM_FILE: string;
+export declare const TARGET_ID_FILE: string;

package/dist/types/cdp-proxy-manager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CDP proxy lifecycle manager (parent-side).
+ *
+ * Owns everything the CLI needs to start, locate, replace and kill the
+ * standalone `cdp-proxy.ts` child process — including its on-disk
+ * metadata files (PROXY_ENDPOINT_FILE / PROXY_PID_FILE /
+ * PROXY_UPSTREAM_FILE). Also handles auto-resolving page-level CDP URLs
+ * to browser-level endpoints via `/json/version`, since puppeteer-core
+ * cannot connect to page-level URLs directly.
+ *
+ * Other modules (notably `mcp-tools-cdp.ts`) use this through the
+ * `getProxyEndpoint()` entry point and never touch the metadata files
+ * themselves. The cross-command targetId is a separate concern owned by
+ * `cdp-target-store.ts`.
+ */
+/**
+ * True if the previously spawned proxy process is still running.
+ */
+export declare function isProxyAlive(): boolean;
+/**
+ * The local WebSocket URL the running proxy is serving, or null.
+ */
+export declare function readProxyEndpoint(): string | null;
+/**
+ * The Chrome endpoint the running proxy is connected to, or null.
+ */
+export declare function readProxyUpstream(): string | null;
+/**
+ * Stop the running proxy and discard the cross-command targetId.
+ *
+ * Sends SIGTERM and waits for the proxy's own SIGTERM handler to remove
+ * its PROXY_*_FILE metadata via `cleanupIfOwned()`. When the PID file
+ * disappears we know the next `spawnProxy()` can safely take over
+ * without tripping the duplicate-proxy guard. Falls back to SIGKILL +
+ * manual sweep if the proxy is unresponsive within `PROXY_TERM_GRACE_MS`.
+ *
+ * The targetId file is cleared regardless of the proxy's state because
+ * it points into the outgoing Chrome's tab list.
+ */
+export declare function killProxy(): Promise<void>;
+/**
+ * Resolve the proxy endpoint to use for the given Chrome endpoint.
+ *
+ * - Page-level URLs are auto-resolved to browser-level via /json/version.
+ * - If a proxy is already running and connected to the same upstream,
+ *   reuse it.
+ * - If a proxy is running but pointed at a different upstream, kill it
+ *   and start a fresh one.
+ * - If spawning the proxy fails, fall back to the raw Chrome endpoint
+ *   (the caller will hit Chrome's permission popup directly but at
+ *   least the command does not fail outright).
+ */
+export declare function getProxyEndpoint(chromeEndpoint: string): Promise<string>;

package/dist/types/cdp-proxy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CDP WebSocket Proxy — standalone process.
+ *
+ * Holds a persistent WebSocket connection to Chrome's CDP endpoint and
+ * exposes a local WebSocket server. Midscene CLI processes connect to the
+ * proxy instead of Chrome directly, so Chrome's "Allow remote debugging"
+ * permission popup only fires once (when the proxy connects).
+ *
+ * Lifecycle notes:
+ *  - When all downstream clients disconnect the proxy stays running but
+ *    marks the upstream as needing reconnection. The actual reconnect is
+ *    deferred to the moment the next client connects, so Chrome's CDP
+ *    state (notably Target.setDiscoverTargets) is reset and the new
+ *    client receives all targetCreated events.
+ *  - On startup, if another proxy is already alive the new instance
+ *    announces "duplicate proxy detected" on stderr and exits 0 without
+ *    touching the existing metadata files.
+ *
+ * Exit conditions:
+ *  1. Upstream Chrome connection closes or errors.
+ *  2. No downstream client message for IDLE_TIMEOUT_MS (default 5 min).
+ *  3. SIGTERM / SIGINT.
+ *  4. Duplicate proxy detected on startup (exits 0 with stderr notice).
+ *
+ * Usage (spawned by mcp-tools-cdp.ts):
+ *   node cdp-proxy.js <chrome-ws-endpoint>
+ *
+ * On startup, prints the proxy endpoint to stdout as a single JSON line:
+ *   {"endpoint":"ws://127.0.0.1:<port>/devtools/browser"}
+ * and writes:
+ *   - PROXY_ENDPOINT_FILE — the local proxy URL above
+ *   - PROXY_PID_FILE      — this process's pid
+ *   - PROXY_UPSTREAM_FILE — the Chrome endpoint the proxy is connected to,
+ *                           so callers can detect when the requested
+ *                           upstream has changed and replace the proxy.
+ */
+export {};

package/dist/types/cdp-target-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Persistent store for the CDP-mode "current tab" targetId.
+ *
+ * The Midscene CLI runs each command as a fresh Node process, so anything
+ * the previous command knew about which tab was being driven must survive
+ * across processes. This store writes the chosen targetId to a temp file
+ * after `connect`/`act`/etc. succeed, and the next command reads it back
+ * to bind to the exact same tab — even when Chrome holds 14 of them.
+ *
+ * Owns nothing else. The CDP proxy lifecycle and its own metadata files
+ * live in `cdp-proxy-manager.ts`.
+ */
+/**
+ * Read the saved targetId, or null if no command has stored one yet.
+ */
+export declare function readSavedTargetId(): string | null;
+/**
+ * Save a targetId so the next CLI command can rebind to the same tab.
+ */
+export declare function saveTargetId(targetId: string): void;
+/**
+ * Discard the saved targetId — call when disconnecting or when the
+ * upstream Chrome changes (the targetId would point into the old
+ * browser's tab list).
+ */
+export declare function cleanupTargetIdFile(): void;

package/dist/types/chrome-extension/agent.d.ts

@@ -0,0 +1,4 @@
+import { Agent as PageAgent } from '@godscene/core/agent';
+export declare class ChromeExtensionProxyPageAgent extends PageAgent {
+    protected isRetryableContextError(error: unknown): boolean;
+}