opengstack 0.13.4

package/docs/designs/CHROME_VS_CHROMIUM_EXPLORATION.md

@@ -0,0 +1,84 @@
+# Chrome vs Chromium: Why We Use Playwright's Bundled Chromium
+
+## The Original Vision
+
+When we built `$B connect`, the plan was to connect to the user's **real Chrome browser** — the one with their cookies, sessions, extensions, and open tabs. No more cookie import. The design called for:
+
+1. `chromium.connectOverCDP(wsUrl)` connecting to a running Chrome via CDP
+2. Quit Chrome gracefully, relaunch with `--remote-debugging-port=9222`
+3. Access the user's real browsing context
+
+This is why `chrome-launcher.ts` existed (361 LOC of browser binary discovery, CDP port probing, and runtime detection) and why the method was called `connectCDP()`.
+
+## What Actually Happened
+
+Real Chrome silently blocks `--load-extension` when launched via Playwright's `channel: 'chrome'`. The extension wouldn't load. We needed the extension for the side panel (activity feed, refs, chat).
+
+The implementation fell back to `chromium.launchPersistentContext()` with Playwright's bundled Chromium — which reliably loads extensions via `--load-extension` and `--disable-extensions-except`. But the naming stayed: `connectCDP()`, `connectionMode: 'cdp'`, `BROWSE_CDP_URL`, `chrome-launcher.ts`.
+
+The original vision (access user's real browser state) was never implemented. We launched a fresh browser every time — functionally identical to Playwright's Chromium, but with 361 lines of dead code and misleading names.
+
+## The Discovery (2026-03-22)
+
+During a `/office-hours` design session, we traced the architecture and discovered:
+
+1. `connectCDP()` doesn't use CDP — it calls `launchPersistentContext()`
+2. `connectionMode: 'cdp'` is misleading — it's just "headed mode"
+3. `chrome-launcher.ts` is dead code — its only import was in an unreachable `attemptReconnect()` method
+4. `preExistingTabIds` was designed for protecting real Chrome tabs we never connect to
+5. `$B handoff` (headless → headed) used a different API (`launch()` + `newContext()`) that couldn't load extensions, creating two different "headed" experiences
+
+## The Fix
+
+### Renamed
+- `connectCDP()` → `launchHeaded()`
+- `connectionMode: 'cdp'` → `connectionMode: 'headed'`
+- `BROWSE_CDP_URL` → `BROWSE_HEADED`
+
+### Deleted
+- `chrome-launcher.ts` (361 LOC)
+- `attemptReconnect()` (dead method)
+- `preExistingTabIds` (dead concept)
+- `reconnecting` field (dead state)
+- `cdp-connect.test.ts` (tests for deleted code)
+
+### Converged
+- `$B handoff` now uses `launchPersistentContext()` + extension loading (same as `$B connect`)
+- One headed mode, not two
+- Handoff gives you the extension + side panel for free
+
+### Gated
+- Sidebar chat behind `--chat` flag
+- `$B connect` (default): activity feed + refs only
+- `$B connect --chat`: + experimental standalone chat agent
+
+## Architecture (after)
+
+```
+Browser States:
+  HEADLESS (default) ←→ HEADED ($B connect or $B handoff)
+     Playwright            Playwright (same engine)
+     launch()              launchPersistentContext()
+     invisible             visible + extension + side panel
+
+Sidebar (orthogonal add-on, headed only):
+  Activity tab    — always on, shows live browse commands
+  Refs tab        — always on, shows @ref overlays
+  Chat tab        — opt-in via --chat, experimental standalone agent
+
+Data Bridge (sidebar → workspace):
+  Sidebar writes to .context/sidebar-inbox/*.json
+  Workspace reads via $B inbox
+```
+
+## Why Not Real Chrome?
+
+Real Chrome blocks `--load-extension` when launched by Playwright. This is a Chrome security feature — extensions loaded via command-line args are restricted in Chromium-based browsers to prevent malicious extension injection.
+
+Playwright's bundled Chromium doesn't have this restriction because it's designed for testing and automation. The `ignoreDefaultArgs` option lets us bypass Playwright's own extension-blocking flags.
+
+If we ever want to access the user's real cookies/sessions, the path is:
+1. Cookie import (already works via `$B cookie-import`)
+2. Conductor session injection (future — sidebar sends messages to workspace agent)
+
+Not reconnecting to real Chrome.

package/docs/designs/CONDUCTOR_CHROME_SIDEBAR_INTEGRATION.md

@@ -0,0 +1,57 @@
+# Chrome Sidebar + Conductor: What We Need
+
+## What we're building
+
+Right now when Claude is working in a Conductor workspace — editing files, running tests, browsing your app — you can only watch from Conductor's chat window. If Claude is doing QA on your website, you see tool calls scrolling by but you can't actually *see* the browser.
+
+We built a Chrome sidebar that fixes this. When you run `$B connect`, Chrome opens with a side panel that shows everything Claude is doing in real time. You can type messages in the sidebar and Claude acts on them — "click the signup button", "go to the settings page", "summarize what you see."
+
+The problem: the sidebar currently runs its own separate Claude instance. It can't see what the main Conductor session is doing, and the main session can't see what the sidebar is doing. They're two separate agents that don't talk to each other.
+
+The fix is simple: make the sidebar a *window into* the Conductor session, not a separate thing.
+
+## What we need from Conductor (3 things)
+
+### 1. Let us watch what the agent is doing
+
+We need a way to subscribe to the active session's events. Something like an SSE stream or WebSocket that sends us events as they happen:
+
+- "Claude is editing `src/App.tsx`"
+- "Claude is running `npm test`"
+- "Claude says: I'll fix the CSS issue..."
+
+The sidebar already knows how to render these events — tool calls show as compact badges, text shows as chat bubbles. We just need a pipe from Conductor's session to our extension.
+
+### 2. Let us send messages into the session
+
+When the user types "click the other button" in the Chrome sidebar, that message should appear in the Conductor session as if the user typed it in the workspace chat. The agent picks it up on its next turn and acts on it.
+
+This is the magic moment: user is watching Chrome, sees something wrong, types a correction in the sidebar, and Claude responds — without the user ever switching windows.
+
+### 3. Let us create a workspace from a directory
+
+When `$B connect` launches, it creates a git worktree for file isolation. We want to register that worktree as a Conductor workspace so the user can see the sidebar agent's file changes in Conductor's file tree. This also sets up the foundation for multiple browser sessions, each with their own workspace.
+
+## Why this matters
+
+Today, `/qa` and `/design-review` feel like a black box. Claude says "I found 3 issues" but you can't see what it's looking at. With the sidebar connected to Conductor:
+
+- **You watch Claude test your app** in real time — every click, every navigation, every screenshot appears in Chrome while you watch
+- **You can interrupt** — "no, test the mobile view" or "skip that page" — without switching windows
+- **One agent, two views** — the same Claude that's editing your code is also controlling the browser. No context duplication, no stale state
+
+## What's already built (gstack side)
+
+Everything on our side is done and shipping:
+
+- Chrome extension that auto-loads when you run `$B connect`
+- Side panel that auto-opens (zero setup for the user)
+- Streaming event renderer (tool calls, text, results)
+- Chat input with message queuing
+- Reconnect logic with status banners
+- Session management with persistent chat history
+- Agent lifecycle (spawn, stop, kill, timeout detection)
+
+The only change on our side: swap the data source from "local `claude -p` subprocess" to "Conductor session stream." The extension code stays the same.
+
+**Estimated effort:** 2-3 days Conductor engineering, 1 day gstack integration.

package/docs/designs/CONDUCTOR_SESSION_API.md

@@ -0,0 +1,108 @@
+# Conductor Session Streaming API Proposal
+
+## Problem
+
+When Claude controls your real browser via CDP (gstack `$B connect`), you look at two
+windows: **Conductor** (to see Claude's thinking) and **Chrome** (to see Claude's actions).
+
+gstack's Chrome extension Side Panel shows browse activity — every command, result,
+and error. But for *full* session mirroring (Claude's thinking, tool calls, code edits),
+the Side Panel needs Conductor to expose the conversation stream.
+
+## What this enables
+
+A "Session" tab in the gstack Chrome extension Side Panel that shows:
+- Claude's thinking/content (truncated for performance)
+- Tool call names + icons (Edit, Bash, Read, etc.)
+- Turn boundaries with cost estimates
+- Real-time updates as the conversation progresses
+
+The user sees everything in one place — Claude's actions in their browser + Claude's
+thinking in the Side Panel — without switching windows.
+
+## Proposed API
+
+### `GET http://127.0.0.1:{PORT}/workspace/{ID}/session/stream`
+
+Server-Sent Events endpoint that re-emits Claude Code's conversation as NDJSON events.
+
+**Event types** (reuse Claude Code's `--output-format stream-json` format):
+
+```
+event: assistant
+data: {"type":"assistant","content":"Let me check that page...","truncated":true}
+
+event: tool_use
+data: {"type":"tool_use","name":"Bash","input":"$B snapshot","truncated_input":true}
+
+event: tool_result
+data: {"type":"tool_result","name":"Bash","output":"[snapshot output...]","truncated_output":true}
+
+event: turn_complete
+data: {"type":"turn_complete","input_tokens":1234,"output_tokens":567,"cost_usd":0.02}
+```
+
+**Content truncation:** Tool inputs/outputs capped at 500 chars in the stream. Full
+data stays in Conductor's UI. The Side Panel is a summary view, not a replacement.
+
+### `GET http://127.0.0.1:{PORT}/api/workspaces`
+
+Discovery endpoint listing active workspaces.
+
+```json
+{
+  "workspaces": [
+    {
+      "id": "abc123",
+      "name": "gstack",
+      "branch": "garrytan/chrome-extension-ctrl",
+      "directory": "/Users/garry/gstack",
+      "pid": 12345,
+      "active": true
+    }
+  ]
+}
+```
+
+The Chrome extension auto-selects a workspace by matching the browse server's git repo
+(from `/health` response) to a workspace's directory or name.
+
+## Security
+
+- **Localhost-only.** Same trust model as Claude Code's own debug output.
+- **No auth required.** If Conductor wants auth, include a Bearer token in the
+  workspace listing that the extension passes on SSE requests.
+- **Content truncation** is a privacy feature — long code outputs, file contents, and
+  sensitive tool results never leave Conductor's full UI.
+
+## What gstack builds (extension side)
+
+Already scaffolded in the Side Panel "Session" tab (currently shows placeholder).
+
+When Conductor's API is available:
+1. Side Panel discovers Conductor via port probe or manual entry
+2. Fetches `/api/workspaces`, matches to browse server's repo
+3. Opens `EventSource` to `/workspace/{id}/session/stream`
+4. Renders: assistant messages, tool names + icons, turn boundaries, cost
+5. Falls back gracefully: "Connect Conductor for full session view"
+
+Estimated effort: ~200 LOC in `sidepanel.js`.
+
+## What Conductor builds (server side)
+
+1. SSE endpoint that re-emits Claude Code's stream-json per workspace
+2. `/api/workspaces` discovery endpoint with active workspace list
+3. Content truncation (500 char cap on tool inputs/outputs)
+
+Estimated effort: ~100-200 LOC if Conductor already captures the Claude Code stream
+internally (which it does for its own UI rendering).
+
+## Design decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Transport | SSE (not WebSocket) | Unidirectional, auto-reconnect, simpler |
+| Format | Claude's stream-json | Conductor already parses this; no new schema |
+| Discovery | HTTP endpoint (not file) | Chrome extensions can't read filesystem |
+| Auth | None (localhost) | Same as browse server, CDP port, Claude Code |
+| Truncation | 500 chars | Side Panel is ~300px wide; long content useless |