@silbercue/chrome 0.2.0

package/build/tools/switch-tab.js

@@ -0,0 +1,355 @@
+import { z } from "zod";
+import { settle } from "../cdp/settle.js";
+import { DEVICE_METRICS_OVERRIDE, isHeadless } from "../cdp/emulation.js";
+import { wrapCdpError } from "./error-utils.js";
+import { injectOverlay } from "../overlay/session-overlay.js";
+export const switchTabSchema = z.object({
+    action: z
+        .enum(["open", "switch", "close"])
+        .optional()
+        .default("switch")
+        .describe("Action: open (new tab), switch (to existing tab, default), close (close tab)"),
+    url: z
+        .string()
+        .optional()
+        .describe("URL to navigate to (for open action, defaults to about:blank)"),
+    tab: z
+        .string()
+        .optional()
+        .describe("Tab ID or tab number (1-based index, e.g. '2') to switch to or close (defaults to active tab for close)"),
+});
+/**
+ * Resolve a tab that may be a 1-based numeric index (e.g. "2")
+ * or a CDP targetId (32-char hex). Returns the actual targetId or undefined.
+ */
+function resolveTabId(tabId, pageTabs) {
+    if (/^\d{1,3}$/.test(tabId)) {
+        const idx = parseInt(tabId, 10) - 1;
+        return pageTabs[idx]?.targetId;
+    }
+    return pageTabs.find((t) => t.targetId === tabId)?.targetId;
+}
+/**
+ * Mutex for serialising session-switching operations (H3).
+ * Prevents race conditions when parallel tool-calls try to switch tabs concurrently.
+ */
+let _switchLock = Promise.resolve();
+function withSwitchLock(fn) {
+    const prev = _switchLock;
+    let release;
+    _switchLock = new Promise((res) => {
+        release = res;
+    });
+    return prev.then(fn).finally(() => release());
+}
+/** Visible for testing — resets the internal lock to a resolved promise. */
+export function _resetSwitchLock() {
+    _switchLock = Promise.resolve();
+}
+/**
+ * Tracks the tab the user was on before open/switch navigated away.
+ * Used by close to return to the origin tab instead of picking a random one.
+ */
+let _originTabId;
+/** Visible for testing — resets the origin tab tracking. */
+export function _resetOriginTab() {
+    _originTabId = undefined;
+}
+/** Visible for testing — reads the current origin tab. */
+export function _getOriginTabId() {
+    return _originTabId;
+}
+/** FR-014: Hint appended to responses where the active tab changes. */
+const STALE_REFS_HINT = "\n\nNote: Element refs from the previous tab are no longer valid. Call read_page for fresh refs.";
+/**
+ * Attach to a target, enable CDP domains, re-attach TabStateCache listeners,
+ * and propagate the new sessionId. Shared by all three actions.
+ */
+async function activateSession(cdpClient, targetId, tabStateCache, onSessionChange) {
+    // 1. Attach to target -> new sessionId
+    const { sessionId: newSessionId } = await cdpClient.send("Target.attachToTarget", { targetId, flatten: true });
+    // 2. Enable CDP domains on the new session
+    await cdpClient.send("Runtime.enable", {}, newSessionId);
+    await cdpClient.send("Page.enable", {}, newSessionId);
+    await cdpClient.send("Page.setLifecycleEventsEnabled", { enabled: true }, newSessionId);
+    await cdpClient.send("DOM.enable", {}, newSessionId);
+    await cdpClient.send("Accessibility.enable", {}, newSessionId);
+    // BUG-015 fix: Keep renderer alive when window is occluded on macOS (per-tab).
+    if (!isHeadless()) {
+        await cdpClient.send("Emulation.setFocusEmulationEnabled", { enabled: true }, newSessionId);
+    }
+    if (isHeadless()) {
+        await cdpClient.send("Emulation.setDeviceMetricsOverride", DEVICE_METRICS_OVERRIDE, newSessionId);
+    }
+    // 3. Re-attach cache listeners to new session
+    tabStateCache.detachFromClient();
+    tabStateCache.attachToClient(cdpClient, newSessionId);
+    tabStateCache.setActiveTarget(targetId);
+    // 4. Propagate new session to ToolRegistry
+    onSessionChange(newSessionId);
+    // 5. Inject session overlay into the new tab
+    await injectOverlay(cdpClient, newSessionId);
+    return newSessionId;
+}
+export async function switchTabHandler(params, cdpClient, sessionId, tabStateCache, onSessionChange, sessionManager) {
+    const start = performance.now();
+    const method = "switch_tab";
+    // H3: Serialise session-switching to prevent race conditions
+    return withSwitchLock(async () => {
+        try {
+            switch (params.action) {
+                case "open":
+                    return await handleOpen(params, cdpClient, tabStateCache, onSessionChange, start, method, sessionManager);
+                case "switch":
+                    return await handleSwitch(params, cdpClient, tabStateCache, onSessionChange, start, method, sessionManager);
+                case "close":
+                    return await handleClose(params, cdpClient, sessionId, tabStateCache, onSessionChange, start, method);
+            }
+        }
+        catch (err) {
+            const elapsedMs = Math.round(performance.now() - start);
+            return {
+                content: [{ type: "text", text: wrapCdpError(err, "switch_tab") }],
+                isError: true,
+                _meta: { elapsedMs, method },
+            };
+        }
+    });
+}
+async function handleOpen(params, cdpClient, tabStateCache, onSessionChange, start, method, sessionManager) {
+    const url = params.url ?? "about:blank";
+    // Remember origin tab before switching away
+    _originTabId = tabStateCache.activeTargetId ?? undefined;
+    // Create new tab
+    const { targetId } = await cdpClient.send("Target.createTarget", {
+        url,
+    });
+    // Activate session on the new tab
+    const newSessionId = await activateSession(cdpClient, targetId, tabStateCache, onSessionChange);
+    // C1: Re-initialize SessionManager for new tab's OOPIF auto-attach
+    if (sessionManager) {
+        await sessionManager.reinit(cdpClient, newSessionId);
+    }
+    // If a real URL was specified, settle after navigation (about:blank needs no settle)
+    if (params.url && params.url !== "about:blank") {
+        const frameTree = await cdpClient.send("Page.getFrameTree", {}, newSessionId);
+        const mainFrameId = frameTree.frameTree.frame.id;
+        await settle({
+            cdpClient,
+            sessionId: newSessionId,
+            frameId: mainFrameId,
+        });
+    }
+    // Fetch state for response
+    const { state } = await tabStateCache.getOrFetch(cdpClient, targetId, newSessionId);
+    const elapsedMs = Math.round(performance.now() - start);
+    const originLine = _originTabId
+        ? `\nOrigin tab: ${_originTabId} — use switch_tab(action: "close") to return`
+        : "";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tab opened: ${targetId}\nURL: ${state.url}\nTitle: ${state.title}${originLine}${STALE_REFS_HINT}`,
+            },
+        ],
+        _meta: { elapsedMs, method },
+    };
+}
+async function handleSwitch(params, cdpClient, tabStateCache, onSessionChange, start, method, sessionManager) {
+    if (!params.tab) {
+        // No tab: list available tabs so the LLM can pick one
+        const { targetInfos } = await cdpClient.send("Target.getTargets");
+        const pageTabs = targetInfos.filter((t) => t.type === "page");
+        const activeId = tabStateCache.activeTargetId;
+        const lines = pageTabs.map((t, i) => {
+            const marker = t.targetId === activeId ? "★" : " ";
+            return `${marker} Tab ${i + 1}: ${t.targetId} | ${t.title} | ${t.url}`;
+        });
+        return {
+            content: [{ type: "text", text: `Tabs (${pageTabs.length} open):\n${lines.join("\n")}` }],
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    // Verify tab exists before switching (supports numeric index or targetId)
+    const { targetInfos } = await cdpClient.send("Target.getTargets");
+    const pageTabs = targetInfos.filter((t) => t.type === "page");
+    const resolvedId = resolveTabId(params.tab, pageTabs);
+    if (!resolvedId) {
+        return {
+            content: [{ type: "text", text: `Tab not found: ${params.tab}. Use virtual_desk to discover available tabs.` }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    // Remember origin tab before switching away
+    _originTabId = tabStateCache.activeTargetId ?? undefined;
+    // C1: Remember previous state for rollback if attachToTarget fails
+    const previousTargetId = tabStateCache.activeTargetId;
+    // Bring tab to front visually + ensure its window is in foreground
+    await cdpClient.send("Target.activateTarget", { targetId: resolvedId });
+    try {
+        const { windowId } = await cdpClient.send("Browser.getWindowForTarget", { targetId: resolvedId });
+        await cdpClient.send("Browser.setWindowBounds", {
+            windowId,
+            bounds: { windowState: "normal" },
+        });
+    }
+    catch {
+        /* best-effort — window focus is not critical */
+    }
+    // C1: Activate CDP session — rollback on failure
+    let newSessionId;
+    try {
+        newSessionId = await activateSession(cdpClient, resolvedId, tabStateCache, onSessionChange);
+    }
+    catch (attachErr) {
+        // C1: Rollback — re-activate the previous tab visually
+        if (previousTargetId) {
+            try {
+                await cdpClient.send("Target.activateTarget", { targetId: previousTargetId });
+            }
+            catch {
+                /* best-effort rollback */
+            }
+        }
+        throw attachErr;
+    }
+    // C1: Re-initialize SessionManager for new tab's OOPIF auto-attach
+    if (sessionManager) {
+        await sessionManager.reinit(cdpClient, newSessionId);
+    }
+    // Fetch state for response
+    const { state } = await tabStateCache.getOrFetch(cdpClient, resolvedId, newSessionId);
+    const elapsedMs = Math.round(performance.now() - start);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Switched to tab: ${resolvedId}\nURL: ${state.url}\nTitle: ${state.title}${STALE_REFS_HINT}`,
+            },
+        ],
+        _meta: { elapsedMs, method },
+    };
+}
+async function handleClose(params, cdpClient, sessionId, tabStateCache, onSessionChange, start, method) {
+    // Get all page tabs to check if this is the last one
+    const { targetInfos } = await cdpClient.send("Target.getTargets");
+    const pageTabs = targetInfos.filter((t) => t.type === "page");
+    // Resolve tab (supports numeric index or targetId)
+    let targetTab;
+    if (params.tab) {
+        targetTab = resolveTabId(params.tab, pageTabs);
+        if (!targetTab) {
+            return {
+                content: [{ type: "text", text: `Tab not found: ${params.tab}` }],
+                isError: true,
+                _meta: { elapsedMs: Math.round(performance.now() - start), method },
+            };
+        }
+    }
+    else {
+        targetTab = tabStateCache.activeTargetId ?? undefined;
+    }
+    if (!targetTab) {
+        return {
+            content: [{ type: "text", text: "No active tab to close" }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method },
+        };
+    }
+    const isLastTab = pageTabs.length <= 1;
+    const isActiveTab = targetTab === tabStateCache.activeTargetId;
+    let newActiveTab;
+    if (isLastTab) {
+        // Create a new about:blank tab before closing the last one
+        const { targetId: blankTabId } = await cdpClient.send("Target.createTarget", { url: "about:blank" });
+        newActiveTab = blankTabId;
+    }
+    else if (isActiveTab) {
+        // Prefer origin tab (the tab we came from) if it still exists
+        const originAlive = _originTabId &&
+            _originTabId !== targetTab &&
+            pageTabs.some((t) => t.targetId === _originTabId);
+        if (originAlive) {
+            newActiveTab = _originTabId;
+        }
+        else {
+            // Fallback: pick the next available tab
+            newActiveTab = pageTabs.find((t) => t.targetId !== targetTab)?.targetId;
+        }
+    }
+    // C2/H1: If switching to a new tab, complete the switch BEFORE closing & cleanup.
+    // Architecture: activateTarget (visual) -> attachToTarget (session) -> close old tab.
+    if (newActiveTab) {
+        // H1: Activate the new tab visually first
+        await cdpClient.send("Target.activateTarget", { targetId: newActiveTab });
+        // H1: Then attach session
+        let newSessionId;
+        try {
+            newSessionId = await activateSession(cdpClient, newActiveTab, tabStateCache, onSessionChange);
+        }
+        catch (attachErr) {
+            // C2: activateSession failed — don't leave activeTargetId on a tab we're about to close.
+            // Find any other surviving tab to fall back to.
+            const fallback = pageTabs.find((t) => t.targetId !== targetTab && t.targetId !== newActiveTab);
+            if (fallback) {
+                try {
+                    await cdpClient.send("Target.activateTarget", { targetId: fallback.targetId });
+                    const fallbackSessionId = await activateSession(cdpClient, fallback.targetId, tabStateCache, onSessionChange);
+                    // Still close the intended target
+                    await cdpClient.send("Target.closeTarget", { targetId: targetTab });
+                    tabStateCache.invalidate(targetTab);
+                    _originTabId = undefined; // Reset after close
+                    const { state } = await tabStateCache.getOrFetch(cdpClient, fallback.targetId, fallbackSessionId);
+                    const elapsedMs = Math.round(performance.now() - start);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Tab closed: ${targetTab}\nActive tab: ${fallback.targetId} (fallback)\nURL: ${state.url}\nTitle: ${state.title}${STALE_REFS_HINT}`,
+                            },
+                        ],
+                        _meta: { elapsedMs, method },
+                    };
+                }
+                catch {
+                    /* fallback also failed, propagate original error */
+                }
+            }
+            throw attachErr;
+        }
+        // Now safely close the old tab and clean up
+        await cdpClient.send("Target.closeTarget", { targetId: targetTab });
+        tabStateCache.invalidate(targetTab);
+        const usedOrigin = newActiveTab === _originTabId;
+        _originTabId = undefined; // Reset after close
+        const { state } = await tabStateCache.getOrFetch(cdpClient, newActiveTab, newSessionId);
+        const elapsedMs = Math.round(performance.now() - start);
+        const activeLine = usedOrigin
+            ? `Returned to origin tab: ${newActiveTab}`
+            : `Active tab: ${newActiveTab} (origin tab no longer available)`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Tab closed: ${targetTab}\n${activeLine}\nURL: ${state.url}\nTitle: ${state.title}${STALE_REFS_HINT}`,
+                },
+            ],
+            _meta: { elapsedMs, method },
+        };
+    }
+    // Non-active tab was closed, no switch needed
+    await cdpClient.send("Target.closeTarget", { targetId: targetTab });
+    tabStateCache.invalidate(targetTab);
+    const elapsedMs = Math.round(performance.now() - start);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Tab closed: ${targetTab}`,
+            },
+        ],
+        _meta: { elapsedMs, method },
+    };
+}

package/build/tools/tab-status.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 tabStatusSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type TabStatusParams = z.infer<typeof tabStatusSchema>;
+export declare function tabStatusHandler(_params: TabStatusParams, cdpClient: CdpClient, sessionId: string | undefined, tabStateCache: TabStateCache, connectionStatus?: ConnectionStatus): Promise<ToolResponse>;

package/build/tools/tab-status.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { wrapCdpError } from "./error-utils.js";
+export const tabStatusSchema = z.object({});
+export async function tabStatusHandler(_params, cdpClient, sessionId, tabStateCache, connectionStatus) {
+    const start = performance.now();
+    // 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: "tab_status" },
+        };
+    }
+    const activeTarget = tabStateCache.activeTargetId;
+    if (!activeTarget) {
+        return {
+            content: [{ type: "text", text: "No active tab. Use virtual_desk to discover available tabs, or navigate to a page first." }],
+            isError: true,
+            _meta: { elapsedMs: Math.round(performance.now() - start), method: "tab_status" },
+        };
+    }
+    try {
+        const { state, cacheHit } = await tabStateCache.getOrFetch(cdpClient, activeTarget, sessionId);
+        const elapsedMs = Math.round(performance.now() - start);
+        const lines = [
+            `URL: ${state.url}`,
+            `Title: ${state.title}`,
+            `DOM: ${state.domReady ? "ready" : "loading"}`,
+        ];
+        if (state.consoleErrors.length > 0) {
+            lines.push(`Errors (${state.consoleErrors.length}):`);
+            for (const err of state.consoleErrors) {
+                lines.push(`  - ${err.slice(0, 200)}`);
+            }
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            _meta: { elapsedMs, method: "tab_status", cacheHit },
+        };
+    }
+    catch (err) {
+        const elapsedMs = Math.round(performance.now() - start);
+        return {
+            content: [{ type: "text", text: wrapCdpError(err, "tab_status") }],
+            isError: true,
+            _meta: { elapsedMs, method: "tab_status" },
+        };
+    }
+}

package/build/tools/type.d.ts

@@ -0,0 +1,31 @@
+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 typeSchema: z.ZodObject<{
+    ref: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+    clear: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    clear: boolean;
+    ref?: string | undefined;
+    selector?: string | undefined;
+}, {
+    text: string;
+    ref?: string | undefined;
+    selector?: string | undefined;
+    clear?: boolean | undefined;
+}>;
+export type TypeParams = z.infer<typeof typeSchema>;
+/**
+ * Story 16.5: Optional human-type callback injected via the `enhanceTool`
+ * Pro-Hook. When present, this replaces the raw `Input.insertText` with a
+ * realistic per-character typing sequence from the Pro-Repo Human Touch
+ * module. The Free-Repo itself does NOT contain any Human-Touch logic.
+ */
+export type HumanTypeFn = (cdpClient: CdpClient, sessionId: string, text: string) => Promise<void>;
+/** Exported for unit tests — clears the streak state. */
+export declare function _resetTypeStreaks(): void;
+export declare function typeHandler(params: TypeParams, cdpClient: CdpClient, sessionId?: string, sessionManager?: SessionManager): Promise<ToolResponse>;