btcp-browser-agent 0.1.0

package/examples/chrome-extension/SESSION_ONLY_MODE.md

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

package/examples/chrome-extension/TEST_WITH_YOUR_TABS.md

@@ -0,0 +1,97 @@
+# Test Session with Your Current Tabs
+
+## ✅ Good News: Extension is Working!
+
+Your tab list command worked perfectly. You have 5 tabs:
+- GitHub BTCP repo
+- Claude.ai session
+- GitHub Pull Request
+- **YouTube video (ACTIVE)** ← Perfect for testing!
+- Chrome extensions page
+
+## Test the Session Now
+
+Since the YouTube tab (ID: 1892096437) is active, it's perfect for testing:
+
+### Step 1: Create Session
+1. **Click the extension icon** (should still be open)
+2. **Click "Start New Session"** button
+3. **Watch the YouTube tab** - it should get a blue group border
+
+### Step 2: Verify Success
+Check if you see:
+- ✅ Blue/colored border around the YouTube tab
+- ✅ Group label appears: "BTCP Session 1"
+- ✅ Popup shows: "BTCP Session 1" with "1 tab"
+
+### Step 3: Test Auto-Grouping
+1. In the popup, click **"New Tab"** button
+2. A new tab should open at example.com
+3. **It should automatically join the "BTCP Session 1" group**
+4. Popup should update to show "2 tabs"
+
+### Step 4: Test Close Session
+1. Click **"Close Session"** button (red button)
+2. **Both tabs in the group should close** (YouTube + new tab)
+
+## What to Look For
+
+### Console Output (Background Service Worker)
+When you click "Start New Session", you should see:
+
+```
+[SessionManager] createGroup called with options: {}
+[SessionManager] No tabIds provided, getting active tab...
+[SessionManager] Active tab: {id: 1892096437, url: "https://www.youtube.com/...", ...}
+[SessionManager] Creating group with tabs: [1892096437]
+[SessionManager] Group created with ID: <some-number>
+[SessionManager] Group updated with title: BTCP Session 1
+```
+
+### Visual Feedback
+In your browser:
+- YouTube tab gets colored border/background
+- Tab shows group indicator
+- Can collapse/expand the group by clicking the group label
+
+## If It Works
+
+Congratulations! 🎉 Your session management is fully functional!
+
+You can now:
+- ✅ Start sessions to organize tabs
+- ✅ Auto-group new tabs created by the extension
+- ✅ Close entire sessions at once
+- ✅ Track how many tabs are in each session
+
+## If It Doesn't Work
+
+Check these:
+
+1. **Error in popup console?**
+   - Right-click popup → Inspect → Console tab
+   - Share the error message
+
+2. **Error in background console?**
+   - Go to chrome://extensions
+   - Click "service worker" under BTCP Browser Agent
+   - Check console for errors
+
+3. **Nothing happens?**
+   - Make sure YouTube tab is actually active (click on it first)
+   - Try refreshing the extension
+   - Check if "Start New Session" button is enabled
+
+## Next: Make Sessions Automatic
+
+Based on your earlier comment about wanting `launch` to handle sessions, we can make this more automatic:
+
+**Option 1:** First `tabNew` automatically creates a session
+- User doesn't need to click "Start New Session"
+- Just click "New Tab" and session auto-starts
+
+**Option 2:** Session always exists
+- Background script creates default session on startup
+- All operations happen in that session
+
+Would you like me to implement either of these?

package/examples/chrome-extension/build.js

@@ -0,0 +1,43 @@
+import * as esbuild from 'esbuild';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const watch = process.argv.includes('--watch');
+
+const config = {
+  entryPoints: [
+    'src/background.ts',
+    'src/content.ts',
+    'src/popup.ts',
+  ],
+  bundle: true,
+  outdir: 'dist',
+  format: 'esm',
+  platform: 'browser',
+  target: 'chrome120',
+  sourcemap: true,
+};
+
+// Copy static files to dist
+function copyStaticFiles() {
+  const filesToCopy = ['manifest.json', 'popup.html'];
+
+  if (!fs.existsSync('dist')) {
+    fs.mkdirSync('dist', { recursive: true });
+  }
+
+  for (const file of filesToCopy) {
+    fs.copyFileSync(file, path.join('dist', file));
+  }
+}
+
+if (watch) {
+  const ctx = await esbuild.context(config);
+  await ctx.watch();
+  copyStaticFiles();
+  console.log('Watching for changes...');
+} else {
+  await esbuild.build(config);
+  copyStaticFiles();
+  console.log('Build complete');
+}

package/examples/chrome-extension/manifest.json

@@ -0,0 +1,37 @@
+{
+  "manifest_version": 3,
+  "name": "BTCP Browser Agent",
+  "version": "1.0.0",
+  "description": "Browser automation with DOM actions and navigation",
+
+  "permissions": [
+    "activeTab",
+    "tabs",
+    "tabGroups",
+    "scripting",
+    "storage"
+  ],
+
+  "host_permissions": [
+    "<all_urls>"
+  ],
+
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content.js"],
+      "run_at": "document_idle",
+      "all_frames": true
+    }
+  ],
+
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "BTCP Agent"
+  }
+}