@silbercue/chrome 0.2.0

package/build/tools/wait-for.js

@@ -0,0 +1,323 @@
+import { z } from "zod";
+import { settle } from "../cdp/settle.js";
+import { a11yTree } from "../cache/a11y-tree.js";
+import { wrapCdpError } from "./error-utils.js";
+// --- Schema (Task 1) ---
+export const waitForSchema = z.object({
+    condition: z
+        .enum(["element", "network_idle", "js"])
+        .describe("What to wait for: element visibility, network idle, or JS expression returning true"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector or element ref (e.g. 'e5') — required when condition is 'element'"),
+    expression: z
+        .string()
+        .optional()
+        .describe("JavaScript expression that should evaluate to true — required when condition is 'js'"),
+    timeout: z
+        .number()
+        .optional()
+        .default(10000)
+        .describe("Maximum wait time in milliseconds (default: 10000)"),
+});
+// --- Constants ---
+const POLL_INTERVAL_MS = 200;
+// --- Delay helper ---
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForElement(cdpClient, sessionId, selector, timeout) {
+    const start = performance.now();
+    const deadline = start + timeout;
+    const isRef = /^e\d+$/.test(selector);
+    while (performance.now() < deadline) {
+        try {
+            let found = false;
+            if (isRef) {
+                // Ref path
+                const backendNodeId = a11yTree.resolveRef(selector);
+                if (backendNodeId !== undefined) {
+                    // Resolve backendNodeId → objectId via DOM.resolveNode
+                    const { object } = await cdpClient.send("DOM.resolveNode", { backendNodeId }, sessionId);
+                    // Check visibility via callFunctionOn
+                    const { result } = await cdpClient.send("Runtime.callFunctionOn", {
+                        objectId: object.objectId,
+                        functionDeclaration: "function() { const r = this.getBoundingClientRect(); return r.width > 0 && r.height > 0; }",
+                        returnByValue: true,
+                    }, sessionId);
+                    found = result.value === true;
+                }
+                // If resolveRef returns undefined, ref not in cache yet — keep polling
+            }
+            else {
+                // CSS path
+                const checkExpression = `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return false;
+      const rect = el.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    })()`;
+                const evalResult = await cdpClient.send("Runtime.evaluate", { expression: checkExpression, returnByValue: true }, sessionId);
+                found = evalResult.result.value === true;
+            }
+            if (found) {
+                return { found: true, elapsedMs: Math.round(performance.now() - start) };
+            }
+        }
+        catch {
+            // CDP error during polling (e.g. element removed) — swallow and continue
+            // Transport errors will propagate from the outer try/catch in the handler
+        }
+        const remaining = deadline - performance.now();
+        if (remaining <= 0)
+            break;
+        await delay(Math.min(POLL_INTERVAL_MS, remaining));
+    }
+    return { found: false, elapsedMs: Math.round(performance.now() - start) };
+}
+async function waitForNetworkIdle(cdpClient, sessionId, timeout) {
+    // Get main frame ID
+    const frameTree = await cdpClient.send("Page.getFrameTree", {}, sessionId);
+    const frameId = frameTree.frameTree.frame.id;
+    const settleResult = await settle({
+        cdpClient,
+        sessionId,
+        frameId,
+        settleMs: 500,
+        timeoutMs: timeout,
+    });
+    return {
+        settled: settleResult.settled,
+        signal: settleResult.signal,
+        elapsedMs: settleResult.elapsedMs,
+    };
+}
+async function waitForJs(cdpClient, sessionId, expression, timeout) {
+    const start = performance.now();
+    const deadline = start + timeout;
+    let lastValue = undefined;
+    while (performance.now() < deadline) {
+        try {
+            const result = await cdpClient.send("Runtime.evaluate", {
+                expression,
+                returnByValue: true,
+                awaitPromise: false,
+            }, sessionId);
+            if (!result.exceptionDetails) {
+                lastValue = result.result.value;
+                if (result.result.value === true) {
+                    return { met: true, elapsedMs: Math.round(performance.now() - start), lastValue };
+                }
+            }
+            // Exception in expression — swallow and keep polling
+        }
+        catch {
+            // CDP error — swallow and keep polling
+        }
+        const remaining = deadline - performance.now();
+        if (remaining <= 0)
+            break;
+        await delay(Math.min(POLL_INTERVAL_MS, remaining));
+    }
+    return { met: false, elapsedMs: Math.round(performance.now() - start), lastValue };
+}
+// --- Element timeout diagnostics (FR-H7) ---
+/**
+ * After an element wait_for timeout, check if the element exists in DOM.
+ * Returns a diagnostic string helping the LLM understand why the wait failed.
+ */
+async function elementTimeoutDiagnostic(cdpClient, sessionId, selector) {
+    const isRef = /^e\d+$/.test(selector);
+    if (isRef) {
+        const backendNodeId = a11yTree.resolveRef(selector);
+        if (backendNodeId === undefined) {
+            return "\nDebug: Ref not found in cache — page may have changed. Call read_page to get fresh refs.";
+        }
+        return "\nDebug: Ref exists in cache but element has zero size (hidden or not rendered).";
+    }
+    // CSS selector path
+    try {
+        const result = await cdpClient.send("Runtime.evaluate", {
+            expression: `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return { exists: false, hidden: false, tag: "" }; const r = el.getBoundingClientRect(); return { exists: true, hidden: r.width === 0 || r.height === 0, tag: el.tagName.toLowerCase() }; })()`,
+            returnByValue: true,
+        }, sessionId);
+        const v = result.result.value;
+        if (!v.exists) {
+            return `\nDebug: querySelector('${selector}') returned null — element not in DOM.`;
+        }
+        if (v.hidden) {
+            return `\nDebug: <${v.tag}> exists but has zero size (display: none or collapsed). A preceding action may be needed to reveal it.`;
+        }
+        return `\nDebug: <${v.tag}> exists with size > 0 but visibility check failed.`;
+    }
+    catch {
+        return "";
+    }
+}
+// --- JS timeout diagnostics (FR-006) ---
+/**
+ * Extract the first CSS selector from a querySelector/getElementById call in a JS expression.
+ * Returns the CSS selector string, or null if none found.
+ */
+export function extractSelector(expression) {
+    // Match querySelector('...') or querySelector("...")
+    const qsMatch = expression.match(/querySelector\(\s*(['"])(.*?)\1\s*\)/);
+    if (qsMatch)
+        return qsMatch[2];
+    // Match getElementById('...') or getElementById("...")
+    const idMatch = expression.match(/getElementById\(\s*(['"])(.*?)\1\s*\)/);
+    if (idMatch)
+        return `#${idMatch[2]}`;
+    return null;
+}
+/**
+ * After a JS wait_for timeout, check if the extracted selector's element exists in the DOM.
+ * Returns a diagnostic line or empty string if no selector was found.
+ */
+async function jsTimeoutDiagnostic(cdpClient, sessionId, expression) {
+    const selector = extractSelector(expression);
+    if (!selector)
+        return "";
+    try {
+        const result = await cdpClient.send("Runtime.evaluate", {
+            expression: `document.querySelector(${JSON.stringify(selector)}) !== null`,
+            returnByValue: true,
+        }, sessionId);
+        if (result.result.value === true) {
+            return `\nDebug: Element exists but condition not met (content may still be loading).`;
+        }
+        return `\nDebug: querySelector('${selector}') returned null — element not found in DOM.`;
+    }
+    catch {
+        // If CDP call fails, skip diagnostics
+        return "";
+    }
+}
+// --- Main handler (Task 5) ---
+export async function waitForHandler(params, cdpClient, sessionId) {
+    const start = performance.now();
+    // Validation (Task 1.4)
+    if (params.condition === "element" && (!params.selector || params.selector.trim() === "")) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "wait_for condition 'element' requires a 'selector' parameter (CSS selector or ref like 'e5')",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "wait_for" },
+        };
+    }
+    if (params.condition === "js" && (!params.expression || params.expression.trim() === "")) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "wait_for condition 'js' requires an 'expression' parameter",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "wait_for" },
+        };
+    }
+    try {
+        switch (params.condition) {
+            case "element": {
+                const result = await waitForElement(cdpClient, sessionId, params.selector, params.timeout);
+                if (result.found) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Condition 'element' met after ${result.elapsedMs}ms — selector: ${params.selector}`,
+                            },
+                        ],
+                        _meta: { elapsedMs: result.elapsedMs, method: "wait_for", condition: "element" },
+                    };
+                }
+                // FR-H7: Append diagnostic info on timeout
+                const diagnostic = await elementTimeoutDiagnostic(cdpClient, sessionId, params.selector);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Timeout after ${params.timeout}ms waiting for element '${params.selector}' to become visible${diagnostic}`,
+                        },
+                    ],
+                    isError: true,
+                    _meta: { elapsedMs: result.elapsedMs, method: "wait_for", condition: "element" },
+                };
+            }
+            case "network_idle": {
+                const result = await waitForNetworkIdle(cdpClient, sessionId, params.timeout);
+                if (result.settled) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Condition 'network_idle' met after ${result.elapsedMs}ms`,
+                            },
+                        ],
+                        _meta: {
+                            elapsedMs: result.elapsedMs,
+                            method: "wait_for",
+                            condition: "network_idle",
+                            settleSignal: result.signal,
+                        },
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Timeout after ${params.timeout}ms waiting for network idle (signal: ${result.signal})`,
+                        },
+                    ],
+                    isError: true,
+                    _meta: {
+                        elapsedMs: result.elapsedMs,
+                        method: "wait_for",
+                        condition: "network_idle",
+                        settleSignal: result.signal,
+                    },
+                };
+            }
+            case "js": {
+                const result = await waitForJs(cdpClient, sessionId, params.expression, params.timeout);
+                if (result.met) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Condition 'js' met after ${result.elapsedMs}ms`,
+                            },
+                        ],
+                        _meta: { elapsedMs: result.elapsedMs, method: "wait_for", condition: "js" },
+                    };
+                }
+                // FR-006: Append diagnostic info when a querySelector/getElementById is detected
+                const diagnostic = await jsTimeoutDiagnostic(cdpClient, sessionId, params.expression);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Timeout after ${params.timeout}ms waiting for JS expression to return true. Last evaluation returned: ${JSON.stringify(result.lastValue)}${diagnostic}`,
+                        },
+                    ],
+                    isError: true,
+                    _meta: { elapsedMs: result.elapsedMs, method: "wait_for", condition: "js" },
+                };
+            }
+        }
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "wait_for") }],
+            isError: true,
+            _meta: { elapsedMs, method: "wait_for" },
+        };
+    }
+}

package/build/transport/index.d.ts

@@ -0,0 +1,3 @@
+export type { CdpTransport } from "./transport.js";
+export { PipeTransport } from "./pipe-transport.js";
+export { WebSocketTransport } from "./websocket-transport.js";

package/build/transport/index.js

@@ -0,0 +1,2 @@
+export { PipeTransport } from "./pipe-transport.js";
+export { WebSocketTransport } from "./websocket-transport.js";

package/build/transport/pipe-transport.d.ts

@@ -0,0 +1,18 @@
+import type { Readable, Writable } from "node:stream";
+import type { CdpTransport } from "./transport.js";
+export declare class PipeTransport implements CdpTransport {
+    private readonly readable;
+    private readonly writable;
+    private _connected;
+    private _buffer;
+    private _messageCallback;
+    private _errorCallback;
+    private _closeCallback;
+    constructor(readable: Readable, writable: Writable);
+    get connected(): boolean;
+    send(message: string): boolean;
+    onMessage(cb: (message: string) => void): void;
+    onError(cb: (error: Error) => void): void;
+    onClose(cb: () => void): void;
+    close(): Promise<void>;
+}

package/build/transport/pipe-transport.js

@@ -0,0 +1,63 @@
+export class PipeTransport {
+    readable;
+    writable;
+    _connected = true;
+    _buffer = "";
+    _messageCallback = null;
+    _errorCallback = null;
+    _closeCallback = null;
+    constructor(readable, writable) {
+        this.readable = readable;
+        this.writable = writable;
+        this.readable.on("data", (chunk) => {
+            this._buffer += chunk.toString();
+            const parts = this._buffer.split("\0");
+            this._buffer = parts.pop();
+            for (const part of parts) {
+                if (part.length > 0 && this._messageCallback) {
+                    this._messageCallback(part);
+                }
+            }
+        });
+        this.readable.on("error", (err) => {
+            this._errorCallback?.(err);
+        });
+        this.writable.on("error", (err) => {
+            this._errorCallback?.(err);
+        });
+        this.readable.on("close", () => {
+            if (!this._connected)
+                return;
+            this._connected = false;
+            this._closeCallback?.();
+        });
+        this.writable.on("close", () => {
+            if (!this._connected)
+                return;
+            this._connected = false;
+            this._closeCallback?.();
+        });
+    }
+    get connected() {
+        return this._connected;
+    }
+    send(message) {
+        if (!this._connected)
+            return false;
+        return this.writable.write(message + "\0");
+    }
+    onMessage(cb) {
+        this._messageCallback = cb;
+    }
+    onError(cb) {
+        this._errorCallback = cb;
+    }
+    onClose(cb) {
+        this._closeCallback = cb;
+    }
+    async close() {
+        this._connected = false;
+        this.readable.destroy();
+        this.writable.end();
+    }
+}

package/build/transport/transport.d.ts

@@ -0,0 +1,8 @@
+export interface CdpTransport {
+    send(message: string): boolean;
+    onMessage(cb: (message: string) => void): void;
+    onError(cb: (error: Error) => void): void;
+    onClose(cb: () => void): void;
+    close(): Promise<void>;
+    readonly connected: boolean;
+}

package/build/transport/transport.js

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

package/build/transport/websocket-transport.d.ts

@@ -0,0 +1,22 @@
+import type { CdpTransport } from "./transport.js";
+export declare class WebSocketTransport implements CdpTransport {
+    private readonly socket;
+    private _connected;
+    private _messageCallback;
+    private _errorCallback;
+    private _closeCallback;
+    private _recvBuffer;
+    private constructor();
+    static connect(url: string, options?: {
+        timeoutMs?: number;
+    }): Promise<WebSocketTransport>;
+    get connected(): boolean;
+    send(message: string): boolean;
+    onMessage(cb: (message: string) => void): void;
+    onError(cb: (error: Error) => void): void;
+    onClose(cb: () => void): void;
+    close(): Promise<void>;
+    private _onData;
+    private _decodeFrame;
+    private _encodeFrame;
+}

package/build/transport/websocket-transport.js

@@ -0,0 +1,200 @@
+import { randomBytes } from "node:crypto";
+import { request as httpRequest } from "node:http";
+const OPCODES = {
+    TEXT: 0x1,
+    CLOSE: 0x8,
+    PING: 0x9,
+    PONG: 0xa,
+};
+export class WebSocketTransport {
+    socket;
+    _connected = true;
+    _messageCallback = null;
+    _errorCallback = null;
+    _closeCallback = null;
+    _recvBuffer = Buffer.alloc(0);
+    constructor(socket) {
+        this.socket = socket;
+        this.socket.on("data", (chunk) => this._onData(chunk));
+        this.socket.on("error", (err) => this._errorCallback?.(err));
+        this.socket.on("close", () => {
+            this._connected = false;
+            this._closeCallback?.();
+        });
+    }
+    static async connect(url, options) {
+        const parsed = new URL(url);
+        const key = randomBytes(16).toString("base64");
+        const timeoutMs = options?.timeoutMs ?? 30_000;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                req.destroy();
+                reject(new Error(`WebSocket connect timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const req = httpRequest({
+                hostname: parsed.hostname,
+                port: parsed.port || 80,
+                path: parsed.pathname + parsed.search,
+                headers: {
+                    Upgrade: "websocket",
+                    Connection: "Upgrade",
+                    "Sec-WebSocket-Key": key,
+                    "Sec-WebSocket-Version": "13",
+                },
+            });
+            req.on("upgrade", (_res, socket) => {
+                if (settled) {
+                    socket.destroy();
+                    return;
+                }
+                clearTimeout(timer);
+                settled = true;
+                // BUG-003: Accept validation permanently skipped.
+                // Node 22 undici 6.21.1 has a confirmed bug where Sec-WebSocket-Accept hashes
+                // mismatch between client and server — affects both native WebSocket and custom
+                // implementations. Safe to skip: Chrome DevTools is a trusted localhost endpoint.
+                resolve(new WebSocketTransport(socket));
+            });
+            req.on("response", (res) => {
+                if (settled)
+                    return;
+                clearTimeout(timer);
+                settled = true;
+                reject(new Error(`WebSocket handshake failed: server returned HTTP ${res.statusCode}`));
+                req.destroy();
+            });
+            req.on("error", (err) => {
+                if (settled)
+                    return;
+                clearTimeout(timer);
+                settled = true;
+                reject(err);
+            });
+            req.end();
+        });
+    }
+    get connected() {
+        return this._connected;
+    }
+    send(message) {
+        if (!this._connected)
+            return false;
+        const payload = Buffer.from(message, "utf-8");
+        const frame = this._encodeFrame(OPCODES.TEXT, payload);
+        return this.socket.write(frame);
+    }
+    onMessage(cb) {
+        this._messageCallback = cb;
+    }
+    onError(cb) {
+        this._errorCallback = cb;
+    }
+    onClose(cb) {
+        this._closeCallback = cb;
+    }
+    async close() {
+        if (!this._connected)
+            return;
+        this._connected = false;
+        const closeFrame = this._encodeFrame(OPCODES.CLOSE, Buffer.alloc(0));
+        this.socket.write(closeFrame);
+        this.socket.end();
+    }
+    _onData(chunk) {
+        this._recvBuffer = Buffer.concat([this._recvBuffer, chunk]);
+        while (this._recvBuffer.length >= 2) {
+            const result = this._decodeFrame(this._recvBuffer);
+            if (!result)
+                break;
+            const { opcode, payload, bytesConsumed } = result;
+            this._recvBuffer = this._recvBuffer.subarray(bytesConsumed);
+            switch (opcode) {
+                case OPCODES.TEXT:
+                    this._messageCallback?.(payload.toString("utf-8"));
+                    break;
+                case OPCODES.CLOSE:
+                    this._connected = false;
+                    // Send close frame back
+                    this.socket.write(this._encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+                    this.socket.end();
+                    break;
+                case OPCODES.PING:
+                    this.socket.write(this._encodeFrame(OPCODES.PONG, payload));
+                    break;
+                case OPCODES.PONG:
+                    // Ignore unsolicited pongs
+                    break;
+            }
+        }
+    }
+    _decodeFrame(buf) {
+        if (buf.length < 2)
+            return null;
+        const opcode = buf[0] & 0x0f;
+        const masked = (buf[1] & 0x80) !== 0;
+        let payloadLength = buf[1] & 0x7f;
+        let offset = 2;
+        if (payloadLength === 126) {
+            if (buf.length < 4)
+                return null;
+            payloadLength = buf.readUInt16BE(2);
+            offset = 4;
+        }
+        else if (payloadLength === 127) {
+            if (buf.length < 10)
+                return null;
+            // Read as BigInt, but CDP messages won't exceed Number.MAX_SAFE_INTEGER
+            payloadLength = Number(buf.readBigUInt64BE(2));
+            offset = 10;
+        }
+        if (masked) {
+            if (buf.length < offset + 4 + payloadLength)
+                return null;
+            const maskKey = buf.subarray(offset, offset + 4);
+            offset += 4;
+            const payload = Buffer.alloc(payloadLength);
+            for (let i = 0; i < payloadLength; i++) {
+                payload[i] = buf[offset + i] ^ maskKey[i % 4];
+            }
+            return { opcode, payload, bytesConsumed: offset + payloadLength };
+        }
+        if (buf.length < offset + payloadLength)
+            return null;
+        const payload = buf.subarray(offset, offset + payloadLength);
+        return { opcode, payload: Buffer.from(payload), bytesConsumed: offset + payloadLength };
+    }
+    _encodeFrame(opcode, payload) {
+        const mask = randomBytes(4);
+        const payloadLength = payload.length;
+        let header;
+        if (payloadLength < 126) {
+            header = Buffer.alloc(6);
+            header[0] = 0x80 | opcode; // FIN + opcode
+            header[1] = 0x80 | payloadLength; // MASK + length
+            mask.copy(header, 2);
+        }
+        else if (payloadLength < 65536) {
+            header = Buffer.alloc(8);
+            header[0] = 0x80 | opcode;
+            header[1] = 0x80 | 126;
+            header.writeUInt16BE(payloadLength, 2);
+            mask.copy(header, 4);
+        }
+        else {
+            header = Buffer.alloc(14);
+            header[0] = 0x80 | opcode;
+            header[1] = 0x80 | 127;
+            header.writeBigUInt64BE(BigInt(payloadLength), 2);
+            mask.copy(header, 10);
+        }
+        const maskedPayload = Buffer.alloc(payloadLength);
+        for (let i = 0; i < payloadLength; i++) {
+            maskedPayload[i] = payload[i] ^ mask[i % 4];
+        }
+        return Buffer.concat([header, maskedPayload]);
+    }
+}

package/build/types.d.ts

@@ -0,0 +1,21 @@
+export interface ToolMeta {
+    [key: string]: unknown;
+    elapsedMs: number;
+    method: string;
+}
+export type ToolContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface ToolResponse {
+    [key: string]: unknown;
+    content: Array<ToolContentBlock>;
+    isError?: boolean;
+    _meta?: ToolMeta;
+}
+export type ConnectionStatus = "connected" | "reconnecting" | "disconnected";
+export type TransportType = "pipe" | "websocket";

package/build/types.js

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