gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/browser-tools/settle.js

@@ -0,0 +1,173 @@
+/**
+ * browser-tools — DOM settle logic
+ *
+ * Adaptive settling after browser actions. Polls for DOM quiet (mutation
+ * counter stable, no pending critical requests, optional focus stability)
+ * before returning control.
+ */
+import { getPendingCriticalRequests } from "./utils.js";
+// ---------------------------------------------------------------------------
+// Mutation counter (installed in-page via evaluate)
+// ---------------------------------------------------------------------------
+export async function ensureMutationCounter(p) {
+    await p.evaluate(() => {
+        const key = "__piMutationCounter";
+        const installedKey = "__piMutationCounterInstalled";
+        const w = window;
+        if (typeof w[key] !== "number")
+            w[key] = 0;
+        if (w[installedKey])
+            return;
+        const observer = new MutationObserver(() => {
+            const current = typeof w[key] === "number" ? w[key] : 0;
+            w[key] = current + 1;
+        });
+        observer.observe(document.documentElement || document.body, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            characterData: true,
+        });
+        w[installedKey] = true;
+    });
+}
+export async function readMutationCounter(p) {
+    try {
+        return await p.evaluate(() => {
+            const w = window;
+            const value = w.__piMutationCounter;
+            return typeof value === "number" ? value : 0;
+        });
+    }
+    catch {
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Focus descriptor (for focus-stability checks)
+// ---------------------------------------------------------------------------
+export async function readFocusedDescriptor(target) {
+    try {
+        return await target.evaluate(() => {
+            const el = document.activeElement;
+            if (!el || el === document.body || el === document.documentElement)
+                return "";
+            const id = el.id ? `#${el.id}` : "";
+            const role = el.getAttribute("role") || "";
+            const name = (el.getAttribute("aria-label") || el.getAttribute("name") || "").trim();
+            return `${el.tagName.toLowerCase()}${id}|${role}|${name}`;
+        });
+    }
+    catch {
+        return "";
+    }
+}
+// ---------------------------------------------------------------------------
+// Combined settle-state reader (mutation counter + focus in one evaluate)
+// ---------------------------------------------------------------------------
+/**
+ * Reads the mutation counter and optionally the focused element descriptor
+ * in a single `evaluate()` call, saving one round-trip per poll iteration.
+ */
+async function readSettleState(target, checkFocus) {
+    try {
+        return await target.evaluate((wantFocus) => {
+            const w = window;
+            const mutationCount = typeof w.__piMutationCounter === "number" ? w.__piMutationCounter : 0;
+            if (!wantFocus)
+                return { mutationCount, focusDescriptor: "" };
+            const el = document.activeElement;
+            if (!el || el === document.body || el === document.documentElement) {
+                return { mutationCount, focusDescriptor: "" };
+            }
+            const id = el.id ? `#${el.id}` : "";
+            const role = el.getAttribute("role") || "";
+            const name = (el.getAttribute("aria-label") || el.getAttribute("name") || "").trim();
+            return { mutationCount, focusDescriptor: `${el.tagName.toLowerCase()}${id}|${role}|${name}` };
+        }, checkFocus);
+    }
+    catch {
+        return { mutationCount: 0, focusDescriptor: "" };
+    }
+}
+// ---------------------------------------------------------------------------
+// Adaptive settle
+// ---------------------------------------------------------------------------
+/** Threshold (ms) after which zero mutations triggers a shortened quiet window. */
+const ZERO_MUTATION_THRESHOLD_MS = 60;
+/** Shortened quiet window when no mutations have been observed. */
+const ZERO_MUTATION_QUIET_MS = 30;
+export async function settleAfterActionAdaptive(p, opts = {}) {
+    const timeoutMs = Math.max(150, opts.timeoutMs ?? 500);
+    const pollMs = Math.min(100, Math.max(20, opts.pollMs ?? 40));
+    const baseQuietWindowMs = Math.max(60, opts.quietWindowMs ?? 100);
+    const checkFocus = opts.checkFocusStability ?? false;
+    const startedAt = Date.now();
+    let polls = 0;
+    let sawUrlChange = false;
+    let lastActivityAt = startedAt;
+    let previousUrl = p.url();
+    let totalMutationsSeen = 0;
+    let activeQuietWindowMs = baseQuietWindowMs;
+    // Install mutation counter + read initial state in one evaluate sequence.
+    // ensureMutationCounter must run first (installs the observer), then we
+    // read the baseline via the combined reader.
+    await ensureMutationCounter(p).catch((e) => { if (process.env.GSD_DEBUG)
+        console.error("[browser-tools] ensureMutationCounter failed:", e.message); });
+    const initial = await readSettleState(p, checkFocus);
+    let previousMutationCount = initial.mutationCount;
+    let previousFocus = initial.focusDescriptor;
+    while (Date.now() - startedAt < timeoutMs) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        polls += 1;
+        const now = Date.now();
+        const currentUrl = p.url();
+        if (currentUrl !== previousUrl) {
+            sawUrlChange = true;
+            previousUrl = currentUrl;
+            lastActivityAt = now;
+        }
+        // Single combined evaluate for mutation count + focus descriptor.
+        const state = await readSettleState(p, checkFocus);
+        if (state.mutationCount > previousMutationCount) {
+            totalMutationsSeen += state.mutationCount - previousMutationCount;
+            previousMutationCount = state.mutationCount;
+            lastActivityAt = now;
+        }
+        if (checkFocus && state.focusDescriptor !== previousFocus) {
+            previousFocus = state.focusDescriptor;
+            lastActivityAt = now;
+        }
+        const pendingCritical = getPendingCriticalRequests(p);
+        if (pendingCritical > 0) {
+            lastActivityAt = now;
+            continue;
+        }
+        // Zero-mutation short-circuit: after ZERO_MUTATION_THRESHOLD_MS with
+        // no mutations observed at all, reduce the quiet window to settle faster.
+        if (totalMutationsSeen === 0 &&
+            now - startedAt >= ZERO_MUTATION_THRESHOLD_MS &&
+            activeQuietWindowMs !== ZERO_MUTATION_QUIET_MS) {
+            activeQuietWindowMs = ZERO_MUTATION_QUIET_MS;
+        }
+        if (now - lastActivityAt >= activeQuietWindowMs) {
+            const usedShortcut = activeQuietWindowMs === ZERO_MUTATION_QUIET_MS && totalMutationsSeen === 0;
+            return {
+                settleMode: "adaptive",
+                settleMs: now - startedAt,
+                settleReason: usedShortcut
+                    ? "zero_mutation_shortcut"
+                    : sawUrlChange
+                        ? "url_changed_then_quiet"
+                        : "dom_quiet",
+                settlePolls: polls,
+            };
+        }
+    }
+    return {
+        settleMode: "adaptive",
+        settleMs: Date.now() - startedAt,
+        settleReason: "timeout_fallback",
+        settlePolls: polls,
+    };
+}

package/dist/resources/extensions/browser-tools/state.js

@@ -0,0 +1,126 @@
+/**
+ * browser-tools — shared mutable state
+ *
+ * All mutable state lives behind accessor functions (get/set) so that
+ * jiti-transpiled modules see updates reliably.  ES module live bindings
+ * (`export let`) are not guaranteed to work under jiti's CJS shim layer.
+ *
+ * State is initialized to sensible defaults and can be bulk-reset via
+ * `resetAllState()` (called by closeBrowser).
+ */
+import path from "node:path";
+import { createActionTimeline, createBoundedLogPusher, createPageRegistry, } from "./core.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const ARTIFACT_ROOT = path.resolve(process.cwd(), ".artifacts", "browser");
+export const HAR_FILENAME = "session.har";
+// ---------------------------------------------------------------------------
+// Mutable state variables — accessed only via get/set functions
+// ---------------------------------------------------------------------------
+// 1. browser
+let _browser = null;
+export function getBrowser() { return _browser; }
+export function setBrowser(b) { _browser = b; }
+// 2. context
+let _context = null;
+export function getContext() { return _context; }
+export function setContext(c) { _context = c; }
+// 3. pageRegistry (object with internal state — export the instance directly + getter)
+export const pageRegistry = createPageRegistry();
+export function getPageRegistry() { return pageRegistry; }
+// 4. activeFrame
+let _activeFrame = null;
+export function getActiveFrame() { return _activeFrame; }
+export function setActiveFrame(f) { _activeFrame = f; }
+// 5. logPusher (bounded log push function — stateless utility, export directly)
+export const logPusher = createBoundedLogPusher(1000);
+// 6. consoleLogs
+let _consoleLogs = [];
+export function getConsoleLogs() { return _consoleLogs; }
+export function setConsoleLogs(logs) { _consoleLogs = logs; }
+// 7. networkLogs
+let _networkLogs = [];
+export function getNetworkLogs() { return _networkLogs; }
+export function setNetworkLogs(logs) { _networkLogs = logs; }
+// 8. dialogLogs
+let _dialogLogs = [];
+export function getDialogLogs() { return _dialogLogs; }
+export function setDialogLogs(logs) { _dialogLogs = logs; }
+// 9. pendingCriticalRequestsByPage (WeakMap — can't be reassigned, just cleared by replacing)
+let _pendingCriticalRequestsByPage = new WeakMap();
+export function getPendingCriticalRequestsByPage() { return _pendingCriticalRequestsByPage; }
+export function resetPendingCriticalRequestsByPage() { _pendingCriticalRequestsByPage = new WeakMap(); }
+// 10. currentRefMap
+let _currentRefMap = {};
+export function getCurrentRefMap() { return _currentRefMap; }
+export function setCurrentRefMap(m) { _currentRefMap = m; }
+// 11. refVersion
+let _refVersion = 0;
+export function getRefVersion() { return _refVersion; }
+export function setRefVersion(v) { _refVersion = v; }
+// 12. refMetadata
+let _refMetadata = null;
+export function getRefMetadata() { return _refMetadata; }
+export function setRefMetadata(m) { _refMetadata = m; }
+// 13. actionTimeline (object with internal state)
+export const actionTimeline = createActionTimeline(60);
+export function getActionTimeline() { return actionTimeline; }
+// 14. lastActionBeforeState
+let _lastActionBeforeState = null;
+export function getLastActionBeforeState() { return _lastActionBeforeState; }
+export function setLastActionBeforeState(s) { _lastActionBeforeState = s; }
+// 15. lastActionAfterState
+let _lastActionAfterState = null;
+export function getLastActionAfterState() { return _lastActionAfterState; }
+export function setLastActionAfterState(s) { _lastActionAfterState = s; }
+// 16. sessionStartedAt
+let _sessionStartedAt = null;
+export function getSessionStartedAt() { return _sessionStartedAt; }
+export function setSessionStartedAt(t) { _sessionStartedAt = t; }
+// 17. sessionArtifactDir
+let _sessionArtifactDir = null;
+export function getSessionArtifactDir() { return _sessionArtifactDir; }
+export function setSessionArtifactDir(d) { _sessionArtifactDir = d; }
+// 18a. activeTraceSession
+let _activeTraceSession = null;
+export function getActiveTraceSession() { return _activeTraceSession; }
+export function setActiveTraceSession(t) { _activeTraceSession = t; }
+// 18b. harState
+const DEFAULT_HAR_STATE = {
+    enabled: false,
+    configuredAtContextCreation: false,
+    path: null,
+    exportCount: 0,
+    lastExportedPath: null,
+    lastExportedAt: null,
+};
+let _harState = { ...DEFAULT_HAR_STATE };
+export function getHarState() { return _harState; }
+export function setHarState(h) { _harState = h; }
+// ---------------------------------------------------------------------------
+// resetAllState — mirrors closeBrowser()'s reset logic
+// ---------------------------------------------------------------------------
+export function resetAllState() {
+    _browser = null;
+    _context = null;
+    pageRegistry.pages = [];
+    pageRegistry.activePageId = null;
+    pageRegistry.nextId = 1;
+    _activeFrame = null;
+    _consoleLogs = [];
+    _networkLogs = [];
+    _dialogLogs = [];
+    _pendingCriticalRequestsByPage = new WeakMap();
+    _currentRefMap = {};
+    _refVersion = 0;
+    _refMetadata = null;
+    _lastActionBeforeState = null;
+    _lastActionAfterState = null;
+    actionTimeline.entries = [];
+    actionTimeline.nextId = 1;
+    _sessionStartedAt = null;
+    _sessionArtifactDir = null;
+    _activeTraceSession = null;
+    _harState = { ...DEFAULT_HAR_STATE };
+}

package/dist/resources/extensions/browser-tools/tools/action-cache.js

@@ -0,0 +1,179 @@
+import { Type } from "@sinclair/typebox";
+const cache = new Map();
+const MAX_CACHE_SIZE = 200;
+export function registerActionCacheTools(pi, deps) {
+    // -------------------------------------------------------------------------
+    // browser_action_cache
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "browser_action_cache",
+        label: "Browser Action Cache",
+        description: "Manage the action cache that maps page structure + intent → resolved selectors. " +
+            "Cache reduces token cost on repeat visits to same pages. " +
+            "Actions: 'stats' (show cache metrics), 'get' (lookup cached selector), " +
+            "'put' (store a selector mapping), 'clear' (flush cache).",
+        parameters: Type.Object({
+            action: Type.String({
+                description: "Cache action: 'stats', 'get', 'put', or 'clear'.",
+            }),
+            intent: Type.Optional(Type.String({ description: "Semantic intent key (for get/put). E.g., 'submit_form', 'close_dialog'." })),
+            selector: Type.Optional(Type.String({ description: "CSS selector to cache (for put)." })),
+            score: Type.Optional(Type.Number({ description: "Confidence score 0–1 for the cached selector (for put)." })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            try {
+                const { page: p } = await deps.ensureBrowser();
+                const url = p.url();
+                switch (params.action) {
+                    case "stats": {
+                        const entries = [...cache.values()];
+                        const totalHits = entries.reduce((sum, e) => sum + e.hitCount, 0);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Action cache: ${cache.size} entries, ${totalHits} total hits\nMax size: ${MAX_CACHE_SIZE}`,
+                                }],
+                            details: {
+                                size: cache.size,
+                                maxSize: MAX_CACHE_SIZE,
+                                totalHits,
+                                entries: entries.map((e) => ({
+                                    url: e.url,
+                                    selector: e.selector,
+                                    hitCount: e.hitCount,
+                                    score: e.score,
+                                })),
+                            },
+                        };
+                    }
+                    case "get": {
+                        if (!params.intent) {
+                            return {
+                                content: [{ type: "text", text: "Intent parameter required for 'get' action." }],
+                                details: { error: "missing_intent" },
+                                isError: true,
+                            };
+                        }
+                        const domHash = await computeDomHash(p);
+                        const key = buildCacheKey(url, domHash, params.intent);
+                        const entry = cache.get(key);
+                        if (!entry) {
+                            return {
+                                content: [{ type: "text", text: `Cache miss for intent "${params.intent}" on ${url}` }],
+                                details: { hit: false, intent: params.intent, url },
+                            };
+                        }
+                        // Validate the cached selector still exists
+                        const exists = await p.locator(entry.selector).first().isVisible().catch(() => false);
+                        if (!exists) {
+                            cache.delete(key);
+                            return {
+                                content: [{ type: "text", text: `Cache entry stale (selector no longer visible): ${entry.selector}` }],
+                                details: { hit: false, stale: true, selector: entry.selector },
+                            };
+                        }
+                        entry.hitCount++;
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Cache hit: "${params.intent}" → ${entry.selector} (score: ${entry.score}, hits: ${entry.hitCount})`,
+                                }],
+                            details: { hit: true, ...entry },
+                        };
+                    }
+                    case "put": {
+                        if (!params.intent || !params.selector) {
+                            return {
+                                content: [{ type: "text", text: "Intent and selector parameters required for 'put' action." }],
+                                details: { error: "missing_params" },
+                                isError: true,
+                            };
+                        }
+                        const domHash = await computeDomHash(p);
+                        const key = buildCacheKey(url, domHash, params.intent);
+                        // Evict oldest entries if at capacity
+                        if (cache.size >= MAX_CACHE_SIZE && !cache.has(key)) {
+                            const oldestKey = [...cache.entries()]
+                                .sort(([, a], [, b]) => a.timestamp - b.timestamp)[0]?.[0];
+                            if (oldestKey)
+                                cache.delete(oldestKey);
+                        }
+                        const entry = {
+                            selector: params.selector,
+                            score: params.score ?? 1.0,
+                            url,
+                            domHash,
+                            timestamp: Date.now(),
+                            hitCount: 0,
+                        };
+                        cache.set(key, entry);
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Cached: "${params.intent}" → ${params.selector} (cache size: ${cache.size})`,
+                                }],
+                            details: { stored: true, key, ...entry, cacheSize: cache.size },
+                        };
+                    }
+                    case "clear": {
+                        const size = cache.size;
+                        cache.clear();
+                        return {
+                            content: [{ type: "text", text: `Action cache cleared (${size} entries removed).` }],
+                            details: { cleared: size },
+                        };
+                    }
+                    default:
+                        return {
+                            content: [{ type: "text", text: `Unknown action: ${params.action}. Use 'stats', 'get', 'put', or 'clear'.` }],
+                            details: { error: "unknown_action" },
+                            isError: true,
+                        };
+                }
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `Action cache error: ${err.message}` }],
+                    details: { error: err.message },
+                    isError: true,
+                };
+            }
+        },
+    });
+}
+function buildCacheKey(url, domHash, intent) {
+    // Normalize URL — strip hash and query params for broader matching
+    let normalized;
+    try {
+        const u = new URL(url);
+        normalized = `${u.origin}${u.pathname}`;
+    }
+    catch {
+        normalized = url;
+    }
+    return `${normalized}|${domHash}|${intent}`;
+}
+async function computeDomHash(page) {
+    try {
+        return await page.evaluate(() => {
+            // Structural hash based on element count + tag distribution
+            const tags = new Map();
+            const all = document.querySelectorAll("*");
+            for (const el of all) {
+                const tag = el.tagName;
+                tags.set(tag, (tags.get(tag) ?? 0) + 1);
+            }
+            const entries = [...tags.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+            const str = entries.map(([t, c]) => `${t}:${c}`).join("|");
+            // Simple hash
+            let h = 5381;
+            for (let i = 0; i < str.length; i++) {
+                h = ((h << 5) - h + str.charCodeAt(i)) | 0;
+            }
+            return (h >>> 0).toString(16);
+        });
+    }
+    catch {
+        return "unknown";
+    }
+}