btcp-browser-agent 0.1.12 → 0.1.16

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/remote.js

@@ -190,65 +190,6 @@ export function createRemoteAgent(config) {
             });
         }
     }
-    /**
-     * Ensure a session exists, creating one if needed
-     *
-     * This checks in order:
-     * 1. Current active session
-     * 2. Persistent session from storage (reconnects if found)
-     * 3. Existing BTCP tab groups (reconnects to first one found)
-     * 4. Creates a new session if none found (respects maxSession limit)
-     */
-    async function ensureSession() {
-        // 1. Check if there's an active session
-        const sessionResult = await backgroundAgent.execute({ action: 'sessionGetCurrent' });
-        if (sessionResult.success && sessionResult.data) {
-            const session = sessionResult.data.session;
-            if (session?.groupId) {
-                log('Active session found:', session.groupId);
-                return; // Session already exists
-            }
-        }
-        // 2. Try to reconnect via popup initialize (handles persistent session check)
-        log('No active session, trying to reconnect to existing session...');
-        const initResult = await backgroundAgent.execute({ action: 'popupInitialize' });
-        if (initResult.success && initResult.data) {
-            const initData = initResult.data;
-            if (initData.reconnected) {
-                log('Reconnected to existing session');
-                return;
-            }
-        }
-        // 3. Check for existing BTCP tab groups and try to use one
-        const groupsResult = await backgroundAgent.execute({ action: 'groupList' });
-        if (groupsResult.success && groupsResult.data) {
-            const groups = groupsResult.data;
-            const btcpGroup = groups.find(g => g.title?.startsWith('BTCP'));
-            if (btcpGroup) {
-                log('Found existing BTCP tab group, setting it as active session:', btcpGroup.id);
-                const useResult = await backgroundAgent.execute({
-                    action: 'sessionUseGroup',
-                    groupId: btcpGroup.id,
-                });
-                if (useResult.success) {
-                    log('Successfully using existing BTCP group as session');
-                    return;
-                }
-                log('Failed to use existing BTCP group:', useResult.error);
-            }
-        }
-        // 4. Create a new session (will fail if maxSession limit reached)
-        log('No existing session found, creating one automatically...');
-        const groupResult = await backgroundAgent.execute({
-            action: 'groupCreate',
-            title: 'BTCP Session',
-            color: 'blue',
-        });
-        if (!groupResult.success) {
-            throw new Error(`Failed to create session: ${groupResult.error}`);
-        }
-        log('Session created:', groupResult.data);
-    }
     /**
      * Handle incoming tool call request
      */
@@ -257,9 +198,7 @@ export function createRemoteAgent(config) {
         log('Tool call:', name, args);
         emit('toolCall', name, args);
         try {
-            // Auto-ensure session for all browser tools (session management is internal)
-            await ensureSession();
-            // Map tool to command and execute
+            // Map tool to command and execute (session auto-ensured by BackgroundAgent)
             const command = mapToolToCommand(name, args);
             const response = await backgroundAgent.execute(command);
             // Send response back to server

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

@@ -24,13 +24,29 @@ export declare class SessionManager {
     private activeSessionGroupId;
     private sessionCounter;
     private initialized;
+    private initializationPromise;
     private maxSession;
     private maxOpenTab;
     constructor(options?: SessionManagerOptions);
+    /**
+     * Wait for SessionManager to finish initialization
+     */
+    waitForInitialization(): Promise<void>;
     /**
      * Restore session from storage
      */
     private restoreSession;
+    /**
+     * Scan for and cleanup duplicate BTCP session groups
+     * Ensures only one BTCP session exists at any time
+     *
+     * @returns Stats about cleanup: { found, kept, removed }
+     */
+    cleanupDuplicateSessions(): Promise<{
+        found: number;
+        kept: number;
+        removed: number;
+    }>;
     /**
      * Persist session to storage
      */
@@ -80,6 +96,10 @@ export declare class SessionManager {
      * Get the active session group ID
      */
     getActiveSessionGroupId(): number | null;
+    /**
+     * Get the active session group ID (async version that ensures initialization is complete)
+     */
+    getActiveSessionGroupIdAsync(): Promise<number | null>;
     /**
      * Get the maximum number of sessions allowed
      */
@@ -113,6 +133,16 @@ export declare class SessionManager {
      * This validates the group exists and sets it as active with persistence
      */
     useExistingGroupAsSession(groupId: number): Promise<boolean>;
+    /**
+     * Ensure a session exists - restore from storage, use existing, or create new
+     * Returns the session group ID (creates if needed)
+     */
+    ensureSession(): Promise<number>;
+    /**
+     * Get the primary tab in session (ensures session exists first)
+     * Returns the first tab in the session group
+     */
+    getSessionTab(): Promise<number>;
     /**
      * Add a tab to the active session (if one exists)
      * Automatically enforces the tab limit after adding

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

@@ -12,13 +12,20 @@ export class SessionManager {
     activeSessionGroupId = null;
     sessionCounter = 0;
     initialized = false;
+    initializationPromise;
     maxSession;
     maxOpenTab;
     constructor(options = {}) {
         this.maxSession = options.maxSession ?? 1;
         this.maxOpenTab = options.maxOpenTab ?? 1;
-        // Restore session on creation
-        this.restoreSession();
+        // Restore session on creation and store the promise
+        this.initializationPromise = this.restoreSession();
+    }
+    /**
+     * Wait for SessionManager to finish initialization
+     */
+    async waitForInitialization() {
+        await this.initializationPromise;
     }
     /**
      * Restore session from storage
@@ -49,6 +56,8 @@ export class SessionManager {
             else {
                 console.log('[SessionManager] No stored session found');
             }
+            // Clean up any duplicate sessions after restoring
+            await this.cleanupDuplicateSessions();
         }
         catch (err) {
             console.error('[SessionManager] Failed to restore session:', err);
@@ -57,6 +66,98 @@ export class SessionManager {
             this.initialized = true;
         }
     }
+    /**
+     * Scan for and cleanup duplicate BTCP session groups
+     * Ensures only one BTCP session exists at any time
+     *
+     * @returns Stats about cleanup: { found, kept, removed }
+     */
+    async cleanupDuplicateSessions() {
+        try {
+            console.log('[SessionManager] Scanning for duplicate BTCP sessions...');
+            // Get all tab groups
+            const allGroups = await chrome.tabGroups.query({});
+            const btcpGroups = allGroups.filter(g => g.title?.startsWith('BTCP'));
+            console.log(`[SessionManager] Found ${btcpGroups.length} BTCP session group(s)`);
+            if (btcpGroups.length <= 1) {
+                // No duplicates, nothing to clean up
+                return { found: btcpGroups.length, kept: btcpGroups.length, removed: 0 };
+            }
+            // Multiple sessions found - need to consolidate
+            console.warn(`[SessionManager] Found ${btcpGroups.length} BTCP sessions - cleaning up duplicates!`);
+            // Determine which session to keep
+            let toKeep;
+            // Priority 1: Keep the one matching stored session ID
+            if (this.activeSessionGroupId !== null) {
+                const activeGroup = btcpGroups.find(g => g.id === this.activeSessionGroupId);
+                if (activeGroup) {
+                    console.log('[SessionManager] Keeping active session:', activeGroup.id);
+                    toKeep = activeGroup;
+                }
+            }
+            // Priority 2: Keep the one from storage if active session not set
+            if (!toKeep) {
+                const result = await chrome.storage.session.get(SESSION_STORAGE_KEY);
+                const data = result[SESSION_STORAGE_KEY];
+                if (data?.groupId) {
+                    const storedGroup = btcpGroups.find(g => g.id === data.groupId);
+                    if (storedGroup) {
+                        console.log('[SessionManager] Keeping stored session:', storedGroup.id);
+                        toKeep = storedGroup;
+                    }
+                }
+            }
+            // Priority 3: Keep the one with the most tabs
+            if (!toKeep) {
+                console.log('[SessionManager] No active/stored session - keeping the one with most tabs');
+                const groupsWithTabCounts = await Promise.all(btcpGroups.map(async (g) => ({
+                    group: g,
+                    tabs: await chrome.tabs.query({ groupId: g.id })
+                })));
+                groupsWithTabCounts.sort((a, b) => b.tabs.length - a.tabs.length);
+                toKeep = groupsWithTabCounts[0]?.group;
+                if (toKeep) {
+                    console.log(`[SessionManager] Keeping session ${toKeep.id} with ${groupsWithTabCounts[0].tabs.length} tabs`);
+                }
+            }
+            // If we still don't have a group to keep (shouldn't happen), just keep the first one
+            if (!toKeep) {
+                toKeep = btcpGroups[0];
+                console.log('[SessionManager] Fallback: keeping first session:', toKeep.id);
+            }
+            // Delete all other sessions
+            const toDelete = btcpGroups.filter(g => g.id !== toKeep.id);
+            console.log(`[SessionManager] Removing ${toDelete.length} duplicate session(s)`);
+            for (const group of toDelete) {
+                try {
+                    console.log(`[SessionManager] Deleting duplicate session: ${group.id} (${group.title})`);
+                    // Get tabs in this group and ungroup them (don't close them)
+                    const tabs = await chrome.tabs.query({ groupId: group.id });
+                    for (const tab of tabs) {
+                        if (tab.id !== undefined) {
+                            await chrome.tabs.ungroup(tab.id);
+                        }
+                    }
+                }
+                catch (err) {
+                    console.error(`[SessionManager] Failed to delete duplicate session ${group.id}:`, err);
+                }
+            }
+            // Set the kept session as active
+            this.activeSessionGroupId = toKeep.id;
+            await this.persistSession();
+            console.log('[SessionManager] Cleanup complete - only one session remains');
+            return {
+                found: btcpGroups.length,
+                kept: 1,
+                removed: toDelete.length
+            };
+        }
+        catch (err) {
+            console.error('[SessionManager] Failed to cleanup duplicate sessions:', err);
+            return { found: 0, kept: 0, removed: 0 };
+        }
+    }
     /**
      * Persist session to storage
      */
@@ -95,6 +196,7 @@ export class SessionManager {
      * Used when popup detects a stored session that isn't currently active
      */
     async reconnectSession(groupId) {
+        await this.waitForInitialization();
         try {
             console.log('[SessionManager] Attempting to reconnect to session group:', groupId);
             // Verify the group still exists
@@ -106,6 +208,8 @@ export class SessionManager {
             // Restore session state
             this.activeSessionGroupId = groupId;
             this.sessionCounter = data?.sessionCounter ?? this.sessionCounter;
+            // Persist session state after reconnecting
+            await this.persistSession();
             console.log('[SessionManager] Session reconnected successfully');
             return true;
         }
@@ -120,6 +224,8 @@ export class SessionManager {
      * Create a new tab group
      */
     async createGroup(options = {}) {
+        // 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();
@@ -246,6 +352,7 @@ export class SessionManager {
      * Get current active session info
      */
     async getCurrentSession() {
+        await this.waitForInitialization();
         if (this.activeSessionGroupId === null) {
             return null;
         }
@@ -275,6 +382,13 @@ export class SessionManager {
     getActiveSessionGroupId() {
         return this.activeSessionGroupId;
     }
+    /**
+     * Get the active session group ID (async version that ensures initialization is complete)
+     */
+    async getActiveSessionGroupIdAsync() {
+        await this.waitForInitialization();
+        return this.activeSessionGroupId;
+    }
     /**
      * Get the maximum number of sessions allowed
      */
@@ -292,6 +406,7 @@ export class SessionManager {
      * Closes oldest tabs if the limit is exceeded
      */
     async enforceTabLimit() {
+        await this.waitForInitialization();
         if (this.activeSessionGroupId === null) {
             return;
         }
@@ -328,41 +443,31 @@ export class SessionManager {
      * 3. Existing tab groups (BTCP prefixed)
      */
     async getSessionCount() {
-        // If we have an active session, that counts as 1
-        if (this.activeSessionGroupId !== null) {
-            try {
-                // Verify the group still exists
-                await chrome.tabGroups.get(this.activeSessionGroupId);
-                return 1;
-            }
-            catch {
-                // Group no longer exists, clear it
-                this.activeSessionGroupId = null;
-            }
-        }
-        // Check if there's a persistent session in storage
+        // Always count all BTCP tab groups to detect duplicates
         try {
-            const result = await chrome.storage.session.get(SESSION_STORAGE_KEY);
-            const data = result[SESSION_STORAGE_KEY];
-            if (data?.groupId) {
-                // Verify the stored group still exists
-                try {
-                    await chrome.tabGroups.get(data.groupId);
-                    return 1;
+            const groups = await chrome.tabGroups.query({});
+            const btcpGroups = groups.filter(g => g.title?.startsWith('BTCP'));
+            // Clean up stale references while counting
+            if (this.activeSessionGroupId !== null) {
+                const activeExists = btcpGroups.some(g => g.id === this.activeSessionGroupId);
+                if (!activeExists) {
+                    this.activeSessionGroupId = null;
                 }
-                catch {
-                    // Group no longer exists, clear storage
-                    await this.clearStoredSession();
+            }
+            // Check stored session exists
+            try {
+                const result = await chrome.storage.session.get(SESSION_STORAGE_KEY);
+                const data = result[SESSION_STORAGE_KEY];
+                if (data?.groupId) {
+                    const storedExists = btcpGroups.some(g => g.id === data.groupId);
+                    if (!storedExists) {
+                        await this.clearStoredSession();
+                    }
                 }
             }
-        }
-        catch (err) {
-            console.error('[SessionManager] Failed to check persistent session:', err);
-        }
-        // Count existing BTCP tab groups
-        try {
-            const groups = await chrome.tabGroups.query({});
-            const btcpGroups = groups.filter(g => g.title?.startsWith('BTCP'));
+            catch (err) {
+                console.error('[SessionManager] Failed to check persistent session:', err);
+            }
             return btcpGroups.length;
         }
         catch (err) {
@@ -404,11 +509,65 @@ export class SessionManager {
             return false;
         }
     }
+    /**
+     * Ensure a session exists - restore from storage, use existing, or create new
+     * Returns the session group ID (creates if needed)
+     */
+    async ensureSession() {
+        await this.waitForInitialization();
+        // Step 1: Already have active session
+        if (this.activeSessionGroupId !== null) {
+            // Verify it still exists
+            try {
+                await chrome.tabGroups.get(this.activeSessionGroupId);
+                return this.activeSessionGroupId;
+            }
+            catch {
+                // Group no longer exists, continue to restore/create
+                this.activeSessionGroupId = null;
+            }
+        }
+        // Step 2: Try to restore from storage
+        const result = await chrome.storage.session.get(SESSION_STORAGE_KEY);
+        const stored = result[SESSION_STORAGE_KEY];
+        if (stored?.groupId) {
+            const reconnected = await this.reconnectSession(stored.groupId);
+            if (reconnected && this.activeSessionGroupId !== null) {
+                return this.activeSessionGroupId;
+            }
+        }
+        // Step 3: Find existing BTCP group
+        const groups = await chrome.tabGroups.query({});
+        const btcpGroup = groups.find(g => g.title?.startsWith('BTCP'));
+        if (btcpGroup) {
+            const used = await this.useExistingGroupAsSession(btcpGroup.id);
+            if (used && this.activeSessionGroupId !== null) {
+                return this.activeSessionGroupId;
+            }
+        }
+        // Step 4: Create new session
+        console.log('[SessionManager] No existing session found, creating new one...');
+        const newGroup = await this.createGroup({ color: 'blue' });
+        return newGroup.id;
+    }
+    /**
+     * Get the primary tab in session (ensures session exists first)
+     * Returns the first tab in the session group
+     */
+    async getSessionTab() {
+        const groupId = await this.ensureSession();
+        const tabs = await chrome.tabs.query({ groupId });
+        if (tabs.length === 0 || tabs[0].id === undefined) {
+            throw new Error('Session exists but has no tabs');
+        }
+        return tabs[0].id;
+    }
     /**
      * Add a tab to the active session (if one exists)
      * Automatically enforces the tab limit after adding
      */
     async addTabToActiveSession(tabId) {
+        await this.waitForInitialization();
         if (this.activeSessionGroupId === null) {
             return false;
         }

package/packages/extension/dist/transport/base-transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Base transport class with shared functionality
+ *
+ * Provides event handling, state management, and utility methods for transports.
+ */
+import type { Command, Response } from '../types.js';
+import type { Transport, TransportEvents, TransportOptions, TransportState } from './types.js';
+/**
+ * Abstract base class for transports
+ *
+ * Provides common functionality for event handling and state management.
+ * Subclasses must implement `send()`, `connect()`, and `disconnect()`.
+ */
+export declare abstract class BaseTransport implements Transport {
+    abstract readonly name: string;
+    protected state: TransportState;
+    protected debug: boolean;
+    private eventHandlers;
+    constructor(options?: TransportOptions);
+    /**
+     * Send a command - must be implemented by subclasses
+     */
+    abstract send(command: Command): Promise<Response>;
+    /**
+     * Connect the transport - must be implemented by subclasses
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnect the transport - must be implemented by subclasses
+     */
+    abstract disconnect(): void;
+    /**
+     * Get the current connection state
+     */
+    getState(): TransportState;
+    /**
+     * Check if the transport is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Register an event handler
+     */
+    on<K extends keyof TransportEvents>(event: K, handler: TransportEvents[K]): void;
+    /**
+     * Unregister an event handler
+     */
+    off<K extends keyof TransportEvents>(event: K, handler: TransportEvents[K]): void;
+    /**
+     * Emit an event to all registered handlers
+     */
+    protected emit<K extends keyof TransportEvents>(event: K, ...args: Parameters<TransportEvents[K]>): void;
+    /**
+     * Update the transport state and emit stateChange event
+     */
+    protected setState(newState: TransportState): void;
+    /**
+     * Log a message if debug is enabled
+     */
+    protected log(level: 'debug' | 'info' | 'warn' | 'error', ...args: unknown[]): void;
+    /**
+     * Create an error response with the given message
+     */
+    protected createErrorResponse(id: string, error: string): Response;
+}
+//# sourceMappingURL=base-transport.d.ts.map