btcp-browser-agent 0.1.0 → 0.1.1

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

@@ -0,0 +1,138 @@
+/**
+ * Error handling utilities for BTCP Browser Agent
+ *
+ * Provides structured error types with machine-readable codes and
+ * actionable suggestions to help AI agents self-correct.
+ */
+/**
+ * Machine-readable error codes for programmatic error handling
+ */
+export declare enum ErrorCode {
+    /** Element not found with given selector */
+    ELEMENT_NOT_FOUND = "ELEMENT_NOT_FOUND",
+    /** Element exists but doesn't support the requested action */
+    ELEMENT_NOT_COMPATIBLE = "ELEMENT_NOT_COMPATIBLE",
+    /** Ref ID has expired (cleared by new snapshot) */
+    REF_EXPIRED = "REF_EXPIRED",
+    /** Invalid selector syntax or format */
+    INVALID_SELECTOR = "INVALID_SELECTOR",
+    /** Operation timed out waiting for condition */
+    TIMEOUT = "TIMEOUT",
+    /** Element exists but is not visible */
+    ELEMENT_NOT_VISIBLE = "ELEMENT_NOT_VISIBLE",
+    /** Element exists but is disabled */
+    ELEMENT_DISABLED = "ELEMENT_DISABLED",
+    /** Conflicting parameters provided to command */
+    INVALID_PARAMETERS = "INVALID_PARAMETERS",
+    /** Element is not in the expected state */
+    INVALID_STATE = "INVALID_STATE",
+    /** Network or navigation error */
+    NAVIGATION_ERROR = "NAVIGATION_ERROR"
+}
+/**
+ * Structured context information for errors
+ */
+export interface ErrorContext {
+    /** The selector that was used */
+    selector?: string;
+    /** Expected element type or role */
+    expectedType?: string;
+    /** Actual element type or role found */
+    actualType?: string;
+    /** Current state of the element */
+    elementState?: {
+        attached: boolean;
+        visible: boolean;
+        enabled: boolean;
+    };
+    /** Actions available for this element */
+    availableActions?: string[];
+    /** Similar selectors that were found */
+    similarSelectors?: Array<{
+        selector: string;
+        role: string;
+        name: string;
+        similarity?: number;
+    }>;
+    /** Nearby interactive elements */
+    nearbyElements?: Array<{
+        ref: string;
+        role: string;
+        name: string;
+    }>;
+    /** Additional context-specific data */
+    [key: string]: any;
+}
+/**
+ * Detailed error with structured data for AI agents
+ *
+ * Provides both human-readable messages and machine-readable
+ * error codes, context, and recovery suggestions.
+ *
+ * @example
+ * ```typescript
+ * throw new DetailedError(
+ *   ErrorCode.ELEMENT_NOT_FOUND,
+ *   "Element not found: #submit-btn",
+ *   {
+ *     selector: "#submit-btn",
+ *     similarSelectors: [
+ *       { selector: "#submit-button", role: "button", name: "Submit" }
+ *     ]
+ *   },
+ *   [
+ *     "Try using selector: #submit-button",
+ *     "Run snapshot({ interactive: true }) to see all clickable elements"
+ *   ]
+ * );
+ * ```
+ */
+export declare class DetailedError extends Error {
+    readonly code: ErrorCode;
+    readonly context: ErrorContext;
+    readonly suggestions: string[];
+    constructor(code: ErrorCode, message: string, context?: ErrorContext, suggestions?: string[]);
+    /**
+     * Convert to structured object for API responses
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: ErrorCode;
+        context: ErrorContext;
+        suggestions: string[];
+    };
+}
+/**
+ * Helper function to create element not found error with suggestions
+ */
+export declare function createElementNotFoundError(selector: string, options?: {
+    similarSelectors?: Array<{
+        selector: string;
+        role: string;
+        name: string;
+    }>;
+    nearbyElements?: Array<{
+        ref: string;
+        role: string;
+        name: string;
+    }>;
+    isRef?: boolean;
+}): DetailedError;
+/**
+ * Helper function to create element not compatible error
+ */
+export declare function createElementNotCompatibleError(selector: string, action: string, actualType: string, expectedTypes: string[], availableActions?: string[]): DetailedError;
+/**
+ * Helper function to create timeout error with state information
+ */
+export declare function createTimeoutError(selector: string | undefined, expectedState: string, currentState?: {
+    attached: boolean;
+    visible: boolean;
+    enabled: boolean;
+}): DetailedError;
+/**
+ * Helper function to create invalid parameters error
+ */
+export declare function createInvalidParametersError(message: string, conflictingParams: string[], suggestion: string): DetailedError;
+//# sourceMappingURL=errors.d.ts.map

package/packages/core/dist/errors.js

@@ -0,0 +1,157 @@
+/**
+ * Error handling utilities for BTCP Browser Agent
+ *
+ * Provides structured error types with machine-readable codes and
+ * actionable suggestions to help AI agents self-correct.
+ */
+/**
+ * Machine-readable error codes for programmatic error handling
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    /** Element not found with given selector */
+    ErrorCode["ELEMENT_NOT_FOUND"] = "ELEMENT_NOT_FOUND";
+    /** Element exists but doesn't support the requested action */
+    ErrorCode["ELEMENT_NOT_COMPATIBLE"] = "ELEMENT_NOT_COMPATIBLE";
+    /** Ref ID has expired (cleared by new snapshot) */
+    ErrorCode["REF_EXPIRED"] = "REF_EXPIRED";
+    /** Invalid selector syntax or format */
+    ErrorCode["INVALID_SELECTOR"] = "INVALID_SELECTOR";
+    /** Operation timed out waiting for condition */
+    ErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** Element exists but is not visible */
+    ErrorCode["ELEMENT_NOT_VISIBLE"] = "ELEMENT_NOT_VISIBLE";
+    /** Element exists but is disabled */
+    ErrorCode["ELEMENT_DISABLED"] = "ELEMENT_DISABLED";
+    /** Conflicting parameters provided to command */
+    ErrorCode["INVALID_PARAMETERS"] = "INVALID_PARAMETERS";
+    /** Element is not in the expected state */
+    ErrorCode["INVALID_STATE"] = "INVALID_STATE";
+    /** Network or navigation error */
+    ErrorCode["NAVIGATION_ERROR"] = "NAVIGATION_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Detailed error with structured data for AI agents
+ *
+ * Provides both human-readable messages and machine-readable
+ * error codes, context, and recovery suggestions.
+ *
+ * @example
+ * ```typescript
+ * throw new DetailedError(
+ *   ErrorCode.ELEMENT_NOT_FOUND,
+ *   "Element not found: #submit-btn",
+ *   {
+ *     selector: "#submit-btn",
+ *     similarSelectors: [
+ *       { selector: "#submit-button", role: "button", name: "Submit" }
+ *     ]
+ *   },
+ *   [
+ *     "Try using selector: #submit-button",
+ *     "Run snapshot({ interactive: true }) to see all clickable elements"
+ *   ]
+ * );
+ * ```
+ */
+export class DetailedError extends Error {
+    code;
+    context;
+    suggestions;
+    constructor(code, message, context = {}, suggestions = []) {
+        // Build enhanced message with suggestions
+        let fullMessage = message;
+        if (suggestions.length > 0) {
+            fullMessage += '\n\nSuggestions:';
+            suggestions.forEach(suggestion => {
+                fullMessage += `\n  - ${suggestion}`;
+            });
+        }
+        super(fullMessage);
+        this.name = 'DetailedError';
+        this.code = code;
+        this.context = context;
+        this.suggestions = suggestions;
+    }
+    /**
+     * Convert to structured object for API responses
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            suggestions: this.suggestions,
+        };
+    }
+}
+/**
+ * Helper function to create element not found error with suggestions
+ */
+export function createElementNotFoundError(selector, options = {}) {
+    const { similarSelectors = [], nearbyElements = [], isRef = false } = options;
+    const suggestions = [];
+    if (isRef) {
+        suggestions.push('Ref may have expired. Refs are cleared on snapshot() calls and page navigation.', 'Call snapshot() again to get fresh refs.');
+    }
+    if (similarSelectors.length > 0) {
+        suggestions.push(`Similar selectors found: ${similarSelectors.map(s => s.selector).join(', ')}`);
+    }
+    if (nearbyElements.length > 0) {
+        suggestions.push('Run snapshot({ interactive: true }) to see all clickable elements');
+    }
+    return new DetailedError(isRef ? ErrorCode.REF_EXPIRED : ErrorCode.ELEMENT_NOT_FOUND, `Element not found: ${selector}`, {
+        selector,
+        similarSelectors,
+        nearbyElements,
+    }, suggestions);
+}
+/**
+ * Helper function to create element not compatible error
+ */
+export function createElementNotCompatibleError(selector, action, actualType, expectedTypes, availableActions = []) {
+    const suggestions = [];
+    if (availableActions.length > 0) {
+        suggestions.push(`Available actions for ${actualType}: ${availableActions.join(', ')}`);
+    }
+    suggestions.push(`Use snapshot() to verify element type before attempting action`);
+    return new DetailedError(ErrorCode.ELEMENT_NOT_COMPATIBLE, `Element ${selector} is ${actualType}, cannot perform action: ${action}`, {
+        selector,
+        actualType,
+        expectedType: expectedTypes.join(' or '),
+        availableActions,
+    }, suggestions);
+}
+/**
+ * Helper function to create timeout error with state information
+ */
+export function createTimeoutError(selector, expectedState, currentState) {
+    const suggestions = [];
+    if (currentState) {
+        if (currentState.attached && !currentState.visible && expectedState === 'visible') {
+            suggestions.push('Element is attached but not visible. Check CSS display/visibility properties.', 'Try state="attached" if you just need element to exist in DOM.');
+        }
+        if (currentState.attached && currentState.visible && !currentState.enabled && expectedState === 'enabled') {
+            suggestions.push('Element is visible but disabled. Check disabled attribute or aria-disabled.', 'Wait for the condition that enables the element, or use force option if available.');
+        }
+    }
+    suggestions.push('Increase timeout value if element appears slowly.');
+    const message = selector
+        ? `Timeout waiting for ${selector} to be ${expectedState}`
+        : `Timeout waiting for page to be ${expectedState}`;
+    return new DetailedError(ErrorCode.TIMEOUT, message, {
+        selector,
+        expectedType: expectedState,
+        elementState: currentState,
+    }, suggestions);
+}
+/**
+ * Helper function to create invalid parameters error
+ */
+export function createInvalidParametersError(message, conflictingParams, suggestion) {
+    return new DetailedError(ErrorCode.INVALID_PARAMETERS, message, {
+        conflictingParams,
+    }, [suggestion]);
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,120 @@
+/**
+ * @btcp/core
+ *
+ * Core DOM actions for browser automation.
+ * Runs in content script context (web page, extension content script, iframe).
+ *
+ * @example
+ * ```typescript
+ * import { createContentAgent } from '@btcp/core';
+ *
+ * const agent = createContentAgent(document, window);
+ *
+ * // Take a snapshot
+ * const snapshot = await agent.execute({
+ *   id: '1',
+ *   action: 'snapshot'
+ * });
+ *
+ * // Click an element
+ * await agent.execute({
+ *   id: '2',
+ *   action: 'click',
+ *   selector: '@ref:5'  // From snapshot
+ * });
+ * ```
+ */
+import type { Command, Response, RefMap } from './types.js';
+export * from './types.js';
+export * from './errors.js';
+export { createSnapshot } from './snapshot.js';
+export { createRefMap, createSimpleRefMap } from './ref-map.js';
+export { DOMActions } from './actions.js';
+/**
+ * ContentAgent - DOM automation agent that runs in content script context
+ *
+ * This agent handles all DOM-level operations:
+ * - Element interaction (click, type, fill, etc.)
+ * - DOM queries (snapshot, getText, getAttribute, etc.)
+ * - Keyboard/mouse events
+ *
+ * Use this in content scripts or directly in web pages.
+ * For browser-level operations (tabs, navigation, screenshots),
+ * use BrowserAgent from @btcp/extension.
+ */
+export interface ContentAgent {
+    /**
+     * Execute a command and return a response
+     */
+    execute(command: Command): Promise<Response>;
+    /**
+     * Execute a command from JSON string
+     */
+    executeJson(json: string): Promise<string>;
+    /**
+     * Get the element reference map
+     */
+    getRefMap(): RefMap;
+    /**
+     * Clear all element references
+     */
+    clearRefs(): void;
+    /**
+     * Message handler for chrome.runtime.onMessage
+     *
+     * @example
+     * ```typescript
+     * const agent = createContentAgent();
+     * chrome.runtime.onMessage.addListener(agent.handleMessage);
+     * ```
+     */
+    handleMessage: (message: unknown, sender: unknown, sendResponse: (response: unknown) => void) => boolean;
+}
+/**
+ * Create a ContentAgent for DOM automation
+ *
+ * @param doc - The document to operate on (defaults to current document)
+ * @param win - The window context (defaults to current window)
+ * @returns A ContentAgent instance
+ *
+ * @example
+ * ```typescript
+ * // In content script
+ * const agent = createContentAgent();
+ *
+ * // Take a snapshot of the page
+ * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ *
+ * // Click an element using ref from snapshot
+ * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * ```
+ */
+export declare function createContentAgent(doc?: Document, win?: Window): ContentAgent;
+/**
+ * @deprecated Use createContentAgent instead
+ */
+export declare const createAgent: typeof createContentAgent;
+/**
+ * @deprecated Use ContentAgent instead
+ */
+export type Agent = ContentAgent;
+/**
+ * Message types for extension communication
+ */
+export interface AgentMessage {
+    type: 'aspect:command';
+    command: Command;
+}
+export interface AgentResponse {
+    type: 'aspect:response';
+    response: Response;
+}
+/**
+ * Install message listener for extension communication
+ * Call this in your content script to enable command execution via postMessage
+ *
+ * @param agent - The agent instance
+ * @returns Cleanup function to remove the listener
+ */
+export declare function installMessageListener(agent: Agent): () => void;
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/index.js

@@ -0,0 +1,134 @@
+/**
+ * @btcp/core
+ *
+ * Core DOM actions for browser automation.
+ * Runs in content script context (web page, extension content script, iframe).
+ *
+ * @example
+ * ```typescript
+ * import { createContentAgent } from '@btcp/core';
+ *
+ * const agent = createContentAgent(document, window);
+ *
+ * // Take a snapshot
+ * const snapshot = await agent.execute({
+ *   id: '1',
+ *   action: 'snapshot'
+ * });
+ *
+ * // Click an element
+ * await agent.execute({
+ *   id: '2',
+ *   action: 'click',
+ *   selector: '@ref:5'  // From snapshot
+ * });
+ * ```
+ */
+import { DOMActions } from './actions.js';
+import { createRefMap, createSimpleRefMap } from './ref-map.js';
+export * from './types.js';
+export * from './errors.js';
+export { createSnapshot } from './snapshot.js';
+export { createRefMap, createSimpleRefMap } from './ref-map.js';
+export { DOMActions } from './actions.js';
+/**
+ * Create a ContentAgent for DOM automation
+ *
+ * @param doc - The document to operate on (defaults to current document)
+ * @param win - The window context (defaults to current window)
+ * @returns A ContentAgent instance
+ *
+ * @example
+ * ```typescript
+ * // In content script
+ * const agent = createContentAgent();
+ *
+ * // Take a snapshot of the page
+ * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ *
+ * // Click an element using ref from snapshot
+ * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * ```
+ */
+export function createContentAgent(doc = document, win = window) {
+    // Use WeakRef-based map if available for better memory management
+    const refMap = typeof WeakRef !== 'undefined'
+        ? createRefMap()
+        : createSimpleRefMap();
+    const actions = new DOMActions(doc, win, refMap);
+    const agent = {
+        async execute(command) {
+            return actions.execute(command);
+        },
+        async executeJson(json) {
+            try {
+                const command = JSON.parse(json);
+                const response = await actions.execute(command);
+                return JSON.stringify(response);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return JSON.stringify({
+                    id: 'unknown',
+                    success: false,
+                    error: `Failed to parse command: ${message}`,
+                });
+            }
+        },
+        getRefMap() {
+            return refMap;
+        },
+        clearRefs() {
+            refMap.clear();
+            actions.invalidateSnapshot();
+        },
+        handleMessage(message, _sender, sendResponse) {
+            const msg = message;
+            if (msg?.type !== 'btcp:command')
+                return false;
+            agent.execute(msg.command).then(response => {
+                sendResponse({ type: 'btcp:response', response });
+            }).catch(error => {
+                sendResponse({
+                    type: 'btcp:response',
+                    response: {
+                        id: msg.command?.id ?? 'unknown',
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            });
+            return true; // Keep channel open for async response
+        },
+    };
+    return agent;
+}
+/**
+ * @deprecated Use createContentAgent instead
+ */
+export const createAgent = createContentAgent;
+/**
+ * Install message listener for extension communication
+ * Call this in your content script to enable command execution via postMessage
+ *
+ * @param agent - The agent instance
+ * @returns Cleanup function to remove the listener
+ */
+export function installMessageListener(agent) {
+    const handler = async (event) => {
+        // Only accept messages from same window
+        if (event.source !== window)
+            return;
+        const data = event.data;
+        if (data?.type !== 'aspect:command')
+            return;
+        const response = await agent.execute(data.command);
+        window.postMessage({
+            type: 'aspect:response',
+            response,
+        }, '*');
+    };
+    window.addEventListener('message', handler);
+    return () => window.removeEventListener('message', handler);
+}
+//# sourceMappingURL=index.js.map

package/packages/core/dist/ref-map.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @btcp/core - Element Reference Map
+ *
+ * Maintains a mapping between string refs and DOM elements.
+ * Used by the snapshot system to enable @ref:xxx selectors.
+ */
+import type { RefMap } from './types.js';
+/**
+ * Create a new element reference map
+ */
+export declare function createRefMap(): RefMap;
+/**
+ * Simple ref map without WeakRef (for environments that don't support it)
+ */
+export declare function createSimpleRefMap(): RefMap;
+//# sourceMappingURL=ref-map.d.ts.map

package/packages/core/dist/ref-map.js

@@ -0,0 +1,91 @@
+/**
+ * @btcp/core - Element Reference Map
+ *
+ * Maintains a mapping between string refs and DOM elements.
+ * Used by the snapshot system to enable @ref:xxx selectors.
+ */
+/**
+ * Create a new element reference map
+ */
+export function createRefMap() {
+    const map = new Map();
+    let counter = 0;
+    return {
+        get(ref) {
+            const weakRef = map.get(ref);
+            if (!weakRef)
+                return null;
+            const element = weakRef.deref();
+            if (!element) {
+                // Element was garbage collected
+                map.delete(ref);
+                return null;
+            }
+            // Check if element is still in DOM
+            if (!element.isConnected) {
+                map.delete(ref);
+                return null;
+            }
+            return element;
+        },
+        set(ref, element) {
+            map.set(ref, new WeakRef(element));
+        },
+        clear() {
+            map.clear();
+            counter = 0;
+        },
+        generateRef(element) {
+            // Check if element already has a ref
+            for (const [ref, weakRef] of map.entries()) {
+                if (weakRef.deref() === element) {
+                    return ref;
+                }
+            }
+            // Generate new ref
+            const ref = `@ref:${counter++}`;
+            map.set(ref, new WeakRef(element));
+            return ref;
+        },
+    };
+}
+/**
+ * Simple ref map without WeakRef (for environments that don't support it)
+ */
+export function createSimpleRefMap() {
+    const map = new Map();
+    let counter = 0;
+    return {
+        get(ref) {
+            const element = map.get(ref);
+            if (!element)
+                return null;
+            // Check if element is still in DOM
+            if (!element.isConnected) {
+                map.delete(ref);
+                return null;
+            }
+            return element;
+        },
+        set(ref, element) {
+            map.set(ref, element);
+        },
+        clear() {
+            map.clear();
+            counter = 0;
+        },
+        generateRef(element) {
+            // Check if element already has a ref
+            for (const [ref, el] of map.entries()) {
+                if (el === element) {
+                    return ref;
+                }
+            }
+            // Generate new ref
+            const ref = `@ref:${counter++}`;
+            map.set(ref, element);
+            return ref;
+        },
+    };
+}
+//# sourceMappingURL=ref-map.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * @btcp/core - DOM Snapshot
+ *
+ * Generates a flat accessibility snapshot of the DOM.
+ * Produces a compact, AI-friendly list of interactive elements.
+ */
+import type { SnapshotData, RefMap } from './types.js';
+/**
+ * Grep options (mirrors Unix grep flags)
+ */
+interface GrepOptions {
+    /** Pattern to search for */
+    pattern: string;
+    /** Case-insensitive matching (grep -i) */
+    ignoreCase?: boolean;
+    /** Invert match - return non-matching lines (grep -v) */
+    invert?: boolean;
+    /** Treat pattern as fixed string, not regex (grep -F) */
+    fixedStrings?: boolean;
+}
+interface SnapshotOptions {
+    root?: Element;
+    maxDepth?: number;
+    includeHidden?: boolean;
+    interactive?: boolean;
+    compact?: boolean;
+    all?: boolean;
+    format?: 'tree' | 'html';
+    /** Grep filter - string pattern or options object */
+    grep?: string | GrepOptions;
+}
+/**
+ * Generate flat snapshot of the DOM
+ */
+export declare function createSnapshot(document: Document, refMap: RefMap, options?: SnapshotOptions): SnapshotData;
+export {};
+//# sourceMappingURL=snapshot.d.ts.map