btcp-browser-agent 0.1.0 → 0.1.2

package/packages/extension/dist/background.js

@@ -0,0 +1,737 @@
+/**
+ * @btcp/extension - Background Script
+ *
+ * Contains BrowserAgent - the high-level orchestrator that runs in the
+ * extension's background/service worker context.
+ *
+ * BrowserAgent manages:
+ * - Tab lifecycle (create, close, switch, list)
+ * - Navigation (goto, back, forward, reload)
+ * - Screenshots (chrome.tabs.captureVisibleTab)
+ * - Session state
+ * - Routing DOM commands to ContentAgents in target tabs
+ */
+import { SessionManager } from './session-manager.js';
+/**
+ * BackgroundAgent - High-level browser automation orchestrator
+ *
+ * Runs in the extension's background script/service worker.
+ * Manages browser-level operations and routes DOM commands to
+ * ContentAgent instances running in content scripts.
+ *
+ * @example Single tab (default - uses activeTabId)
+ * ```typescript
+ * const agent = new BackgroundAgent();
+ * await agent.navigate('https://example.com');
+ * await agent.execute({ id: '1', action: 'click', selector: '#submit' });
+ * ```
+ *
+ * @example Multi-tab with explicit tabId
+ * ```typescript
+ * const agent = new BackgroundAgent();
+ *
+ * // Open two tabs
+ * const tab1 = await agent.newTab({ url: 'https://google.com' });
+ * const tab2 = await agent.newTab({ url: 'https://github.com', active: false });
+ *
+ * // Interact with specific tabs without switching
+ * await agent.tab(tab1.id).click('#search');
+ * await agent.tab(tab2.id).snapshot();
+ *
+ * // Or specify tabId in command
+ * await agent.execute({ id: '1', action: 'snapshot' }, { tabId: tab2.id });
+ * ```
+ */
+export class BackgroundAgent {
+    activeTabId = null;
+    sessionManager;
+    heartbeatInterval = null;
+    HEARTBEAT_INTERVAL = 30000; // 30 seconds
+    constructor() {
+        this.sessionManager = new SessionManager();
+        // Initialize active tab on creation
+        this.initActiveTab();
+        // Start heartbeat to keep session tabs alive
+        this.startHeartbeat();
+    }
+    async initActiveTab() {
+        const tab = await this.getActiveTab();
+        this.activeTabId = tab?.id ?? null;
+    }
+    /**
+     * Get the current active tab ID
+     */
+    getActiveTabId() {
+        return this.activeTabId;
+    }
+    /**
+     * Set the active tab ID (for manual control)
+     */
+    setActiveTabId(tabId) {
+        this.activeTabId = tabId;
+    }
+    /**
+     * Get a handle for interacting with a specific tab
+     *
+     * This allows you to send commands to any tab without switching the active tab.
+     *
+     * @example
+     * ```typescript
+     * const tab2Handle = browser.tab(tab2.id);
+     * await tab2Handle.snapshot();
+     * await tab2Handle.click('@ref:5');
+     * ```
+     */
+    tab(tabId) {
+        const agent = this;
+        let cmdCounter = 0;
+        const genId = () => `tab_${tabId}_${Date.now()}_${cmdCounter++}`;
+        return {
+            tabId,
+            execute(command) {
+                return agent.sendToContentAgent(command, tabId);
+            },
+            snapshot(options) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'snapshot',
+                    ...options,
+                }, tabId);
+            },
+            click(selector) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'click',
+                    selector,
+                }, tabId);
+            },
+            fill(selector, value) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'fill',
+                    selector,
+                    value,
+                }, tabId);
+            },
+            type(selector, text, options) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'type',
+                    selector,
+                    text,
+                    ...options,
+                }, tabId);
+            },
+            getText(selector) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'getText',
+                    selector,
+                }, tabId);
+            },
+            isVisible(selector) {
+                return agent.sendToContentAgent({
+                    id: genId(),
+                    action: 'isVisible',
+                    selector,
+                }, tabId);
+            },
+        };
+    }
+    // ============================================================================
+    // TAB MANAGEMENT
+    // ============================================================================
+    /**
+     * Get the currently active tab (only if in session)
+     */
+    async getActiveTab() {
+        const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
+        // If no session, return null
+        if (sessionGroupId === null) {
+            return null;
+        }
+        // Get active tab and verify it's in the session
+        return new Promise((resolve) => {
+            chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
+                const activeTab = tabs[0];
+                // Only return if it's in the session group
+                if (activeTab && activeTab.groupId === sessionGroupId) {
+                    resolve(activeTab);
+                }
+                else {
+                    resolve(null);
+                }
+            });
+        });
+    }
+    /**
+     * List all tabs (only in session group)
+     */
+    async listTabs() {
+        // Get active session group ID
+        const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
+        // Session is required
+        if (sessionGroupId === null) {
+            throw new Error('No active session. Create a session first to manage tabs.');
+        }
+        // Only return tabs in the session group
+        const tabs = await new Promise((resolve) => {
+            chrome.tabs.query({ groupId: sessionGroupId }, (t) => resolve(t));
+        });
+        return tabs.map((t) => ({
+            id: t.id,
+            url: t.url,
+            title: t.title,
+            active: t.active,
+            index: t.index,
+        }));
+    }
+    /**
+     * Create a new tab (only in session group)
+     */
+    async newTab(options) {
+        // Require active session
+        const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
+        if (sessionGroupId === null) {
+            throw new Error('No active session. Create a session first to manage tabs.');
+        }
+        const tab = await new Promise((resolve) => {
+            chrome.tabs.create({ url: options?.url, active: options?.active ?? true }, (t) => resolve(t));
+        });
+        if (options?.url) {
+            await this.waitForTabLoad(tab.id);
+        }
+        if (options?.active !== false) {
+            this.activeTabId = tab.id;
+        }
+        // Add to active session
+        if (tab.id) {
+            const added = await this.sessionManager.addTabToActiveSession(tab.id);
+            if (!added) {
+                // If we couldn't add to session, close the tab
+                await chrome.tabs.remove(tab.id);
+                throw new Error('Failed to add new tab to session');
+            }
+        }
+        return {
+            id: tab.id,
+            url: tab.url,
+            title: tab.title,
+            active: tab.active,
+            index: tab.index,
+        };
+    }
+    /**
+     * Check if a tab is in the active session
+     */
+    async isTabInSession(tabId) {
+        const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
+        // Session is required - no operations allowed without it
+        if (sessionGroupId === null) {
+            throw new Error('No active session. Create a session first to manage tabs.');
+        }
+        // Check if tab is in the session group
+        const tab = await chrome.tabs.get(tabId);
+        return tab.groupId === sessionGroupId;
+    }
+    /**
+     * Close a tab (only if in session)
+     */
+    async closeTab(tabId) {
+        const targetId = tabId ?? this.activeTabId;
+        if (!targetId)
+            throw new Error('No tab to close');
+        // Validate tab is in session
+        const inSession = await this.isTabInSession(targetId);
+        if (!inSession) {
+            throw new Error('Cannot close tab: tab is not in the active session');
+        }
+        await new Promise((resolve) => {
+            chrome.tabs.remove(targetId, () => resolve());
+        });
+        // Update active tab if we closed the current one
+        if (targetId === this.activeTabId) {
+            const tab = await this.getActiveTab();
+            this.activeTabId = tab?.id ?? null;
+        }
+    }
+    /**
+     * Switch to a tab (only if in session)
+     */
+    async switchTab(tabId) {
+        // Validate tab is in session
+        const inSession = await this.isTabInSession(tabId);
+        if (!inSession) {
+            throw new Error('Cannot switch to tab: tab is not in the active session');
+        }
+        await new Promise((resolve) => {
+            chrome.tabs.update(tabId, { active: true }, () => resolve());
+        });
+        this.activeTabId = tabId;
+    }
+    // ============================================================================
+    // NAVIGATION
+    // ============================================================================
+    /**
+     * Navigate to a URL (only in session tabs)
+     */
+    async navigate(url, options) {
+        const tabId = this.activeTabId ?? (await this.getActiveTab())?.id;
+        if (!tabId)
+            throw new Error('No active tab');
+        // Validate tab is in session
+        const inSession = await this.isTabInSession(tabId);
+        if (!inSession) {
+            throw new Error('Cannot navigate: tab is not in the active session');
+        }
+        await new Promise((resolve) => {
+            chrome.tabs.update(tabId, { url }, () => resolve());
+        });
+        if (options?.waitUntil) {
+            await this.waitForTabLoad(tabId);
+            // Clear refs and highlights after navigation completes
+            try {
+                await this.sendToContentAgent({
+                    id: `nav_clear_${Date.now()}`,
+                    action: 'clearHighlight'
+                }, tabId);
+            }
+            catch (error) {
+                // Ignore errors - content script might not be ready yet
+                console.log('[BackgroundAgent] Failed to clear highlights after navigation:', error);
+            }
+        }
+    }
+    /**
+     * Go back in history
+     */
+    async back() {
+        const tabId = this.activeTabId ?? (await this.getActiveTab())?.id;
+        if (!tabId)
+            throw new Error('No active tab');
+        await new Promise((resolve) => {
+            chrome.tabs.goBack(tabId, () => resolve());
+        });
+    }
+    /**
+     * Go forward in history
+     */
+    async forward() {
+        const tabId = this.activeTabId ?? (await this.getActiveTab())?.id;
+        if (!tabId)
+            throw new Error('No active tab');
+        await new Promise((resolve) => {
+            chrome.tabs.goForward(tabId, () => resolve());
+        });
+    }
+    /**
+     * Reload the current page
+     */
+    async reload(options) {
+        const tabId = this.activeTabId ?? (await this.getActiveTab())?.id;
+        if (!tabId)
+            throw new Error('No active tab');
+        await new Promise((resolve) => {
+            chrome.tabs.reload(tabId, { bypassCache: options?.bypassCache }, () => resolve());
+        });
+        await this.waitForTabLoad(tabId);
+    }
+    /**
+     * Get the current URL
+     */
+    async getUrl() {
+        const tab = await this.getActiveTab();
+        return tab?.url || '';
+    }
+    /**
+     * Get the page title
+     */
+    async getTitle() {
+        const tab = await this.getActiveTab();
+        return tab?.title || '';
+    }
+    // ============================================================================
+    // SCREENSHOTS
+    // ============================================================================
+    /**
+     * Capture a screenshot of the visible tab
+     */
+    async screenshot(options) {
+        const format = options?.format || 'png';
+        const quality = options?.quality;
+        const dataUrl = await new Promise((resolve, reject) => {
+            chrome.tabs.captureVisibleTab({ format, quality }, (url) => {
+                if (chrome.runtime.lastError) {
+                    reject(new Error(chrome.runtime.lastError.message));
+                }
+                else {
+                    resolve(url);
+                }
+            });
+        });
+        // Extract base64 data from data URL
+        return dataUrl.split(',')[1];
+    }
+    // ============================================================================
+    // COMMAND EXECUTION
+    // ============================================================================
+    /**
+     * Execute a command - routes to appropriate handler
+     *
+     * Browser-level commands (navigate, screenshot, tabs) are handled here.
+     * DOM-level commands are forwarded to the ContentAgent in the target tab.
+     *
+     * @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' });
+     * ```
+     *
+     * @example Specific tab
+     * ```typescript
+     * await browser.execute({ id: '1', action: 'snapshot' }, { tabId: 123 });
+     * ```
+     */
+    async execute(command, options) {
+        try {
+            // Extension commands are handled directly by BrowserAgent
+            if (this.isExtensionCommand(command)) {
+                return this.executeExtensionCommand(command);
+            }
+            // DOM commands are forwarded to ContentAgent in the target tab
+            return this.sendToContentAgent(command, options?.tabId);
+        }
+        catch (error) {
+            return {
+                id: command.id,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Send a command to the ContentAgent in a specific tab
+     */
+    async sendToContentAgent(command, tabId) {
+        const targetTabId = tabId ?? this.activeTabId ?? (await this.getActiveTab())?.id;
+        if (!targetTabId) {
+            return {
+                id: command.id,
+                success: false,
+                error: 'No active tab for DOM command',
+            };
+        }
+        // Try sending with automatic retry and recovery
+        return this.sendMessageWithRetry(targetTabId, command);
+    }
+    /**
+     * Send message with automatic content script re-injection on failure
+     */
+    async sendMessageWithRetry(tabId, command, retries = 1) {
+        return new Promise((resolve) => {
+            chrome.tabs.sendMessage(tabId, { type: 'btcp:command', command }, { frameId: 0 }, // Target only the main frame, not iframes
+            async (response) => {
+                if (chrome.runtime.lastError) {
+                    // Content script not responding - try re-injection
+                    if (retries > 0) {
+                        console.log(`[Recovery] Re-injecting content script into tab ${tabId}`);
+                        const success = await this.reinjectContentScript(tabId);
+                        if (success) {
+                            // Wait briefly for content script to initialize
+                            await new Promise(r => setTimeout(r, 500));
+                            // Retry the command
+                            resolve(this.sendMessageWithRetry(tabId, command, retries - 1));
+                            return;
+                        }
+                    }
+                    resolve({
+                        id: command.id,
+                        success: false,
+                        error: chrome.runtime.lastError.message || 'Failed to send message to tab',
+                    });
+                }
+                else {
+                    const resp = response;
+                    if (resp.type === 'btcp:response') {
+                        resolve(resp.response);
+                    }
+                    else {
+                        resolve({
+                            id: command.id,
+                            success: false,
+                            error: 'Invalid response type',
+                        });
+                    }
+                }
+            });
+        });
+    }
+    /**
+     * Re-inject content script into a tab (for recovery from frozen state)
+     */
+    async reinjectContentScript(tabId) {
+        try {
+            // Check if tab is ready for injection
+            const tab = await chrome.tabs.get(tabId);
+            if (!tab.url || tab.url.startsWith('chrome://') || tab.url.startsWith('chrome-extension://')) {
+                return false; // Can't inject into chrome:// or extension pages
+            }
+            // Execute content script
+            await chrome.scripting.executeScript({
+                target: { tabId },
+                files: ['content.js'],
+            });
+            console.log(`[Recovery] Successfully re-injected content script into tab ${tabId}`);
+            return true;
+        }
+        catch (error) {
+            console.error(`[Recovery] Failed to re-inject content script:`, error);
+            return false;
+        }
+    }
+    /**
+     * Start heartbeat to monitor session tabs
+     */
+    startHeartbeat() {
+        this.heartbeatInterval = setInterval(() => {
+            this.pingSessionTabs();
+        }, this.HEARTBEAT_INTERVAL);
+    }
+    /**
+     * Stop heartbeat (for cleanup)
+     * Note: Currently not called as service workers are terminated by Chrome
+     * Could be used if explicit cleanup is needed in the future
+     */
+    // @ts-expect-error - Unused but kept for potential future use
+    _stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+    }
+    /**
+     * Ping all session tabs to check health
+     */
+    async pingSessionTabs() {
+        try {
+            const tabs = await this.listTabs().catch(() => []);
+            for (const tab of tabs) {
+                chrome.tabs.sendMessage(tab.id, { type: 'btcp:ping' }, { frameId: 0 }, // Target only the main frame, not iframes
+                (response) => {
+                    if (chrome.runtime.lastError) {
+                        console.log(`[Heartbeat] Tab ${tab.id} unresponsive, will re-inject on next command`);
+                    }
+                    else {
+                        const resp = response;
+                        if (resp.type === 'btcp:pong' && !resp.ready) {
+                            console.log(`[Heartbeat] Tab ${tab.id} content script not ready`);
+                        }
+                    }
+                });
+            }
+        }
+        catch (error) {
+            // Silently ignore errors during heartbeat (e.g., no active session)
+        }
+    }
+    // ============================================================================
+    // PRIVATE HELPERS
+    // ============================================================================
+    isExtensionCommand(command) {
+        const extensionActions = [
+            'navigate', 'back', 'forward', 'reload',
+            'getUrl', 'getTitle', 'screenshot',
+            'tabNew', 'tabClose', 'tabSwitch', 'tabList',
+            'groupCreate', 'groupUpdate', 'groupDelete', 'groupList',
+            'groupAddTabs', 'groupRemoveTabs', 'groupGet',
+            'sessionGetCurrent', 'popupInitialize',
+        ];
+        return extensionActions.includes(command.action);
+    }
+    async executeExtensionCommand(command) {
+        switch (command.action) {
+            case 'navigate':
+                await this.navigate(command.url, { waitUntil: command.waitUntil });
+                return { id: command.id, success: true, data: { url: command.url } };
+            case 'back':
+                await this.back();
+                return { id: command.id, success: true, data: { navigated: 'back' } };
+            case 'forward':
+                await this.forward();
+                return { id: command.id, success: true, data: { navigated: 'forward' } };
+            case 'reload':
+                await this.reload({ bypassCache: command.bypassCache });
+                return { id: command.id, success: true, data: { reloaded: true } };
+            case 'getUrl': {
+                const url = await this.getUrl();
+                return { id: command.id, success: true, data: { url } };
+            }
+            case 'getTitle': {
+                const title = await this.getTitle();
+                return { id: command.id, success: true, data: { title } };
+            }
+            case 'screenshot': {
+                const screenshot = await this.screenshot({
+                    format: command.format,
+                    quality: command.quality,
+                });
+                return { id: command.id, success: true, data: { screenshot, format: command.format || 'png' } };
+            }
+            case 'tabNew': {
+                const tab = await this.newTab({ url: command.url, active: command.active });
+                return { id: command.id, success: true, data: { tabId: tab.id, url: tab.url } };
+            }
+            case 'tabClose':
+                await this.closeTab(command.tabId);
+                return { id: command.id, success: true, data: { closed: command.tabId ?? this.activeTabId } };
+            case 'tabSwitch':
+                await this.switchTab(command.tabId);
+                return { id: command.id, success: true, data: { switched: command.tabId } };
+            case 'tabList': {
+                const tabs = await this.listTabs();
+                return { id: command.id, success: true, data: { tabs } };
+            }
+            case 'groupCreate': {
+                const group = await this.sessionManager.createGroup({
+                    tabIds: command.tabIds,
+                    title: command.title,
+                    color: command.color,
+                    collapsed: command.collapsed,
+                });
+                return { id: command.id, success: true, data: { group } };
+            }
+            case 'groupUpdate': {
+                const group = await this.sessionManager.updateGroup(command.groupId, {
+                    title: command.title,
+                    color: command.color,
+                    collapsed: command.collapsed,
+                });
+                return { id: command.id, success: true, data: { group } };
+            }
+            case 'groupDelete':
+                await this.sessionManager.deleteGroup(command.groupId);
+                return { id: command.id, success: true, data: { deleted: command.groupId } };
+            case 'groupList': {
+                const groups = await this.sessionManager.listGroups();
+                return { id: command.id, success: true, data: { groups } };
+            }
+            case 'groupAddTabs':
+                await this.sessionManager.addTabsToGroup(command.groupId, command.tabIds);
+                return { id: command.id, success: true, data: { addedTabs: command.tabIds } };
+            case 'groupRemoveTabs':
+                await this.sessionManager.removeTabsFromGroup(command.tabIds);
+                return { id: command.id, success: true, data: { removedTabs: command.tabIds } };
+            case 'groupGet': {
+                const group = await this.sessionManager.getGroup(command.groupId);
+                return { id: command.id, success: true, data: { group } };
+            }
+            case 'sessionGetCurrent': {
+                const session = await this.sessionManager.getCurrentSession();
+                return { id: command.id, success: true, data: { session } };
+            }
+            case 'popupInitialize': {
+                console.log('[BackgroundAgent] Popup initializing, checking for session reconnection...');
+                // Check if we have a stored session but no active connection
+                const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
+                if (sessionGroupId === null) {
+                    // Try to reconnect from storage
+                    const result = await chrome.storage.session.get('btcp_active_session');
+                    const stored = result['btcp_active_session'];
+                    if (stored?.groupId) {
+                        console.log('[BackgroundAgent] Found stored session, attempting reconnection...');
+                        const reconnected = await this.sessionManager.reconnectSession(stored.groupId);
+                        return {
+                            id: command.id,
+                            success: true,
+                            data: { initialized: true, reconnected },
+                        };
+                    }
+                }
+                return { id: command.id, success: true, data: { initialized: true, reconnected: false } };
+            }
+            default:
+                throw new Error(`Unknown extension action: ${command.action}`);
+        }
+    }
+    waitForTabLoad(tabId, timeout = 30000) {
+        return new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            const checkTab = () => {
+                chrome.tabs.get(tabId, (tab) => {
+                    if (chrome.runtime.lastError) {
+                        reject(new Error(chrome.runtime.lastError.message));
+                        return;
+                    }
+                    if (tab.status === 'complete') {
+                        resolve();
+                        return;
+                    }
+                    if (Date.now() - startTime > timeout) {
+                        reject(new Error('Tab load timeout'));
+                        return;
+                    }
+                    setTimeout(checkTab, 100);
+                });
+            };
+            checkTab();
+        });
+    }
+}
+// ============================================================================
+// MESSAGE LISTENER SETUP
+// ============================================================================
+// Singleton instance for message handling
+let backgroundAgent = null;
+/**
+ * Get or create the BackgroundAgent singleton
+ */
+export function getBackgroundAgent() {
+    if (!backgroundAgent) {
+        backgroundAgent = new BackgroundAgent();
+    }
+    return backgroundAgent;
+}
+/**
+ * @deprecated Use getBackgroundAgent instead
+ */
+export const getBrowserAgent = getBackgroundAgent;
+/**
+ * Set up the message listener for the background script
+ * Call this once in your background.ts to enable command routing
+ */
+export function setupMessageListener() {
+    chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+        const msg = message;
+        if (msg.type !== 'btcp:command') {
+            return false;
+        }
+        const agent = getBackgroundAgent();
+        // Execute the command (BackgroundAgent handles routing to correct tab)
+        agent.execute(msg.command)
+            .then((response) => {
+            sendResponse({ type: 'btcp:response', response });
+        })
+            .catch((error) => {
+            sendResponse({
+                type: 'btcp:response',
+                response: {
+                    id: msg.command.id,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+        });
+        return true; // Keep channel open for async response
+    });
+}
+// Legacy exports for backwards compatibility
+export const handleCommand = (command, _tabId) => getBackgroundAgent().execute(command);
+export const executeExtensionCommand = (command) => getBackgroundAgent().execute(command);
+export const sendToContentScript = (_tabId, command) => getBackgroundAgent().sendToContentAgent(command, _tabId);
+/**
+ * @deprecated Use BackgroundAgent instead
+ */
+export const BrowserAgent = BackgroundAgent;
+//# sourceMappingURL=background.js.map