btcp-browser-agent 0.1.0 → 0.1.1

package/examples/chrome-extension/CHANGELOG.md

@@ -1,210 +0,0 @@
-# Changelog
-
-## Latest Changes
-
-### Session Management with Auto-Created Blank Tab
-
-**What Changed:**
-- When you click "Start New Session", it now **creates a new blank tab** and adds it to the session
-- Previously used the current active tab, which could interrupt your workflow
-- The new blank tab is ready for automation without affecting existing tabs
-
-**Why:**
-- Clean slate for each session
-- Doesn't interfere with tabs you already have open
-- Clear starting point for automation
-
-**How It Works:**
-```javascript
-// User clicks "Start New Session"
-await client.groupCreate({ title: "BTCP Session 1" });
-
-// This now:
-// 1. Creates a new blank tab (about:blank)
-// 2. Adds it to a blue tab group labeled "BTCP Session 1"
-// 3. Makes it the active tab
-// 4. Ready for navigation/automation
-```
-
-**User Experience:**
-1. Click "Start New Session"
-2. New blank tab opens in a blue group
-3. All subsequent operations work in this session
-4. Your existing tabs remain untouched
-
-### Session-Only Mode
-
-**What Changed:**
-- Extension **only manages tabs within its session/tab group**
-- All operations require an active session
-- No operations allowed outside the session
-
-**Operations Affected:**
-- `listTabs()` - Only shows session tabs
-- `tabNew()` - Only creates in session
-- `closeTab()` - Only closes session tabs
-- `switchTab()` - Only switches to session tabs
-- `navigate()` - Only navigates session tabs
-- All DOM operations - Only in session tabs
-
-**Error Messages:**
-Without a session:
-```
-Error: "No active session. Create a session first to manage tabs."
-```
-
-Trying to access outside tabs:
-```
-Error: "Cannot switch to tab: tab is not in the active session"
-```
-
-**Benefits:**
-- ✅ Better security and isolation
-- ✅ Clear visual boundaries (tab groups)
-- ✅ Explicit user consent required
-- ✅ Protects personal tabs from automation
-- ✅ Clean separation of contexts
-
-## Testing the Changes
-
-### Test 1: New Blank Tab on Session Start
-```
-1. Open extension popup
-2. Click "Start New Session"
-3. Expected: New blank tab opens in blue group
-4. Verify: Tab shows "about:blank" URL
-5. Verify: Tab group labeled "BTCP Session 1"
-```
-
-### Test 2: Session Isolation
-```
-1. Have 3 regular tabs open (A, B, C)
-2. Start new session → new blank tab D in group
-3. Click "List Tabs" → should only show tab D
-4. Create new tab → should join session with D
-5. Tabs A, B, C remain untouched
-```
-
-### Test 3: Operations Require Session
-```
-1. Open popup without starting session
-2. Click "List Tabs" → Error shown
-3. Click "New Tab" → Error shown
-4. Start session → Operations now work
-```
-
-## Migration Guide
-
-### Before
-```javascript
-// Extension used current active tab
-await client.groupCreate();
-// Your current tab got grouped
-
-// Could access any tab
-const tabs = await client.listTabs(); // All tabs
-```
-
-### After
-```javascript
-// Extension creates new blank tab
-await client.groupCreate();
-// New blank tab created in group
-// Your existing tabs untouched
-
-// Only session tabs accessible
-const tabs = await client.listTabs(); // Only session tabs
-```
-
-### If You Want to Group Existing Tab
-```javascript
-// Get tab you want to add
-const targetTab = await chrome.tabs.get(tabId);
-
-// Create session with that tab
-await client.groupCreate({ tabIds: [targetTab.id] });
-
-// Or add to existing session
-const session = await client.sessionGetCurrent();
-await client.groupAddTabs(session.groupId, [targetTab.id]);
-```
-
-## Visual Guide
-
-### Session Start Flow
-
-**Before:**
-```
-Browser tabs: [Gmail] [GitHub] [YouTube*]
-                                    ↑ active
-User clicks "Start New Session"
-Result: [Gmail] [GitHub] [(YouTube* in blue group)]
-                          ↑ YouTube grouped, disrupts workflow
-```
-
-**After:**
-```
-Browser tabs: [Gmail] [GitHub] [YouTube]
-User clicks "Start New Session"
-Result: [Gmail] [GitHub] [YouTube] [(blank* in blue group)]
-                                      ↑ New tab, clean slate
-```
-
-### Session Isolation
-
-```
-Before session:
-[Tab A] [Tab B] [Tab C] [Tab D] [Tab E]
-  ↑ Extension could access all tabs
-
-After session:
-[Tab A] [Tab B] [Tab C] | [Session: Tab D] [Tab E*]
-                         ↑ Blue group boundary
-                           Extension only accesses D and E
-```
-
-## Breaking Changes
-
-### 1. Session Required
-**Before:** Could use extension without session
-**After:** Must create session first
-
-**Fix:** Always call `groupCreate()` before other operations
-
-### 2. No Universal Tab Access
-**Before:** Could access any tab in window
-**After:** Can only access tabs in session
-
-**Fix:** Add tabs to session explicitly or create new tabs via extension
-
-### 3. Active Tab Behavior
-**Before:** Session used current active tab
-**After:** Session creates new blank tab
-
-**Fix:** If you need to add existing tab, use `groupCreate({ tabIds: [existingTabId] })`
-
-## Rollback
-
-If you need the old behavior, you can modify the source:
-
-**Remove session requirement:**
-In `background.ts`, change validation:
-```typescript
-if (sessionGroupId === null) {
-  return true; // Allow without session
-}
-```
-
-**Use current tab instead of new:**
-In `session-manager.ts`, revert to:
-```typescript
-const [activeTab] = await chrome.tabs.query({ active: true });
-targetTabIds = [activeTab.id];
-```
-
-## Version Info
-
-- **Build Date:** 2026-01-16
-- **Session Manager:** Creates blank tab by default
-- **Access Mode:** Session-only (no universal access)
-- **Backward Compatible:** No (requires session for all operations)

package/examples/chrome-extension/DEBUG.md

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

@@ -1,147 +0,0 @@
-# ✅ 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
-```