@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/computer/motor/cdp.d.ts

@@ -0,0 +1,107 @@
+import { type SerializedOutline } from "./outline.ts";
+export interface CdpConsoleEntry {
+    level: string;
+    text: string;
+}
+export interface CdpPageContext {
+    contextId: string;
+    targetId: string;
+    title: string;
+    url: string;
+}
+export interface CdpSnapshotTarget {
+    ref: string;
+    source: "browser_ax";
+    role: string;
+    name: string;
+    value?: string;
+    actions: string[];
+    backendNodeId?: number;
+}
+export interface CdpPageSnapshot {
+    contextId: string;
+    snapshotId: string;
+    targetId: string;
+    title: string;
+    url: string;
+    capturedAt: number;
+    text: string;
+    targets: CdpSnapshotTarget[];
+    outline: SerializedOutline;
+    diagnostics: {
+        cdp: "connected";
+        targetCount: number;
+    };
+}
+export interface CdpEvaluationResult {
+    contextId: string;
+    value: unknown;
+}
+/** Window frame in screen points, as reported by the AX side. */
+export interface WindowFrame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare class CdpTab {
+    private nextId;
+    private readonly pending;
+    private consoleBuffer;
+    private loadFired;
+    private readonly ws;
+    readonly targetId: string;
+    title: string;
+    private constructor();
+    static connect(wsUrl: string, targetId: string, title: string): Promise<CdpTab>;
+    get isOpen(): boolean;
+    close(): void;
+    /** Evaluates a JS expression in the page and returns its primitive value. */
+    evaluate(expression: string): Promise<unknown>;
+    accessibilityTree(): Promise<unknown[]>;
+    navigate(url: string): Promise<void>;
+    clickBackendNode(backendNodeId: number): Promise<void>;
+    typeIntoBackendNode(backendNodeId: number, text: string, replace: boolean): Promise<void>;
+    scrollBy(deltaX: number, deltaY: number, backendNodeId?: number): Promise<void>;
+    typeIntoFocused(text: string): Promise<void>;
+    keypress(keys: string[]): Promise<void>;
+    mouseAt(x: number, y: number, type: "mouseMoved" | "mousePressed" | "mouseReleased", button?: "left" | "right" | "middle", clickCount?: number): Promise<void>;
+    dragPath(path: Array<{
+        x: number;
+        y: number;
+    }>): Promise<void>;
+    private withBackendNode;
+    /** Screen bounds of the browser window containing this tab. */
+    windowBounds(): Promise<WindowFrame | undefined>;
+    /** Returns buffered console messages/exceptions and clears the buffer. */
+    drainConsole(): CdpConsoleEntry[];
+    private send;
+    private handleMessage;
+    private pushConsole;
+    private rejectAllPending;
+}
+/** Close session-owned CDP state without affecting the browser process. */
+export declare function disconnectCdp(): void;
+/**
+ * Returns a CDP connection to the tab matching the controlled window's title
+ * (and, when provided, the window's screen frame), or undefined when CDP is
+ * disabled, unreachable, or no tab matches. Reuses the cached connection
+ * while it still matches; failures are cached briefly so an unreachable
+ * endpoint never adds per-call latency.
+ */
+export declare function cdpTabForWindow(windowTitle: string, frame?: WindowFrame): Promise<CdpTab | undefined>;
+export declare function listCdpPageContexts(): Promise<CdpPageContext[]>;
+export declare function cdpClickForContext(contextId: string, backendNodeId: number): Promise<boolean>;
+export declare function cdpTypeForContext(contextId: string, backendNodeId: number, text: string, replace: boolean): Promise<boolean>;
+export declare function cdpScrollForContext(contextId: string, deltaX: number, deltaY: number, backendNodeId?: number): Promise<boolean>;
+export declare function cdpTypeFocusedForContext(contextId: string, text: string): Promise<boolean>;
+export declare function cdpKeypressForContext(contextId: string, keys: string[]): Promise<boolean>;
+export declare function cdpMouseForContext(contextId: string, x: number, y: number, type: "mouseMoved" | "mousePressed" | "mouseReleased", button?: "left" | "right" | "middle", clickCount?: number): Promise<boolean>;
+export declare function cdpDragForContext(contextId: string, path: Array<{
+    x: number;
+    y: number;
+}>): Promise<boolean>;
+export declare function cdpNavigateContext(contextId: string, url: string): Promise<boolean>;
+export declare function cdpEvaluateForContext(contextId: string, expression: string): Promise<CdpEvaluationResult | undefined>;
+export declare function cdpSnapshotForContext(contextId: string): Promise<CdpPageSnapshot | undefined>;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/core/computer/motor/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../../../src/core/computer/motor/cdp.ts"],"names":[],"mappings":"AASA,OAAO,EAAqB,KAAK,iBAAiB,EAAoB,MAAM,cAAc,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,iBAAiB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,WAAW,EAAE;QACZ,GAAG,EAAE,WAAW,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACpB,CAAC;CACF;AAED,MAAM,WAAW,mBAAmB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAQD,qBAAa,MAAM;IAClB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyF;IACjH,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,SAAS,CAA2B;IAI5C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IAErB,OAAO,eAIN;IAED,OAAa,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiCpF;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,KAAK,IAAI,IAAI,CASZ;IAED,6EAA6E;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnD;IAEK,iBAAiB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAG5C;IAEK,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWzC;IAEK,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3D;IAEK,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9F;IAEK,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpF;IAEK,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjD;IAEK,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB5C;IAEK,OAAO,CACZ,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,EACrD,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,EAC5C,UAAU,SAAI,GACZ,OAAO,CAAC,IAAI,CAAC,CAQf;IAEK,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAanE;YAEa,eAAe;IAe7B,+DAA+D;IACzD,YAAY,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAKrD;IAED,0EAA0E;IAC1E,YAAY,IAAI,eAAe,EAAE,CAIhC;IAED,OAAO,CAAC,IAAI;IA2BZ,OAAO,CAAC,aAAa;IA0CrB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,gBAAgB;CAMxB;AAMD,2EAA2E;AAC3E,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AASD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmC3G;AAUD,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAQrE;AAED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnG;AAED,wBAAsB,iBAAiB,CACtC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhG;AAED,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/F;AAED,wBAAsB,kBAAkB,CACvC,SAAS,EAAE,MAAM,EACjB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,EACrD,MAAM,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,EAC5C,UAAU,SAAI,GACZ,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlH;AAED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzF;AAED,wBAAsB,qBAAqB,CAC1C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAS1C;AAED,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA2BnG","sourcesContent":["// Minimal Chrome DevTools Protocol client.\n//\n// Opt-in: set ADA_COMPUTER_USE_CDP_PORT to the --remote-debugging-port of a\n// running Chromium-family browser. When active, navigate_browser uses\n// Page.navigate (event-driven, no AppleScript) and recent console messages\n// and uncaught exceptions are attached to tool results. Everything else\n// keeps the AX/CGEvent path, so with the env var unset this module is inert.\n\nimport { randomUUID } from \"node:crypto\";\nimport { parseLookResponse, type SerializedOutline, serializeOutline } from \"./outline.ts\";\n\nexport interface CdpConsoleEntry {\n\tlevel: string;\n\ttext: string;\n}\n\nexport interface CdpPageContext {\n\tcontextId: string;\n\ttargetId: string;\n\ttitle: string;\n\turl: string;\n}\n\nexport interface CdpSnapshotTarget {\n\tref: string;\n\tsource: \"browser_ax\";\n\trole: string;\n\tname: string;\n\tvalue?: string;\n\tactions: string[];\n\tbackendNodeId?: number;\n}\n\nexport interface CdpPageSnapshot {\n\tcontextId: string;\n\tsnapshotId: string;\n\ttargetId: string;\n\ttitle: string;\n\turl: string;\n\tcapturedAt: number;\n\ttext: string;\n\ttargets: CdpSnapshotTarget[];\n\toutline: SerializedOutline;\n\tdiagnostics: {\n\t\tcdp: \"connected\";\n\t\ttargetCount: number;\n\t};\n}\n\nexport interface CdpEvaluationResult {\n\tcontextId: string;\n\tvalue: unknown;\n}\n\n/** Window frame in screen points, as reported by the AX side. */\nexport interface WindowFrame {\n\tx: number;\n\ty: number;\n\tw: number;\n\th: number;\n}\n\nconst COMMAND_TIMEOUT_MS = 5_000;\nconst CDP_CONTEXT_PREFIX = \"browser:\";\nconst NAVIGATE_LOAD_TIMEOUT_MS = 10_000;\nconst CONNECT_FAILURE_RETRY_MS = 5_000;\nconst CONSOLE_BUFFER_LIMIT = 20;\n\nexport class CdpTab {\n\tprivate nextId = 1;\n\tprivate readonly pending = new Map<number, { resolve: (result: any) => void; reject: (error: Error) => void }>();\n\tprivate consoleBuffer: CdpConsoleEntry[] = [];\n\tprivate loadFired: (() => void) | undefined;\n\n\t// Campos normales y no propiedades de constructor: este repositorio compila\n\t// con `erasableSyntaxOnly`, que prohíbe la forma corta.\n\tprivate readonly ws: WebSocket;\n\treadonly targetId: string;\n\tpublic title: string;\n\n\tprivate constructor(ws: WebSocket, targetId: string, title: string) {\n\t\tthis.ws = ws;\n\t\tthis.targetId = targetId;\n\t\tthis.title = title;\n\t}\n\n\tstatic async connect(wsUrl: string, targetId: string, title: string): Promise<CdpTab> {\n\t\tconst ws = new WebSocket(wsUrl);\n\t\ttry {\n\t\t\tawait new Promise<void>((resolve, reject) => {\n\t\t\t\tconst timer = setTimeout(\n\t\t\t\t\t() => reject(new Error(`Timed out connecting to CDP target at ${wsUrl}`)),\n\t\t\t\t\tCOMMAND_TIMEOUT_MS,\n\t\t\t\t);\n\t\t\t\tws.onopen = () => {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\tresolve();\n\t\t\t\t};\n\t\t\t\tws.onerror = () => {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\treject(new Error(`Failed to connect to CDP target at ${wsUrl}`));\n\t\t\t\t};\n\t\t\t});\n\n\t\t\tconst tab = new CdpTab(ws, targetId, title);\n\t\t\tws.onmessage = (event) => tab.handleMessage(String(event.data));\n\t\t\tws.onclose = () => tab.rejectAllPending(new Error(\"CDP connection closed.\"));\n\t\t\tws.onerror = () => tab.rejectAllPending(new Error(\"CDP connection error.\"));\n\t\t\tawait tab.send(\"Runtime.enable\");\n\t\t\tawait tab.send(\"Page.enable\");\n\t\t\treturn tab;\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tws.close();\n\t\t\t} catch {\n\t\t\t\t// already closed\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\tget isOpen(): boolean {\n\t\treturn this.ws.readyState === WebSocket.OPEN;\n\t}\n\n\tclose(): void {\n\t\tthis.loadFired?.();\n\t\tthis.loadFired = undefined;\n\t\tthis.rejectAllPending(new Error(\"CDP connection closed.\"));\n\t\ttry {\n\t\t\tthis.ws.close();\n\t\t} catch {\n\t\t\t// already closed\n\t\t}\n\t}\n\n\t/** Evaluates a JS expression in the page and returns its primitive value. */\n\tasync evaluate(expression: string): Promise<unknown> {\n\t\tconst result = await this.send(\"Runtime.evaluate\", {\n\t\t\texpression,\n\t\t\treturnByValue: true,\n\t\t\ttimeout: COMMAND_TIMEOUT_MS,\n\t\t\tawaitPromise: true,\n\t\t});\n\t\treturn result?.result?.value;\n\t}\n\n\tasync accessibilityTree(): Promise<unknown[]> {\n\t\tconst result = await this.send(\"Accessibility.getFullAXTree\");\n\t\treturn Array.isArray(result?.nodes) ? result.nodes : [];\n\t}\n\n\tasync navigate(url: string): Promise<void> {\n\t\tconst loaded = new Promise<void>((resolve) => {\n\t\t\tthis.loadFired = resolve;\n\t\t});\n\t\ttry {\n\t\t\tawait this.send(\"Page.navigate\", { url });\n\t\t\t// SPAs and slow pages may never fire load; cap the wait and move on.\n\t\t\tawait Promise.race([loaded, new Promise<void>((resolve) => setTimeout(resolve, NAVIGATE_LOAD_TIMEOUT_MS))]);\n\t\t} finally {\n\t\t\tthis.loadFired = undefined;\n\t\t}\n\t}\n\n\tasync clickBackendNode(backendNodeId: number): Promise<void> {\n\t\tawait this.withBackendNode(\n\t\t\tbackendNodeId,\n\t\t\t\"function(){ this.scrollIntoView({block:'center', inline:'center'}); this.click(); }\",\n\t\t);\n\t}\n\n\tasync typeIntoBackendNode(backendNodeId: number, text: string, replace: boolean): Promise<void> {\n\t\tawait this.withBackendNode(\n\t\t\tbackendNodeId,\n\t\t\t\"function(text, replace){ this.scrollIntoView({block:'center', inline:'center'}); this.focus(); if (replace) { if ('value' in this) this.value = ''; else this.textContent = ''; } if ('value' in this) this.value += text; else this.textContent = (this.textContent || '') + text; this.dispatchEvent(new InputEvent('input', {bubbles:true, inputType:'insertText', data:text})); this.dispatchEvent(new Event('change', {bubbles:true})); }\",\n\t\t\t[text, replace],\n\t\t);\n\t}\n\n\tasync scrollBy(deltaX: number, deltaY: number, backendNodeId?: number): Promise<void> {\n\t\tif (backendNodeId) {\n\t\t\tawait this.withBackendNode(\n\t\t\t\tbackendNodeId,\n\t\t\t\t\"function(dx, dy){ this.scrollIntoView({block:'center', inline:'center'}); this.scrollBy(dx, dy); }\",\n\t\t\t\t[deltaX, deltaY],\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\t\tawait this.send(\"Runtime.evaluate\", {\n\t\t\texpression: `window.scrollBy(${JSON.stringify(deltaX)}, ${JSON.stringify(deltaY)})`,\n\t\t});\n\t}\n\n\tasync typeIntoFocused(text: string): Promise<void> {\n\t\tawait this.send(\"Input.insertText\", { text });\n\t}\n\n\tasync keypress(keys: string[]): Promise<void> {\n\t\tconst modifierBits: Record<string, number> = {\n\t\t\talt: 1,\n\t\t\toption: 1,\n\t\t\tcontrol: 2,\n\t\t\tctrl: 2,\n\t\t\tmeta: 4,\n\t\t\tcommand: 4,\n\t\t\tcmd: 4,\n\t\t\tshift: 8,\n\t\t};\n\t\tconst modifiers = keys.reduce((bits, key) => bits | (modifierBits[key.toLowerCase()] ?? 0), 0);\n\t\tfor (const key of keys.filter((candidate) => modifierBits[candidate.toLowerCase()] === undefined)) {\n\t\t\tawait this.send(\"Input.dispatchKeyEvent\", {\n\t\t\t\ttype: \"keyDown\",\n\t\t\t\tkey,\n\t\t\t\tcode: key,\n\t\t\t\ttext: key.length === 1 && modifiers === 0 ? key : undefined,\n\t\t\t\tmodifiers,\n\t\t\t});\n\t\t\tawait this.send(\"Input.dispatchKeyEvent\", { type: \"keyUp\", key, code: key, modifiers });\n\t\t}\n\t}\n\n\tasync mouseAt(\n\t\tx: number,\n\t\ty: number,\n\t\ttype: \"mouseMoved\" | \"mousePressed\" | \"mouseReleased\",\n\t\tbutton: \"left\" | \"right\" | \"middle\" = \"left\",\n\t\tclickCount = 1,\n\t): Promise<void> {\n\t\tawait this.send(\"Input.dispatchMouseEvent\", {\n\t\t\ttype,\n\t\t\tx,\n\t\t\ty,\n\t\t\tbutton: type === \"mouseMoved\" ? \"none\" : button,\n\t\t\tclickCount,\n\t\t});\n\t}\n\n\tasync dragPath(path: Array<{ x: number; y: number }>): Promise<void> {\n\t\tif (path.length < 2) throw new Error(\"CDP drag requires at least two points.\");\n\t\tawait this.mouseAt(path[0].x, path[0].y, \"mousePressed\");\n\t\tfor (const point of path.slice(1))\n\t\t\tawait this.send(\"Input.dispatchMouseEvent\", {\n\t\t\t\ttype: \"mouseMoved\",\n\t\t\t\tx: point.x,\n\t\t\t\ty: point.y,\n\t\t\t\tbutton: \"left\",\n\t\t\t\tbuttons: 1,\n\t\t\t});\n\t\tconst end = path[path.length - 1];\n\t\tawait this.mouseAt(end.x, end.y, \"mouseReleased\");\n\t}\n\n\tprivate async withBackendNode(\n\t\tbackendNodeId: number,\n\t\tfunctionDeclaration: string,\n\t\targs: unknown[] = [],\n\t): Promise<void> {\n\t\tconst resolved = await this.send(\"DOM.resolveNode\", { backendNodeId });\n\t\tconst objectId = resolved?.object?.objectId;\n\t\tif (typeof objectId !== \"string\") throw new Error(`CDP could not resolve backend node ${backendNodeId}.`);\n\t\tawait this.send(\"Runtime.callFunctionOn\", {\n\t\t\tobjectId,\n\t\t\tfunctionDeclaration,\n\t\t\targuments: args.map((value) => ({ value })),\n\t\t});\n\t}\n\n\t/** Screen bounds of the browser window containing this tab. */\n\tasync windowBounds(): Promise<WindowFrame | undefined> {\n\t\tconst result = await this.send(\"Browser.getWindowForTarget\", { targetId: this.targetId });\n\t\tconst bounds = result?.bounds;\n\t\tif (typeof bounds?.left !== \"number\" || typeof bounds?.width !== \"number\") return undefined;\n\t\treturn { x: bounds.left, y: bounds.top, w: bounds.width, h: bounds.height };\n\t}\n\n\t/** Returns buffered console messages/exceptions and clears the buffer. */\n\tdrainConsole(): CdpConsoleEntry[] {\n\t\tconst entries = this.consoleBuffer;\n\t\tthis.consoleBuffer = [];\n\t\treturn entries;\n\t}\n\n\tprivate send(method: string, params: Record<string, unknown> = {}): Promise<any> {\n\t\tconst id = this.nextId++;\n\t\treturn new Promise((resolve, reject) => {\n\t\t\tconst timer = setTimeout(() => {\n\t\t\t\tthis.pending.delete(id);\n\t\t\t\treject(new Error(`CDP command '${method}' timed out after ${COMMAND_TIMEOUT_MS}ms.`));\n\t\t\t}, COMMAND_TIMEOUT_MS);\n\t\t\tthis.pending.set(id, {\n\t\t\t\tresolve: (result) => {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\tresolve(result);\n\t\t\t\t},\n\t\t\t\treject: (error) => {\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\treject(error);\n\t\t\t\t},\n\t\t\t});\n\t\t\ttry {\n\t\t\t\tthis.ws.send(JSON.stringify({ id, method, params }));\n\t\t\t} catch (error) {\n\t\t\t\tclearTimeout(timer);\n\t\t\t\tthis.pending.delete(id);\n\t\t\t\treject(error instanceof Error ? error : new Error(String(error)));\n\t\t\t}\n\t\t});\n\t}\n\n\tprivate handleMessage(raw: string): void {\n\t\tlet message: any;\n\t\ttry {\n\t\t\tmessage = JSON.parse(raw);\n\t\t} catch {\n\t\t\treturn;\n\t\t}\n\n\t\tif (typeof message.id === \"number\") {\n\t\t\tconst pending = this.pending.get(message.id);\n\t\t\tif (!pending) return;\n\t\t\tthis.pending.delete(message.id);\n\t\t\tif (message.error) {\n\t\t\t\tpending.reject(new Error(`CDP error: ${message.error.message ?? \"unknown\"}`));\n\t\t\t} else {\n\t\t\t\tpending.resolve(message.result);\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tswitch (message.method) {\n\t\t\tcase \"Page.loadEventFired\":\n\t\t\t\tthis.loadFired?.();\n\t\t\t\tbreak;\n\t\t\tcase \"Runtime.consoleAPICalled\": {\n\t\t\t\tconst args = Array.isArray(message.params?.args) ? message.params.args : [];\n\t\t\t\tconst text = args\n\t\t\t\t\t.map((arg: any) => (arg?.value !== undefined ? String(arg.value) : (arg?.description ?? \"\")))\n\t\t\t\t\t.filter(Boolean)\n\t\t\t\t\t.join(\" \");\n\t\t\t\tthis.pushConsole({ level: String(message.params?.type ?? \"log\"), text });\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase \"Runtime.exceptionThrown\": {\n\t\t\t\tconst details = message.params?.exceptionDetails;\n\t\t\t\tconst text = details?.exception?.description ?? details?.text ?? \"Uncaught exception\";\n\t\t\t\tthis.pushConsole({ level: \"exception\", text: String(text) });\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate pushConsole(entry: CdpConsoleEntry): void {\n\t\tif (!entry.text) return;\n\t\tthis.consoleBuffer.push(entry);\n\t\tif (this.consoleBuffer.length > CONSOLE_BUFFER_LIMIT) {\n\t\t\tthis.consoleBuffer.shift();\n\t\t}\n\t}\n\n\tprivate rejectAllPending(error: Error): void {\n\t\tfor (const pending of this.pending.values()) {\n\t\t\tpending.reject(error);\n\t\t}\n\t\tthis.pending.clear();\n\t}\n}\n\nconst connectedTabs = new Map<string, CdpTab>();\nconst connectingTabs = new Map<string, Promise<CdpTab>>();\nlet lastConnectFailureAt = 0;\n\n/** Close session-owned CDP state without affecting the browser process. */\nexport function disconnectCdp(): void {\n\tfor (const tab of connectedTabs.values()) tab.close();\n\tconnectedTabs.clear();\n\tconnectingTabs.clear();\n\tlastConnectFailureAt = 0;\n}\n\nfunction cdpEnabled(): boolean {\n\tconst rawPort = process.env.ADA_COMPUTER_USE_CDP_PORT ?? \"\";\n\tif (!/^\\d+$/.test(rawPort)) return false;\n\tconst port = Number(rawPort);\n\treturn Number.isInteger(port) && port > 0 && port <= 65535 && typeof WebSocket !== \"undefined\";\n}\n\n/**\n * Returns a CDP connection to the tab matching the controlled window's title\n * (and, when provided, the window's screen frame), or undefined when CDP is\n * disabled, unreachable, or no tab matches. Reuses the cached connection\n * while it still matches; failures are cached briefly so an unreachable\n * endpoint never adds per-call latency.\n */\nexport async function cdpTabForWindow(windowTitle: string, frame?: WindowFrame): Promise<CdpTab | undefined> {\n\tif (!cdpEnabled()) return undefined;\n\tif (Date.now() - lastConnectFailureAt < CONNECT_FAILURE_RETRY_MS) return undefined;\n\n\tfor (const tab of connectedTabs.values()) {\n\t\tif (tab.isOpen && titlesMatch(tab.title, windowTitle) && (await tabMatchesFrame(tab, frame))) return tab;\n\t}\n\n\ttry {\n\t\tconst pages = await cdpPages();\n\t\tconst match = await pickTab(pages, windowTitle, frame);\n\t\tif (!match) return undefined;\n\n\t\tconst existing = connectedTabs.get(match.id);\n\t\tif (existing?.isOpen) {\n\t\t\texisting.title = match.title;\n\t\t\treturn existing;\n\t\t}\n\t\tlet connecting = connectingTabs.get(match.id);\n\t\tif (!connecting) {\n\t\t\tconnecting = CdpTab.connect(match.webSocketDebuggerUrl!, match.id, match.title);\n\t\t\tconnectingTabs.set(match.id, connecting);\n\t\t}\n\t\tlet connected: CdpTab;\n\t\ttry {\n\t\t\tconnected = await connecting;\n\t\t} finally {\n\t\t\tconnectingTabs.delete(match.id);\n\t\t}\n\t\tconnectedTabs.set(match.id, connected);\n\t\treturn connected;\n\t} catch {\n\t\tlastConnectFailureAt = Date.now();\n\t\treturn undefined;\n\t}\n}\n\ninterface CdpPageTarget {\n\tid: string;\n\ttype: string;\n\ttitle: string;\n\turl?: string;\n\twebSocketDebuggerUrl?: string;\n}\n\nexport async function listCdpPageContexts(): Promise<CdpPageContext[]> {\n\tconst pages = await cdpPages();\n\treturn pages.map((page) => ({\n\t\tcontextId: cdpContextId(page.id),\n\t\ttargetId: page.id,\n\t\ttitle: page.title,\n\t\turl: page.url ?? \"\",\n\t}));\n}\n\nexport async function cdpClickForContext(contextId: string, backendNodeId: number): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.clickBackendNode(backendNodeId);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpTypeForContext(\n\tcontextId: string,\n\tbackendNodeId: number,\n\ttext: string,\n\treplace: boolean,\n): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.typeIntoBackendNode(backendNodeId, text, replace);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpScrollForContext(\n\tcontextId: string,\n\tdeltaX: number,\n\tdeltaY: number,\n\tbackendNodeId?: number,\n): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.scrollBy(deltaX, deltaY, backendNodeId);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpTypeFocusedForContext(contextId: string, text: string): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.typeIntoFocused(text);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpKeypressForContext(contextId: string, keys: string[]): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.keypress(keys);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpMouseForContext(\n\tcontextId: string,\n\tx: number,\n\ty: number,\n\ttype: \"mouseMoved\" | \"mousePressed\" | \"mouseReleased\",\n\tbutton: \"left\" | \"right\" | \"middle\" = \"left\",\n\tclickCount = 1,\n): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.mouseAt(x, y, type, button, clickCount);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpDragForContext(contextId: string, path: Array<{ x: number; y: number }>): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.dragPath(path);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpNavigateContext(contextId: string, url: string): Promise<boolean> {\n\treturn (\n\t\t(await withCdpContextTab(contextId, async (tab) => {\n\t\t\tawait tab.navigate(url);\n\t\t\treturn true;\n\t\t})) === true\n\t);\n}\n\nexport async function cdpEvaluateForContext(\n\tcontextId: string,\n\texpression: string,\n): Promise<CdpEvaluationResult | undefined> {\n\tconst page = await cdpPageForContext(contextId);\n\tif (!page?.webSocketDebuggerUrl) return undefined;\n\tconst tab = await CdpTab.connect(page.webSocketDebuggerUrl, page.id, page.title);\n\ttry {\n\t\treturn { contextId, value: await tab.evaluate(expression) };\n\t} finally {\n\t\ttab.close();\n\t}\n}\n\nexport async function cdpSnapshotForContext(contextId: string): Promise<CdpPageSnapshot | undefined> {\n\tconst page = await cdpPageForContext(contextId);\n\tif (!page?.webSocketDebuggerUrl) return undefined;\n\n\tconst tab = await CdpTab.connect(page.webSocketDebuggerUrl, page.id, page.title);\n\ttry {\n\t\tconst [textValue, nodes] = await Promise.all([\n\t\t\ttab.evaluate(\"document.body ? document.body.innerText : ''\").catch(() => \"\"),\n\t\t\ttab.accessibilityTree().catch(() => []),\n\t\t]);\n\t\tconst snapshotId = randomUUID();\n\t\tconst { targets, outline } = cdpSnapshotOutline(snapshotId, nodes);\n\t\treturn {\n\t\t\tcontextId,\n\t\t\tsnapshotId,\n\t\t\ttargetId: page.id,\n\t\t\ttitle: page.title,\n\t\t\turl: page.url ?? \"\",\n\t\t\tcapturedAt: Date.now(),\n\t\t\ttext: typeof textValue === \"string\" ? textValue : String(textValue ?? \"\"),\n\t\t\ttargets,\n\t\t\toutline,\n\t\t\tdiagnostics: { cdp: \"connected\", targetCount: targets.length },\n\t\t};\n\t} finally {\n\t\ttab.close();\n\t}\n}\n\nasync function withCdpContextTab<T>(contextId: string, run: (tab: CdpTab) => Promise<T>): Promise<T | undefined> {\n\tconst page = await cdpPageForContext(contextId);\n\tif (!page?.webSocketDebuggerUrl) return undefined;\n\tconst tab = await CdpTab.connect(page.webSocketDebuggerUrl, page.id, page.title);\n\ttry {\n\t\treturn await run(tab);\n\t} finally {\n\t\ttab.close();\n\t}\n}\n\nasync function cdpPageForContext(contextId: string): Promise<CdpPageTarget | undefined> {\n\tif (!contextId.startsWith(CDP_CONTEXT_PREFIX)) return undefined;\n\tconst targetId = contextId.slice(CDP_CONTEXT_PREFIX.length);\n\tconst pages = await cdpPages();\n\treturn pages.find((candidate) => candidate.id === targetId);\n}\n\nasync function cdpPages(): Promise<CdpPageTarget[]> {\n\tif (!cdpEnabled()) return [];\n\tconst port = process.env.ADA_COMPUTER_USE_CDP_PORT;\n\tconst response = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(2_000) });\n\tconst targets = (await response.json()) as CdpPageTarget[];\n\treturn targets.filter(\n\t\t(target) =>\n\t\t\ttarget.type === \"page\" &&\n\t\t\ttarget.webSocketDebuggerUrl &&\n\t\t\tisLocalDebuggerWebSocket(target.webSocketDebuggerUrl, port),\n\t);\n}\n\nfunction cdpContextId(targetId: string): string {\n\treturn `${CDP_CONTEXT_PREFIX}${targetId}`;\n}\n\nfunction axString(raw: any): string {\n\tconst value = raw?.value ?? raw;\n\treturn typeof value === \"string\" ? value.trim() : \"\";\n}\n\nfunction cdpSnapshotOutline(\n\tsnapshotId: string,\n\tnodes: unknown[],\n): { targets: CdpSnapshotTarget[]; outline: SerializedOutline } {\n\tconst records = new Map<string, any>();\n\tfor (const raw of nodes as any[]) {\n\t\tconst nodeId = String(raw?.nodeId ?? \"\");\n\t\tif (nodeId) records.set(nodeId, raw);\n\t}\n\tconst targets: CdpSnapshotTarget[] = [];\n\tconst build = (raw: any, seen: Set<string>): any => {\n\t\tconst nodeId = String(raw?.nodeId ?? randomUUID());\n\t\tif (seen.has(nodeId)) return undefined;\n\t\tseen.add(nodeId);\n\t\tconst role = axString(raw?.role);\n\t\tconst name = axString(raw?.name);\n\t\tconst actions = browserActionsForAxRole(role);\n\t\tconst backendNodeId = Number.isFinite(raw?.backendDOMNodeId) ? Math.trunc(raw.backendDOMNodeId) : undefined;\n\t\tconst wireRef = `cdp:${nodeId}`;\n\t\tif (actions.length > 0 && name && (!actions.includes(\"click\") || backendNodeId)) {\n\t\t\ttargets.push({\n\t\t\t\tref: wireRef,\n\t\t\t\tsource: \"browser_ax\",\n\t\t\t\trole,\n\t\t\t\tname,\n\t\t\t\tvalue: axString(raw?.value) || undefined,\n\t\t\t\tactions,\n\t\t\t\tbackendNodeId,\n\t\t\t});\n\t\t}\n\t\tconst childIds: string[] = Array.isArray(raw?.childIds) ? raw.childIds.map(String) : [];\n\t\treturn {\n\t\t\tref: wireRef,\n\t\t\trole,\n\t\t\tsubrole: \"\",\n\t\t\tidentifier: \"\",\n\t\t\ttitle: name,\n\t\t\tdescription: axString(raw?.description),\n\t\t\tvalue: axString(raw?.value),\n\t\t\tactions,\n\t\t\tcanPress: actions.includes(\"click\"),\n\t\t\tcanFocus: actions.length > 0,\n\t\t\tcanSetValue: actions.includes(\"set_text\"),\n\t\t\tcanScroll: false,\n\t\t\tcanIncrement: false,\n\t\t\tcanDecrement: false,\n\t\t\tisTextInput: actions.includes(\"set_text\"),\n\t\t\trect: { x: 0, y: 0, w: 0, h: 0 },\n\t\t\tchildren: childIds\n\t\t\t\t.map((id: string) => records.get(id))\n\t\t\t\t.filter(Boolean)\n\t\t\t\t.map((child: any) => build(child, seen))\n\t\t\t\t.filter(Boolean),\n\t\t};\n\t};\n\tconst roots = (nodes as any[]).filter((raw) => !raw?.parentId || !records.has(String(raw.parentId)));\n\tconst children = roots.map((root) => build(root, new Set())).filter(Boolean);\n\tconst rawOutline =\n\t\tchildren.length === 1\n\t\t\t? children[0]\n\t\t\t: {\n\t\t\t\t\tref: `cdp:root:${snapshotId}`,\n\t\t\t\t\trole: \"document\",\n\t\t\t\t\tsubrole: \"\",\n\t\t\t\t\tidentifier: \"\",\n\t\t\t\t\ttitle: \"Browser page\",\n\t\t\t\t\tdescription: \"\",\n\t\t\t\t\tvalue: \"\",\n\t\t\t\t\tactions: [],\n\t\t\t\t\tcanPress: false,\n\t\t\t\t\tcanFocus: false,\n\t\t\t\t\tcanSetValue: false,\n\t\t\t\t\tcanScroll: false,\n\t\t\t\t\tcanIncrement: false,\n\t\t\t\t\tcanDecrement: false,\n\t\t\t\t\tisTextInput: false,\n\t\t\t\t\trect: { x: 0, y: 0, w: 0, h: 0 },\n\t\t\t\t\tchildren,\n\t\t\t\t};\n\tconst parsed = parseLookResponse({\n\t\tlookId: snapshotId,\n\t\tcapturedAt: Date.now() / 1000,\n\t\twindow: {\n\t\t\twindowId: 0,\n\t\t\tframePoints: { x: 0, y: 0, w: 1, h: 1 },\n\t\t\tscaleFactor: 1,\n\t\t\tisModal: false,\n\t\t\trole: \"document\",\n\t\t\tsubrole: \"\",\n\t\t},\n\t\toutline: rawOutline,\n\t\ttimings: {},\n\t}).parsedOutline!;\n\tconst modelRefByWire = parsed.wireRefToRef;\n\tfor (const target of targets) target.ref = modelRefByWire.get(target.ref) ?? target.ref;\n\treturn { targets, outline: serializeOutline(parsed) };\n}\n\nfunction browserActionsForAxRole(role: string): string[] {\n\tconst normalized = role.toLowerCase();\n\tif ([\"button\", \"link\", \"checkbox\", \"radio\", \"menuitem\", \"tab\"].includes(normalized)) return [\"click\"];\n\tif ([\"textbox\", \"searchbox\", \"combobox\"].includes(normalized)) return [\"click\", \"set_text\"];\n\tif ([\"listbox\", \"slider\", \"spinbutton\"].includes(normalized)) return [\"click\"];\n\treturn [];\n}\n\nfunction isLocalDebuggerWebSocket(wsUrl: string, expectedPort: string | undefined): boolean {\n\ttry {\n\t\tconst parsed = new URL(wsUrl);\n\t\tconst localHosts = new Set([\"127.0.0.1\", \"localhost\", \"[::1]\"]);\n\t\treturn (\n\t\t\t(parsed.protocol === \"ws:\" || parsed.protocol === \"wss:\") &&\n\t\t\tlocalHosts.has(parsed.hostname) &&\n\t\t\tparsed.port === expectedPort\n\t\t);\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Picks the tab for a window title. Disambiguation order, applied only while\n * more than one candidate remains:\n *   1. exact title matches beat prefix matches;\n *   2. the tab whose browser window frame matches the controlled window\n *      (separates same-titled tabs in different windows);\n *   3. the visible tab (separates same-titled tabs in one window — the\n *      active tab is \"visible\", background tabs are \"hidden\").\n * /json/list ordering is never trusted; it is an undocumented MRU detail.\n */\nasync function pickTab(\n\tpages: CdpPageTarget[],\n\twindowTitle: string,\n\tframe?: WindowFrame,\n): Promise<CdpPageTarget | undefined> {\n\tconst matches = pages.filter((target) => titlesMatch(target.title, windowTitle));\n\tif (matches.length === 0) return pages.length === 1 ? pages[0] : undefined;\n\tif (matches.length === 1) return matches[0];\n\n\tconst wanted = windowTitle.trim().toLowerCase();\n\tconst exact = matches.filter((target) => target.title.trim().toLowerCase() === wanted);\n\tconst pool = exact.length > 0 ? exact : matches;\n\tif (pool.length === 1) return pool[0];\n\n\tlet visibleFallback: CdpPageTarget | undefined;\n\tfor (const candidate of pool) {\n\t\ttry {\n\t\t\tconst tab = await CdpTab.connect(candidate.webSocketDebuggerUrl!, candidate.id, candidate.title);\n\t\t\tconst inFrame = await tabMatchesFrame(tab, frame, false);\n\t\t\tconst visibility = await tab.evaluate(\"document.visibilityState\").catch(() => undefined);\n\t\t\ttab.close();\n\t\t\tif (frame && inFrame && visibility === \"visible\") return candidate;\n\t\t\tif (frame && inFrame && !visibleFallback) visibleFallback = candidate;\n\t\t\tif (!frame && visibility === \"visible\") return candidate;\n\t\t} catch {\n\t\t\t// candidate unreachable; try the next one\n\t\t}\n\t}\n\treturn visibleFallback ?? pool[0];\n}\n\n/**\n * Whether the tab's browser window frame matches the AX window frame.\n * `trustOnUnknown` controls the answer when bounds cannot be read: cache\n * verification trusts the existing connection, candidate selection does not.\n */\nasync function tabMatchesFrame(tab: CdpTab, frame: WindowFrame | undefined, trustOnUnknown = true): Promise<boolean> {\n\tif (!frame) return true;\n\tconst bounds = await tab.windowBounds().catch(() => undefined);\n\tif (!bounds) return trustOnUnknown;\n\tconst tolerance = 50;\n\treturn (\n\t\tMath.abs(bounds.x + bounds.w / 2 - (frame.x + frame.w / 2)) <= tolerance &&\n\t\tMath.abs(bounds.y + bounds.h / 2 - (frame.y + frame.h / 2)) <= tolerance\n\t);\n}\n\n// The AX window title for a Chrome-family browser is usually the active tab\n// title, sometimes suffixed (\" - Google Chrome\", profile name), so compare\n// by prefix in both directions.\nfunction titlesMatch(tabTitle: string, windowTitle: string): boolean {\n\tconst tab = tabTitle.trim().toLowerCase();\n\tconst win = windowTitle.trim().toLowerCase();\n\tif (!tab || !win) return false;\n\treturn tab === win || win.startsWith(tab) || tab.startsWith(win);\n}\n"]}