btcp-browser-agent 0.1.4 → 0.1.7

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 {
@@ -87,12 +93,19 @@ export interface GrepOptions {
     /** Treat pattern as fixed string, not regex (grep -F) */
     fixedStrings?: boolean;
 }
+/**
+ * Snapshot mode determines what content to capture
+ */
+export type SnapshotMode = 'interactive' | 'outline' | 'content';
+/**
+ * Snapshot output format
+ */
+export type SnapshotFormat = 'tree' | 'html' | 'markdown';
 export interface SnapshotCommand extends BaseCommand {
     action: 'snapshot';
     selector?: Selector;
     maxDepth?: number;
     includeHidden?: boolean;
-    interactive?: boolean;
     compact?: boolean;
     minDepth?: number;
     samplingStrategy?: 'importance' | 'balanced' | 'depth-first';
@@ -100,10 +113,28 @@ export interface SnapshotCommand extends BaseCommand {
     landmarks?: boolean;
     incremental?: boolean;
     baseSnapshot?: SnapshotData;
-    all?: boolean;
-    format?: 'tree' | 'html';
+    /**
+     * Snapshot mode:
+     * - 'interactive': Find clickable elements (default)
+     * - 'outline': Understand page structure with xpaths + metadata
+     * - 'content': Extract text content from sections
+     */
+    mode?: SnapshotMode;
+    /**
+     * Output format:
+     * - 'tree': Flat accessibility tree (default)
+     * - 'html': Raw HTML
+     * - 'markdown': Markdown formatted content
+     */
+    format?: SnapshotFormat;
     /** Filter output lines - simple string or full grep options */
     grep?: string | GrepOptions;
+    /** Max chars per section in content mode */
+    maxLength?: number;
+    /** Include links as [text](url) in markdown format */
+    includeLinks?: boolean;
+    /** Include images as ![alt](src) in markdown format */
+    includeImages?: boolean;
 }
 export interface QuerySelectorCommand extends BaseCommand {
     action: 'querySelector';
@@ -177,7 +208,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 +215,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 +242,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 +273,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 +296,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:
@@ -87,9 +87,13 @@ export interface Client {
     snapshot(options?: {
         selector?: string;
         maxDepth?: number;
-        interactive?: boolean;
+        mode?: 'interactive' | 'outline' | 'content';
         compact?: boolean;
-        format?: 'tree' | 'html';
+        format?: 'tree' | 'html' | 'markdown';
+        grep?: string;
+        maxLength?: number;
+        includeLinks?: boolean;
+        includeImages?: boolean;
     }): Promise<string>;
     /**
      * Click an element
@@ -202,6 +206,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',
                         });
@@ -171,9 +175,13 @@ export function createClient() {
                 action: 'snapshot',
                 selector: options?.selector,
                 maxDepth: options?.maxDepth,
-                interactive: options?.interactive,
+                mode: options?.mode,
                 compact: options?.compact,
                 format: options?.format,
+                grep: options?.grep,
+                maxLength: options?.maxLength,
+                includeLinks: options?.includeLinks,
+                includeImages: options?.includeImages,
             });
             assertSuccess(response);
             return response.data;

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 {