gstack/docs/designs/SIDEBAR_MESSAGE_FLOW.md

Sidebar Flow

How the GStack Browser sidebar actually works. Read this before touching sidepanel.js, background.js, content.js, terminal-agent.ts, or sidebar-related server endpoints.

The sidebar has one primary surface — the Terminal pane, an interactive claude PTY. Activity / Refs / Inspector survive as debug overlays behind the debug toggle in the footer. The chat queue path (one-shot claude -p, sidebar-agent.ts) was ripped once the PTY proved out — the Terminal pane is strictly more capable.

Components

┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│  sidepanel.js + │────▶│  server.ts   │────▶│terminal-agent.ts │
│  -terminal.js   │     │  (compiled)  │     │  (non-compiled)  │
│  (xterm.js)     │     │              │     │  PTY listener    │
└─────────────────┘     └──────────────┘     └──────────────────┘
        ▲                       │                      │
        │  ws://127.0.0.1:<termPort>/ws (Sec-WebSocket-Protocol auth)
        └───────────────────────┼──────────────────────▶│ Bun.spawn(claude)
                                │                      │  terminal: {data}
                                │                      ▼
                                │              ┌──────────────────┐
                                │              │  claude PTY      │
                                │              └──────────────────┘
            POST /pty-session   │
            (Bearer AUTH_TOKEN) │
                                ▼
                       ┌──────────────────┐
                       │ pty-session-     │
                       │ cookie.ts        │
                       │ (in-memory token │
                       │  registry)       │
                       └──────────────────┘
                                │
                                │ POST /internal/grant (loopback)
                                ▼
                       ┌──────────────────┐
                       │  validTokens Set │
                       │  in agent memory │
                       └──────────────────┘

The compiled browse server can't posix_spawn external executables — terminal-agent.ts runs as a separate non-compiled bun run process and owns the claude subprocess.

Startup + first-keystroke timeline

T+0ms     CLI runs `$B connect`
            ├── Server starts (compiled)
            └── Spawns terminal-agent.ts via `bun run`

T+500ms   terminal-agent.ts boots
            ├── Bun.serve on 127.0.0.1:0 (random port)
            ├── Writes <stateDir>/terminal-port (server reads it for /health)
            ├── Writes <stateDir>/terminal-internal-token (loopback handshake)
            └── Probes claude → writes claude-available.json

T+1-3s    Extension loads, sidebar opens
            ├── sidepanel-terminal.js: setState(IDLE), shows "Starting Claude Code..."
            └── tryAutoConnect() polls until window.gstackServerPort + token are set

T+ready   tryAutoConnect calls connect()
            ├── POST /pty-session (Authorization: Bearer AUTH_TOKEN)
            │   └── server mints session token, posts /internal/grant to agent
            │   └── responds with {terminalPort, ptySessionToken}
            ├── GET /claude-available (preflight)
            ├── new WebSocket(`ws://127.0.0.1:<terminalPort>/ws`,
            │                 [`gstack-pty.<token>`])
            │   └── Browser sends Sec-WebSocket-Protocol + Origin
            │   └── Agent validates Origin AND token BEFORE upgrading
            │   └── Agent echoes the protocol back (REQUIRED — browser
            │       closes the connection without it)
            ├── On open: send {type:"resize"} then a single \n byte
            └── Agent message handler sees the byte → spawnClaude()

Auth: WebSocket can't send Authorization headers

Browser WebSocket clients can't set Authorization. They CAN set Sec-WebSocket-Protocol via the second arg of new WebSocket(url, protocols). We exploit that:

1. POST /pty-session (auth: Bearer AUTH_TOKEN) → server mints a short-lived session token, pushes it to the agent over loopback, returns it in the JSON body.
2. Extension calls new WebSocket(url, ['gstack-pty.<token>']).
3. Agent reads Sec-WebSocket-Protocol, strips gstack-pty., validates against validTokens, echoes the protocol back. Echo is mandatory — without it Chromium closes the connection on receipt of the upgrade response.

A Set-Cookie: gstack_pty=... header is also returned for non-browser callers (curl, integration tests). The cookie path was the original v1 design but SameSite=Strict cookies don't survive the cross-port jump from server.ts:34567 → agent: from a chrome-extension origin. The protocol-token path is what the browser actually uses.

Dual-token model

Token	Lives in	Used for	Lifetime
AUTH_TOKEN	<stateDir>/browse.json; in-memory in server.ts	/pty-session POST (mint cookie + token)	server lifetime
gstack-pty.<...> (Sec-WebSocket-Protocol)	Browser memory only; agent validTokens Set	/ws upgrade auth	30 min, auto-revoked on WS close
INTERNAL_TOKEN	<stateDir>/terminal-internal-token; in agent memory	server → agent loopback /internal/grant	agent lifetime

AUTH_TOKEN is never valid for /ws directly. The session token is never valid for /pty-session or /command. Strict separation prevents an SSE or page-content token leak from escalating into shell access.

Threat model

The Terminal pane bypasses the prompt-injection security stack on purpose — the user is typing directly to claude, there's no untrusted page content in the loop. Trust source is the keyboard, same as any local terminal.

That trust assumption is load-bearing on three transport guarantees:

1. Local-only listener. terminal-agent.ts binds 127.0.0.1 only. The dual-listener tunnel surface (server.ts TUNNEL_PATHS) does not include /pty-session or /terminal/*, so the tunnel returns 404 by default-deny.
2. Origin gate. /ws upgrades require Origin: chrome-extension://<id>. A localhost web page can't mount a cross-site WebSocket hijack against the shell because its Origin is a regular http(s)://....
3. Session token auth. Minted only by an authenticated /pty-session POST, scoped to one WS, auto-revoked on close.

Drop any one of those three and the whole tab becomes unsafe.

Lifecycle

• Eager auto-connect. Sidebar opens → tryAutoConnect polls for the bootstrap globals and connects as soon as they're set. No keypress required.
• One PTY per WS. Closing the WebSocket SIGINTs claude, then SIGKILLs after 3s. The session token is revoked so a stolen token can't be replayed.
• No auto-reconnect on close. The user sees "Session ended, click to start a new session." Auto-reconnect would burn a fresh claude session on every reload. v1.1 may add session resumption keyed on tab/session id (see TODOS).
• Manual restart anytime. A ↻ Restart button lives in the always- visible terminal toolbar — works mid-session, not just from the ENDED state.

Quick-action toolbar

Three browser-action buttons live next to the Restart button at the top of the Terminal pane:

Button	Behavior
🧹 Cleanup	window.gstackInjectToTerminal(prompt) — pipes a "remove ads/banners" instruction into the live PTY. claude in the terminal sees it and acts.
📸 Screenshot	POST /command screenshot — direct browse-server call, no PTY involvement.
🍪 Cookies	Navigates to the /cookie-picker page.

The Inspector's "Send to Code" button uses the same gstackInjectToTerminal path to forward CSS inspector data into claude.

Debug surfaces (Activity / Refs / Inspector)

Behind the debug toggle in the footer. SSE-driven, independent of the Terminal pane:

• Activity — streams every browse command via /activity/stream SSE.
• Refs — REST: GET /refs — current page's @ref element labels.
• Inspector — CDP-based element picker; SSE on /inspector/events.

When the debug strip closes, the Terminal pane re-becomes visible. xterm.js doesn't auto-redraw when its container flips from display:none to display:flex, so sidepanel-terminal.js runs a MutationObserver on #tab-terminal's class attribute and forces a fit + refresh when .active returns.

Files

Component	File	Runs in
Sidebar UI shell	extension/sidepanel.html + sidepanel.js + sidepanel.css	Chrome side panel
Terminal UI	extension/sidepanel-terminal.js + extension/lib/xterm.js	Chrome side panel
Service worker	extension/background.js	Chrome background
Content script	extension/content.js	Page context
HTTP server	browse/src/server.ts	Bun (compiled binary)
PTY agent	browse/src/terminal-agent.ts	Bun (non-compiled)
PTY token store	browse/src/pty-session-cookie.ts	Bun (compiled, in server.ts)
CLI entry	browse/src/cli.ts	Bun (compiled binary)
State file	<stateDir>/browse.json	Filesystem
Terminal port	<stateDir>/terminal-port	Filesystem
Internal token	<stateDir>/terminal-internal-token	Filesystem
Claude probe	<stateDir>/claude-available.json	Filesystem
Active tab	<stateDir>/active-tab.json	Filesystem (claude reads)