btcp-browser-agent 0.1.7 → 0.1.9

package/packages/core/dist/assertions.js

@@ -0,0 +1,230 @@
+/**
+ * @btcp/core - Assertions Module
+ *
+ * Provides verification utilities for DOM actions with async waiting support.
+ * Returns structured results for consistent error handling.
+ */
+// ============================================================================
+// CORE ASSERTIONS
+// ============================================================================
+/**
+ * Assert that an element is still connected to the DOM
+ */
+export function assertConnected(element) {
+    const connected = element.isConnected;
+    return {
+        success: connected,
+        error: connected ? null : 'Element is not connected to DOM',
+        description: 'Element should be connected to DOM',
+        expected: true,
+        actual: connected,
+        context: {
+            tagName: element.tagName,
+        },
+    };
+}
+/**
+ * Assert that an input/textarea value contains the expected text
+ */
+export function assertValueContains(element, text) {
+    const value = element.value;
+    const contains = value.includes(text);
+    return {
+        success: contains,
+        error: contains ? null : `Value "${value}" does not contain "${text}"`,
+        description: 'Value should contain expected text',
+        expected: text,
+        actual: value,
+        context: {
+            tagName: element.tagName,
+            inputType: element instanceof HTMLInputElement ? element.type : 'textarea',
+        },
+    };
+}
+/**
+ * Assert that an input/textarea value equals the expected value exactly
+ */
+export function assertValueEquals(element, value) {
+    const actualValue = element.value;
+    const equals = actualValue === value;
+    return {
+        success: equals,
+        error: equals ? null : `Value "${actualValue}" does not equal "${value}"`,
+        description: 'Value should equal expected value',
+        expected: value,
+        actual: actualValue,
+        context: {
+            tagName: element.tagName,
+            inputType: element instanceof HTMLInputElement ? element.type : 'textarea',
+        },
+    };
+}
+/**
+ * Assert that a checkbox/radio is in the expected checked state
+ */
+export function assertChecked(element, expected) {
+    const checked = element.checked;
+    const matches = checked === expected;
+    return {
+        success: matches,
+        error: matches ? null : `Element is ${checked ? 'checked' : 'unchecked'}, expected ${expected ? 'checked' : 'unchecked'}`,
+        description: expected ? 'Element should be checked' : 'Element should be unchecked',
+        expected,
+        actual: checked,
+        context: {
+            tagName: element.tagName,
+            inputType: element.type,
+        },
+    };
+}
+/**
+ * Assert that a select element has the expected values selected
+ */
+export function assertSelected(element, values) {
+    const selectedValues = Array.from(element.selectedOptions).map(opt => opt.value);
+    const missingValues = values.filter(v => !selectedValues.includes(v));
+    const success = missingValues.length === 0;
+    return {
+        success,
+        error: success ? null : `Options not selected: ${missingValues.join(', ')}`,
+        description: 'Select should have expected options selected',
+        expected: values,
+        actual: selectedValues,
+        context: {
+            tagName: element.tagName,
+            multiple: element.multiple,
+            missingValues: missingValues.length > 0 ? missingValues : undefined,
+        },
+    };
+}
+/**
+ * Assert that a URL matches the expected origin
+ */
+export function assertUrlOrigin(actualUrl, expectedUrl) {
+    try {
+        const actual = new URL(actualUrl);
+        const expected = new URL(expectedUrl);
+        const success = actual.origin === expected.origin;
+        return {
+            success,
+            error: success ? null : `Origin mismatch: expected ${expected.origin}, got ${actual.origin}`,
+            description: 'URL origin should match expected',
+            expected: expected.origin,
+            actual: actual.origin,
+            context: {
+                actualUrl,
+                expectedUrl,
+            },
+        };
+    }
+    catch (error) {
+        // URL parsing failed
+        return {
+            success: false,
+            error: `URL parsing failed: ${error instanceof Error ? error.message : String(error)}`,
+            description: 'URL origin should match expected',
+            expected: expectedUrl,
+            actual: actualUrl,
+            context: {
+                error: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+/**
+ * Assert that an element is visible (or hidden)
+ */
+export function assertVisible(element, win, expected = true) {
+    const style = win.getComputedStyle(element);
+    const visible = style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        style.opacity !== '0';
+    const success = visible === expected;
+    return {
+        success,
+        error: success ? null : `Element is ${visible ? 'visible' : 'hidden'}, expected ${expected ? 'visible' : 'hidden'}`,
+        description: expected ? 'Element should be visible' : 'Element should be hidden',
+        expected,
+        actual: visible,
+        context: {
+            tagName: element.tagName,
+            display: style.display,
+            visibility: style.visibility,
+            opacity: style.opacity,
+        },
+    };
+}
+/**
+ * Assert that an element is enabled (or disabled)
+ */
+export function assertEnabled(element, expected = true) {
+    const disabled = element.disabled ?? false;
+    const enabled = !disabled;
+    const success = enabled === expected;
+    return {
+        success,
+        error: success ? null : `Element is ${enabled ? 'enabled' : 'disabled'}, expected ${expected ? 'enabled' : 'disabled'}`,
+        description: expected ? 'Element should be enabled' : 'Element should be disabled',
+        expected,
+        actual: enabled,
+        context: {
+            tagName: element.tagName,
+            disabled,
+        },
+    };
+}
+// ============================================================================
+// ASYNC WAITING
+// ============================================================================
+/**
+ * Wait for an assertion to pass within a timeout period
+ *
+ * Polls the assertion function at regular intervals until it passes
+ * or the timeout is reached.
+ *
+ * @param assertFn - Function that returns an AssertionResult
+ * @param options - Timeout and interval options
+ * @returns WaitResult with success status and timing information
+ *
+ * @example
+ * ```typescript
+ * const result = await waitForAssertion(
+ *   () => assertValueEquals(input, 'hello'),
+ *   { timeout: 1000, interval: 50 }
+ * );
+ *
+ * if (!result.success) {
+ *   throw createVerificationError('fill', result, selector);
+ * }
+ * ```
+ */
+export async function waitForAssertion(assertFn, options = {}) {
+    const { timeout = 1000, interval = 50 } = options;
+    const startTime = Date.now();
+    let attempts = 0;
+    let lastResult;
+    while (Date.now() - startTime < timeout) {
+        attempts++;
+        lastResult = assertFn();
+        if (lastResult.success) {
+            return {
+                success: true,
+                elapsed: Date.now() - startTime,
+                attempts,
+                result: lastResult,
+            };
+        }
+        // Wait before next attempt
+        await new Promise(resolve => setTimeout(resolve, interval));
+    }
+    // Final attempt after timeout
+    attempts++;
+    lastResult = assertFn();
+    return {
+        success: lastResult.success,
+        elapsed: Date.now() - startTime,
+        attempts,
+        result: lastResult,
+    };
+}
+//# sourceMappingURL=assertions.js.map

package/packages/core/dist/errors.d.ts

@@ -4,6 +4,7 @@
  * Provides structured error types with machine-readable codes and
  * actionable suggestions to help AI agents self-correct.
  */
+import type { WaitResult } from './assertions.js';
 /**
  * Machine-readable error codes for programmatic error handling
  */
@@ -27,7 +28,9 @@ export declare enum ErrorCode {
     /** Element is not in the expected state */
     INVALID_STATE = "INVALID_STATE",
     /** Network or navigation error */
-    NAVIGATION_ERROR = "NAVIGATION_ERROR"
+    NAVIGATION_ERROR = "NAVIGATION_ERROR",
+    /** Action verification failed after completion */
+    VERIFICATION_FAILED = "VERIFICATION_FAILED"
 }
 /**
  * Structured context information for errors
@@ -135,4 +138,23 @@ export declare function createTimeoutError(selector: string | undefined, expecte
  * Helper function to create invalid parameters error
  */
 export declare function createInvalidParametersError(message: string, conflictingParams: string[], suggestion: string): DetailedError;
+/**
+ * Helper function to create verification error with assertion details
+ *
+ * @param action - The action that failed verification (e.g., 'fill', 'type', 'check')
+ * @param waitResult - The result from waitForAssertion
+ * @param selector - Optional selector for the element
+ *
+ * @example
+ * ```typescript
+ * const result = await waitForAssertion(
+ *   () => assertValueEquals(element, value)
+ * );
+ *
+ * if (!result.success) {
+ *   throw createVerificationError('fill', result, selector);
+ * }
+ * ```
+ */
+export declare function createVerificationError(action: string, waitResult: WaitResult, selector?: string): DetailedError;
 //# sourceMappingURL=errors.d.ts.map

package/packages/core/dist/errors.js

@@ -29,6 +29,8 @@ export var ErrorCode;
     ErrorCode["INVALID_STATE"] = "INVALID_STATE";
     /** Network or navigation error */
     ErrorCode["NAVIGATION_ERROR"] = "NAVIGATION_ERROR";
+    /** Action verification failed after completion */
+    ErrorCode["VERIFICATION_FAILED"] = "VERIFICATION_FAILED";
 })(ErrorCode || (ErrorCode = {}));
 /**
  * Detailed error with structured data for AI agents
@@ -154,4 +156,51 @@ export function createInvalidParametersError(message, conflictingParams, suggest
         conflictingParams,
     }, [suggestion]);
 }
+/**
+ * Helper function to create verification error with assertion details
+ *
+ * @param action - The action that failed verification (e.g., 'fill', 'type', 'check')
+ * @param waitResult - The result from waitForAssertion
+ * @param selector - Optional selector for the element
+ *
+ * @example
+ * ```typescript
+ * const result = await waitForAssertion(
+ *   () => assertValueEquals(element, value)
+ * );
+ *
+ * if (!result.success) {
+ *   throw createVerificationError('fill', result, selector);
+ * }
+ * ```
+ */
+export function createVerificationError(action, waitResult, selector) {
+    const { result, elapsed, attempts } = waitResult;
+    const suggestions = [];
+    // Add context-specific suggestions based on the assertion
+    if (result.description.includes('value')) {
+        suggestions.push('The element value may have been modified by event handlers.', 'Check for input masking, formatting, or validation that transforms the value.');
+    }
+    if (result.description.includes('checked')) {
+        suggestions.push('The checkbox/radio state may be controlled by JavaScript.', 'Verify the element is not disabled or read-only.');
+    }
+    if (result.description.includes('selected')) {
+        suggestions.push('Some options may not exist in the select element.', 'Use snapshot() to verify available option values.');
+    }
+    if (result.description.includes('origin')) {
+        suggestions.push('The page may have redirected to a different domain.', 'Check for authentication redirects or HTTPS upgrades.');
+    }
+    suggestions.push(`Verification waited ${elapsed}ms with ${attempts} attempts.`);
+    const message = selector
+        ? `${action} verification failed for ${selector}: ${result.description}`
+        : `${action} verification failed: ${result.description}`;
+    return new DetailedError(ErrorCode.VERIFICATION_FAILED, message, {
+        selector,
+        expected: result.expected,
+        actual: result.actual,
+        elapsed,
+        attempts,
+        ...result.context,
+    }, suggestions);
+}
 //# sourceMappingURL=errors.js.map

package/packages/core/dist/index.d.ts

@@ -20,6 +20,7 @@
 import type { Command, Response, RefMap } from './types.js';
 export * from './types.js';
 export * from './errors.js';
+export * from './assertions.js';
 export { createSnapshot } from './snapshot.js';
 export { createRefMap, createSimpleRefMap } from './ref-map.js';
 export { DOMActions, generateCommandId } from './actions.js';

package/packages/core/dist/index.js

@@ -21,6 +21,7 @@ import { DOMActions } from './actions.js';
 import { createRefMap, createSimpleRefMap } from './ref-map.js';
 export * from './types.js';
 export * from './errors.js';
+export * from './assertions.js';
 export { createSnapshot } from './snapshot.js';
 export { createRefMap, createSimpleRefMap } from './ref-map.js';
 export { DOMActions, generateCommandId } from './actions.js';

package/packages/extension/dist/background.d.ts

@@ -119,8 +119,10 @@ export declare class BackgroundAgent {
     switchTab(tabId: number): Promise<void>;
     /**
      * Navigate to a URL (only in session tabs)
+     * Always waits for page to be idle before returning.
+     * Verifies navigation completed to the expected origin.
      */
-    navigate(url: string, options?: {
+    navigate(url: string, _options?: {
         waitUntil?: 'load' | 'domcontentloaded';
     }): Promise<void>;
     /**
@@ -205,6 +207,11 @@ export declare class BackgroundAgent {
     private isExtensionCommand;
     private executeExtensionCommand;
     private waitForTabLoad;
+    /**
+     * Wait for the page to become idle (no pending network requests or JS execution)
+     * Uses requestIdleCallback in the content script to detect when the browser is idle.
+     */
+    private waitForIdle;
 }
 /**
  * Get or create the BackgroundAgent singleton

package/packages/extension/dist/background.js

@@ -12,6 +12,7 @@
  * - Routing DOM commands to ContentAgents in target tabs
  */
 import { SessionManager } from './session-manager.js';
+import { assertUrlOrigin, createVerificationError } from '../../core/dist/index.js';
 // Command ID counter for auto-generated IDs
 let bgCommandIdCounter = 0;
 /**
@@ -282,8 +283,10 @@ export class BackgroundAgent {
     // ============================================================================
     /**
      * Navigate to a URL (only in session tabs)
+     * Always waits for page to be idle before returning.
+     * Verifies navigation completed to the expected origin.
      */
-    async navigate(url, options) {
+    async navigate(url, _options) {
         const tabId = this.activeTabId ?? (await this.getActiveTab())?.id;
         if (!tabId)
             throw new Error('No active tab');
@@ -295,20 +298,40 @@ export class BackgroundAgent {
         await new Promise((resolve) => {
             chrome.tabs.update(tabId, { url }, () => resolve());
         });
-        if (options?.waitUntil) {
-            await this.waitForTabLoad(tabId);
-            // Clear refs and highlights after navigation completes
-            try {
-                await this.sendToContentAgent({
-                    id: `nav_clear_${Date.now()}`,
-                    action: 'clearHighlight'
-                }, tabId);
+        // Always wait for tab to load and become idle
+        await this.waitForTabLoad(tabId);
+        await this.waitForIdle(tabId);
+        // Verify navigation completed to the expected origin
+        const tab = await chrome.tabs.get(tabId);
+        const finalUrl = tab.url || '';
+        // Use assertion module for origin verification
+        const result = assertUrlOrigin(finalUrl, url);
+        if (!result.success) {
+            // Only throw for actual origin mismatches, not URL parsing errors
+            if (result.context?.error) {
+                // URL parsing failed (e.g., chrome:// pages) - skip verification
+                console.log('[BackgroundAgent] Skipping URL verification for special page:', finalUrl);
             }
-            catch (error) {
-                // Ignore errors - content script might not be ready yet
-                console.log('[BackgroundAgent] Failed to clear highlights after navigation:', error);
+            else {
+                throw createVerificationError('navigate', {
+                    success: false,
+                    elapsed: 0,
+                    attempts: 1,
+                    result,
+                });
             }
         }
+        // Clear refs and highlights after navigation completes
+        try {
+            await this.sendToContentAgent({
+                id: `nav_clear_${Date.now()}`,
+                action: 'clearHighlight'
+            }, tabId);
+        }
+        catch (error) {
+            // Ignore errors - content script might not be ready yet
+            console.log('[BackgroundAgent] Failed to clear highlights after navigation:', error);
+        }
     }
     /**
      * Go back in history
@@ -494,9 +517,9 @@ export class BackgroundAgent {
             if (!tab.url || tab.url.startsWith('chrome://') || tab.url.startsWith('chrome-extension://')) {
                 return false; // Can't inject into chrome:// or extension pages
             }
-            // Execute content script
+            // Execute content script (main frame only)
             await chrome.scripting.executeScript({
-                target: { tabId },
+                target: { tabId, frameIds: [0] },
                 files: ['content.js'],
             });
             console.log(`[Recovery] Successfully re-injected content script into tab ${tabId}`);
@@ -694,6 +717,42 @@ export class BackgroundAgent {
             checkTab();
         });
     }
+    /**
+     * Wait for the page to become idle (no pending network requests or JS execution)
+     * Uses requestIdleCallback in the content script to detect when the browser is idle.
+     */
+    async waitForIdle(tabId, timeout = 10000) {
+        const startTime = Date.now();
+        // Poll until the page reports idle or timeout
+        while (Date.now() - startTime < timeout) {
+            try {
+                const results = await chrome.scripting.executeScript({
+                    target: { tabId, frameIds: [0] }, // Only inject into main frame
+                    func: () => {
+                        return new Promise((resolve) => {
+                            // Use requestIdleCallback to detect when browser is idle
+                            if ('requestIdleCallback' in window) {
+                                requestIdleCallback(() => resolve(true), { timeout: 1000 });
+                            }
+                            else {
+                                // Fallback: wait a short period
+                                setTimeout(() => resolve(true), 500);
+                            }
+                        });
+                    },
+                });
+                if (results?.[0]?.result) {
+                    return;
+                }
+            }
+            catch (error) {
+                // Content script may not be ready yet, wait and retry
+                await new Promise(resolve => setTimeout(resolve, 200));
+            }
+        }
+        // Timeout reached, continue anyway
+        console.log('[BackgroundAgent] waitForIdle timeout reached, continuing');
+    }
 }
 // ============================================================================
 // MESSAGE LISTENER SETUP

package/packages/extension/dist/content.js

@@ -7,6 +7,12 @@
 import { createContentAgent } from '../../core/dist/index.js';
 let agent = null;
 let isContentScriptReady = false;
+// Track injected scripts by scriptId
+const injectedScripts = new Map();
+// Track pending script commands waiting for ack
+const pendingScriptCommands = new Map();
+// Counter for generating unique command IDs
+let scriptCommandCounter = 0;
 /**
  * Get or create the ContentAgent instance for this page
  */
@@ -28,9 +34,113 @@ function isCoreCommand(command) {
         'navigate', 'back', 'forward', 'reload',
         'getUrl', 'getTitle', 'screenshot',
         'tabNew', 'tabClose', 'tabSwitch', 'tabList',
+        'scriptInject', 'scriptSend',
     ];
     return !extensionActions.includes(command.action);
 }
+/**
+ * Inject a script into the page's main world
+ */
+function handleScriptInject(command) {
+    const id = command.id || 'unknown';
+    const scriptId = command.scriptId || 'default';
+    try {
+        // Remove existing script with same ID if present
+        const existing = injectedScripts.get(scriptId);
+        if (existing) {
+            existing.element.remove();
+            injectedScripts.delete(scriptId);
+        }
+        // Create script element
+        const script = document.createElement('script');
+        script.textContent = command.code;
+        script.setAttribute('data-btcp-script-id', scriptId);
+        // Inject into page's main world by appending to document
+        (document.head || document.documentElement).appendChild(script);
+        // Track the injected script
+        injectedScripts.set(scriptId, {
+            element: script,
+            injectedAt: Date.now(),
+        });
+        console.log(`[ContentScript] Injected script: ${scriptId}`);
+        return {
+            id,
+            success: true,
+            data: { scriptId, injected: true },
+        };
+    }
+    catch (error) {
+        return {
+            id,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            errorCode: 'INJECTION_FAILED',
+        };
+    }
+}
+/**
+ * Send a command to an injected script and wait for acknowledgment
+ */
+function handleScriptSend(command) {
+    const id = command.id || 'unknown';
+    const scriptId = command.scriptId || 'default';
+    const timeout = command.timeout ?? 30000;
+    const commandId = `script_cmd_${Date.now()}_${scriptCommandCounter++}`;
+    return new Promise((resolve) => {
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            pendingScriptCommands.delete(commandId);
+            resolve({
+                id,
+                success: false,
+                error: `Script command timed out after ${timeout}ms`,
+                errorCode: 'SCRIPT_TIMEOUT',
+            });
+        }, timeout);
+        // Track pending command
+        pendingScriptCommands.set(commandId, { resolve, timeoutId });
+        // Send command to page script via postMessage
+        const message = {
+            type: 'btcp:script-command',
+            commandId,
+            scriptId,
+            payload: command.payload,
+        };
+        window.postMessage(message, '*');
+    });
+}
+/**
+ * Listen for script acknowledgments from page scripts
+ */
+window.addEventListener('message', (event) => {
+    if (event.source !== window)
+        return;
+    const msg = event.data;
+    if (msg?.type !== 'btcp:script-ack')
+        return;
+    const pending = pendingScriptCommands.get(msg.commandId);
+    if (!pending)
+        return;
+    // Clear timeout and remove from pending
+    clearTimeout(pending.timeoutId);
+    pendingScriptCommands.delete(msg.commandId);
+    // Resolve with response
+    if (msg.error) {
+        pending.resolve({
+            id: msg.commandId,
+            success: false,
+            error: msg.error,
+            errorCode: 'SCRIPT_ERROR',
+        });
+    }
+    else {
+        pending.resolve({
+            id: msg.commandId,
+            success: true,
+            data: { result: msg.result },
+        });
+    }
+});
 /**
  * Handle a command from the background script
  */
@@ -54,6 +164,10 @@ async function handleCommand(command) {
                 success: true,
                 data: { title: document.title },
             };
+        case 'scriptInject':
+            return handleScriptInject(command);
+        case 'scriptSend':
+            return handleScriptSend(command);
         default:
             // Forward to background script
             return {