btcp-browser-agent 0.1.0

package/examples/chrome-extension/DEBUG.md

@@ -0,0 +1,231 @@
+# Debugging Guide: Start Session Not Working
+
+## Step 1: Load the Extension
+
+1. Open Chrome and go to `chrome://extensions`
+2. Enable **Developer mode** (toggle in top right)
+3. Click **Load unpacked**
+4. Navigate to: `/Users/minh/Documents/btcp/btcp-browser-agent/examples/chrome-extension/dist/`
+5. Select the `dist` folder and click **Select**
+
+## Step 2: Check Extension Loaded
+
+You should see:
+- **BTCP Browser Agent** card in the extensions list
+- No errors shown in the extension card
+- Extension icon appears in the Chrome toolbar
+
+If you see errors, note them and check Step 3.
+
+## Step 3: Check for Permission Errors
+
+### View Background Service Worker Logs:
+1. On the extension card, click **service worker** link (under "Inspect views")
+2. This opens DevTools for the background script
+3. Check Console tab for errors
+
+**Common errors:**
+- `chrome.tabGroups is not defined` → Permission missing
+- `SessionManager is not a constructor` → Build issue
+- `Failed to execute 'group'` → Invalid tab IDs
+
+### Check Console Output:
+Look for these messages when extension loads:
+- No errors = Good ✅
+- Red errors = Problem ❌
+
+## Step 4: Test the Popup
+
+1. Click the extension icon in Chrome toolbar
+2. Popup should open showing:
+   - **Session** section at top
+   - "No active session" (gray)
+   - "Start New Session" button (blue)
+   - Quick Actions section below
+
+3. **Open popup DevTools:**
+   - Right-click anywhere in the popup
+   - Select **Inspect**
+   - Go to **Console** tab
+
+## Step 5: Test Start Session Button
+
+### Click "Start New Session" button and watch for:
+
+**In Popup Console (DevTools):**
+```
+[timestamp]
+Starting new session...
+```
+
+Then either:
+```javascript
+// Success:
+{
+  "created": "BTCP Session 1",
+  "groupId": 123
+}
+
+// Or Error:
+Error: [error message here]
+```
+
+**In Background Service Worker Console:**
+Look for command execution logs or errors.
+
+## Step 6: Common Issues & Solutions
+
+### Issue 1: "chrome.tabGroups is undefined"
+**Cause:** Permission not granted
+**Fix:**
+1. Open `manifest.json`
+2. Verify `"tabGroups"` is in `"permissions"` array
+3. Rebuild: `npm run build`
+4. Reload extension in `chrome://extensions`
+
+### Issue 2: "No active tab for DOM command"
+**Cause:** Extension needs an active tab to create group
+**Fix:**
+1. Make sure you have at least one tab open
+2. Click on a regular webpage tab (not chrome:// pages)
+3. Then click extension icon and try again
+
+### Issue 3: "Failed to execute 'group' on 'tabs'"
+**Cause:** Invalid tab ID or tab already closed
+**Fix:**
+1. Open a new tab first
+2. Navigate to a regular website (e.g., example.com)
+3. Then try creating session
+
+### Issue 4: Button click does nothing
+**Cause:** JavaScript error in popup
+**Fix:**
+1. Check popup console for errors (see Step 4)
+2. Common errors:
+   - `client.groupCreate is not a function` → Rebuild needed
+   - `btnStartSession is null` → HTML/JS mismatch
+   - `Cannot read property 'group'` → API response issue
+
+### Issue 5: "SessionManager is not a constructor"
+**Cause:** session-manager.js not properly built/imported
+**Fix:**
+```bash
+# Rebuild the packages
+cd /Users/minh/Documents/btcp/btcp-browser-agent
+npm run build
+cd examples/chrome-extension
+npm run build
+```
+Then reload extension.
+
+## Step 7: Manual Console Testing
+
+### Test in Background Service Worker Console:
+```javascript
+// Get background agent
+const agent = globalThis.__backgroundAgent;
+
+// Test session manager
+agent.sessionManager.createGroup({ title: "Test Session" })
+  .then(group => console.log("Created:", group))
+  .catch(err => console.error("Error:", err));
+```
+
+### Test in Popup Console:
+```javascript
+// Get client
+const client = createClient();
+
+// Test group creation
+client.groupCreate({ title: "Test Session" })
+  .then(result => console.log("Result:", result))
+  .catch(err => console.error("Error:", err));
+```
+
+## Step 8: Check Tab Groups API
+
+Test if Chrome supports tab groups:
+```javascript
+// In any console:
+console.log(chrome.tabGroups);
+// Should show: Object with methods like 'group', 'update', 'query'
+// If undefined: Chrome version too old or API not available
+```
+
+**Minimum Chrome version:** 89+ (tab groups API)
+
+## Step 9: Verify Session Creation Manually
+
+After clicking "Start New Session":
+
+1. **Check tabs in browser:**
+   - Do you see a blue colored tab group?
+   - Is there a label like "BTCP Session 1"?
+
+2. **If no group visible:**
+   - SessionManager may have created group but no tabs in it
+   - Try clicking "New Tab" button
+   - New tab should appear in a blue group
+
+## Step 10: Full Debug Flow
+
+Run this complete test in **Background Service Worker Console**:
+
+```javascript
+// 1. Check SessionManager exists
+console.log("SessionManager:", globalThis.SessionManager);
+
+// 2. Check background agent has session manager
+const agent = globalThis.__backgroundAgent || getBackgroundAgent();
+console.log("Agent has sessionManager:", !!agent.sessionManager);
+
+// 3. Try creating a group directly
+agent.sessionManager.createGroup({ title: "Debug Test" })
+  .then(group => {
+    console.log("✅ Group created:", group);
+    return chrome.tabs.query({ groupId: group.id });
+  })
+  .then(tabs => {
+    console.log("✅ Tabs in group:", tabs.length);
+  })
+  .catch(err => {
+    console.error("❌ Error:", err);
+    console.error("Stack:", err.stack);
+  });
+```
+
+## Step 11: Collect Debug Info
+
+If still not working, collect this info:
+
+```javascript
+// Run in Background Service Worker Console:
+{
+  chromeVersion: navigator.userAgent.match(/Chrome\/(\d+)/)?.[1],
+  tabGroupsAPI: typeof chrome.tabGroups,
+  sessionManagerLoaded: typeof SessionManager !== 'undefined',
+  backgroundAgent: typeof getBackgroundAgent !== 'undefined',
+  activeTabs: await chrome.tabs.query({ active: true }),
+  allGroups: await chrome.tabGroups.query({})
+}
+```
+
+## Quick Fix Checklist
+
+- [ ] Extension loaded without errors
+- [ ] Developer mode enabled
+- [ ] `tabGroups` permission in manifest
+- [ ] At least one regular tab open (not chrome://)
+- [ ] Background service worker console has no errors
+- [ ] Popup console has no errors
+- [ ] Chrome version 89 or higher
+- [ ] Extension reloaded after rebuild
+
+## Getting More Help
+
+If still stuck, provide:
+1. Chrome version
+2. Console errors from both background and popup
+3. Result of Step 10 debug flow
+4. Screenshot of extension popup
+5. Output of Step 11 debug info

package/examples/chrome-extension/ERROR_FIXED.md

@@ -0,0 +1,147 @@
+# ✅ Error Fixed: "Tabs can only be moved to and from normal windows"
+
+## What Was the Problem?
+
+The error occurred because:
+1. The extension was trying to get the "current window" using `chrome.windows.getCurrent()`
+2. When called from a popup, this returns the **popup window**, not the main browser window
+3. Chrome only allows tab grouping in **normal windows**, not popup/devtools/app windows
+
+## The Fix
+
+Changed `session-manager.ts` to:
+1. Find which window the target tab belongs to
+2. Verify it's a "normal" window type
+3. Use that window's ID for group creation
+4. Provide clear error messages if window type is wrong
+
+## How to Test Now
+
+### Step 1: Reload Extension
+```bash
+# Go to: chrome://extensions
+# Find: BTCP Browser Agent
+# Click the refresh icon (or remove and re-add)
+```
+
+### Step 2: Proper Test Setup
+1. **Open a regular browser window** (if you don't have one)
+2. **Open a regular website** in a tab (e.g., https://example.com)
+   - NOT chrome:// pages
+   - NOT extension pages
+   - NOT devtools
+3. **Make sure that tab is active** (click on it to focus)
+4. **Then click the extension icon** in the toolbar
+5. **Click "Start New Session"**
+
+### Step 3: Expected Result
+
+✅ **Success looks like:**
+```
+[SessionManager] createGroup called with options: {}
+[SessionManager] No tabIds provided, getting active tab...
+[SessionManager] Active tab: {id: 123, url: "https://example.com", ...}
+[SessionManager] Creating group with tabs: [123]
+[SessionManager] Group created with ID: 456
+[SessionManager] Group updated with title: BTCP Session 1
+```
+
+✅ **Visual confirmation:**
+- Your active tab gets a **blue border/group indicator**
+- The tab shows group label: **"BTCP Session 1"**
+- Popup updates to show session info
+
+## Common Mistakes to Avoid
+
+### ❌ Wrong: Opening popup in a popup window
+**Don't:** Open extension in its own window
+
+**Do:** Use the extension icon in the main browser toolbar
+
+### ❌ Wrong: Testing on chrome:// pages
+**Don't:** Have chrome://extensions as active tab
+
+**Do:** Have a real website (https://...) as active tab
+
+### ❌ Wrong: Using DevTools window
+**Don't:** Have DevTools undocked as separate window
+
+**Do:** Keep DevTools docked or use regular browser window
+
+## Verification Test
+
+Run this in the **Background Service Worker Console**:
+
+```javascript
+// Check window types
+chrome.windows.getAll({ populate: true }, (windows) => {
+  windows.forEach(w => {
+    console.log(`Window ${w.id}:`, {
+      type: w.type,
+      focused: w.focused,
+      tabs: w.tabs?.length || 0,
+      tabTitles: w.tabs?.map(t => t.title)
+    });
+  });
+});
+
+// This should show at least one window with type: "normal"
+```
+
+## Still Not Working?
+
+If you still get errors, provide:
+
+1. **Error message** (exact text from console)
+2. **Window type** (from verification test above)
+3. **Active tab URL** (what page are you on?)
+4. **How you opened the extension** (toolbar icon? right-click?)
+
+## Next Steps After Fix Works
+
+Once "Start New Session" works:
+
+1. ✅ **Test "New Tab" button** - should auto-join the session
+2. ✅ **Test "Close Session" button** - should close all tabs in group
+3. ✅ **Test multiple tabs** - create several tabs, verify they all join
+4. ✅ **Test session persistence** - session should exist until you close it
+
+## Technical Details
+
+The key change in `session-manager.ts`:
+
+```typescript
+// OLD (broken):
+const groupId = await chrome.tabs.group({
+  tabIds: targetTabIds,
+  createProperties: {
+    windowId: (await chrome.windows.getCurrent()).id,  // ❌ Returns popup window!
+  },
+});
+
+// NEW (fixed):
+const tabs = await chrome.tabs.query({ windowId: chrome.windows.WINDOW_ID_CURRENT });
+const targetTab = tabs.find(t => targetTabIds.includes(t.id!));
+const window = await chrome.windows.get(targetTab.windowId);
+
+if (window.type !== 'normal') {
+  throw new Error(`Tabs can only be grouped in normal windows`);
+}
+
+const groupId = await chrome.tabs.group({
+  tabIds: targetTabIds,
+  createProperties: {
+    windowId: targetTab.windowId,  // ✅ Uses tab's actual window!
+  },
+});
+```
+
+## Build Version
+
+This fix is included in the build dated: **2026-01-16**
+
+Make sure you rebuild and reload:
+```bash
+npm run build
+# Then reload extension in chrome://extensions
+```

package/examples/chrome-extension/QUICK_TEST.md

@@ -0,0 +1,189 @@
+# 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

@@ -0,0 +1,149 @@
+# 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