@silbercue/chrome 0.2.0

package/build/tools/type.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import { resolveElement, buildRefNotFoundError, RefNotFoundError } from "./element-utils.js";
+import { wrapCdpError } from "./error-utils.js";
+import { a11yTree } from "../cache/a11y-tree.js";
+// --- Schema (Task 2) ---
+export const typeSchema = z.object({
+    ref: z
+        .string()
+        .optional()
+        .describe("Element reference from read_page (e.g. 'e12') — preferred over selector"),
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector as fallback (e.g. 'input[name=email]')"),
+    text: z
+        .string()
+        .describe("Text to type into the element"),
+    clear: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Clear existing field content before typing (default: false)"),
+});
+// --- Constants ---
+const INPUT_ROLES = new Set(["textbox", "searchbox", "combobox", "spinbutton"]);
+/** FR-023: Emit a fill_form hint after this many consecutive type calls within the window. */
+const FILL_FORM_HINT_THRESHOLD = 2;
+/** FR-023: Time window (ms) in which consecutive type calls are considered "in the same form session". */
+const FILL_FORM_HINT_WINDOW_MS = 10_000;
+// --- Helpers ---
+function truncate(text, maxLen) {
+    return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+}
+const typeStreaks = new Map();
+/** Exported for unit tests — clears the streak state. */
+export function _resetTypeStreaks() {
+    typeStreaks.clear();
+}
+/**
+ * FR-023 scope-fix: Probe the closest <form> ancestor of the resolved element
+ * and tag it with a stable, per-form identifier (persisted via a dataset
+ * marker so subsequent probes on the same form return the same ID).
+ *
+ * Returns null when:
+ *   - the element has no <form> ancestor (e.g. a loose input field), or
+ *   - the probe fails (detached node, hostile page, etc.).
+ *
+ * A null return suppresses the streak hint, which is the safe default —
+ * we'd rather miss a hint than show one for unrelated form fills.
+ */
+async function probeFormScope(cdpClient, objectId, targetSession) {
+    try {
+        const res = (await cdpClient.send("Runtime.callFunctionOn", {
+            functionDeclaration: `function() {
+          const f = this.closest('form');
+          if (!f) return null;
+          if (!f.dataset.__silbercueFormId) {
+            f.dataset.__silbercueFormId = '__sc_' + Math.random().toString(36).slice(2, 10);
+          }
+          return f.dataset.__silbercueFormId;
+        }`,
+            objectId,
+            returnByValue: true,
+            silent: true,
+        }, targetSession));
+        return res?.result?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function recordTypeCallAndMaybeHint(sessionId, formId) {
+    if (!sessionId)
+        return null;
+    const now = Date.now();
+    const existing = typeStreaks.get(sessionId);
+    // The streak continues only when ALL of the following hold:
+    //   1. We are still inside the time window.
+    //   2. The current call has a non-null form scope.
+    //   3. That form scope matches the previous call's form scope.
+    // Otherwise we reset the streak with the current call as the new baseline.
+    if (existing &&
+        now - existing.lastAt <= FILL_FORM_HINT_WINDOW_MS &&
+        formId !== null &&
+        existing.formId === formId) {
+        existing.count += 1;
+        existing.lastAt = now;
+        if (existing.count >= FILL_FORM_HINT_THRESHOLD && !existing.hintShown) {
+            existing.hintShown = true;
+            return `\n\nTip: ${existing.count} consecutive type calls into the same form in ${Math.round(FILL_FORM_HINT_WINDOW_MS / 1000)}s — next time try fill_form({ fields: [...] }) for one-round-trip form fills. It handles text inputs, <select>, checkbox, and radio natively, so you don't need evaluate or separate click calls.`;
+        }
+        return null;
+    }
+    typeStreaks.set(sessionId, { count: 1, lastAt: now, hintShown: false, formId });
+    return null;
+}
+// --- Main handler ---
+export async function typeHandler(params, cdpClient, sessionId, sessionManager) {
+    const start = performance.now();
+    // Story 16.5: Extract optional humanType callback injected by the
+    // `enhanceTool` Pro-Hook. The field is NOT part of the Zod schema — it is
+    // read from the raw params map via type-guard and stripped from the params
+    // object before downstream code uses it.
+    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;
+    }
+    // Validation: require text parameter (defensive — Zod enforces this at schema level,
+    // but handler may be called directly without schema parsing)
+    if (params.text === undefined || params.text === null) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "type requires a 'text' parameter",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "type" },
+        };
+    }
+    // Validation: require at least ref or selector
+    if (!params.ref && !params.selector) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "type requires either 'ref' or 'selector' to identify the target element",
+                },
+            ],
+            isError: true,
+            _meta: { elapsedMs: 0, method: "type" },
+        };
+    }
+    try {
+        // Step 1: Resolve element (ref preferred over selector, with OOPIF routing)
+        const target = params.ref ? { ref: params.ref } : { selector: params.selector };
+        const element = await resolveElement(cdpClient, sessionId, target, sessionManager);
+        const targetSession = element.resolvedSessionId;
+        // FR-023 scope-fix: Probe the form ancestor BEFORE we mutate the DOM via
+        // focus/clear/insertText. We need a stable form-scope ID up-front so the
+        // streak detector at Step 6 only fires when both type calls land in the
+        // SAME <form>. Probe failures return null and silently suppress the hint.
+        const formScopeId = sessionId
+            ? await probeFormScope(cdpClient, element.objectId, targetSession)
+            : null;
+        // Step 2: Role check — only for ref-resolved elements (CSS path skips check)
+        if (element.resolvedVia === "ref" && element.role && !INPUT_ROLES.has(element.role)) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Element ${params.ref} is not a text input (role: ${element.role}). Expected textbox, searchbox, combobox, or spinbutton.`,
+                    },
+                ],
+                isError: true,
+                _meta: { elapsedMs, method: "type" },
+            };
+        }
+        // Step 3: Focus the element (use resolved session for OOPIF)
+        // Try DOM.focus first, fall back to JS this.focus() for Shadow-DOM/post-mutation nodes (BUG-006)
+        try {
+            await cdpClient.send("DOM.focus", { backendNodeId: element.backendNodeId }, targetSession);
+        }
+        catch {
+            // Fallback: JS focus via Runtime.callFunctionOn (handles Shadow-DOM and stale backendNodeIds)
+            try {
+                await cdpClient.send("Runtime.callFunctionOn", {
+                    functionDeclaration: "function() { this.focus(); }",
+                    objectId: element.objectId,
+                    silent: true,
+                }, targetSession);
+            }
+            catch {
+                const elapsedMs = Math.round(performance.now() - start);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not focus element ${params.ref ?? params.selector}. Element may be hidden or not focusable.`,
+                        },
+                    ],
+                    isError: true,
+                    _meta: { elapsedMs, method: "type" },
+                };
+            }
+        }
+        // Step 4: Clear field if requested (use resolved session for OOPIF)
+        if (params.clear) {
+            await cdpClient.send("Runtime.callFunctionOn", {
+                objectId: element.objectId,
+                functionDeclaration: "function() { this.value = ''; this.dispatchEvent(new Event('input', { bubbles: true })); }",
+                returnByValue: true,
+            }, targetSession);
+        }
+        // Step 5: Insert text (use resolved session for OOPIF — no auto-settle)
+        // Story 16.5: If humanType callback is injected, delegate to it.
+        if (params.text.length > 0) {
+            if (humanType) {
+                await humanType(cdpClient, targetSession, params.text);
+            }
+            else {
+                await cdpClient.send("Input.insertText", { text: params.text }, targetSession);
+            }
+        }
+        // Step 6: Success response
+        const elapsedMs = Math.round(performance.now() - start);
+        const displayName = element.name
+            ? `${element.role} '${element.name}'`
+            : (params.ref ?? params.selector);
+        // FR-023: Emit fill_form hint once per streak when the LLM makes consecutive
+        // type calls into the SAME form (form-scoped via probeFormScope above).
+        const fillFormHint = recordTypeCallAndMaybeHint(sessionId, formScopeId) ?? "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Typed "${truncate(params.text, 50)}" into ${displayName}${fillFormHint}`,
+                },
+            ],
+            _meta: { elapsedMs, method: "type", cleared: params.clear, elementClass: params.ref ? a11yTree.classifyRef(params.ref) : "clickable" },
+        };
+    }
+    catch (err) {
+        // RefNotFoundError — contextual error with input-field alternatives
+        if (err instanceof RefNotFoundError && params.ref) {
+            const errorText = buildRefNotFoundError(params.ref, INPUT_ROLES);
+            return {
+                content: [{ type: "text", text: errorText }],
+                isError: true,
+                _meta: { elapsedMs: 0, method: "type" },
+            };
+        }
+        // Generic error
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "type") }],
+            isError: true,
+            _meta: { elapsedMs, method: "type" },
+        };
+    }
+}

package/build/tools/virtual-desk.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { ToolResponse, ConnectionStatus } from "../types.js";
+import type { TabStateCache } from "../cache/tab-state-cache.js";
+export declare const virtualDeskSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type VirtualDeskParams = z.infer<typeof virtualDeskSchema>;
+export declare function virtualDeskHandler(_params: VirtualDeskParams, cdpClient: CdpClient, sessionId: string | undefined, tabStateCache: TabStateCache, connectionStatus?: ConnectionStatus): Promise<ToolResponse>;

package/build/tools/virtual-desk.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { wrapCdpError } from "./error-utils.js";
+export const virtualDeskSchema = z.object({});
+function truncateUrl(url, maxLen) {
+    if (url.length <= maxLen)
+        return url;
+    const short = url.replace(/^https?:\/\//, "");
+    if (short.length <= maxLen)
+        return short;
+    return short.slice(0, maxLen - 3) + "...";
+}
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 3) + "...";
+}
+/**
+ * Infer loading state from CDP target info when no cache entry exists.
+ * about:blank or empty title typically indicate a tab that's still loading.
+ */
+function inferLoadingState(target) {
+    if (target.url === "" || target.url === "about:blank")
+        return "loading";
+    if (target.title === "")
+        return "loading";
+    return "ready";
+}
+export async function virtualDeskHandler(_params, cdpClient, sessionId, tabStateCache, connectionStatus) {
+    const start = performance.now();
+    const method = "virtual_desk";
+    // If disconnected or reconnecting, report status immediately
+    if (connectionStatus && connectionStatus !== "connected") {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: `Connection: ${connectionStatus} — tool calls may fail until reconnected` }],
+            isError: true,
+            _meta: { elapsedMs, method },
+        };
+    }
+    try {
+        // Single CDP call for ALL tabs — no N+1 problem
+        const { targetInfos } = await cdpClient.send("Target.getTargets");
+        const pageTabs = targetInfos.filter((t) => t.type === "page");
+        if (pageTabs.length === 0) {
+            return {
+                content: [{ type: "text", text: "No open tabs" }],
+                _meta: { elapsedMs: Math.round(performance.now() - start), method },
+            };
+        }
+        // Fetch window info for each tab (parallel CDP calls)
+        const windowInfos = await Promise.all(pageTabs.map(async (tab) => {
+            try {
+                return await cdpClient.send("Browser.getWindowForTarget", { targetId: tab.targetId });
+            }
+            catch {
+                return null;
+            }
+        }));
+        // Group tabs by windowId
+        const windowMap = new Map();
+        for (let i = 0; i < pageTabs.length; i++) {
+            const wInfo = windowInfos[i];
+            const key = wInfo?.windowId ?? -1;
+            if (!windowMap.has(key)) {
+                windowMap.set(key, { info: wInfo, tabs: [] });
+            }
+            windowMap.get(key).tabs.push({ tab: pageTabs[i], index: i });
+        }
+        // Build output grouped by window
+        const activeId = tabStateCache.activeTargetId;
+        const lines = [];
+        let tabCounter = 0;
+        for (const [windowId, group] of windowMap) {
+            // Window header with bounds
+            if (group.info) {
+                const b = group.info.bounds;
+                const stateLabel = b.windowState !== "normal" ? ` — ${b.windowState}` : "";
+                lines.push(`Window ${windowId} (${b.width}x${b.height} at ${b.left},${b.top}${stateLabel}):`);
+            }
+            else {
+                lines.push(`Window (unknown):`);
+            }
+            // Tabs within this window
+            for (const { tab } of group.tabs) {
+                tabCounter++;
+                const isActive = tab.targetId === activeId;
+                const cached = tabStateCache.get(tab.targetId);
+                const url = truncateUrl(tab.url, 80);
+                const title = truncate(cached?.title || tab.title, 40);
+                const status = cached?.loadingState ?? inferLoadingState(tab);
+                const marker = isActive ? ">" : " ";
+                lines.push(`${marker} Tab ${tabCounter}: ${tab.targetId} | ${status} | ${title} | ${url}`);
+            }
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            _meta: { elapsedMs: Math.round(performance.now() - start), method, tabCount: pageTabs.length },
+        };
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, method) }],
+            isError: true,
+            _meta: { elapsedMs, method },
+        };
+    }
+}

package/build/tools/visual-constants.d.ts

@@ -0,0 +1,3 @@
+export declare const CLICKABLE_TAGS: Set<string>;
+export declare const CLICKABLE_ROLES: Set<string>;
+export declare const COMPUTED_STYLES: readonly ["display", "visibility", "color", "background-color", "font-size", "position", "z-index"];

package/build/tools/visual-constants.js

@@ -0,0 +1,10 @@
+// Shared constants used by dom-snapshot and a11y-tree visual enrichment.
+export const CLICKABLE_TAGS = new Set(["A", "BUTTON", "INPUT", "SELECT", "TEXTAREA"]);
+export const CLICKABLE_ROLES = new Set([
+    "button", "link", "checkbox", "radio", "tab", "menuitem",
+    "switch", "slider", "option", "treeitem",
+]);
+export const COMPUTED_STYLES = [
+    "display", "visibility", "color", "background-color",
+    "font-size", "position", "z-index",
+];

package/build/tools/wait-for.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import type { CdpClient } from "../cdp/cdp-client.js";
+import type { ToolResponse } from "../types.js";
+export declare const waitForSchema: z.ZodObject<{
+    condition: z.ZodEnum<["element", "network_idle", "js"]>;
+    selector: z.ZodOptional<z.ZodString>;
+    expression: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    condition: "element" | "network_idle" | "js";
+    expression?: string | undefined;
+    selector?: string | undefined;
+}, {
+    condition: "element" | "network_idle" | "js";
+    timeout?: number | undefined;
+    expression?: string | undefined;
+    selector?: string | undefined;
+}>;
+export type WaitForParams = z.infer<typeof waitForSchema>;
+/**
+ * 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 declare function extractSelector(expression: string): string | null;
+export declare function waitForHandler(params: WaitForParams, cdpClient: CdpClient, sessionId?: string): Promise<ToolResponse>;