agent-web-interface 4.2.0 → 4.4.0

package/dist/src/tools/action-stabilization.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Action Stabilization
+ *
+ * Stabilizes the page after actions using tiered waiting (DOM + network).
+ *
+ * @module tools/action-stabilization
+ */
+import type { Page } from 'puppeteer-core';
+import { type StabilizationResult } from '../delta/dom-stabilizer.js';
+import type { PageHandle } from '../browser/page-registry.js';
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { RuntimeHealth } from '../state/health.types.js';
+/**
+ * Stabilize page after an action using tiered waiting strategy.
+ *
+ * This addresses the core issue: actions may trigger API calls that complete
+ * after DOM mutations settle. The tiered approach:
+ *
+ * 1. Wait for DOM to stabilize (MutationObserver) - catches SPA rendering
+ * 2. Wait for network to quiet down (networkidle) - catches pending API calls
+ * 3. If DOM stabilization fails (navigation), fall back to network idle wait
+ *
+ * Timeouts are generous but never throw - we proceed even if network stays busy
+ * (common with analytics, long-polling, websockets).
+ *
+ * @param page - Puppeteer Page instance
+ * @param networkTimeoutMs - Optional custom timeout for network idle (default: 3000ms)
+ * @returns Stabilization result with status
+ */
+export declare function stabilizeAfterAction(page: Page, networkTimeoutMs?: number): Promise<StabilizationResult>;
+/**
+ * Stabilize page after explicit navigation (goto, back, forward, reload).
+ *
+ * Uses a longer network timeout since navigations typically trigger more
+ * requests than in-page actions.
+ *
+ * @param page - Puppeteer Page instance
+ * @returns Stabilization result with status
+ */
+export declare function stabilizeAfterNavigation(page: Page): Promise<StabilizationResult>;
+/**
+ * Capture snapshot without recovery (fallback path).
+ */
+export declare function captureSnapshotFallback(handle: PageHandle): Promise<{
+    snapshot: BaseSnapshot;
+    runtime_health: RuntimeHealth;
+}>;
+//# sourceMappingURL=action-stabilization.d.ts.map

package/dist/src/tools/action-stabilization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-stabilization.d.ts","sourceRoot":"","sources":["../../../src/tools/action-stabilization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAS9D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,gBAAgB,GAAE,MAAuC,GACxD,OAAO,CAAC,mBAAmB,CAAC,CA0C9B;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAEvF;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,cAAc,EAAE,aAAa,CAAA;CAAE,CAAC,CAGpE"}

package/dist/src/tools/action-stabilization.js

@@ -0,0 +1,87 @@
+/**
+ * Action Stabilization
+ *
+ * Stabilizes the page after actions using tiered waiting (DOM + network).
+ *
+ * @module tools/action-stabilization
+ */
+import { stabilizeDom } from '../delta/dom-stabilizer.js';
+import { createHealthyRuntime } from '../state/health.types.js';
+import { compileSnapshot } from '../snapshot/index.js';
+import { waitForNetworkQuiet, ACTION_NETWORK_IDLE_TIMEOUT_MS, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS, } from '../browser/page-stabilization.js';
+/**
+ * Stabilize page after an action using tiered waiting strategy.
+ *
+ * This addresses the core issue: actions may trigger API calls that complete
+ * after DOM mutations settle. The tiered approach:
+ *
+ * 1. Wait for DOM to stabilize (MutationObserver) - catches SPA rendering
+ * 2. Wait for network to quiet down (networkidle) - catches pending API calls
+ * 3. If DOM stabilization fails (navigation), fall back to network idle wait
+ *
+ * Timeouts are generous but never throw - we proceed even if network stays busy
+ * (common with analytics, long-polling, websockets).
+ *
+ * @param page - Puppeteer Page instance
+ * @param networkTimeoutMs - Optional custom timeout for network idle (default: 3000ms)
+ * @returns Stabilization result with status
+ */
+export async function stabilizeAfterAction(page, networkTimeoutMs = ACTION_NETWORK_IDLE_TIMEOUT_MS) {
+    // Step 1: Try MutationObserver-based DOM stabilization first
+    const result = await stabilizeDom(page);
+    // Step 2: Handle based on DOM stabilization result
+    if (result.status === 'stable' || result.status === 'timeout') {
+        // DOM settled (or timed out) - now wait for network to quiet down
+        // This catches API calls that haven't rendered to DOM yet
+        const networkIdle = await waitForNetworkQuiet(page, networkTimeoutMs);
+        if (!networkIdle && result.status === 'stable') {
+            // DOM was stable but network didn't idle - add a note
+            return {
+                ...result,
+                warning: result.warning ?? 'Network did not reach idle state within timeout',
+            };
+        }
+        return result;
+    }
+    // status === 'error' means page.evaluate() failed, likely due to navigation
+    // Fall back to waiting for network idle on the new page
+    try {
+        // Wait for network to settle on the new page
+        await waitForNetworkQuiet(page, networkTimeoutMs);
+        return {
+            status: 'stable',
+            waitTimeMs: result.waitTimeMs,
+            warning: 'Navigation detected; waited for networkidle',
+        };
+    }
+    catch (waitError) {
+        // If network wait also fails, the page might be in an unusual state
+        // Return the original error but with additional context
+        const message = waitError instanceof Error ? waitError.message : String(waitError);
+        return {
+            status: 'error',
+            waitTimeMs: result.waitTimeMs,
+            warning: `${result.warning}. Fallback network wait also failed: ${message}`,
+        };
+    }
+}
+/**
+ * Stabilize page after explicit navigation (goto, back, forward, reload).
+ *
+ * Uses a longer network timeout since navigations typically trigger more
+ * requests than in-page actions.
+ *
+ * @param page - Puppeteer Page instance
+ * @returns Stabilization result with status
+ */
+export async function stabilizeAfterNavigation(page) {
+    return stabilizeAfterAction(page, NAVIGATION_NETWORK_IDLE_TIMEOUT_MS);
+}
+/**
+ * Capture snapshot without recovery (fallback path).
+ */
+export async function captureSnapshotFallback(handle) {
+    const snapshot = await compileSnapshot(handle.cdp, handle.page, handle.page_id);
+    return { snapshot, runtime_health: createHealthyRuntime() };
+}
+//# sourceMappingURL=action-stabilization.js.map

package/dist/src/tools/action-stabilization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-stabilization.js","sourceRoot":"","sources":["../../../src/tools/action-stabilization.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,YAAY,EAA4B,MAAM,4BAA4B,CAAC;AAIpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAU,EACV,mBAA2B,8BAA8B;IAEzD,6DAA6D;IAC7D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAExC,mDAAmD;IACnD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9D,kEAAkE;QAClE,0DAA0D;QAC1D,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAEtE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/C,sDAAsD;YACtD,OAAO;gBACL,GAAG,MAAM;gBACT,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,iDAAiD;aAC7E,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,4EAA4E;IAC5E,wDAAwD;IACxD,IAAI,CAAC;QACH,6CAA6C;QAC7C,MAAM,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAElD,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,6CAA6C;SACvD,CAAC;IACJ,CAAC;IAAC,OAAO,SAAS,EAAE,CAAC;QACnB,oEAAoE;QACpE,wDAAwD;QACxD,MAAM,OAAO,GAAG,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnF,OAAO;YACL,MAAM,EAAE,OAAO;YACf,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,wCAAwC,OAAO,EAAE;SAC5E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAU;IACvD,OAAO,oBAAoB,CAAC,IAAI,EAAE,kCAAkC,CAAC,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAkB;IAElB,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAChF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,oBAAoB,EAAE,EAAE,CAAC;AAC9D,CAAC"}

package/dist/src/tools/browser-tools.d.ts

@@ -1,150 +1,12 @@
 /**
  * Browser Tools
  *
- * MCP tool handlers for browser automation.
- */
-import type { SessionManager } from '../browser/session-manager.js';
-import { SnapshotStore } from '../snapshot/index.js';
-/**
- * Initialize tools with a session manager instance.
- * Must be called before using any tool handlers.
- *
- * @param manager - SessionManager instance
- */
-export declare function initializeTools(manager: SessionManager): void;
-/**
- * Get the snapshot store.
- */
-export declare function getSnapshotStore(): SnapshotStore;
-/**
- * List all open browser pages with their metadata.
- *
- * Syncs with browser context to ensure all tabs are registered,
- * including tabs opened externally or after reconnection.
- *
- * @returns XML result with page list
- */
-export declare function listPages(): Promise<import('./tool-schemas.js').ListPagesOutput>;
-/**
- * Close a specific page.
- *
- * @param rawInput - Close options (will be validated)
- * @returns Close result
- */
-export declare function closePage(rawInput: unknown): Promise<import('./tool-schemas.js').ClosePageOutput>;
-/**
- * Close the entire browser session.
- *
- * @param rawInput - Close options (will be validated)
- * @returns Close result
- */
-export declare function closeSession(rawInput: unknown): Promise<import('./tool-schemas.js').CloseSessionOutput>;
-/**
- * Navigate to a URL.
- *
- * @param rawInput - Navigation options (will be validated)
- * @returns Navigation result with snapshot data
- */
-export declare function navigate(rawInput: unknown): Promise<import('./tool-schemas.js').NavigateOutput>;
-/**
- * Go back in browser history.
- *
- * @param rawInput - Navigation options (will be validated)
- * @returns Navigation result with snapshot data
- */
-export declare function goBack(rawInput: unknown): Promise<import('./tool-schemas.js').GoBackOutput>;
-/**
- * Go forward in browser history.
- *
- * @param rawInput - Navigation options (will be validated)
- * @returns Navigation result with snapshot data
- */
-export declare function goForward(rawInput: unknown): Promise<import('./tool-schemas.js').GoForwardOutput>;
-/**
- * Reload the current page.
- *
- * @param rawInput - Navigation options (will be validated)
- * @returns Navigation result with snapshot data
- */
-export declare function reload(rawInput: unknown): Promise<import('./tool-schemas.js').ReloadOutput>;
-/**
- * Capture a fresh snapshot of the current page.
- *
- * @param rawInput - Capture options (will be validated)
- * @returns Snapshot data for the current page
- */
-export declare function captureSnapshot(rawInput: unknown): Promise<import('./tool-schemas.js').CaptureSnapshotOutput>;
-/**
- * Find elements by semantic criteria.
- *
- * @param rawInput - Query filters (will be validated)
- * @returns Matched nodes
- */
-export declare function findElements(rawInput: unknown): import('./tool-schemas.js').FindElementsOutput;
-/**
- * Get full details for a specific node.
- *
- * @param rawInput - Node details request (will be validated)
- * @returns Full node details
- */
-export declare function getNodeDetails(rawInput: unknown): import('./tool-schemas.js').GetNodeDetailsOutput;
-/**
- * Scroll an element into view.
- *
- * @param rawInput - Scroll options (will be validated)
- * @returns Scroll result with delta
- */
-export declare function scrollElementIntoView(rawInput: unknown): Promise<import('./tool-schemas.js').ScrollElementIntoViewOutput>;
-/**
- * Scroll the page up or down.
- *
- * @param rawInput - Scroll options (will be validated)
- * @returns Scroll result with delta
- */
-export declare function scrollPage(rawInput: unknown): Promise<import('./tool-schemas.js').ScrollPageOutput>;
-/**
- * Click an element.
- *
- * @param rawInput - Click options (will be validated)
- * @returns Click result with navigation-aware outcome
- */
-export declare function click(rawInput: unknown): Promise<import('./tool-schemas.js').ClickOutput>;
-/**
- * Type text into an element.
- *
- * @param rawInput - Type options (will be validated)
- * @returns Type result with delta
- */
-export declare function type(rawInput: unknown): Promise<import('./tool-schemas.js').TypeOutput>;
-/**
- * Press a keyboard key (no agent_version).
- *
- * @param rawInput - Press options (will be validated)
- * @returns Press result with delta
- */
-export declare function press(rawInput: unknown): Promise<import('./tool-schemas.js').PressOutput>;
-/**
- * Select a dropdown option.
- *
- * @param rawInput - Select options (will be validated)
- * @returns Select result with delta
- */
-export declare function select(rawInput: unknown): Promise<import('./tool-schemas.js').SelectOutput>;
-/**
- * Hover over an element.
- *
- * @param rawInput - Hover options (will be validated)
- * @returns Hover result with delta
- */
-export declare function hover(rawInput: unknown): Promise<import('./tool-schemas.js').HoverOutput>;
-/**
- * Take a screenshot of the page or a specific element.
- *
- * Observation tool - does not mutate page state.
- * Returns inline image (<2MB) or temp file path (>=2MB).
- *
- * @param rawInput - Screenshot options (will be validated)
- * @returns ImageResult or FileResult
- */
-export declare function takeScreenshot(rawInput: unknown): Promise<import('./tool-schemas.js').TakeScreenshotOutput>;
+ * Re-export barrel for all browser automation tool handlers.
+ * The actual implementations live in category-specific modules.
+ */
+export { initializeTools, type ActionContext, prepareActionContext, captureSnapshotWithRecovery, createActionCapture, buildRuntimeHealth, } from './action-context.js';
+export { listPages, closePage, closeSession, navigate, goBack, goForward, reload, } from './navigation-tools.js';
+export { captureSnapshot, findElements, getNodeDetails, scrollElementIntoView, scrollPage, mapSchemaKindToNodeKind, } from './observation-tools.js';
+export { click, type, press, select, hover } from './interaction-tools.js';
+export { drag, wheel, takeScreenshot } from './viewport-tools.js';
 //# sourceMappingURL=browser-tools.d.ts.map

package/dist/src/tools/browser-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/browser-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/browser-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,MAAM,EACN,SAAS,EACT,MAAM,GACP,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,UAAU,EACV,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAG3E,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}