btcp-browser-agent 0.1.4 → 0.1.6

package/README.md

@@ -86,11 +86,11 @@ import { createContentAgent } from 'btcp-browser-agent';
 const agent = createContentAgent();
 
 // Take a snapshot
-const { data } = await agent.execute({ id: '1', action: '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({ id: '2', action: 'click', selector: '@ref:5' });
+await agent.execute({ action: 'click', selector: '@ref:5' });
 ```
 
 **Popup (sending commands via messaging):**
@@ -116,11 +116,11 @@ import { createContentAgent } from 'btcp-browser-agent';
 const agent = createContentAgent();
 
 // Take a snapshot
-const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+const { data } = await agent.execute({ action: 'snapshot' });
 
 // Interact with elements
-await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
-await agent.execute({ id: '3', action: 'fill', selector: '@ref:3', value: 'Hello' });
+await agent.execute({ action: 'click', selector: '@ref:5' });
+await agent.execute({ action: 'fill', selector: '@ref:3', value: 'Hello' });
 ```
 
 ## API Reference
@@ -150,7 +150,7 @@ await agent.reload();
 const screenshot = await agent.screenshot({ format: 'png' });
 
 // Execute commands (routes to ContentAgent for DOM operations)
-await agent.execute({ id: '1', action: 'click', selector: '#submit' });
+await agent.execute({ action: 'click', selector: '#submit' });
 ```
 
 #### Multi-Tab Operations
@@ -167,7 +167,7 @@ await githubTab.click('@ref:5');
 
 // Method 2: Specify tabId in execute
 await agent.execute(
-  { id: '1', action: 'getText', selector: 'h1' },
+  { action: 'getText', selector: 'h1' },
   { tabId: tab2.id }
 );
 
@@ -184,10 +184,7 @@ import { createContentAgent } from 'btcp-browser-agent';
 const agent = createContentAgent();
 
 // Execute commands
-const response = await agent.execute({
-  id: 'cmd1',
-  action: 'snapshot'
-});
+const response = await agent.execute({ action: 'snapshot' });
 ```
 
 #### Available Actions
@@ -238,11 +235,11 @@ const response = await agent.execute({
 The `snapshot` action returns element references for stable selection:
 
 ```typescript
-const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+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({ id: '2', action: 'click', selector: '@ref:5' });
+await agent.execute({ action: 'click', selector: '@ref:5' });
 ```
 
 ## Architecture

package/dist/index.d.ts

@@ -25,10 +25,10 @@
  * ```typescript
  * import { createContentAgent } from '@btcp/browser-agent';
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  */
 export { createContentAgent, type ContentAgent, DOMActions, createSnapshot, createRefMap, createSimpleRefMap, type Command, type Response, type SnapshotData, type BoundingBox, type RefMap, type Modifier, } from '../packages/core/dist/index.js';
 export type { ExtensionMessage, ExtensionResponse, TabInfo, ChromeTab, ExtensionCommand, } from '../packages/extension/dist/index.js';
-export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, type Client, } from '../packages/extension/dist/index.js';
+export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, generateCommandId, type Client, BrowserAgent, getBrowserAgent, } from '../packages/extension/dist/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,11 +25,13 @@
  * ```typescript
  * import { createContentAgent } from '@btcp/browser-agent';
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  */
 // Re-export everything from core (for standalone usage)
 export { createContentAgent, DOMActions, createSnapshot, createRefMap, createSimpleRefMap, } from '../packages/core/dist/index.js';
 // Re-export extension functions
-export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, } from '../packages/extension/dist/index.js';
+export { BackgroundAgent, getBackgroundAgent, setupMessageListener, createClient, generateCommandId, 
+// Deprecated aliases for backwards compatibility
+BrowserAgent, getBrowserAgent, } from '../packages/extension/dist/index.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "btcp-browser-agent",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",

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

@@ -4,6 +4,10 @@
  * Element interaction handlers using native browser APIs.
  */
 import type { Command, Response, RefMap } from './types.js';
+/**
+ * Generate a unique command ID
+ */
+export declare function generateCommandId(): string;
 /**
  * DOM Actions executor
  */
@@ -18,6 +22,8 @@ export declare class DOMActions {
     constructor(doc: Document, win: Window, refMap: RefMap);
     /**
      * Execute a command and return a response
+     *
+     * The command ID is auto-generated internally - users don't need to provide it.
      */
     execute(command: Command): Promise<Response>;
     private dispatch;

package/packages/core/dist/actions.js

@@ -5,6 +5,14 @@
  */
 import { createSnapshot } from './snapshot.js';
 import { DetailedError, createElementNotFoundError, createElementNotCompatibleError, createTimeoutError, createInvalidParametersError, } from './errors.js';
+// Command ID counter for auto-generated IDs
+let commandIdCounter = 0;
+/**
+ * Generate a unique command ID
+ */
+export function generateCommandId() {
+    return `cmd_${Date.now()}_${commandIdCounter++}`;
+}
 /**
  * DOM Actions executor
  */
@@ -23,18 +31,22 @@ export class DOMActions {
     }
     /**
      * Execute a command and return a response
+     *
+     * The command ID is auto-generated internally - users don't need to provide it.
      */
     async execute(command) {
+        // Auto-generate ID if not provided
+        const id = command.id || generateCommandId();
         try {
             const data = await this.dispatch(command);
-            return { id: command.id, success: true, data };
+            return { id, success: true, data };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             // Include structured error data if available
             if (error instanceof DetailedError) {
                 return {
-                    id: command.id,
+                    id,
                     success: false,
                     error: message,
                     errorCode: error.code,
@@ -42,7 +54,7 @@ export class DOMActions {
                     suggestions: error.suggestions,
                 };
             }
-            return { id: command.id, success: false, error: message };
+            return { id, success: false, error: message };
         }
     }
     async dispatch(command) {

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

@@ -11,17 +11,10 @@
  * const agent = createContentAgent(document, window);
  *
  * // Take a snapshot
- * const snapshot = await agent.execute({
- *   id: '1',
- *   action: 'snapshot'
- * });
+ * const snapshot = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element
- * await agent.execute({
- *   id: '2',
- *   action: 'click',
- *   selector: '@ref:5'  // From snapshot
- * });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 import type { Command, Response, RefMap } from './types.js';
@@ -29,7 +22,7 @@ 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';
+export { DOMActions, generateCommandId } from './actions.js';
 /**
  * ContentAgent - DOM automation agent that runs in content script context
  *
@@ -83,10 +76,10 @@ export interface ContentAgent {
  * const agent = createContentAgent();
  *
  * // Take a snapshot of the page
- * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ * const { data } = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element using ref from snapshot
- * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 export declare function createContentAgent(doc?: Document, win?: Window): ContentAgent;

package/packages/core/dist/index.js

@@ -11,17 +11,10 @@
  * const agent = createContentAgent(document, window);
  *
  * // Take a snapshot
- * const snapshot = await agent.execute({
- *   id: '1',
- *   action: 'snapshot'
- * });
+ * const snapshot = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element
- * await agent.execute({
- *   id: '2',
- *   action: 'click',
- *   selector: '@ref:5'  // From snapshot
- * });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 import { DOMActions } from './actions.js';
@@ -30,7 +23,7 @@ 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';
+export { DOMActions, generateCommandId } from './actions.js';
 /**
  * Create a ContentAgent for DOM automation
  *
@@ -44,10 +37,10 @@ export { DOMActions } from './actions.js';
  * const agent = createContentAgent();
  *
  * // Take a snapshot of the page
- * const { data } = await agent.execute({ id: '1', action: 'snapshot' });
+ * const { data } = await agent.execute({ action: 'snapshot' });
  *
  * // Click an element using ref from snapshot
- * await agent.execute({ id: '2', action: 'click', selector: '@ref:5' });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  * ```
  */
 export function createContentAgent(doc = document, win = window) {

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

@@ -5,8 +5,14 @@
  */
 export type CoreAction = 'click' | 'dblclick' | 'type' | 'fill' | 'clear' | 'check' | 'uncheck' | 'select' | 'focus' | 'blur' | 'hover' | 'scroll' | 'scrollIntoView' | 'snapshot' | 'querySelector' | 'querySelectorAll' | 'getText' | 'getAttribute' | 'getProperty' | 'getBoundingBox' | 'isVisible' | 'isEnabled' | 'isChecked' | 'press' | 'keyDown' | 'keyUp' | 'wait' | 'evaluate' | 'validateElement' | 'validateRefs' | 'highlight' | 'clearHighlight';
 export interface BaseCommand {
+    /** Optional command ID. Auto-generated if not provided. */
+    id?: string;
+    action: CoreAction;
+}
+export interface InternalCommand {
     id: string;
     action: CoreAction;
+    [key: string]: unknown;
 }
 export type Selector = string;
 export interface ClickCommand extends BaseCommand {
@@ -177,7 +183,6 @@ export interface EvaluateCommand extends BaseCommand {
  * @example Pre-validate before typing
  * ```typescript
  * const validation = await agent.execute({
- *   id: 'v1',
  *   action: 'validateElement',
  *   selector: '#username',
  *   capabilities: ['editable']
@@ -185,7 +190,6 @@ export interface EvaluateCommand extends BaseCommand {
  *
  * if (validation.data.compatible) {
  *   await agent.execute({
- *     id: 'a1',
  *     action: 'type',
  *     selector: '#username',
  *     text: 'user@example.com'
@@ -213,20 +217,19 @@ export interface ValidateElementCommand extends BaseCommand {
  * @example Check ref validity
  * ```typescript
  * const validation = await agent.execute({
- *   id: 'v1',
  *   action: 'validateRefs',
  *   refs: ['@ref:0', '@ref:1', '@ref:2']
  * });
  *
  * // Use only valid refs
  * for (const ref of validation.data.valid) {
- *   await agent.execute({ id: '...', action: 'click', selector: ref });
+ *   await agent.execute({ action: 'click', selector: ref });
  * }
  *
  * // Handle invalid refs
  * if (validation.data.invalid.length > 0) {
  *   // Take new snapshot to get fresh refs
- *   await agent.execute({ id: '...', action: 'snapshot' });
+ *   await agent.execute({ action: 'snapshot' });
  * }
  * ```
  */
@@ -245,17 +248,17 @@ export interface ValidateRefsCommand extends BaseCommand {
  * @example Highlight elements after snapshot
  * ```typescript
  * // Take a snapshot first
- * await agent.execute({ id: 's1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  *
  * // Show visual highlights
- * await agent.execute({ id: 'h1', action: 'highlight' });
+ * await agent.execute({ action: 'highlight' });
  *
  * // Labels now visible on page with @ref:0, @ref:1, etc.
  * // Use the refs to interact with elements
- * await agent.execute({ id: 'c1', action: 'click', selector: '@ref:5' });
+ * await agent.execute({ action: 'click', selector: '@ref:5' });
  *
  * // Clear highlights when done
- * await agent.execute({ id: 'ch1', action: 'clearHighlight' });
+ * await agent.execute({ action: 'clearHighlight' });
  * ```
  */
 export interface HighlightCommand extends BaseCommand {
@@ -268,7 +271,7 @@ export interface HighlightCommand extends BaseCommand {
  *
  * @example Clear highlights
  * ```typescript
- * await agent.execute({ id: 'ch1', action: 'clearHighlight' });
+ * await agent.execute({ action: 'clearHighlight' });
  * ```
  */
 export interface ClearHighlightCommand extends BaseCommand {

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

@@ -43,7 +43,7 @@ export interface TabHandle {
  * ```typescript
  * const agent = new BackgroundAgent();
  * await agent.navigate('https://example.com');
- * await agent.execute({ id: '1', action: 'click', selector: '#submit' });
+ * await agent.execute({ action: 'click', selector: '#submit' });
  * ```
  *
  * @example Multi-tab with explicit tabId
@@ -59,7 +59,7 @@ export interface TabHandle {
  * await agent.tab(tab2.id).snapshot();
  *
  * // Or specify tabId in command
- * await agent.execute({ id: '1', action: 'snapshot' }, { tabId: tab2.id });
+ * await agent.execute({ action: 'snapshot' }, { tabId: tab2.id });
  * ```
  */
 export declare class BackgroundAgent {
@@ -158,17 +158,19 @@ export declare class BackgroundAgent {
      * Browser-level commands (navigate, screenshot, tabs) are handled here.
      * DOM-level commands are forwarded to the ContentAgent in the target tab.
      *
+     * Command IDs are auto-generated internally - users don't need to provide them.
+     *
      * @param command - The command to execute
      * @param options - Optional settings including target tabId
      *
      * @example Default (active tab)
      * ```typescript
-     * await browser.execute({ id: '1', action: 'snapshot' });
+     * await browser.execute({ action: 'snapshot' });
      * ```
      *
      * @example Specific tab
      * ```typescript
-     * await browser.execute({ id: '1', action: 'snapshot' }, { tabId: 123 });
+     * await browser.execute({ action: 'snapshot' }, { tabId: 123 });
      * ```
      */
     execute(command: Command, options?: {

package/packages/extension/dist/background.js

@@ -12,6 +12,14 @@
  * - Routing DOM commands to ContentAgents in target tabs
  */
 import { SessionManager } from './session-manager.js';
+// Command ID counter for auto-generated IDs
+let bgCommandIdCounter = 0;
+/**
+ * Generate a unique command ID for background script
+ */
+function generateBgCommandId() {
+    return `bg_${Date.now()}_${bgCommandIdCounter++}`;
+}
 /**
  * BackgroundAgent - High-level browser automation orchestrator
  *
@@ -23,7 +31,7 @@ import { SessionManager } from './session-manager.js';
  * ```typescript
  * const agent = new BackgroundAgent();
  * await agent.navigate('https://example.com');
- * await agent.execute({ id: '1', action: 'click', selector: '#submit' });
+ * await agent.execute({ action: 'click', selector: '#submit' });
  * ```
  *
  * @example Multi-tab with explicit tabId
@@ -39,7 +47,7 @@ import { SessionManager } from './session-manager.js';
  * await agent.tab(tab2.id).snapshot();
  *
  * // Or specify tabId in command
- * await agent.execute({ id: '1', action: 'snapshot' }, { tabId: tab2.id });
+ * await agent.execute({ action: 'snapshot' }, { tabId: tab2.id });
  * ```
  */
 export class BackgroundAgent {
@@ -381,31 +389,36 @@ export class BackgroundAgent {
      * Browser-level commands (navigate, screenshot, tabs) are handled here.
      * DOM-level commands are forwarded to the ContentAgent in the target tab.
      *
+     * Command IDs are auto-generated internally - users don't need to provide them.
+     *
      * @param command - The command to execute
      * @param options - Optional settings including target tabId
      *
      * @example Default (active tab)
      * ```typescript
-     * await browser.execute({ id: '1', action: 'snapshot' });
+     * await browser.execute({ action: 'snapshot' });
      * ```
      *
      * @example Specific tab
      * ```typescript
-     * await browser.execute({ id: '1', action: 'snapshot' }, { tabId: 123 });
+     * await browser.execute({ action: 'snapshot' }, { tabId: 123 });
      * ```
      */
     async execute(command, options) {
+        // Auto-generate ID if not provided
+        const id = command.id || generateBgCommandId();
+        const internalCmd = { ...command, id };
         try {
             // Extension commands are handled directly by BrowserAgent
-            if (this.isExtensionCommand(command)) {
-                return this.executeExtensionCommand(command);
+            if (this.isExtensionCommand(internalCmd)) {
+                return this.executeExtensionCommand(internalCmd);
             }
             // DOM commands are forwarded to ContentAgent in the target tab
-            return this.sendToContentAgent(command, options?.tabId);
+            return this.sendToContentAgent(internalCmd, options?.tabId);
         }
         catch (error) {
             return {
-                id: command.id,
+                id,
                 success: false,
                 error: error instanceof Error ? error.message : String(error),
             };
@@ -415,16 +428,19 @@ export class BackgroundAgent {
      * Send a command to the ContentAgent in a specific tab
      */
     async sendToContentAgent(command, tabId) {
+        // Ensure command has an ID for internal use
+        const id = command.id || generateBgCommandId();
+        const internalCmd = { ...command, id };
         const targetTabId = tabId ?? this.activeTabId ?? (await this.getActiveTab())?.id;
         if (!targetTabId) {
             return {
-                id: command.id,
+                id,
                 success: false,
                 error: 'No active tab for DOM command',
             };
         }
         // Try sending with automatic retry and recovery
-        return this.sendMessageWithRetry(targetTabId, command);
+        return this.sendMessageWithRetry(targetTabId, internalCmd);
     }
     /**
      * Send message with automatic content script re-injection on failure
@@ -717,7 +733,7 @@ export function setupMessageListener() {
             sendResponse({
                 type: 'btcp:response',
                 response: {
-                    id: msg.command.id,
+                    id: msg.command.id || 'unknown',
                     success: false,
                     error: error instanceof Error ? error.message : String(error),
                 },

package/packages/extension/dist/content.js

@@ -40,23 +40,24 @@ async function handleCommand(command) {
         return getContentAgent().execute(command);
     }
     // Extension commands that need content script execution
+    const id = command.id || 'unknown';
     switch (command.action) {
         case 'getUrl':
             return {
-                id: command.id,
+                id,
                 success: true,
                 data: { url: window.location.href },
             };
         case 'getTitle':
             return {
-                id: command.id,
+                id,
                 success: true,
                 data: { title: document.title },
             };
         default:
             // Forward to background script
             return {
-                id: command.id,
+                id,
                 success: false,
                 error: `Command ${command.action} must be handled by background script`,
             };
@@ -83,7 +84,7 @@ chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
         sendResponse({
             type: 'btcp:response',
             response: {
-                id: msg.command.id,
+                id: msg.command.id || 'unknown',
                 success: false,
                 error: error instanceof Error ? error.message : String(error),
             },

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

@@ -26,7 +26,7 @@
  * import { createContentAgent } from '@btcp/core';
  *
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  *
  * @example Popup/external usage:
@@ -202,6 +202,10 @@ export interface Client {
         reconnected: boolean;
     }>;
 }
+/**
+ * Generate a unique command ID for BTCP commands
+ */
+export declare function generateCommandId(): string;
 /**
  * Create a client for communicating with the extension
  *

package/packages/extension/dist/index.js

@@ -26,7 +26,7 @@
  * import { createContentAgent } from '@btcp/core';
  *
  * const agent = createContentAgent();
- * await agent.execute({ id: '1', action: 'snapshot' });
+ * await agent.execute({ action: 'snapshot' });
  * ```
  *
  * @example Popup/external usage:
@@ -49,7 +49,10 @@ _BrowserAgent as BrowserAgent, _getBrowserAgent as getBrowserAgent, };
 // Re-export ContentAgent for content script usage
 export { createContentAgent } from '../../core/dist/index.js';
 let commandIdCounter = 0;
-function generateCommandId() {
+/**
+ * Generate a unique command ID for BTCP commands
+ */
+export function generateCommandId() {
     return `cmd_${Date.now()}_${commandIdCounter++}`;
 }
 /**
@@ -99,11 +102,12 @@ export function createClient() {
             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 }, (response) => {
+            chrome.runtime.sendMessage({ type: 'btcp:command', command: { ...command, id } }, (response) => {
                 if (chrome.runtime.lastError) {
                     resolve({
-                        id: command.id,
+                        id,
                         success: false,
                         error: chrome.runtime.lastError.message || 'Unknown error',
                     });
@@ -116,7 +120,7 @@ export function createClient() {
                     else {
                         // Unexpected pong response
                         resolve({
-                            id: command.id,
+                            id,
                             success: false,
                             error: 'Unexpected response type',
                         });

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

@@ -7,7 +7,8 @@ import type { Command as CoreCommand, Response } from '../../core/dist/index.js'
 import type { SessionCommand } from './session-types.js';
 export type ExtensionAction = 'navigate' | 'back' | 'forward' | 'reload' | 'getUrl' | 'getTitle' | 'screenshot' | 'tabNew' | 'tabClose' | 'tabSwitch' | 'tabList' | 'groupCreate' | 'groupUpdate' | 'groupDelete' | 'groupList' | 'groupAddTabs' | 'groupRemoveTabs' | 'groupGet' | 'sessionGetCurrent' | 'popupInitialize';
 export interface ExtensionBaseCommand {
-    id: string;
+    /** Optional command ID. Auto-generated if not provided. */
+    id?: string;
     action: ExtensionAction;
 }
 export interface NavigateCommand extends ExtensionBaseCommand {