btcp-browser-agent 0.1.16 → 0.1.17

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 browser-tool-calling-protocol
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 browser-tool-calling-protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,338 +1,338 @@
-# btcp-browser-agent
-
-Give AI agents the power to see and control any browser.
-
-A lightweight foundation for building AI systems that need browser access — automation, testing, web agents, or any browser-based workflow.
-
-## Why This Package?
-
-AI agents struggle with browsers because:
-- Raw HTML is too noisy (thousands of nodes)
-- CSS selectors break when layouts change
-- No stable way to reference elements across turns
-
-**Browser Agent solves this with smart snapshots:**
-
-```
-BUTTON "Submit" [@ref:0]
-TEXTBOX "Email" [required] [@ref:1]
-LINK "Forgot password?" [@ref:2]
-```
-
-One command gives your agent a clean, semantic view of any page. Stable `@ref` markers let it interact without fragile selectors.
-
-## Features
-
-- **Smart Snapshots** - Accessibility tree format optimized for AI comprehension
-- **Stable Element Refs** - `@ref:N` markers that survive DOM changes within a session
-- **Full Browser Control** - Navigation, tabs, screenshots, keyboard/mouse
-- **46 DOM Actions** - Click, type, fill, scroll, hover, and more
-- **Two Modes** - Chrome extension (full control) or standalone (same-origin)
-
-## Quick Example
-
-```typescript
-import { createClient } from 'btcp-browser-agent/extension';
-
-const agent = createClient();
-
-// Navigate and understand the page
-await agent.navigate('https://example.com');
-const snapshot = await agent.snapshot();
-// Returns: BUTTON "Login" [@ref:0], TEXTBOX "Email" [@ref:1], ...
-
-// Interact using refs - no CSS selectors needed
-await agent.fill('@ref:1', 'user@example.com');
-await agent.click('@ref:0');
-```
-
-## Use Cases
-
-- **AI Assistants** - Let LLMs browse the web and complete tasks for users
-- **Browser Agents** - Foundation for autonomous web agents that research, navigate, and act
-- **Automated Testing** - Reliable UI tests with stable element refs that don't break on layout changes
-- **Web Automation** - Form filling, data extraction, multi-step workflow automation
-- **Web Scraping** - Extract structured data with semantic understanding of page content
-
-## Installation
-
-```bash
-npm install btcp-browser-agent
-```
-
-## Usage Modes
-
-### Extension Mode (Full Browser Control)
-
-For Chrome extensions with cross-origin access, tab management, and screenshots.
-
-**Background Script:**
-```typescript
-import { BackgroundAgent, setupMessageListener } from 'btcp-browser-agent/extension';
-
-// Option 1: Just set up message routing
-setupMessageListener();
-
-// Option 2: Use BackgroundAgent directly for programmatic control
-const agent = new BackgroundAgent();
-await agent.navigate('https://example.com');
-await agent.screenshot();
-```
-
-**Content Script:**
-```typescript
-import { createContentAgent } from 'btcp-browser-agent';
-
-const agent = createContentAgent();
-
-// Take a snapshot
-const { data } = await agent.execute({ action: 'snapshot' });
-console.log(data.tree);  // Accessibility tree with refs
-
-// Click an element using ref from snapshot
-await agent.execute({ action: 'click', selector: '@ref:5' });
-```
-
-**Popup (sending commands via messaging):**
-```typescript
-import { createClient } from 'btcp-browser-agent';
-
-const client = createClient();
-
-// Navigate and interact
-await client.navigate('https://example.com');
-const snapshot = await client.snapshot();
-await client.click('@ref:5');
-const screenshot = await client.screenshot();
-```
-
-### Standalone Mode (No Extension)
-
-For use directly in a web page (limited to same-origin, no tab management):
-
-```typescript
-import { createContentAgent } from 'btcp-browser-agent';
-
-const agent = createContentAgent();
-
-// Take a snapshot
-const { data } = await agent.execute({ action: 'snapshot' });
-
-// Interact with elements
-await agent.execute({ action: 'click', selector: '@ref:5' });
-await agent.execute({ action: 'fill', selector: '@ref:3', value: 'Hello' });
-```
-
-## API Reference
-
-### BackgroundAgent (Extension Background Script)
-
-High-level browser orchestrator that runs in the extension's background script.
-
-```typescript
-import { BackgroundAgent } from 'btcp-browser-agent/extension';
-
-const agent = new BackgroundAgent();
-
-// Tab Management
-await agent.newTab({ url: 'https://example.com' });
-await agent.switchTab(tabId);
-await agent.closeTab(tabId);
-const tabs = await agent.listTabs();
-
-// Navigation
-await agent.navigate('https://example.com');
-await agent.back();
-await agent.forward();
-await agent.reload();
-
-// Screenshots
-const screenshot = await agent.screenshot({ format: 'png' });
-
-// Execute commands (routes to ContentAgent for DOM operations)
-await agent.execute({ action: 'click', selector: '#submit' });
-```
-
-#### Multi-Tab Operations
-
-```typescript
-// Open tabs
-const tab1 = await agent.newTab({ url: 'https://google.com' });
-const tab2 = await agent.newTab({ url: 'https://github.com', active: false });
-
-// Method 1: tab() handle - interact without switching
-const githubTab = agent.tab(tab2.id);
-await githubTab.snapshot();
-await githubTab.click('@ref:5');
-
-// Method 2: Specify tabId in execute
-await agent.execute(
-  { action: 'getText', selector: 'h1' },
-  { tabId: tab2.id }
-);
-
-// Active tab stays tab1 (no switching needed)
-```
-
-### ContentAgent (Content Script)
-
-DOM automation agent that runs in content scripts or web pages.
-
-```typescript
-import { createContentAgent } from 'btcp-browser-agent';
-
-const agent = createContentAgent();
-
-// Execute commands
-const response = await agent.execute({ action: 'snapshot' });
-```
-
-#### Available Actions
-
-**DOM Reading:**
-| Action | Description |
-|--------|-------------|
-| `snapshot` | Get accessibility tree with element refs |
-| `getText` | Get element text content |
-| `getAttribute` | Get element attribute value |
-| `isVisible` | Check if element is visible |
-| `isEnabled` | Check if element is enabled |
-| `isChecked` | Check if checkbox/radio is checked |
-| `getBoundingBox` | Get element dimensions |
-
-**Element Interaction:**
-| Action | Description |
-|--------|-------------|
-| `click` | Click an element |
-| `dblclick` | Double-click an element |
-| `type` | Type text (keystroke by keystroke) |
-| `fill` | Fill input (instant) |
-| `clear` | Clear input value |
-| `check` | Check checkbox |
-| `uncheck` | Uncheck checkbox |
-| `select` | Select dropdown option |
-| `hover` | Hover over element |
-| `focus` | Focus element |
-| `blur` | Remove focus |
-
-**Keyboard/Mouse:**
-| Action | Description |
-|--------|-------------|
-| `press` | Press a key |
-| `keyDown` | Key down event |
-| `keyUp` | Key up event |
-
-**Other:**
-| Action | Description |
-|--------|-------------|
-| `scroll` | Scroll page or element |
-| `scrollIntoView` | Scroll element into view |
-| `wait` | Wait for element state |
-| `evaluate` | Execute JavaScript |
-
-### Element Refs
-
-The `snapshot` action returns element references for stable selection:
-
-```typescript
-const { data } = await agent.execute({ action: 'snapshot' });
-// data.tree: "BUTTON 'Submit' [@ref:5]\nTEXTBOX 'Email' [@ref:3]"
-
-// Use refs in subsequent commands
-await agent.execute({ action: 'click', selector: '@ref:5' });
-```
-
-### Script Injection
-
-Inject custom JavaScript into the page's main world and communicate with it:
-
-```typescript
-// Inject a helper script
-await client.scriptInject(`
-  window.addEventListener('message', (e) => {
-    if (e.data?.type === 'btcp:script-command') {
-      const { commandId, payload } = e.data;
-      // Handle command and respond
-      window.postMessage({
-        type: 'btcp:script-ack',
-        commandId,
-        result: { /* your data */ }
-      }, '*');
-    }
-  });
-`, { scriptId: 'helper' });
-
-// Send commands to injected script
-const result = await client.scriptSend(
-  { action: 'getData', id: '123' },
-  { scriptId: 'helper' }
-);
-```
-
-**Why script injection?**
-- Access page-level APIs (fetch with page cookies, window globals)
-- Interact with page frameworks (React state, etc.)
-- Execute code with full page context
-
-## Architecture
-
-The package provides a clean separation between browser-level and DOM-level operations:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Background Script (Extension Service Worker)                    │
-│  ┌─────────────────────────────────────────────────────────────┐│
-│  │ BackgroundAgent                                              ││
-│  │  - Tab management (create, close, switch, list)             ││
-│  │  - Navigation (goto, back, forward, reload)                 ││
-│  │  - Screenshots (chrome.tabs.captureVisibleTab)              ││
-│  │  - Routes DOM commands → ContentAgent                       ││
-│  └─────────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────────┘
-                              │
-            chrome.tabs.sendMessage
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Content Script (Per Tab)                                        │
-│  ┌─────────────────────────────────────────────────────────────┐│
-│  │ ContentAgent                                                 ││
-│  │  - DOM snapshot (accessibility tree)                        ││
-│  │  - Element interaction (click, type, fill, hover)           ││
-│  │  - DOM queries (getText, getAttribute, isVisible)           ││
-│  │  - Keyboard/mouse events                                    ││
-│  └─────────────────────────────────────────────────────────────┘│
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Package Structure
-
-```
-btcp-browser-agent/
-├── @btcp/core          # ContentAgent - DOM operations
-│   ├── createContentAgent()
-│   ├── DOMActions
-│   └── createSnapshot()
-│
-├── @btcp/extension     # BackgroundAgent - Browser operations
-│   ├── BackgroundAgent
-│   ├── setupMessageListener()
-│   └── createClient()
-│
-└── btcp-browser-agent   # Main package - re-exports both
-```
-
-## Capabilities Comparison
-
-| Capability | ContentAgent (Standalone) | BackgroundAgent (Extension) |
-|------------|--------------------------|--------------------------|
-| DOM Snapshot | Yes | Yes (via ContentAgent) |
-| Element Clicks | Yes | Yes (via ContentAgent) |
-| Form Filling | Yes | Yes (via ContentAgent) |
-| Cross-origin | Same-origin only | Any page |
-| Tab Management | No | Yes |
-| Navigation | No | Yes |
-| Screenshots | No | Yes |
-
-## License
-
-Apache-2.0
+# btcp-browser-agent
+
+Give AI agents the power to see and control any browser.
+
+A lightweight foundation for building AI systems that need browser access — automation, testing, web agents, or any browser-based workflow.
+
+## Why This Package?
+
+AI agents struggle with browsers because:
+- Raw HTML is too noisy (thousands of nodes)
+- CSS selectors break when layouts change
+- No stable way to reference elements across turns
+
+**Browser Agent solves this with smart snapshots:**
+
+```
+BUTTON "Submit" [@ref:0]
+TEXTBOX "Email" [required] [@ref:1]
+LINK "Forgot password?" [@ref:2]
+```
+
+One command gives your agent a clean, semantic view of any page. Stable `@ref` markers let it interact without fragile selectors.
+
+## Features
+
+- **Smart Snapshots** - Accessibility tree format optimized for AI comprehension
+- **Stable Element Refs** - `@ref:N` markers that survive DOM changes within a session
+- **Full Browser Control** - Navigation, tabs, screenshots, keyboard/mouse
+- **46 DOM Actions** - Click, type, fill, scroll, hover, and more
+- **Two Modes** - Chrome extension (full control) or standalone (same-origin)
+
+## Quick Example
+
+```typescript
+import { createClient } from 'btcp-browser-agent/extension';
+
+const agent = createClient();
+
+// Navigate and understand the page
+await agent.navigate('https://example.com');
+const snapshot = await agent.snapshot();
+// Returns: BUTTON "Login" [@ref:0], TEXTBOX "Email" [@ref:1], ...
+
+// Interact using refs - no CSS selectors needed
+await agent.fill('@ref:1', 'user@example.com');
+await agent.click('@ref:0');
+```
+
+## Use Cases
+
+- **AI Assistants** - Let LLMs browse the web and complete tasks for users
+- **Browser Agents** - Foundation for autonomous web agents that research, navigate, and act
+- **Automated Testing** - Reliable UI tests with stable element refs that don't break on layout changes
+- **Web Automation** - Form filling, data extraction, multi-step workflow automation
+- **Web Scraping** - Extract structured data with semantic understanding of page content
+
+## Installation
+
+```bash
+npm install btcp-browser-agent
+```
+
+## Usage Modes
+
+### Extension Mode (Full Browser Control)
+
+For Chrome extensions with cross-origin access, tab management, and screenshots.
+
+**Background Script:**
+```typescript
+import { BackgroundAgent, setupMessageListener } from 'btcp-browser-agent/extension';
+
+// Option 1: Just set up message routing
+setupMessageListener();
+
+// Option 2: Use BackgroundAgent directly for programmatic control
+const agent = new BackgroundAgent();
+await agent.navigate('https://example.com');
+await agent.screenshot();
+```
+
+**Content Script:**
+```typescript
+import { createContentAgent } from 'btcp-browser-agent';
+
+const agent = createContentAgent();
+
+// Take a snapshot
+const { data } = await agent.execute({ action: 'snapshot' });
+console.log(data.tree);  // Accessibility tree with refs
+
+// Click an element using ref from snapshot
+await agent.execute({ action: 'click', selector: '@ref:5' });
+```
+
+**Popup (sending commands via messaging):**
+```typescript
+import { createClient } from 'btcp-browser-agent';
+
+const client = createClient();
+
+// Navigate and interact
+await client.navigate('https://example.com');
+const snapshot = await client.snapshot();
+await client.click('@ref:5');
+const screenshot = await client.screenshot();
+```
+
+### Standalone Mode (No Extension)
+
+For use directly in a web page (limited to same-origin, no tab management):
+
+```typescript
+import { createContentAgent } from 'btcp-browser-agent';
+
+const agent = createContentAgent();
+
+// Take a snapshot
+const { data } = await agent.execute({ action: 'snapshot' });
+
+// Interact with elements
+await agent.execute({ action: 'click', selector: '@ref:5' });
+await agent.execute({ action: 'fill', selector: '@ref:3', value: 'Hello' });
+```
+
+## API Reference
+
+### BackgroundAgent (Extension Background Script)
+
+High-level browser orchestrator that runs in the extension's background script.
+
+```typescript
+import { BackgroundAgent } from 'btcp-browser-agent/extension';
+
+const agent = new BackgroundAgent();
+
+// Tab Management
+await agent.newTab({ url: 'https://example.com' });
+await agent.switchTab(tabId);
+await agent.closeTab(tabId);
+const tabs = await agent.listTabs();
+
+// Navigation
+await agent.navigate('https://example.com');
+await agent.back();
+await agent.forward();
+await agent.reload();
+
+// Screenshots
+const screenshot = await agent.screenshot({ format: 'png' });
+
+// Execute commands (routes to ContentAgent for DOM operations)
+await agent.execute({ action: 'click', selector: '#submit' });
+```
+
+#### Multi-Tab Operations
+
+```typescript
+// Open tabs
+const tab1 = await agent.newTab({ url: 'https://google.com' });
+const tab2 = await agent.newTab({ url: 'https://github.com', active: false });
+
+// Method 1: tab() handle - interact without switching
+const githubTab = agent.tab(tab2.id);
+await githubTab.snapshot();
+await githubTab.click('@ref:5');
+
+// Method 2: Specify tabId in execute
+await agent.execute(
+  { action: 'getText', selector: 'h1' },
+  { tabId: tab2.id }
+);
+
+// Active tab stays tab1 (no switching needed)
+```
+
+### ContentAgent (Content Script)
+
+DOM automation agent that runs in content scripts or web pages.
+
+```typescript
+import { createContentAgent } from 'btcp-browser-agent';
+
+const agent = createContentAgent();
+
+// Execute commands
+const response = await agent.execute({ action: 'snapshot' });
+```
+
+#### Available Actions
+
+**DOM Reading:**
+| Action | Description |
+|--------|-------------|
+| `snapshot` | Get accessibility tree with element refs |
+| `getText` | Get element text content |
+| `getAttribute` | Get element attribute value |
+| `isVisible` | Check if element is visible |
+| `isEnabled` | Check if element is enabled |
+| `isChecked` | Check if checkbox/radio is checked |
+| `getBoundingBox` | Get element dimensions |
+
+**Element Interaction:**
+| Action | Description |
+|--------|-------------|
+| `click` | Click an element |
+| `dblclick` | Double-click an element |
+| `type` | Type text (keystroke by keystroke) |
+| `fill` | Fill input (instant) |
+| `clear` | Clear input value |
+| `check` | Check checkbox |
+| `uncheck` | Uncheck checkbox |
+| `select` | Select dropdown option |
+| `hover` | Hover over element |
+| `focus` | Focus element |
+| `blur` | Remove focus |
+
+**Keyboard/Mouse:**
+| Action | Description |
+|--------|-------------|
+| `press` | Press a key |
+| `keyDown` | Key down event |
+| `keyUp` | Key up event |
+
+**Other:**
+| Action | Description |
+|--------|-------------|
+| `scroll` | Scroll page or element |
+| `scrollIntoView` | Scroll element into view |
+| `wait` | Wait for element state |
+| `evaluate` | Execute JavaScript |
+
+### Element Refs
+
+The `snapshot` action returns element references for stable selection:
+
+```typescript
+const { data } = await agent.execute({ action: 'snapshot' });
+// data.tree: "BUTTON 'Submit' [@ref:5]\nTEXTBOX 'Email' [@ref:3]"
+
+// Use refs in subsequent commands
+await agent.execute({ action: 'click', selector: '@ref:5' });
+```
+
+### Script Injection
+
+Inject custom JavaScript into the page's main world and communicate with it:
+
+```typescript
+// Inject a helper script
+await client.scriptInject(`
+  window.addEventListener('message', (e) => {
+    if (e.data?.type === 'btcp:script-command') {
+      const { commandId, payload } = e.data;
+      // Handle command and respond
+      window.postMessage({
+        type: 'btcp:script-ack',
+        commandId,
+        result: { /* your data */ }
+      }, '*');
+    }
+  });
+`, { scriptId: 'helper' });
+
+// Send commands to injected script
+const result = await client.scriptSend(
+  { action: 'getData', id: '123' },
+  { scriptId: 'helper' }
+);
+```
+
+**Why script injection?**
+- Access page-level APIs (fetch with page cookies, window globals)
+- Interact with page frameworks (React state, etc.)
+- Execute code with full page context
+
+## Architecture
+
+The package provides a clean separation between browser-level and DOM-level operations:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Background Script (Extension Service Worker)                    │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │ BackgroundAgent                                              ││
+│  │  - Tab management (create, close, switch, list)             ││
+│  │  - Navigation (goto, back, forward, reload)                 ││
+│  │  - Screenshots (chrome.tabs.captureVisibleTab)              ││
+│  │  - Routes DOM commands → ContentAgent                       ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+                              │
+            chrome.tabs.sendMessage
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Content Script (Per Tab)                                        │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │ ContentAgent                                                 ││
+│  │  - DOM snapshot (accessibility tree)                        ││
+│  │  - Element interaction (click, type, fill, hover)           ││
+│  │  - DOM queries (getText, getAttribute, isVisible)           ││
+│  │  - Keyboard/mouse events                                    ││
+│  └─────────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Package Structure
+
+```
+btcp-browser-agent/
+├── @btcp/core          # ContentAgent - DOM operations
+│   ├── createContentAgent()
+│   ├── DOMActions
+│   └── createSnapshot()
+│
+├── @btcp/extension     # BackgroundAgent - Browser operations
+│   ├── BackgroundAgent
+│   ├── setupMessageListener()
+│   └── createClient()
+│
+└── btcp-browser-agent   # Main package - re-exports both
+```
+
+## Capabilities Comparison
+
+| Capability | ContentAgent (Standalone) | BackgroundAgent (Extension) |
+|------------|--------------------------|--------------------------|
+| DOM Snapshot | Yes | Yes (via ContentAgent) |
+| Element Clicks | Yes | Yes (via ContentAgent) |
+| Form Filling | Yes | Yes (via ContentAgent) |
+| Cross-origin | Same-origin only | Any page |
+| Tab Management | No | Yes |
+| Navigation | No | Yes |
+| Screenshots | No | Yes |
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "btcp-browser-agent",
-  "version": "0.1.16",
-  "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/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

package/packages/extension/dist/session-manager.js

@@ -15,6 +15,7 @@ export class SessionManager {
     initializationPromise;
     maxSession;
     maxOpenTab;
+    ensureSessionPromise = null;
     constructor(options = {}) {
         this.maxSession = options.maxSession ?? 1;
         this.maxOpenTab = options.maxOpenTab ?? 1;
@@ -222,17 +223,21 @@ export class SessionManager {
     }
     /**
      * Create a new tab group
+     * @param options Group creation options
+     * @param internal If true, bypasses session limit check (used by ensureSession)
      */
-    async createGroup(options = {}) {
+    async createGroup(options = {}, internal = false) {
         // Wait for initialization to complete first
         await this.waitForInitialization();
-        console.log('[SessionManager] createGroup called with options:', options);
-        // Check if we can create a new session
-        const canCreate = await this.canCreateSession();
-        if (!canCreate) {
-            const count = await this.getSessionCount();
-            throw new Error(`Maximum session limit reached (${count}/${this.maxSession}). ` +
-                `Close an existing session before creating a new one.`);
+        console.log('[SessionManager] createGroup called with options:', options, 'internal:', internal);
+        // Check if we can create a new session (skip if internal call from ensureSession)
+        if (!internal) {
+            const canCreate = await this.canCreateSession();
+            if (!canCreate) {
+                const count = await this.getSessionCount();
+                throw new Error(`Maximum session limit reached (${count}/${this.maxSession}). ` +
+                    `Close an existing session before creating a new one.`);
+            }
         }
         const { tabIds = [], title = this.generateSessionName(), color = 'blue', collapsed = false, } = options;
         // If no tabIds provided, create a new blank tab for the session
@@ -512,18 +517,42 @@ export 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
      */
     async ensureSession() {
+        // Return existing promise if already in progress
+        if (this.ensureSessionPromise) {
+            console.log('[SessionManager] ensureSession already in progress, waiting...');
+            return this.ensureSessionPromise;
+        }
+        // Create new promise and store it
+        this.ensureSessionPromise = this._doEnsureSession();
+        try {
+            return await this.ensureSessionPromise;
+        }
+        finally {
+            // Clear promise when done
+            this.ensureSessionPromise = null;
+        }
+    }
+    /**
+     * Internal implementation of ensureSession
+     */
+    async _doEnsureSession() {
         await this.waitForInitialization();
+        console.log('[SessionManager] Starting ensureSession...');
         // Step 1: Already have active session
         if (this.activeSessionGroupId !== null) {
             // Verify it still exists
             try {
                 await chrome.tabGroups.get(this.activeSessionGroupId);
+                console.log('[SessionManager] Active session still valid:', this.activeSessionGroupId);
                 return this.activeSessionGroupId;
             }
             catch {
                 // Group no longer exists, continue to restore/create
+                console.log('[SessionManager] Active session no longer exists');
                 this.activeSessionGroupId = null;
             }
         }
@@ -531,23 +560,33 @@ export class SessionManager {
         const result = await chrome.storage.session.get(SESSION_STORAGE_KEY);
         const stored = result[SESSION_STORAGE_KEY];
         if (stored?.groupId) {
+            console.log('[SessionManager] Step 2: Attempting to reconnect to stored session:', stored.groupId);
             const reconnected = await this.reconnectSession(stored.groupId);
             if (reconnected && this.activeSessionGroupId !== null) {
+                console.log('[SessionManager] Reconnected to stored session:', this.activeSessionGroupId);
                 return this.activeSessionGroupId;
             }
         }
         // Step 3: Find existing BTCP group
+        console.log('[SessionManager] Step 3: Looking for existing BTCP groups...');
         const groups = await chrome.tabGroups.query({});
+        console.log('[SessionManager] Found tab groups:', groups.map(g => ({ id: g.id, title: g.title })));
         const btcpGroup = groups.find(g => g.title?.startsWith('BTCP'));
         if (btcpGroup) {
+            console.log('[SessionManager] Found existing BTCP group:', btcpGroup.id, btcpGroup.title);
             const used = await this.useExistingGroupAsSession(btcpGroup.id);
             if (used && this.activeSessionGroupId !== null) {
+                console.log('[SessionManager] Successfully reused existing session:', this.activeSessionGroupId);
                 return this.activeSessionGroupId;
             }
         }
-        // Step 4: Create new session
+        else {
+            console.log('[SessionManager] No existing BTCP groups found');
+        }
+        // Step 4: Create new session (bypass limit check since we already tried to reuse)
         console.log('[SessionManager] No existing session found, creating new one...');
-        const newGroup = await this.createGroup({ color: 'blue' });
+        const newGroup = await this.createGroup({ color: 'blue' }, true); // internal=true bypasses limit
+        console.log('[SessionManager] Created new session:', newGroup.id);
         return newGroup.id;
     }
     /**