@silbercue/chrome 0.2.0

package/build/tools/fill-form.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { resolveElement, buildRefNotFoundError, RefNotFoundError } from "./element-utils.js";
+import { wrapCdpError } from "./error-utils.js";
+// --- Constants ---
+/** Roles relevant for form fields — used to filter "Did you mean?" suggestions */
+const FORM_FIELD_ROLES = new Set([
+    "textbox", "searchbox", "combobox", "spinbutton",
+    "checkbox", "radio", "listbox", "switch",
+]);
+// --- Schema (Task 1.1) ---
+const fieldSchema = z.object({
+    ref: z
+        .string()
+        .optional()
+        .describe("A11y-Tree element ref (e.g. 'e5') — preferred over selector"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector (e.g. '#email') — fallback when ref is not available"),
+    value: z
+        .union([z.string(), z.boolean(), z.number()])
+        .describe("Value to set: string for text/select, boolean for checkbox/radio, number coerced to string"),
+});
+export const fillFormSchema = z.object({
+    fields: z
+        .array(fieldSchema)
+        .min(1)
+        .describe("Array of fields to fill. Each field needs ref or selector plus value."),
+});
+// --- Helpers ---
+function truncate(text, maxLen) {
+    return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+}
+function fieldIdentifier(field) {
+    return field.ref ?? field.selector ?? "unknown";
+}
+// --- Element type detection (Task 1.2, step 3) ---
+async function getElementTypeInfo(cdpClient, objectId, sessionId) {
+    const typeInfo = await cdpClient.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function() {
+        var tag = this.tagName;
+        var type = (this.type || '').toLowerCase();
+        var checked = !!this.checked;
+        return JSON.stringify({ tag: tag, type: type, checked: checked });
+      }`,
+        returnByValue: true,
+    }, sessionId);
+    return JSON.parse(typeInfo.result.value);
+}
+// --- Select handler (Task 1.2, step 4A — AC #2) ---
+async function fillSelect(cdpClient, objectId, sessionId, value) {
+    await cdpClient.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `function(val) {
+        var opts = Array.from(this.options);
+        var match = opts.find(function(o) { return o.value === val || o.textContent.trim() === val; });
+        if (!match) {
+          var available = opts.map(function(o) { return o.textContent.trim() || o.value; }).filter(Boolean);
+          throw new Error('Option not found: ' + val + ' — available: [' + available.join(', ') + ']');
+        }
+        this.value = match.value;
+        this.dispatchEvent(new Event('change', { bubbles: true }));
+      }`,
+        arguments: [{ value }],
+        returnByValue: true,
+    }, sessionId);
+}
+// --- Checkbox/Radio click handler (Task 1.2, step 4B — AC #3) ---
+async function clickCheckboxOrRadio(cdpClient, sessionId, backendNodeId) {
+    // Step 1: Reset scroll to origin (same pattern as click.ts)
+    await cdpClient.send("Runtime.evaluate", { expression: "window.scrollTo(0,0)" }, sessionId);
+    // Step 2: Scroll element into view
+    await cdpClient.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }, sessionId);
+    // Step 3: Get viewport-relative center via DOM.getContentQuads
+    const quadsResult = await cdpClient.send("DOM.getContentQuads", { backendNodeId }, sessionId);
+    if (!quadsResult.quads || quadsResult.quads.length === 0) {
+        throw new Error("Element has no visible layout quads");
+    }
+    const q = quadsResult.quads[0];
+    const x = (q[0] + q[2] + q[4] + q[6]) / 4;
+    const y = (q[1] + q[3] + q[5] + q[7]) / 4;
+    // Step 4: Dispatch mouse events
+    await cdpClient.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button: "left", clickCount: 1 }, sessionId);
+    await cdpClient.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button: "left", clickCount: 1 }, sessionId);
+}
+// --- Text input handler (Task 1.2, step 4C — AC #1) ---
+async function fillTextInput(cdpClient, sessionId, backendNodeId, objectId, value, humanType) {
+    // Step 1: Focus
+    await cdpClient.send("DOM.focus", { backendNodeId }, sessionId);
+    // Step 2: Clear (always — fill_form sets definitive values)
+    await cdpClient.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: "function() { this.value = ''; this.dispatchEvent(new Event('input', { bubbles: true })); }",
+        returnByValue: true,
+    }, sessionId);
+    // Step 3: Type text
+    // Story 16.5: If humanType callback is injected (via Pro-Hook), delegate.
+    if (value.length > 0) {
+        if (humanType) {
+            await humanType(cdpClient, sessionId, value);
+        }
+        else {
+            await cdpClient.send("Input.insertText", { text: value }, sessionId);
+        }
+    }
+}
+// --- Main handler (Task 1.2) ---
+export async function fillFormHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    const results = [];
+    // Story 16.5: Extract optional humanType callback injected by the
+    // `enhanceTool` Pro-Hook. The field is NOT part of the Zod schema and must
+    // be stripped from `params` before downstream code uses it (so it never
+    // leaks into per-field validation or response payloads).
+    const rawParams = params;
+    const maybeHuman = rawParams.humanType;
+    const humanType = typeof maybeHuman === "function" ? maybeHuman : undefined;
+    if ("humanType" in rawParams) {
+        const { humanType: _humanType, ...rest } = rawParams;
+        void _humanType;
+        params = rest;
+    }
+    // Process fields sequentially (CDP commands are not parallelizable on same tab)
+    for (const field of params.fields) {
+        const id = fieldIdentifier(field);
+        // Step 1: Validate ref/selector — at least one must be set
+        if (!field.ref && !field.selector) {
+            results.push({
+                ref: field.ref,
+                selector: field.selector,
+                status: "error",
+                message: "Field needs either 'ref' or 'selector'",
+                value: field.value,
+            });
+            continue;
+        }
+        try {
+            // Step 2: Resolve element
+            const target = field.ref ? { ref: field.ref } : { selector: field.selector };
+            const element = await resolveElement(cdpClient, sessionId, target, sessionManager);
+            const targetSession = element.resolvedSessionId;
+            // Step 3: Determine element type via DOM inspection
+            const info = await getElementTypeInfo(cdpClient, element.objectId, targetSession);
+            // Build display name for response
+            const displayName = element.name
+                ? `${element.role} '${element.name}'`
+                : id;
+            // Step 4: Dispatch based on element type
+            if (info.tag === "SELECT") {
+                // --- SELECT ---
+                await fillSelect(cdpClient, element.objectId, targetSession, String(field.value));
+                results.push({
+                    ref: field.ref,
+                    selector: field.selector,
+                    status: "ok",
+                    displayName,
+                    value: field.value,
+                });
+            }
+            else if (info.tag === "INPUT" &&
+                (info.type === "checkbox" || info.type === "radio")) {
+                // --- CHECKBOX / RADIO ---
+                const desiredChecked = !!field.value;
+                if (desiredChecked !== info.checked) {
+                    await clickCheckboxOrRadio(cdpClient, targetSession, element.backendNodeId);
+                }
+                results.push({
+                    ref: field.ref,
+                    selector: field.selector,
+                    status: "ok",
+                    displayName,
+                    value: field.value,
+                });
+            }
+            else if (info.tag === "INPUT" && info.type === "file") {
+                // --- FILE INPUT — not supported, point to file_upload tool ---
+                results.push({
+                    ref: field.ref,
+                    selector: field.selector,
+                    status: "error",
+                    message: `Field ${id} is a file input — use the file_upload tool instead of fill_form`,
+                    value: field.value,
+                });
+                continue;
+            }
+            else {
+                // --- TEXT INPUT (default) ---
+                const textValue = String(field.value);
+                await fillTextInput(cdpClient, targetSession, element.backendNodeId, element.objectId, textValue, humanType);
+                results.push({
+                    ref: field.ref,
+                    selector: field.selector,
+                    status: "ok",
+                    displayName,
+                    value: field.value,
+                });
+            }
+        }
+        catch (err) {
+            // RefNotFoundError — contextual "did you mean?" error
+            if (err instanceof RefNotFoundError && field.ref) {
+                const errorText = buildRefNotFoundError(field.ref, FORM_FIELD_ROLES);
+                results.push({
+                    ref: field.ref,
+                    selector: field.selector,
+                    status: "error",
+                    message: errorText,
+                    value: field.value,
+                });
+                continue;
+            }
+            // CDP connection error or other — wrap and continue
+            const message = wrapCdpError(err, "fill_form");
+            results.push({
+                ref: field.ref,
+                selector: field.selector,
+                status: "error",
+                message,
+                value: field.value,
+            });
+        }
+    }
+    // --- Build response (Task 1.3) ---
+    const elapsedMs = Math.round(performance.now() - start);
+    const okCount = results.filter((r) => r.status === "ok").length;
+    const errorCount = results.filter((r) => r.status === "error").length;
+    const totalCount = results.length;
+    // Format response lines
+    const lines = [];
+    if (errorCount === 0) {
+        lines.push(`Filled ${okCount} fields:`);
+    }
+    else {
+        lines.push(`Filled ${okCount}/${totalCount} fields (${errorCount} error${errorCount > 1 ? "s" : ""}):`);
+    }
+    for (const r of results) {
+        const id = r.ref ?? r.selector ?? "unknown";
+        if (r.status === "ok") {
+            const displayValue = typeof r.value === "boolean"
+                ? String(r.value)
+                : `"${truncate(String(r.value ?? ""), 50)}"`;
+            const name = r.displayName ?? id;
+            lines.push(`- ${id} (${name}): ${displayValue} \u2713`);
+        }
+        else {
+            lines.push(`- ${id}: ${r.message}`);
+        }
+    }
+    const allFailed = okCount === 0;
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        ...(allFailed ? { isError: true } : {}),
+        _meta: { elapsedMs, method: "fill_form" },
+    };
+}

package/build/tools/handle-dialog.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { DialogHandler } from "../cdp/dialog-handler.js";
+import type { ToolResponse } from "../types.js";
+export declare const handleDialogSchema: z.ZodObject<{
+    action: z.ZodEnum<["accept", "dismiss", "get_status"]>;
+    text: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "accept" | "dismiss" | "get_status";
+    text?: string | undefined;
+}, {
+    action: "accept" | "dismiss" | "get_status";
+    text?: string | undefined;
+}>;
+export type HandleDialogParams = z.infer<typeof handleDialogSchema>;
+export declare function handleDialogHandler(params: HandleDialogParams, dialogHandler: DialogHandler): Promise<ToolResponse>;

package/build/tools/handle-dialog.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+export const handleDialogSchema = z.object({
+    action: z.enum(["accept", "dismiss", "get_status"]).describe("accept: accept the next dialog, dismiss: dismiss/cancel it, get_status: check pending dialogs"),
+    text: z.string().optional().describe("Text to enter in prompt dialogs (only used with action: accept)"),
+});
+export async function handleDialogHandler(params, dialogHandler) {
+    const start = performance.now();
+    switch (params.action) {
+        case "accept": {
+            const config = {
+                autoAccept: true,
+                promptText: params.text,
+                timeoutMs: 0,
+            };
+            dialogHandler.pushHandler(config);
+            const message = params.text
+                ? `Dialog handler configured: next dialog will be accepted with text: '${params.text}'`
+                : "Dialog handler configured: next dialog will be accepted";
+            return {
+                content: [{ type: "text", text: message }],
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "handle_dialog" },
+            };
+        }
+        case "dismiss": {
+            dialogHandler.pushHandler({
+                autoAccept: false,
+                timeoutMs: 0,
+            });
+            return {
+                content: [{ type: "text", text: "Dialog handler configured: next dialog will be dismissed" }],
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "handle_dialog" },
+            };
+        }
+        case "get_status": {
+            const notifications = dialogHandler.consumeNotifications();
+            if (notifications.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No dialogs occurred" }],
+                    _meta: { elapsedMs: Math.round(performance.now() - start), method: "handle_dialog" },
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(notifications, null, 2) }],
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "handle_dialog" },
+            };
+        }
+    }
+}

package/build/tools/index.d.ts

@@ -0,0 +1,35 @@
+export { evaluateSchema, evaluateHandler } from "./evaluate.js";
+export type { EvaluateParams } from "./evaluate.js";
+export { navigateSchema, navigateHandler } from "./navigate.js";
+export type { NavigateParams } from "./navigate.js";
+export { readPageSchema, readPageHandler } from "./read-page.js";
+export type { ReadPageParams } from "./read-page.js";
+export { screenshotSchema, screenshotHandler } from "./screenshot.js";
+export type { ScreenshotParams } from "./screenshot.js";
+export { waitForSchema, waitForHandler } from "./wait-for.js";
+export type { WaitForParams } from "./wait-for.js";
+export { clickSchema, clickHandler } from "./click.js";
+export type { ClickParams } from "./click.js";
+export { typeSchema, typeHandler } from "./type.js";
+export type { TypeParams } from "./type.js";
+export { resolveElement, buildRefNotFoundError } from "./element-utils.js";
+export type { ResolvedElement, ElementTarget } from "./element-utils.js";
+export { tabStatusSchema, tabStatusHandler } from "./tab-status.js";
+export type { TabStatusParams } from "./tab-status.js";
+export { switchTabSchema, switchTabHandler } from "./switch-tab.js";
+export type { SwitchTabParams } from "./switch-tab.js";
+export { virtualDeskSchema, virtualDeskHandler } from "./virtual-desk.js";
+export type { VirtualDeskParams } from "./virtual-desk.js";
+export { runPlanSchema, runPlanHandler } from "./run-plan.js";
+export type { RunPlanParams } from "./run-plan.js";
+export { domSnapshotSchema, domSnapshotHandler } from "./dom-snapshot.js";
+export type { DomSnapshotParams } from "./dom-snapshot.js";
+export { CLICKABLE_TAGS, CLICKABLE_ROLES, COMPUTED_STYLES } from "./visual-constants.js";
+export { consoleLogsSchema, consoleLogsHandler } from "./console-logs.js";
+export type { ConsoleLogsParams } from "./console-logs.js";
+export { networkMonitorSchema, networkMonitorHandler } from "./network-monitor.js";
+export type { NetworkMonitorParams } from "./network-monitor.js";
+export { configureSessionSchema, configureSessionHandler } from "./configure-session.js";
+export type { ConfigureSessionParams } from "./configure-session.js";
+export { observeSchema, observeHandler } from "./observe.js";
+export type { ObserveParams } from "./observe.js";

package/build/tools/index.js

@@ -0,0 +1,18 @@
+export { evaluateSchema, evaluateHandler } from "./evaluate.js";
+export { navigateSchema, navigateHandler } from "./navigate.js";
+export { readPageSchema, readPageHandler } from "./read-page.js";
+export { screenshotSchema, screenshotHandler } from "./screenshot.js";
+export { waitForSchema, waitForHandler } from "./wait-for.js";
+export { clickSchema, clickHandler } from "./click.js";
+export { typeSchema, typeHandler } from "./type.js";
+export { resolveElement, buildRefNotFoundError } from "./element-utils.js";
+export { tabStatusSchema, tabStatusHandler } from "./tab-status.js";
+export { switchTabSchema, switchTabHandler } from "./switch-tab.js";
+export { virtualDeskSchema, virtualDeskHandler } from "./virtual-desk.js";
+export { runPlanSchema, runPlanHandler } from "./run-plan.js";
+export { domSnapshotSchema, domSnapshotHandler } from "./dom-snapshot.js";
+export { CLICKABLE_TAGS, CLICKABLE_ROLES, COMPUTED_STYLES } from "./visual-constants.js";
+export { consoleLogsSchema, consoleLogsHandler } from "./console-logs.js";
+export { networkMonitorSchema, networkMonitorHandler } from "./network-monitor.js";
+export { configureSessionSchema, configureSessionHandler } from "./configure-session.js";
+export { observeSchema, observeHandler } from "./observe.js";

package/build/tools/navigate.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { ToolResponse } from "../types.js";
+export declare const navigateSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    action: z.ZodDefault<z.ZodOptional<z.ZodEnum<["goto", "back"]>>>;
+    settle_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "goto" | "back";
+    url?: string | undefined;
+    settle_ms?: number | undefined;
+}, {
+    url?: string | undefined;
+    action?: "goto" | "back" | undefined;
+    settle_ms?: number | undefined;
+}>;
+export type NavigateParams = z.infer<typeof navigateSchema>;
+export declare function navigateHandler(params: NavigateParams, cdpClient: CdpClient, sessionId?: string): Promise<ToolResponse>;

package/build/tools/navigate.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { settle } from "../cdp/settle.js";
+import { wrapCdpError } from "./error-utils.js";
+export const navigateSchema = z.object({
+    url: z.string().optional().describe("URL to navigate to (required for goto action)"),
+    action: z
+        .enum(["goto", "back"])
+        .optional()
+        .default("goto")
+        .describe("Navigation action: goto (default) or back"),
+    settle_ms: z
+        .number()
+        .optional()
+        .describe("Extra wait time in ms after page load (default: 500)"),
+});
+export async function navigateHandler(params, cdpClient, sessionId) {
+    const start = performance.now();
+    const method = "navigate";
+    try {
+        if (params.action === "back") {
+            return await handleBack(cdpClient, sessionId, params.settle_ms, start, method);
+        }
+        return await handleGoto(cdpClient, sessionId, params.url, params.settle_ms, start, method);
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "navigate") }],
+            isError: true,
+            _meta: { elapsedMs, method },
+        };
+    }
+}
+async function handleGoto(cdpClient, sessionId, url, settleMs, start, method) {
+    if (!url) {
+        return {
+            content: [{ type: "text", text: "URL is required for goto action" }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    const navResult = await cdpClient.send("Page.navigate", { url }, sessionId);
+    if (navResult.errorText) {
+        return {
+            content: [{ type: "text", text: `Navigation failed: ${navResult.errorText} for ${url}` }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    const isSpa = !navResult.loaderId;
+    const settleResult = await settle({
+        cdpClient,
+        sessionId: sessionId,
+        frameId: navResult.frameId,
+        loaderId: navResult.loaderId,
+        spaNavigation: isSpa,
+        settleMs,
+    });
+    return await buildSuccessResponse(cdpClient, sessionId, start, method, settleResult);
+}
+async function handleBack(cdpClient, sessionId, settleMs, start, method) {
+    const history = await cdpClient.send("Page.getNavigationHistory", {}, sessionId);
+    if (history.currentIndex <= 0) {
+        return {
+            content: [{ type: "text", text: "No previous page in history" }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    const prevEntry = history.entries[history.currentIndex - 1];
+    const frameTree = await cdpClient.send("Page.getFrameTree", {}, sessionId);
+    const mainFrameId = frameTree.frameTree.frame.id;
+    await cdpClient.send("Page.navigateToHistoryEntry", { entryId: prevEntry.id }, sessionId);
+    // Back navigation: no loaderId available upfront — accept any lifecycle events for main frame
+    const settleResult = await settle({
+        cdpClient,
+        sessionId: sessionId,
+        frameId: mainFrameId,
+        settleMs,
+    });
+    return await buildSuccessResponse(cdpClient, sessionId, start, method, settleResult);
+}
+async function buildSuccessResponse(cdpClient, sessionId, start, method, settleResult) {
+    let finalUrl = "unknown";
+    let title = "";
+    try {
+        const urlResult = await cdpClient.send("Runtime.evaluate", { expression: "document.URL", returnByValue: true }, sessionId);
+        finalUrl = urlResult.result.value;
+    }
+    catch {
+        // URL retrieval failed — continue with "unknown"
+    }
+    try {
+        const titleResult = await cdpClient.send("Runtime.evaluate", { expression: "document.title", returnByValue: true }, sessionId);
+        title = titleResult.result.value;
+    }
+    catch {
+        // Title retrieval failed — continue with empty title
+    }
+    const elapsedMs = Math.round(performance.now() - start);
+    let text = title
+        ? `Navigated to ${finalUrl} — ${title}`
+        : `Navigated to ${finalUrl}`;
+    if (!settleResult.settled) {
+        text += " (page not fully settled)";
+    }
+    return {
+        content: [{ type: "text", text }],
+        _meta: { elapsedMs, method, settled: settleResult.settled, settleSignal: settleResult.signal },
+    };
+}

package/build/tools/network-monitor.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { NetworkCollector } from "../cdp/network-collector.js";
+import type { ToolResponse } from "../types.js";
+export declare const networkMonitorSchema: z.ZodObject<{
+    action: z.ZodEnum<["start", "get", "stop"]>;
+    filter: z.ZodOptional<z.ZodEnum<["failed"]>>;
+    pattern: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "start" | "get" | "stop";
+    filter?: "failed" | undefined;
+    pattern?: string | undefined;
+}, {
+    action: "start" | "get" | "stop";
+    filter?: "failed" | undefined;
+    pattern?: string | undefined;
+}>;
+export type NetworkMonitorParams = z.infer<typeof networkMonitorSchema>;
+export declare function networkMonitorHandler(params: NetworkMonitorParams, networkCollector: NetworkCollector): Promise<ToolResponse>;

package/build/tools/network-monitor.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export const networkMonitorSchema = z.object({
+    action: z.enum(["start", "get", "stop"])
+        .describe("start: begin recording, get: retrieve recorded requests, stop: return and clear"),
+    filter: z.enum(["failed"])
+        .optional()
+        .describe("Filter results — 'failed': only requests with HTTP >= 400 or network errors"),
+    pattern: z.string()
+        .optional()
+        .describe("Regex pattern to match against request URLs"),
+});
+export async function networkMonitorHandler(params, networkCollector) {
+    const start = performance.now();
+    // action: "start"
+    if (params.action === "start") {
+        await networkCollector.start();
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        status: "monitoring",
+                        since: networkCollector.monitoringSince,
+                    }) }],
+            _meta: { elapsedMs: Math.round(performance.now() - start), method: "network_monitor" },
+        };
+    }
+    // action: "get"
+    if (params.action === "get") {
+        if (!networkCollector.isMonitoring) {
+            return {
+                content: [{ type: "text", text: "Network-Monitoring nicht aktiv — starte mit action: 'start'" }],
+                isError: true,
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "network_monitor" },
+            };
+        }
+        let requests;
+        try {
+            requests = (params.filter || params.pattern)
+                ? networkCollector.getFiltered(params.filter, params.pattern)
+                : networkCollector.getAll();
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Invalid regex pattern: ${err.message}` }],
+                isError: true,
+                _meta: { elapsedMs: Math.round(performance.now() - start), method: "network_monitor" },
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(requests) }],
+            _meta: {
+                elapsedMs: Math.round(performance.now() - start),
+                method: "network_monitor",
+                count: requests.length,
+            },
+        };
+    }
+    // action: "stop"
+    const requests = await networkCollector.stop();
+    return {
+        content: [{ type: "text", text: JSON.stringify(requests) }],
+        _meta: {
+            elapsedMs: Math.round(performance.now() - start),
+            method: "network_monitor",
+            count: requests.length,
+        },
+    };
+}

package/build/tools/observe.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { SessionManager } from "../cdp/session-manager.js";
+import type { ToolResponse } from "../types.js";
+export declare const observeSchema: z.ZodObject<{
+    selector: z.ZodString;
+    duration: z.ZodOptional<z.ZodNumber>;
+    until: z.ZodOptional<z.ZodString>;
+    then_click: z.ZodOptional<z.ZodString>;
+    click_first: z.ZodOptional<z.ZodString>;
+    collect: z.ZodDefault<z.ZodOptional<z.ZodEnum<["text", "attributes", "all"]>>>;
+    interval: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    selector: string;
+    collect: "text" | "all" | "attributes";
+    interval: number;
+    duration?: number | undefined;
+    until?: string | undefined;
+    then_click?: string | undefined;
+    click_first?: string | undefined;
+}, {
+    selector: string;
+    timeout?: number | undefined;
+    duration?: number | undefined;
+    until?: string | undefined;
+    then_click?: string | undefined;
+    click_first?: string | undefined;
+    collect?: "text" | "all" | "attributes" | undefined;
+    interval?: number | undefined;
+}>;
+export type ObserveParams = z.infer<typeof observeSchema>;
+/**
+ * Build the observer function for "collect" mode.
+ * Runs for `duration` ms, collects all text/attribute changes.
+ */
+export declare function buildCollectFunction(duration: number, interval: number, collect: "text" | "attributes" | "all", clickFirstSelector?: string): string;
+/**
+ * Build the observer function for "until" mode.
+ * Waits until a JS condition is met, optionally clicks a target element.
+ */
+export declare function buildUntilFunction(untilExpression: string, timeout: number, interval: number, collect: "text" | "attributes" | "all", thenClickSelector?: string, clickFirstSelector?: string): string;
+export declare function observeHandler(params: ObserveParams, cdpClient: CdpClient, sessionId: string, sessionManager?: SessionManager): Promise<ToolResponse>;