btcp-browser-agent 0.1.0 → 0.1.1

package/examples/chrome-extension/QUICK_TEST.md

@@ -1,189 +0,0 @@
-# Quick Test: Session Debugging
-
-## 1. Load Extension (Fresh Start)
-
-```bash
-# Location: chrome://extensions
-# 1. Remove old version if exists
-# 2. Click "Load unpacked"
-# 3. Select: /Users/minh/Documents/btcp/btcp-browser-agent/examples/chrome-extension/dist
-```
-
-## 2. Open Background Console
-
-1. In `chrome://extensions`, find **BTCP Browser Agent**
-2. Click **service worker** (under "Inspect views")
-3. This opens the background script DevTools
-
-## 3. Run This Test in Background Console
-
-Copy and paste this entire block:
-
-```javascript
-console.log('=== BTCP Session Debug Test ===');
-
-// Test 1: Check API availability
-console.log('1. Chrome APIs:');
-console.log('  - chrome.tabs:', typeof chrome.tabs);
-console.log('  - chrome.tabGroups:', typeof chrome.tabGroups);
-console.log('  - chrome.windows:', typeof chrome.windows);
-
-// Test 2: Check SessionManager
-console.log('\n2. SessionManager:');
-console.log('  - SessionManager class:', typeof SessionManager);
-
-// Test 3: Check BackgroundAgent
-console.log('\n3. BackgroundAgent:');
-const agent = getBackgroundAgent();
-console.log('  - Agent exists:', !!agent);
-console.log('  - Has sessionManager:', !!agent?.sessionManager);
-
-// Test 4: Check tabs
-console.log('\n4. Current tabs:');
-chrome.tabs.query({}, (tabs) => {
-  console.log('  - Total tabs:', tabs.length);
-  console.log('  - Active tabs:', tabs.filter(t => t.active).length);
-  const activeTab = tabs.find(t => t.active);
-  if (activeTab) {
-    console.log('  - Active tab ID:', activeTab.id);
-    console.log('  - Active tab URL:', activeTab.url);
-  }
-});
-
-// Test 5: Try creating session
-console.log('\n5. Attempting to create session...');
-if (agent?.sessionManager) {
-  agent.sessionManager.createGroup({ title: 'Test Session' })
-    .then(group => {
-      console.log('✅ SUCCESS! Group created:');
-      console.log('  - ID:', group.id);
-      console.log('  - Title:', group.title);
-      console.log('  - Color:', group.color);
-      return chrome.tabs.query({ groupId: group.id });
-    })
-    .then(tabs => {
-      console.log('  - Tabs in group:', tabs.length);
-      console.log('\n🎉 Session working! Check your tabs for a blue group.');
-    })
-    .catch(err => {
-      console.error('❌ FAILED! Error:', err.message);
-      console.error('   Stack:', err.stack);
-    });
-} else {
-  console.error('❌ SessionManager not available!');
-}
-```
-
-## 4. What to Look For
-
-### SUCCESS looks like:
-```
-=== BTCP Session Debug Test ===
-1. Chrome APIs:
-  - chrome.tabs: object
-  - chrome.tabGroups: object
-  - chrome.windows: object
-
-2. SessionManager:
-  - SessionManager class: function
-
-3. BackgroundAgent:
-  - Agent exists: true
-  - Has sessionManager: true
-
-4. Current tabs:
-  - Total tabs: 3
-  - Active tabs: 1
-  - Active tab ID: 123
-  - Active tab URL: https://example.com/
-
-5. Attempting to create session...
-[SessionManager] createGroup called with options: {title: "Test Session"}
-[SessionManager] No tabIds provided, getting active tab...
-[SessionManager] Active tab: {id: 123, ...}
-[SessionManager] Creating group with tabs: [123]
-[SessionManager] Group created with ID: 456
-[SessionManager] Group updated with title: Test Session
-[SessionManager] Group info: {id: 456, title: "Test Session", ...}
-✅ SUCCESS! Group created:
-  - ID: 456
-  - Title: Test Session
-  - Color: blue
-  - Tabs in group: 1
-
-🎉 Session working! Check your tabs for a blue group.
-```
-
-### FAILURE might show:
-```
-❌ FAILED! Error: No active tab available to create session
-```
-**Fix:** Open a regular webpage (not chrome:// page)
-
-```
-  - chrome.tabGroups: undefined
-```
-**Fix:** Update Chrome to version 89+
-
-```
-❌ SessionManager not available!
-```
-**Fix:** Extension not built correctly, run: `npm run build`
-
-## 5. Test from Popup
-
-If background test works, test the popup:
-
-1. Click extension icon
-2. Right-click in popup → Inspect
-3. In popup console, run:
-
-```javascript
-// Quick popup test
-const client = createClient();
-client.groupCreate({ title: 'Popup Test' })
-  .then(result => console.log('✅ Popup works:', result))
-  .catch(err => console.error('❌ Popup failed:', err));
-```
-
-## 6. Common Issues Found
-
-### Issue: "Cannot group extension page tabs"
-**Symptom:** Error when popup tries to group itself
-**Solution:** Make sure the ACTIVE tab is a regular webpage, not the popup or chrome:// page
-
-### Issue: "activeTab is undefined"
-**Symptom:** No tab found to add to group
-**Solution:**
-1. Click on a regular webpage tab FIRST
-2. THEN open the extension popup
-3. Try creating session
-
-### Issue: "chrome.tabGroups is not defined"
-**Symptom:** API not available
-**Solution:**
-1. Check Chrome version: `chrome://version`
-2. Needs Chrome 89 or higher
-3. Update Chrome if needed
-
-## 7. Next Steps Based on Results
-
-**If Test 5 succeeds but popup fails:**
-→ Check popup console for errors
-→ Verify popup.js has client.groupCreate method
-→ Check communication between popup and background
-
-**If Test 5 fails with "No active tab":**
-→ Open a website in a tab
-→ Click on that tab (make it active)
-→ Run test again
-
-**If SessionManager not found:**
-→ Rebuild: `npm run build` in project root
-→ Rebuild: `npm run build` in examples/chrome-extension
-→ Reload extension
-
-**If everything works in test but not in UI:**
-→ Check popup console for JavaScript errors
-→ Verify button event listeners attached
-→ Check if updateSessionUI() is being called

package/examples/chrome-extension/README.md

@@ -1,149 +0,0 @@
-# Chrome Extension Example
-
-Production-ready TypeScript example using `@btcp/browser-agent`.
-
-## Project Structure
-
-```
-examples/chrome-extension/
-├── src/
-│   ├── content.ts      # DOM agent + message listener
-│   ├── background.ts   # routes messages
-│   └── popup.ts        # UI using createClient
-├── dist/               # Built output (gitignored)
-├── manifest.json       # Chrome extension manifest
-├── popup.html          # Popup UI
-├── package.json        # Build dependencies
-├── tsconfig.json       # TypeScript config
-└── build.js            # esbuild script
-```
-
-## Source Files
-
-**src/content.ts** - registers DOM agent and message listener
-```typescript
-import { createContentAgent } from '@btcp/browser-agent/extension';
-
-const agent = createContentAgent();
-chrome.runtime.onMessage.addListener(agent.handleMessage);
-```
-
-**src/background.ts** - routes messages
-```typescript
-import { setupMessageListener } from '@btcp/browser-agent/extension';
-setupMessageListener();
-```
-
-**src/popup.ts** - sends commands
-```typescript
-import { createClient } from '@btcp/browser-agent/extension';
-
-const client = createClient();
-await client.navigate('https://example.com');
-const { tree } = await client.snapshot();
-await client.click('@ref:5');
-```
-
-## Setup
-
-```bash
-# Install dependencies
-npm install
-
-# Build the extension
-npm run build
-
-# Or watch for changes
-npm run watch
-```
-
-## Load Extension
-
-1. Open `chrome://extensions`
-2. Enable "Developer mode"
-3. Click "Load unpacked"
-4. Select this directory
-
-## Architecture
-
-```
-Popup ──chrome.runtime.sendMessage──► Background (setupMessageListener)
-                                           │
-                                    chrome.tabs.sendMessage
-                                           ▼
-                                      Content Script (auto-registered)
-                                           │
-                                      ContentAgent → DOM
-```
-
-## API Usage
-
-```typescript
-import { createClient } from '@btcp/browser-agent/extension';
-
-const client = createClient();
-
-// Navigation
-await client.navigate('https://example.com');
-await client.back();
-await client.forward();
-await client.reload();
-
-// DOM operations
-const { tree } = await client.snapshot();
-await client.click('@ref:5');
-await client.fill('@ref:3', 'hello@example.com');
-await client.type('@ref:3', 'typing slowly', { delay: 50 });
-const text = await client.getText('@ref:5');
-const visible = await client.isVisible('@ref:5');
-
-// Tab management
-const tabs = await client.tabList();
-const newTab = await client.tabNew({ url: 'https://github.com' });
-await client.tabSwitch(newTab.tabId);
-await client.tabClose(newTab.tabId);
-
-// Screenshot
-const base64 = await client.screenshot();
-```
-
-## Command Reference
-
-### Browser Operations (BackgroundAgent)
-
-| Method | Description |
-|--------|-------------|
-| `navigate(url)` | Navigate to URL |
-| `back()` / `forward()` | History navigation |
-| `reload()` | Reload page |
-| `screenshot()` | Capture visible tab |
-| `tabNew()` / `tabClose()` | Tab management |
-| `tabSwitch()` / `tabList()` | Tab switching |
-| `getUrl()` / `getTitle()` | Get page info |
-
-### DOM Operations (ContentAgent)
-
-| Method | Description |
-|--------|-------------|
-| `snapshot()` | Get accessibility tree with refs |
-| `click(selector)` | Click element |
-| `fill(selector, value)` | Set input value |
-| `type(selector, text)` | Type text with events |
-| `getText(selector)` | Get element text |
-| `isVisible(selector)` | Check visibility |
-
-## Selectors
-
-```typescript
-// Ref from snapshot (recommended)
-await client.click('@ref:5');
-
-// CSS selectors
-await client.click('#submit');
-await client.click('.btn-primary');
-await client.click('[data-testid="login"]');
-```
-
-## License
-
-Apache-2.0

package/examples/chrome-extension/SESSION_ONLY_MODE.md

@@ -1,305 +0,0 @@
-# Session-Only Mode
-
-## Overview
-
-The BTCP Browser Agent **only manages tabs within its session/tab group**. No operations are allowed outside of a session.
-
-## Key Principle
-
-**Session is Required** - All operations require an active session:
-
-- ❌ Cannot list tabs without a session
-- ❌ Cannot create tabs without a session
-- ❌ Cannot navigate without a session
-- ❌ Cannot perform DOM operations without a session
-- ✅ Must create session first, then all operations work within that session
-
-## How It Works
-
-### 1. Session Must Be Created First
-
-```javascript
-// Create a session to start working
-await client.groupCreate({ title: "BTCP Session 1" });
-
-// Now all operations work (scoped to session)
-await client.tabNew({ url: "https://example.com" });
-await client.listTabs(); // Only session tabs
-```
-
-### 2. Without Session = Error
-
-```javascript
-// Try to list tabs without session
-await client.listTabs();
-// ❌ Error: "No active session. Create a session first to manage tabs."
-
-// Try to create tab without session
-await client.tabNew({ url: "https://example.com" });
-// ❌ Error: "No active session. Create a session first to manage tabs."
-```
-
-### 3. Operations Are Session-Scoped
-
-Once a session exists, all operations only affect tabs in that session:
-
-```javascript
-// Create session with tab A
-await client.groupCreate(); // Tab A joins session
-
-// Create new tabs (auto-added to session)
-await client.tabNew({ url: "https://example.com" }); // Tab B
-await client.tabNew({ url: "https://github.com" }); // Tab C
-
-// List tabs (only shows A, B, C)
-const tabs = await client.listTabs(); // [A, B, C]
-
-// User manually opens Tab D outside session
-
-// Try to list tabs (still only shows session tabs)
-const tabs2 = await client.listTabs(); // [A, B, C] - no Tab D
-
-// Try to access Tab D
-await client.switchTab(tabD.id);
-// ❌ Error: "Cannot switch to tab: tab is not in the active session"
-```
-
-## Implementation Details
-
-### Session Requirement Check
-
-Every operation checks for active session:
-
-```typescript
-async listTabs(): Promise<TabInfo[]> {
-  const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
-
-  // Session is required
-  if (sessionGroupId === null) {
-    throw new Error('No active session. Create a session first.');
-  }
-
-  // Only query tabs in the session group
-  const tabs = await chrome.tabs.query({ groupId: sessionGroupId });
-  return tabs.map(mapToTabInfo);
-}
-```
-
-### Tab Validation
-
-Operations validate tab membership:
-
-```typescript
-private async isTabInSession(tabId: number): Promise<boolean> {
-  const sessionGroupId = this.sessionManager.getActiveSessionGroupId();
-
-  // Session required
-  if (sessionGroupId === null) {
-    throw new Error('No active session.');
-  }
-
-  // Check if tab is in session
-  const tab = await chrome.tabs.get(tabId);
-  return tab.groupId === sessionGroupId;
-}
-```
-
-### New Tab Creation
-
-New tabs are automatically added to session:
-
-```typescript
-async newTab(options?: { url?: string }): Promise<TabInfo> {
-  // Check session exists
-  if (!this.sessionManager.getActiveSessionGroupId()) {
-    throw new Error('No active session.');
-  }
-
-  // Create tab
-  const tab = await chrome.tabs.create({ url: options?.url });
-
-  // Add to session
-  const added = await this.sessionManager.addTabToActiveSession(tab.id);
-  if (!added) {
-    // Cleanup if failed
-    await chrome.tabs.remove(tab.id);
-    throw new Error('Failed to add tab to session');
-  }
-
-  return mapToTabInfo(tab);
-}
-```
-
-## Usage Example
-
-### Complete Workflow
-
-```javascript
-// 1. Create session (required first step)
-await client.groupCreate({ title: "Work Session" });
-// Current tab joins blue group "Work Session"
-
-// 2. Now can create tabs (auto-added to session)
-await client.tabNew({ url: "https://example.com" });
-await client.tabNew({ url: "https://github.com" });
-
-// 3. List tabs (only shows session tabs)
-const tabs = await client.listTabs();
-console.log(tabs.length); // 3 tabs
-
-// 4. Navigate, interact (only session tabs)
-await client.navigate("https://newsite.com");
-await client.click("#button");
-await client.fill("#input", "value");
-
-// 5. Close session (closes all tabs)
-const session = await client.sessionGetCurrent();
-await client.groupDelete(session.groupId);
-```
-
-### Error Handling
-
-```javascript
-try {
-  // Try operation without session
-  await client.listTabs();
-} catch (err) {
-  if (err.message.includes('No active session')) {
-    // Create session first
-    await client.groupCreate();
-
-    // Now retry
-    const tabs = await client.listTabs();
-  }
-}
-```
-
-## Benefits
-
-### 1. Security & Isolation
-- Extension cannot access tabs outside its scope
-- User's personal tabs are protected
-- Clear boundaries enforced by code
-
-### 2. Explicit Consent
-- User must explicitly create session
-- Visual indicator (tab group color/label)
-- No accidental access to unrelated tabs
-
-### 3. Clean Separation
-- Each session is independent
-- Easy to manage multiple workflows
-- Clear visual organization
-
-### 4. Predictable Behavior
-- All operations scoped to one group
-- No ambiguity about which tabs are managed
-- Consistent error messages
-
-## Visual Indicators
-
-### Chrome Tab Groups
-- Session tabs have **colored border** (e.g., blue)
-- Group label shows session name (e.g., "BTCP Session 1")
-- Can collapse/expand the group
-- Easy to see which tabs are in scope
-
-### Extension Popup
-- Shows session status (active/inactive)
-- Displays session name and tab count
-- Info: "Extension only manages tabs within the active session"
-- Buttons disabled when no session
-
-## Comparison
-
-### Before (Universal Access)
-```javascript
-// Could access any tab
-const allTabs = await client.listTabs(); // All tabs in window
-
-// Could navigate any tab
-await client.switchTab(anyTabId); // Works
-
-// Could close any tab
-await client.tabClose(anyTabId); // Works
-```
-
-### After (Session-Only)
-```javascript
-// Must create session first
-await client.groupCreate();
-
-// Only session tabs
-const sessionTabs = await client.listTabs(); // Only grouped tabs
-
-// Only session tabs accessible
-await client.switchTab(sessionTabId); // ✅ Works
-await client.switchTab(outsideTabId); // ❌ Error
-
-// Only session tabs closable
-await client.tabClose(sessionTabId); // ✅ Works
-await client.tabClose(outsideTabId); // ❌ Error
-```
-
-## FAQ
-
-**Q: Can I use the extension without creating a session?**
-A: No. Session creation is required for all operations.
-
-**Q: What if I manually move a tab out of the session group?**
-A: The extension immediately loses access to that tab.
-
-**Q: Can I manually add tabs to the session?**
-A: Yes! Drag any tab into the session group, and it becomes accessible.
-
-**Q: What happens if the session group is deleted?**
-A: All operations will fail until a new session is created.
-
-**Q: Can operations work across multiple sessions?**
-A: No. Only one active session at a time, and operations are scoped to it.
-
-**Q: Why is session required?**
-A: Security, isolation, and explicit user consent. The extension should only manage what the user explicitly adds to the session.
-
-## Testing
-
-### Test Session Requirement
-
-```javascript
-// 1. Try without session (should fail)
-try {
-  await client.listTabs();
-  console.error('❌ Should have failed');
-} catch (err) {
-  console.log('✅ Correctly requires session:', err.message);
-}
-
-// 2. Create session
-await client.groupCreate({ title: "Test" });
-
-// 3. Operations now work
-const tabs = await client.listTabs();
-console.log('✅ Session allows operations:', tabs.length);
-
-// 4. Try accessing outside tab (should fail)
-// (manually open tab outside session first)
-try {
-  await client.switchTab(outsideTabId);
-  console.error('❌ Should have blocked outside tab');
-} catch (err) {
-  console.log('✅ Correctly blocks outside tab:', err.message);
-}
-```
-
-## Summary
-
-**Core Principle**: Session-first, session-only
-
-- ✅ Session required for all operations
-- ✅ All operations scoped to session tabs only
-- ✅ Clear errors when session missing
-- ✅ Visual boundaries via tab groups
-- ✅ Explicit user consent required
-- ✅ Maximum security and isolation
-
-The extension is now a **pure session manager** - it only works within the boundaries of its explicitly created session.