agent-web-interface 4.3.0 → 4.5.0

package/dist/src/state/value-masking.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Value Masking
+ *
+ * Masks sensitive field values (passwords, tokens, SSNs) for safe display.
+ *
+ * @module state/value-masking
+ */
+/**
+ * Sensitive field name patterns (case-insensitive).
+ * Values in these fields will be masked.
+ */
+export declare const SENSITIVE_FIELD_PATTERNS: string[];
+/**
+ * Input types that should always be masked.
+ */
+export declare const MASKED_INPUT_TYPES: string[];
+/**
+ * Input types with partial masking (show first/last chars).
+ */
+export declare const PARTIAL_MASK_TYPES: string[];
+/**
+ * Mask sensitive values in val_hint.
+ *
+ * Rules:
+ * - password type: always full mask
+ * - sensitive field names: always full mask
+ * - email/tel: partial mask (show first/last chars)
+ * - default: truncate to 12 chars, mask middle
+ */
+export declare function maskValue(value: string, inputType?: string, label?: string): string;
+/**
+ * Partial mask: show first 2 and last 2 chars.
+ * Example: "example@email.com" -> "ex•••om"
+ */
+export declare function partialMask(value: string): string;
+//# sourceMappingURL=value-masking.d.ts.map

package/dist/src/state/value-masking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-masking.d.ts","sourceRoot":"","sources":["../../../src/state/value-masking.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB,UAkBpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,UAAe,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,kBAAkB,UAA4B,CAAC;AAE5D;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CA8BnF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD"}

package/dist/src/state/value-masking.js

@@ -0,0 +1,86 @@
+/**
+ * Value Masking
+ *
+ * Masks sensitive field values (passwords, tokens, SSNs) for safe display.
+ *
+ * @module state/value-masking
+ */
+/**
+ * Sensitive field name patterns (case-insensitive).
+ * Values in these fields will be masked.
+ */
+export const SENSITIVE_FIELD_PATTERNS = [
+    'password',
+    'passwd',
+    'pass',
+    'secret',
+    'token',
+    'auth',
+    'key',
+    'api_key',
+    'apikey',
+    'otp',
+    'pin',
+    'cvv',
+    'cvc',
+    'ssn',
+    'social',
+    'credit',
+    'card',
+];
+/**
+ * Input types that should always be masked.
+ */
+export const MASKED_INPUT_TYPES = ['password'];
+/**
+ * Input types with partial masking (show first/last chars).
+ */
+export const PARTIAL_MASK_TYPES = ['email', 'tel', 'phone'];
+/**
+ * Mask sensitive values in val_hint.
+ *
+ * Rules:
+ * - password type: always full mask
+ * - sensitive field names: always full mask
+ * - email/tel: partial mask (show first/last chars)
+ * - default: truncate to 12 chars, mask middle
+ */
+export function maskValue(value, inputType, label) {
+    // Strip newlines first
+    const cleanValue = value.replace(/[\r\n]/g, ' ').trim();
+    if (!cleanValue)
+        return '';
+    // Password type: always full mask
+    if (inputType && MASKED_INPUT_TYPES.includes(inputType.toLowerCase())) {
+        return '••••••••';
+    }
+    // Check sensitive field names
+    const lowerLabel = (label ?? '').toLowerCase();
+    for (const pattern of SENSITIVE_FIELD_PATTERNS) {
+        if (lowerLabel.includes(pattern)) {
+            return '***';
+        }
+    }
+    // Email/tel: partial mask
+    if (inputType && PARTIAL_MASK_TYPES.includes(inputType.toLowerCase())) {
+        return partialMask(cleanValue);
+    }
+    // Default: truncate and partial mask if long
+    if (cleanValue.length <= 12) {
+        return cleanValue;
+    }
+    return partialMask(cleanValue.substring(0, 12));
+}
+/**
+ * Partial mask: show first 2 and last 2 chars.
+ * Example: "example@email.com" -> "ex•••om"
+ */
+export function partialMask(value) {
+    if (value.length <= 4) {
+        return '••••';
+    }
+    const first = value.substring(0, 2);
+    const last = value.substring(value.length - 2);
+    return `${first}•••${last}`;
+}
+//# sourceMappingURL=value-masking.js.map

package/dist/src/state/value-masking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-masking.js","sourceRoot":"","sources":["../../../src/state/value-masking.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,UAAU;IACV,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,KAAK;IACL,SAAS;IACT,QAAQ;IACR,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,MAAM;CACP,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,UAAU,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,SAAkB,EAAE,KAAc;IACzE,uBAAuB;IACvB,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAExD,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,CAAC;IAE3B,kCAAkC;IAClC,IAAI,SAAS,IAAI,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACtE,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,8BAA8B;IAC9B,MAAM,UAAU,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/C,KAAK,MAAM,OAAO,IAAI,wBAAwB,EAAE,CAAC;QAC/C,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACjC,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,IAAI,SAAS,IAAI,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACtE,OAAO,WAAW,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED,6CAA6C;IAC7C,IAAI,UAAU,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,OAAO,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/C,OAAO,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;AAC9B,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * Action Context
+ *
+ * Shared action context helpers used by all tool handler modules.
+ * Provides snapshot capture with CDP recovery, action context preparation,
+ * runtime health building, and tool initialization.
+ */
+import type { PageHandle } from '../browser/page-registry.js';
+import type { BaseSnapshot } from '../snapshot/snapshot.types.js';
+import type { RuntimeHealth } from '../state/health.types.js';
+import { type CaptureWithStabilizationResult } from '../snapshot/snapshot-health.js';
+import type { CaptureSnapshotFn } from './execute-action.js';
+import type { ToolContext } from './tool-context.types.js';
+/**
+ * Build runtime health details from a capture attempt.
+ */
+export declare function buildRuntimeHealth(cdpHealth: RuntimeHealth['cdp'], result: CaptureWithStabilizationResult): RuntimeHealth;
+/**
+ * Capture a snapshot with stabilization and CDP recovery when empty.
+ */
+export declare function captureSnapshotWithRecovery(ctx: ToolContext, handle: PageHandle, pageId: string): Promise<{
+    snapshot: BaseSnapshot;
+    handle: PageHandle;
+    runtime_health: RuntimeHealth;
+}>;
+/**
+ * Create a capture function that keeps the handle updated after recovery.
+ */
+export declare function createActionCapture(ctx: ToolContext, handleRef: {
+    current: PageHandle;
+}, pageId: string): CaptureSnapshotFn;
+/**
+ * Context for action execution.
+ */
+export interface ActionContext {
+    /** Mutable reference to page handle (updated on recovery) */
+    handleRef: {
+        current: PageHandle;
+    };
+    /** Resolved page ID */
+    pageId: string;
+    /** Snapshot capture function */
+    captureSnapshot: CaptureSnapshotFn;
+    /** Tool context instance */
+    ctx: ToolContext;
+}
+/**
+ * Prepare context for action execution.
+ * Resolves page, ensures CDP session health, and creates capture function.
+ *
+ * @param pageId - Optional page ID to resolve
+ * @returns Action context with handle, capture function, and session
+ */
+export declare function prepareActionContext(pageId: string | undefined, ctx: ToolContext): Promise<ActionContext>;
+//# sourceMappingURL=action-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action-context.d.ts","sourceRoot":"","sources":["../../../src/tools/action-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,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;AAC9D,OAAO,EAGL,KAAK,8BAA8B,EACpC,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,MAAM,EAAE,8BAA8B,GACrC,aAAa,CAYf;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,cAAc,EAAE,aAAa,CAAA;CAAE,CAAC,CAoBxF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,WAAW,EAChB,SAAS,EAAE;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,EAClC,MAAM,EAAE,MAAM,GACb,iBAAiB,CASnB;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,SAAS,EAAE;QAAE,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;IACnC,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,eAAe,EAAE,iBAAiB,CAAC;IACnC,4BAA4B;IAC5B,GAAG,EAAE,WAAW,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,aAAa,CAAC,CASxB"}

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

@@ -0,0 +1,69 @@
+/**
+ * Action Context
+ *
+ * Shared action context helpers used by all tool handler modules.
+ * Provides snapshot capture with CDP recovery, action context preparation,
+ * runtime health building, and tool initialization.
+ */
+import { captureWithStabilization, determineHealthCode, } from '../snapshot/snapshot-health.js';
+/**
+ * Build runtime health details from a capture attempt.
+ */
+export function buildRuntimeHealth(cdpHealth, result) {
+    const code = determineHealthCode(result);
+    return {
+        cdp: cdpHealth,
+        snapshot: {
+            ok: code === 'HEALTHY',
+            code,
+            attempts: result.attempts,
+            message: result.health.message,
+        },
+    };
+}
+/**
+ * Capture a snapshot with stabilization and CDP recovery when empty.
+ */
+export async function captureSnapshotWithRecovery(ctx, handle, pageId) {
+    const ensureResult = await ctx.ensureCdpSession(handle);
+    handle = ensureResult.handle;
+    let result = await captureWithStabilization(handle.cdp, handle.page, pageId);
+    let runtime_health = buildRuntimeHealth(ensureResult.runtime_health.cdp, result);
+    if (!result.health.valid) {
+        const healthCode = determineHealthCode(result);
+        console.warn(`[RECOVERY] Empty snapshot for ${pageId} (${healthCode}); rebinding CDP session`);
+        handle = await ctx.getSessionManager().rebindCdpSession(pageId);
+        result = await captureWithStabilization(handle.cdp, handle.page, pageId, { maxRetries: 1 });
+        runtime_health = buildRuntimeHealth({ ok: true, recovered: true, recovery_method: 'rebind' }, result);
+    }
+    return { snapshot: result.snapshot, handle, runtime_health };
+}
+/**
+ * Create a capture function that keeps the handle updated after recovery.
+ */
+export function createActionCapture(ctx, handleRef, pageId) {
+    return async () => {
+        const captureResult = await captureSnapshotWithRecovery(ctx, handleRef.current, pageId);
+        handleRef.current = captureResult.handle;
+        return {
+            snapshot: captureResult.snapshot,
+            runtime_health: captureResult.runtime_health,
+        };
+    };
+}
+/**
+ * Prepare context for action execution.
+ * Resolves page, ensures CDP session health, and creates capture function.
+ *
+ * @param pageId - Optional page ID to resolve
+ * @returns Action context with handle, capture function, and session
+ */
+export async function prepareActionContext(pageId, ctx) {
+    const handleRef = { current: ctx.resolveExistingPage(pageId) };
+    const resolvedPageId = handleRef.current.page_id;
+    handleRef.current = (await ctx.ensureCdpSession(handleRef.current)).handle;
+    await handleRef.current.page.bringToFront();
+    const captureSnapshot = createActionCapture(ctx, handleRef, resolvedPageId);
+    return { handleRef, pageId: resolvedPageId, captureSnapshot, ctx };
+}
+//# sourceMappingURL=action-context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"action-context.js","sourceRoot":"","sources":["../../../src/tools/action-context.ts"],"names":[],"mappings":"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"}

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,CAiD9B;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,93 @@
+/**
+ * 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);
+        // Step 3: After network settled, briefly wait for any DOM renders triggered by API responses.
+        // Only needed when DOM was already stable and network actually reached idle
+        // (meaning data arrived that could trigger React/framework re-renders).
+        if (result.status === 'stable' && networkIdle) {
+            await stabilizeDom(page, { maxTimeoutMs: 500 });
+        }
+        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,8FAA8F;QAC9F,4EAA4E;QAC5E,wEAAwE;QACxE,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,WAAW,EAAE,CAAC;YAC9C,MAAM,YAAY,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,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,171 +1,13 @@
 /**
  * Browser Tools
  *
- * MCP tool handlers for browser automation.
- */
-import type { SessionManager } from '../browser/session-manager.js';
-import type { NodeKind } from '../snapshot/snapshot.types.js';
-export { getSnapshotStore } from './tool-context.js';
-/**
- * Initialize tools with a session manager instance.
- * Must be called before using any tool handlers.
- */
-export declare function initializeTools(manager: SessionManager): void;
-/**
- * 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>;
-/**
- * Map schema kind values to internal NodeKind values.
- *
- * The find_elements schema uses user-friendly names that don't always match
- * internal NodeKind values. For example, 'textbox' in the schema maps to
- * both 'input' and 'textarea' internally.
- *
- * @param schemaKind - Kind value from the find_elements schema
- * @returns Matching NodeKind value(s)
- */
-export declare function mapSchemaKindToNodeKind(schemaKind: string): NodeKind | NodeKind[];
-/**
- * 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 or at viewport coordinates.
- *
- * Three modes:
- * 1. eid only → click element center (existing behavior)
- * 2. eid + x/y → click at offset relative to element top-left
- * 3. x/y only → click at absolute viewport coordinates
- *
- * @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>;
-/**
- * Drag from one point to another.
- *
- * If eid is provided, coordinates are relative to the element's top-left corner.
- * Otherwise, coordinates are absolute viewport coordinates.
- *
- * @param rawInput - Drag options (will be validated)
- * @returns Drag result with updated snapshot
- */
-export declare function drag(rawInput: unknown): Promise<import('./tool-schemas.js').DragOutput>;
-/**
- * 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 { type ActionContext, prepareActionContext, captureSnapshotWithRecovery, createActionCapture, buildRuntimeHealth, } from './action-context.js';
+export { listPages, closePage, 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';
+export { readPage } from './readability-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,KAAK,aAAa,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGlG,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;AAGlE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC"}