btcp-browser-agent 0.1.14 → 0.1.17

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "btcp-browser-agent",
-  "version": "0.1.14",
-  "description": "Give AI agents the power to control browsers. A foundation for building agentic systems with smart DOM snapshots and stable element references.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./core": {
-      "types": "./packages/core/dist/index.d.ts",
-      "import": "./packages/core/dist/index.js",
-      "default": "./packages/core/dist/index.js"
-    },
-    "./extension": {
-      "types": "./packages/extension/dist/index.d.ts",
-      "import": "./packages/extension/dist/index.js",
-      "default": "./packages/extension/dist/index.js"
-    },
-    "./extension/content": {
-      "types": "./packages/extension/dist/content.d.ts",
-      "import": "./packages/extension/dist/content.js",
-      "default": "./packages/extension/dist/content.js"
-    },
-    "./extension/background": {
-      "types": "./packages/extension/dist/background.d.ts",
-      "import": "./packages/extension/dist/background.js",
-      "default": "./packages/extension/dist/background.js"
-    }
-  },
-  "scripts": {
-    "build": "npm run build:packages && tsc -p tsconfig.build.json",
-    "build:packages": "tsc -p packages/core/tsconfig.json && tsc -p packages/extension/tsconfig.json && tsc -p packages/cli/tsconfig.json",
-    "clean": "rm -rf dist packages/*/dist",
-    "prepare": "npm run build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
-  "workspaces": [
-    "packages/core",
-    "packages/extension",
-    "packages/cli"
-  ],
-  "files": [
-    "dist",
-    "packages/core/dist",
-    "packages/extension/dist",
-    "!**/__tests__",
-    "!**/*.map"
-  ],
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/browser-tool-calling-protocol/btcp-browser-agent.git"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@types/chrome": "^0.0.268",
-    "@types/node": "^20.10.0",
-    "jsdom": "^24.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^2.0.0"
-  }
-}
+{
+  "name": "btcp-browser-agent",
+  "version": "0.1.17",
+  "description": "Give AI agents the power to control browsers. A foundation for building agentic systems with smart DOM snapshots and stable element references.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./packages/core/dist/index.d.ts",
+      "import": "./packages/core/dist/index.js",
+      "default": "./packages/core/dist/index.js"
+    },
+    "./extension": {
+      "types": "./packages/extension/dist/index.d.ts",
+      "import": "./packages/extension/dist/index.js",
+      "default": "./packages/extension/dist/index.js"
+    },
+    "./extension/content": {
+      "types": "./packages/extension/dist/content.d.ts",
+      "import": "./packages/extension/dist/content.js",
+      "default": "./packages/extension/dist/content.js"
+    },
+    "./extension/background": {
+      "types": "./packages/extension/dist/background.d.ts",
+      "import": "./packages/extension/dist/background.js",
+      "default": "./packages/extension/dist/background.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:packages && tsc -p tsconfig.build.json",
+    "build:packages": "tsc -p packages/core/tsconfig.json && tsc -p packages/extension/tsconfig.json && tsc -p packages/cli/tsconfig.json",
+    "clean": "rm -rf dist packages/*/dist",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "workspaces": [
+    "packages/core",
+    "packages/extension",
+    "packages/cli"
+  ],
+  "files": [
+    "dist",
+    "packages/core/dist",
+    "packages/extension/dist",
+    "!**/__tests__",
+    "!**/*.map"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/browser-tool-calling-protocol/btcp-browser-agent.git"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/chrome": "^0.0.268",
+    "@types/node": "^20.10.0",
+    "jsdom": "^24.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  }
+}

package/packages/core/dist/actions.js

@@ -864,15 +864,15 @@ export class DOMActions {
         // Create overlay container with absolute positioning covering entire document
         this.overlayContainer = this.document.createElement('div');
         this.overlayContainer.id = 'btcp-highlight-overlay';
-        this.overlayContainer.style.cssText = `
-      position: absolute;
-      top: 0;
-      left: 0;
-      width: ${this.document.documentElement.scrollWidth}px;
-      height: ${this.document.documentElement.scrollHeight}px;
-      pointer-events: none;
-      z-index: 999999;
-      contain: layout style paint;
+        this.overlayContainer.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: ${this.document.documentElement.scrollWidth}px;
+      height: ${this.document.documentElement.scrollHeight}px;
+      pointer-events: none;
+      z-index: 999999;
+      contain: layout style paint;
     `;
         let highlightedCount = 0;
         // Create border overlays and labels for each ref
@@ -893,17 +893,17 @@ export class DOMActions {
                 const border = this.document.createElement('div');
                 border.className = 'btcp-ref-border';
                 border.dataset.ref = ref;
-                border.style.cssText = `
-          position: absolute;
-          width: ${bbox.width}px;
-          height: ${bbox.height}px;
-          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
-          border: 2px solid rgba(59, 130, 246, 0.8);
-          border-radius: 2px;
-          box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.2);
-          pointer-events: none;
-          will-change: transform;
-          contain: layout style paint;
+                border.style.cssText = `
+          position: absolute;
+          width: ${bbox.width}px;
+          height: ${bbox.height}px;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          border: 2px solid rgba(59, 130, 246, 0.8);
+          border-radius: 2px;
+          box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.2);
+          pointer-events: none;
+          will-change: transform;
+          contain: layout style paint;
         `;
                 // Create label
                 const label = this.document.createElement('div');
@@ -911,21 +911,21 @@ export class DOMActions {
                 label.dataset.ref = ref;
                 // Extract number from ref (e.g., "@ref:5" -> "5")
                 label.textContent = ref.replace('@ref:', '');
-                label.style.cssText = `
-          position: absolute;
-          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
-          background: rgba(59, 130, 246, 0.9);
-          color: white;
-          padding: 2px 6px;
-          border-radius: 3px;
-          font-family: monospace;
-          font-size: 11px;
-          font-weight: bold;
-          box-shadow: 0 2px 4px rgba(0,0,0,0.3);
-          pointer-events: none;
-          white-space: nowrap;
-          will-change: transform;
-          contain: layout style paint;
+                label.style.cssText = `
+          position: absolute;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          background: rgba(59, 130, 246, 0.9);
+          color: white;
+          padding: 2px 6px;
+          border-radius: 3px;
+          font-family: monospace;
+          font-size: 11px;
+          font-weight: bold;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.3);
+          pointer-events: none;
+          white-space: nowrap;
+          will-change: transform;
+          contain: layout style paint;
         `;
                 this.overlayContainer.appendChild(border);
                 this.overlayContainer.appendChild(label);

package/packages/core/dist/snapshot.js

@@ -723,6 +723,53 @@ function getSectionName(element) {
     }
     return '';
 }
+/**
+ * Create head snapshot - lightweight HTTP HEAD-style page overview
+ * Returns page metadata without DOM traversal for fast verification
+ */
+function createHeadSnapshot(document, _refMap, options) {
+    const { root = document.body } = options;
+    const win = document.defaultView || window;
+    // Count elements (lightweight - no deep traversal)
+    const allElements = root.querySelectorAll('*');
+    const interactiveSelector = 'button, a[href], input, textarea, select, [role="button"], [tabindex]:not([tabindex="-1"])';
+    const interactiveElements = root.querySelectorAll(interactiveSelector);
+    // Page status detection
+    const viewportArea = win.innerWidth * win.innerHeight;
+    const hasInteractive = interactiveElements.length > 0;
+    const isComplete = document.readyState === 'complete';
+    let status = 'loading';
+    if (viewportArea === 0) {
+        status = 'loading';
+    }
+    else if (!hasInteractive) {
+        status = 'empty';
+    }
+    else if (isComplete) {
+        status = 'ready';
+    }
+    else {
+        status = 'interactive';
+    }
+    // Build output
+    const output = [
+        `URL: ${document.location?.href || 'about:blank'}`,
+        `TITLE: ${document.title || 'Untitled'}`,
+        `VIEWPORT: ${win.innerWidth}x${win.innerHeight}`,
+        `STATUS: ${status}`,
+        `ELEMENTS: total=${allElements.length} interactive=${interactiveElements.length}`,
+        `READY_STATE: ${document.readyState}`
+    ].join('\n');
+    return {
+        tree: output,
+        refs: {}, // No refs in head mode
+        metadata: {
+            totalInteractiveElements: interactiveElements.length,
+            capturedElements: 0,
+            quality: 'high'
+        }
+    };
+}
 /**
  * Create outline snapshot - structural overview with metadata
  */
@@ -1219,6 +1266,9 @@ export function createSnapshot(document, refMap, options = {}) {
     const { root = document.body, maxDepth = 50, includeHidden = false, mode = 'interactive', format = 'tree', grep: grepPattern } = options;
     // Dispatch based on mode
     const effectiveMode = mode;
+    if (effectiveMode === 'head') {
+        return createHeadSnapshot(document, refMap, { ...options, root });
+    }
     if (effectiveMode === 'outline') {
         return createOutlineSnapshot(document, refMap, { ...options, root });
     }

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

@@ -96,7 +96,7 @@ export interface GrepOptions {
 /**
  * Snapshot mode determines what content to capture
  */
-export type SnapshotMode = 'interactive' | 'outline' | 'content';
+export type SnapshotMode = 'interactive' | 'outline' | 'content' | 'head';
 /**
  * Snapshot output format
  */
@@ -115,6 +115,7 @@ export interface SnapshotCommand extends BaseCommand {
     baseSnapshot?: SnapshotData;
     /**
      * Snapshot mode:
+     * - 'head': Lightweight page overview (URL, title, element counts, status)
      * - 'interactive': Find clickable elements (default)
      * - 'outline': Understand page structure with xpaths + metadata
      * - 'content': Extract text content from sections

package/packages/extension/dist/background.js

@@ -446,7 +446,7 @@ export class BackgroundAgent {
                     resolve({
                         id: command.id,
                         success: false,
-                        error: chrome.runtime.lastError.message || 'Failed to send message to tab',
+                        error: chrome.runtime.lastError?.message || 'Failed to send message to tab',
                     });
                 }
                 else if (!response) {

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

@@ -40,6 +40,7 @@
  * ```
  */
 import type { Command, Response } from './types.js';
+import type { Transport } from './transport/types.js';
 import { BackgroundAgent as _BackgroundAgent, getBackgroundAgent as _getBackgroundAgent, setupMessageListener as _setupMessageListener, BrowserAgent as _BrowserAgent, getBrowserAgent as _getBrowserAgent } from './background.js';
 export * from './types.js';
 export { createScriptMessenger, createMethodMessenger, type MessageDefinitions, type ScriptMessenger, type MethodMessenger, type ScriptMessengerOptions, type PayloadOf, type ResultOf, } from './script-messenger.js';
@@ -47,6 +48,7 @@ export { createRemoteAgent, getBrowserToolDefinitions, mapToolToCommand, formatR
 export { _BackgroundAgent as BackgroundAgent, _getBackgroundAgent as getBackgroundAgent, _setupMessageListener as setupMessageListener, _BrowserAgent as BrowserAgent, _getBrowserAgent as getBrowserAgent, };
 export { createContentAgent, type ContentAgent } from '../../core/dist/index.js';
 export type { SnapshotData, BoundingBox, Modifier, } from '../../core/dist/index.js';
+export * from './transport/index.js';
 /**
  * Client for sending commands to the extension background script
  */
@@ -147,6 +149,24 @@ export interface Client {
      */
     evaluate(expression: string): Promise<unknown>;
 }
+/**
+ * Options for creating a client
+ */
+export interface CreateClientOptions {
+    /**
+     * Transport to use for sending commands.
+     * Defaults to ChromeExtensionTransport.
+     *
+     * @example Using direct transport in background script:
+     * ```typescript
+     * import { createClient, createDirectTransport, getBackgroundAgent } from '@btcp/browser-agent/extension';
+     *
+     * const transport = createDirectTransport({ agent: getBackgroundAgent() });
+     * const client = createClient({ transport });
+     * ```
+     */
+    transport?: Transport;
+}
 /**
  * Generate a unique command ID for BTCP commands
  */
@@ -154,24 +174,31 @@ export declare function generateCommandId(): string;
 /**
  * Create a client for communicating with the extension
  *
- * This function works in both popup/content scripts and background scripts:
- * - In popup/content scripts: Uses chrome.runtime.sendMessage to communicate with background
- * - In background scripts: Uses BackgroundAgent directly for better performance
+ * By default uses ChromeExtensionTransport for popup/content script contexts.
+ * Pass a custom transport for different communication mechanisms.
  *
- * @example Popup usage:
+ * @example Default (Chrome Extension):
  * ```typescript
  * import { createClient } from '@btcp/browser-agent/extension';
  * const client = createClient();
  * await client.navigate('https://example.com');
  * ```
  *
- * @example Background script usage:
+ * @example With explicit transport:
  * ```typescript
- * import { createClient } from '@btcp/browser-agent/extension';
- * const client = createClient();
- * // Works the same way - commands go directly to BackgroundAgent
- * await client.navigate('https://example.com');
+ * import { createClient, createChromeExtensionTransport } from '@btcp/browser-agent/extension';
+ *
+ * const transport = createChromeExtensionTransport({ debug: true });
+ * const client = createClient({ transport });
+ * ```
+ *
+ * @example Direct transport (background script):
+ * ```typescript
+ * import { createClient, createDirectTransport, getBackgroundAgent } from '@btcp/browser-agent/extension';
+ *
+ * const transport = createDirectTransport({ agent: getBackgroundAgent() });
+ * const client = createClient({ transport });
  * ```
  */
-export declare function createClient(): Client;
+export declare function createClient(options?: CreateClientOptions): Client;
 //# sourceMappingURL=index.d.ts.map

package/packages/extension/dist/index.js

@@ -39,6 +39,7 @@
  * await client.click('@ref:5');
  * ```
  */
+import { ChromeExtensionTransport } from './transport/chrome-extension.js';
 // Import for local use (and re-export below)
 import { BackgroundAgent as _BackgroundAgent, getBackgroundAgent as _getBackgroundAgent, setupMessageListener as _setupMessageListener, BrowserAgent as _BrowserAgent, getBrowserAgent as _getBrowserAgent, } from './background.js';
 export * from './types.js';
@@ -52,6 +53,8 @@ export { _BackgroundAgent as BackgroundAgent, _getBackgroundAgent as getBackgrou
 _BrowserAgent as BrowserAgent, _getBrowserAgent as getBrowserAgent, };
 // Re-export ContentAgent for content script usage
 export { createContentAgent } from '../../core/dist/index.js';
+// Re-export transport module
+export * from './transport/index.js';
 let commandIdCounter = 0;
 /**
  * Generate a unique command ID for BTCP commands
@@ -59,79 +62,41 @@ let commandIdCounter = 0;
 export function generateCommandId() {
     return `cmd_${Date.now()}_${commandIdCounter++}`;
 }
-/**
- * Check if we're running in a background/service worker context
- */
-function isBackgroundContext() {
-    // In Manifest V3, background scripts run as service workers
-    return typeof ServiceWorkerGlobalScope !== 'undefined' && self instanceof ServiceWorkerGlobalScope;
-}
 /**
  * Create a client for communicating with the extension
  *
- * This function works in both popup/content scripts and background scripts:
- * - In popup/content scripts: Uses chrome.runtime.sendMessage to communicate with background
- * - In background scripts: Uses BackgroundAgent directly for better performance
+ * By default uses ChromeExtensionTransport for popup/content script contexts.
+ * Pass a custom transport for different communication mechanisms.
  *
- * @example Popup usage:
+ * @example Default (Chrome Extension):
  * ```typescript
  * import { createClient } from '@btcp/browser-agent/extension';
  * const client = createClient();
  * await client.navigate('https://example.com');
  * ```
  *
- * @example Background script usage:
+ * @example With explicit transport:
  * ```typescript
- * import { createClient } from '@btcp/browser-agent/extension';
- * const client = createClient();
- * // Works the same way - commands go directly to BackgroundAgent
- * await client.navigate('https://example.com');
+ * import { createClient, createChromeExtensionTransport } from '@btcp/browser-agent/extension';
+ *
+ * const transport = createChromeExtensionTransport({ debug: true });
+ * const client = createClient({ transport });
+ * ```
+ *
+ * @example Direct transport (background script):
+ * ```typescript
+ * import { createClient, createDirectTransport, getBackgroundAgent } from '@btcp/browser-agent/extension';
+ *
+ * const transport = createDirectTransport({ agent: getBackgroundAgent() });
+ * const client = createClient({ transport });
  * ```
  */
-export function createClient() {
-    // Detect if we're in background context
-    const inBackground = isBackgroundContext();
-    // Lazily get the background agent to avoid circular dependency issues
-    let bgAgent = null;
-    function getAgent() {
-        if (!bgAgent) {
-            // Use the singleton getter from background.js
-            bgAgent = _getBackgroundAgent();
-        }
-        return bgAgent;
-    }
+export function createClient(options = {}) {
+    // Default to Chrome extension transport
+    const transport = options.transport ?? new ChromeExtensionTransport();
     async function sendCommand(command) {
-        // In background context, use BackgroundAgent directly
-        if (inBackground) {
-            return getAgent().execute(command);
-        }
-        // In popup/content context, use message passing
         const id = command.id || generateCommandId();
-        return new Promise((resolve) => {
-            chrome.runtime.sendMessage({ type: 'btcp:command', command: { ...command, id } }, (response) => {
-                if (chrome.runtime.lastError) {
-                    resolve({
-                        id,
-                        success: false,
-                        error: chrome.runtime.lastError.message || 'Unknown error',
-                    });
-                }
-                else {
-                    const resp = response;
-                    if (resp.type === 'btcp:response') {
-                        resolve(resp.response);
-                    }
-                    else {
-                        // Unexpected pong response
-                        resolve({
-                            id,
-                            success: false,
-                            error: 'Unexpected response type',
-                        });
-                    }
-                }
-            });
-        });
+        return transport.send({ ...command, id });
     }
     function assertSuccess(response) {
         if (!response.success) {

package/packages/extension/dist/session-manager.d.ts

@@ -27,6 +27,7 @@ export declare class SessionManager {
     private initializationPromise;
     private maxSession;
     private maxOpenTab;
+    private ensureSessionPromise;
     constructor(options?: SessionManagerOptions);
     /**
      * Wait for SessionManager to finish initialization
@@ -62,8 +63,10 @@ export declare class SessionManager {
     reconnectSession(groupId: number): Promise<boolean>;
     /**
      * Create a new tab group
+     * @param options Group creation options
+     * @param internal If true, bypasses session limit check (used by ensureSession)
      */
-    createGroup(options?: GroupCreateOptions): Promise<GroupInfo>;
+    createGroup(options?: GroupCreateOptions, internal?: boolean): Promise<GroupInfo>;
     /**
      * Update an existing tab group
      */
@@ -136,8 +139,14 @@ export declare class SessionManager {
     /**
      * Ensure a session exists - restore from storage, use existing, or create new
      * Returns the session group ID (creates if needed)
+     *
+     * This method is atomic - concurrent calls will wait for the same promise
      */
     ensureSession(): Promise<number>;
+    /**
+     * Internal implementation of ensureSession
+     */
+    private _doEnsureSession;
     /**
      * Get the primary tab in session (ensures session exists first)
      * Returns the first tab in the session group