feat(agent): add multi-provider runtime (codex + claude)

.gitignore

@@ -7,4 +7,6 @@ node_modules/
 .npm
 pnpm-debug.log*
 .worktrees/
-docs/plans/*
+docs/plans/*
+.superset
+AGENTS.local.md

AGENTS.md

@@ -1,13 +1,8 @@
 # BrowserForce — Agent Guidelines
 
-## Playwriter Reference
+## Local Private Overrides
 
-**Before writing any new code, always check how [playwriter](../playwriter) solves the same problem.** Playwriter is the reference implementation for a browser extension + CDP relay + MCP server stack. It lives at `~/Documents/projects/playwriter`.
-
-Rules:
-- **Don't reinvent what playwriter already solved.** Read the relevant playwriter source file first.
-- **Only add code for new requirements or problems playwriter hasn't already solved.**
-- Reference files: `playwriter/src/cdp-relay.ts`, `playwriter/src/executor.ts`, `playwriter/src/mcp.ts`, `playwriter/src/relay-client.ts`
+@AGENTS.local.md
 
 ## Project Overview
 
@@ -157,6 +152,38 @@ When a user clicks "Cancel" on Chrome's automation infobar, Chrome detaches the
 
 `RelayServer.start()` accepts `{ writeCdpUrl: false }` to prevent test instances from clobbering `~/.browserforce/cdp-url`. **All test `relay.start()` calls must pass `{ writeCdpUrl: false }`** or the production cdp-url file gets overwritten with random test ports.
 
+### Client Arbitration: BF_CLIENT_MODE
+
+`BF_CLIENT_MODE` controls agent-side CDP arbitration:
+- `multi-client` (default): allows concurrent `/cdp` clients.
+- `single-active`: opt-in mode that allows only one active `/cdp` client connection at a time.
+
+In `single-active`, contention returns HTTP `409 Conflict` for additional `/cdp` connects while the slot is busy. Slot state is exposed at `GET /client-slot` (`mode`, `busy`, `activeClientId`, `connectedAt`).
+
+### MCP Standby Polling
+
+MCP handles `409`/busy connect errors by entering standby and polling `GET /client-slot` with short jittered intervals (~200-400ms), then reconnecting when `busy: false` (up to a 30s connect timeout).
+
+### BrowserForce Agent Session Identity (No Fixed ID)
+
+For side-panel chat UX, **never hardcode or assume a fixed `sessionId`**.
+
+- Sessions are user-selectable conversation threads (ChatGPT/Atlas style).
+- The UI must list prior sessions and let the user resume any session.
+- New chats must create a new generated session ID (UUID/ULID), then persist metadata + transcript.
+- Streaming channels (`/events`) must be scoped by explicit selected `sessionId`.
+- Do not infer continuity from "current Codex turn/session" alone; BrowserForce Agent keeps its own session store.
+
+### Codex Provider Session Continuity + Usage Telemetry
+
+For side-panel chat continuity, BrowserForce session metadata stores Codex provider state:
+
+- Persist Codex thread identity at `providerState.codex.sessionId`.
+- On each new run, pass that mapping as `resumeSessionId` so runner can invoke `codex exec resume <id> --json`.
+- Persist latest context/token telemetry at `providerState.codex.latestUsage`.
+- Emit and consume `run.usage` and `run.provider_session` events.
+- Side-panel hydrates usage from `GET /v1/sessions/:sessionId` and shows `Context: unavailable` when telemetry is missing.
+
 ## Security Rules
 
 - Relay binds to `127.0.0.1` ONLY. Never `0.0.0.0`.
@@ -165,6 +192,12 @@ When a user clicks "Cancel" on Chrome's automation infobar, Chrome detaches the
 - Token file permissions: `0o600` (owner read/write only).
 - Single extension slot. Second extension connection gets HTTP 409.
 
+## Operational Non-Goals
+
+- No new dependencies for client arbitration or standby behavior.
+- No per-tab ownership model; arbitration is one relay-level client slot.
+- No extension protocol changes for this feature area.
+
 ## Development Workflow
 
 ### Commands
@@ -229,3 +262,5 @@ Run with: `node --test relay/test/relay-server.test.js` and `node --test mcp/tes
 5. **Relay port collision**: Default port 19222. If tests fail with EADDRINUSE, kill stale processes: `lsof -ti:19222 | xargs kill -9`.
 
 6. **Test writeCdpUrl**: Never call `relay.start()` in tests without `{ writeCdpUrl: false }` — it overwrites the production cdp-url file.
+
+7. **No fixed chat session IDs**: BrowserForce Agent chat must always use explicit user-selected/generated session IDs and persisted session history. Never bind side-panel chat to a single hardcoded ID.