clawdbot 2026.1.4-1

package/docs/nodes.md

@@ -0,0 +1,157 @@
+---
+summary: "Nodes: pairing, capabilities, permissions, and CLI helpers for canvas/camera/screen/system"
+read_when:
+  - Pairing iOS/Android nodes to a gateway
+  - Using node canvas/camera for agent context
+  - Adding new node commands or CLI helpers
+---
+
+# Nodes
+
+A **node** is a companion device (iOS/Android today) that connects to the Gateway over the **Bridge** and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`.
+
+macOS can also run in **node mode**: the menubar app connects to the Gateway’s bridge and exposes its local canvas/camera commands as a node (so `clawdbot nodes …` works against this Mac).
+
+## Pairing + status
+
+Pairing is gateway-owned and approval-based. See `docs/gateway/pairing.md` for the full flow.
+
+Quick CLI:
+
+```bash
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+clawdbot nodes reject <requestId>
+clawdbot nodes status
+clawdbot nodes describe --node <idOrNameOrIp>
+clawdbot nodes rename --node <idOrNameOrIp> --name "Kitchen iPad"
+```
+
+Notes:
+- `nodes rename` stores a display name override in the gateway pairing store.
+
+## Invoking commands
+
+Low-level (raw RPC):
+
+```bash
+clawdbot nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'
+```
+
+Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows.
+
+## Screenshots (canvas snapshots)
+
+If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format, base64 }`.
+
+CLI helper (writes to a temp file and prints `MEDIA:<path>`):
+
+```bash
+clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format png
+clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
+```
+
+Simple shortcut (auto-picks a single connected node if possible):
+
+```bash
+clawdbot canvas snapshot --format png
+clawdbot canvas snapshot --format jpg --max-width 1200 --quality 0.9
+```
+
+## Photos + videos (node camera)
+
+Photos (`jpg`):
+
+```bash
+clawdbot nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
+clawdbot nodes camera snap --node <idOrNameOrIp> --facing front
+```
+
+Video clips (`mp4`):
+
+```bash
+clawdbot nodes camera clip --node <idOrNameOrIp> --duration 10s
+clawdbot nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio
+```
+
+Notes:
+- The node must be **foregrounded** for `canvas.*` and `camera.*` (background calls return `NODE_BACKGROUND_UNAVAILABLE`).
+- Clip duration is clamped (currently `<= 60s`) to avoid oversized base64 payloads.
+- Android will prompt for `CAMERA`/`RECORD_AUDIO` permissions when possible; denied permissions fail with `*_PERMISSION_REQUIRED`.
+
+## Screen recordings (nodes)
+
+Nodes expose `screen.record` (mp4). Example:
+
+```bash
+clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
+clawdbot nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio
+```
+
+Notes:
+- `screen.record` requires the node app to be foregrounded.
+- Android will show the system screen-capture prompt before recording.
+- Screen recordings are clamped to `<= 60s`.
+- `--no-audio` disables microphone capture (supported on iOS/Android; macOS uses system capture audio).
+
+## Location (nodes)
+
+Nodes expose `location.get` when Location is enabled in settings.
+
+CLI helper:
+
+```bash
+clawdbot nodes location get --node <idOrNameOrIp>
+clawdbot nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000
+```
+
+Notes:
+- Location is **off by default**.
+- “Always” requires system permission; background fetch is best-effort.
+- The response includes lat/lon, accuracy (meters), and timestamp.
+
+## SMS (Android nodes)
+
+Android nodes can expose `sms.send` when the user grants **SMS** permission and the device supports telephony.
+
+Low-level invoke:
+
+```bash
+clawdbot nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from Clawdbot"}'
+```
+
+Notes:
+- The permission prompt must be accepted on the Android device before the capability is advertised.
+- Wi-Fi-only devices without telephony will not advertise `sms.send`.
+
+## System commands (mac node)
+
+The macOS node exposes `system.run` and `system.notify`.
+
+Examples:
+
+```bash
+clawdbot nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
+clawdbot nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
+```
+
+Notes:
+- `system.run` returns stdout/stderr/exit code in the payload.
+- `system.notify` respects notification permission state on the macOS app.
+
+## Permissions map
+
+Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by permission name (e.g. `screenRecording`, `accessibility`) with boolean values (`true` = granted).
+
+## Mac node mode
+
+- The macOS menubar app connects to the Gateway bridge as a node (so `clawdbot nodes …` works against this Mac).
+- In remote mode, the app opens an SSH tunnel for the bridge port and connects to `localhost`.
+
+## Where to look in code
+
+- CLI wiring: `src/cli/nodes-cli.ts`
+- Canvas snapshot decoding/temp paths: `src/cli/nodes-canvas.ts`
+- Duration parsing for CLI: `src/cli/parse-duration.ts`
+- iOS node commands: `apps/ios/Sources/Model/NodeAppModel.swift`
+- Android node commands: `apps/android/app/src/main/java/com/clawdbot/android/node/*`

package/docs/onboarding-config-protocol.md

@@ -0,0 +1,29 @@
+# Onboarding + Config Protocol
+
+Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI.
+
+## Components
+- Wizard engine: `src/wizard` (session + prompts + onboarding state).
+- CLI: `src/commands/onboard-*.ts` uses the wizard with the CLI prompter.
+- Gateway RPC: wizard + config schema endpoints serve UI clients.
+- macOS: SwiftUI onboarding uses the wizard step model.
+- Web UI: config form renders from JSON Schema + hints.
+
+## Gateway RPC
+- `wizard.start` params: `{ mode?: "local"|"remote", workspace?: string }`
+- `wizard.next` params: `{ sessionId, answer?: { stepId, value? } }`
+- `wizard.cancel` params: `{ sessionId }`
+- `wizard.status` params: `{ sessionId }`
+- `config.schema` params: `{}`
+
+Responses (shape)
+- Wizard: `{ sessionId, done, step?, status?, error? }`
+- Config schema: `{ schema, uiHints, version, generatedAt }`
+
+## UI Hints
+- `uiHints` keyed by path; optional metadata (label/help/group/order/advanced/sensitive/placeholder).
+- Sensitive fields render as password inputs; no redaction layer.
+- Unsupported schema nodes fall back to the raw JSON editor.
+
+## Notes
+- This doc is the single place to track protocol refactors for onboarding/config.

package/docs/onboarding.md

@@ -0,0 +1,185 @@
+---
+summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, Anthropic OAuth, workspace bootstrap ritual)"
+read_when:
+  - Designing the macOS onboarding assistant
+  - Implementing Anthropic auth or identity setup
+---
+<!-- {% raw %} -->
+# Onboarding (macOS app)
+
+This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind Claude (Anthropic) auth for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
+
+## Page order (high level)
+
+1) **Local vs Remote**
+2) **(Local only)** Connect Claude (Anthropic OAuth) — optional, but recommended
+3) **Connect Gmail (optional)** — run `clawdbot hooks gmail setup` to configure Pub/Sub hooks
+4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
+
+## 1) Local vs Remote
+
+First question: where does the **Gateway** run?
+
+- **Local (this Mac):** onboarding can run the Anthropic OAuth flow and write the Clawdbot token store locally.
+- **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
+
+Gateway auth tip:
+- If you only use Clawdbot on this Mac (loopback gateway), keep auth **Off**.
+- Use **Token** for multi-machine access or non-loopback binds.
+
+Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user).
+
+## 2) Local-only: Connect Claude (Anthropic OAuth)
+
+This is the “bind Clawdbot to Anthropic” step. It is explicitly the **Anthropic (Claude Pro/Max) OAuth flow**, not a generic “login”.
+
+### Recommended: OAuth
+
+The macOS app should:
+- Start the Anthropic OAuth (PKCE) flow in the user’s browser.
+- Ask the user to paste the `code#state` value.
+- Exchange it for tokens and write credentials to:
+  - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
+
+Why this location matters: it’s the Clawdbot-owned OAuth store.
+On first run, Clawdbot can import existing OAuth tokens from legacy p/Claude locations if present.
+
+### Alternative: API key (instructions only)
+
+Offer an “API key” option, but for now it is **instructions only**:
+- Get an Anthropic API key.
+- Provide it to Clawdbot via your preferred mechanism (env/config).
+
+Note: environment variables are often confusing when the Gateway is launched by a GUI app (launchd environment != your shell).
+
+### Model safety rule
+
+Clawdbot should **always pass** `--model` when invoking the embedded agent (don’t rely on defaults).
+
+Example (CLI):
+
+```bash
+clawdbot agent --mode rpc --model anthropic/claude-opus-4-5 "<message>"
+```
+
+If the user skips auth, onboarding should be clear: the agent likely won’t respond until auth is configured.
+
+## 4) Onboarding chat (dedicated session)
+
+The onboarding flow now embeds the SwiftUI chat view directly. It uses a **special session key**
+(`onboarding`) so the “newborn agent” ritual stays separate from the main chat.
+
+This onboarding chat is where the agent:
+- does the BOOTSTRAP.md identity ritual (one question at a time)
+- visits **soul.md** with the user and writes `SOUL.md` (values, tone, boundaries)
+- asks how the user wants to talk (web-only / WhatsApp / Telegram)
+- guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
+
+If the workspace bootstrap is already complete (BOOTSTRAP.md removed), the onboarding chat step is skipped.
+
+## 2.5) Optional: Connect Gmail
+
+The macOS onboarding includes an optional Gmail step. It runs:
+
+```bash
+clawdbot hooks gmail setup --account you@gmail.com
+```
+
+This writes the full `hooks.gmail` config, installs `gcloud` / `gog` / `tailscale`
+via Homebrew if needed, and configures the Pub/Sub push endpoint. After setup,
+restart the gateway so the internal Gmail watcher starts.
+
+Once setup is complete, the user can switch to the normal chat (`main`) via the menu bar panel.
+
+## 5) Agent bootstrap ritual (outside onboarding)
+
+We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
+
+- Workspace is created implicitly (default `~/.clawdbot/workspace`) when local is selected,
+  but only if the folder is empty or already contains `AGENTS.md`.
+- Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
+- `BOOTSTRAP.md` tells the agent to keep it conversational:
+  - open with a cute hello
+  - ask **one question at a time** (no multi-question bombardment)
+  - offer a small set of suggestions where helpful (name, creature, emoji)
+  - wait for the user’s reply before asking the next question
+- The agent writes results to:
+  - `IDENTITY.md` (agent name, vibe/creature, emoji)
+  - `USER.md` (who the user is + how they want to be addressed)
+  - `SOUL.md` (identity, tone, boundaries — crafted from the soul.md prompt)
+  - `~/.clawdbot/clawdbot.json` (structured identity defaults)
+- After the ritual, the agent **deletes `BOOTSTRAP.md`** so it only runs once.
+
+Identity data still feeds the same defaults as before:
+
+- outbound prefix emoji (`messages.responsePrefix`)
+- group mention patterns / wake words
+- default session intro (“You are Samantha…”)
+- macOS UI labels
+
+## 6) Workspace notes (no explicit onboarding step)
+
+The workspace is created automatically as part of agent bootstrap (no dedicated onboarding screen).
+
+Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
+
+```bash
+cd ~/.clawdbot/workspace
+git init
+git add AGENTS.md
+git commit -m "Add agent workspace"
+```
+
+Daily memory lives under `memory/` in the workspace:
+- one file per day: `memory/YYYY-MM-DD.md`
+- read today + yesterday on session start
+- keep it short (durable facts, preferences, decisions; avoid secrets)
+
+## Remote mode note (why OAuth is hidden)
+
+If the Gateway runs on another machine, the Anthropic OAuth credentials must be created/stored on that host (where the agent runtime runs).
+
+For now, remote onboarding should:
+- explain why OAuth isn't shown
+- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the workspace location on the gateway host
+- mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
+
+### Manual credential setup
+
+On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format:
+
+```json
+{
+  "anthropic": {
+    "access": "sk-ant-oat01-...",
+    "refresh": "sk-ant-ort01-...",
+    "expires": 1767304352803
+  }
+}
+```
+
+Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
+
+**Note:** Clawdbot can auto-import from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
+
+### Using Claude Code credentials
+
+If Claude Code is installed on the gateway host, convert its credentials:
+
+```bash
+cat ~/.claude/.credentials.json | jq '{
+  anthropic: {
+    access: .claudeAiOauth.accessToken,
+    refresh: .claudeAiOauth.refreshToken,
+    expires: .claudeAiOauth.expiresAt
+  }
+}' > ~/.clawdbot/credentials/oauth.json
+chmod 600 ~/.clawdbot/credentials/oauth.json
+```
+
+| Claude Code field | Clawdbot field |
+|-------------------|---------------|
+| `accessToken` | `access` |
+| `refreshToken` | `refresh` |
+| `expiresAt` | `expires` |
+<!-- {% endraw %} -->

package/docs/presence.md

@@ -0,0 +1,133 @@
+---
+summary: "How Clawdbot presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+---
+# Presence
+
+Clawdbot “presence” is a lightweight, best-effort view of:
+- The **Gateway** itself (one per host), and
+- The **clients connected to the Gateway** (mac app, WebChat, CLI, etc.).
+
+Presence is used primarily to render the mac app’s **Instances** tab and to provide quick operator visibility.
+
+## The data model
+
+Presence entries are structured objects with (some) fields:
+- `instanceId` (optional but strongly recommended): stable client identity used for dedupe
+- `host`: a human-readable name (often the machine name)
+- `ip`: best-effort IP address (may be missing or stale)
+- `version`: client version string
+- `deviceFamily` (optional): hardware family like `iPad`, `iPhone`, `Mac`
+- `modelIdentifier` (optional): hardware model identifier like `iPad16,6` or `Mac16,6`
+- `mode`: e.g. `gateway`, `app`, `webchat`, `cli`
+- `lastInputSeconds` (optional): “seconds since last user input” for that client machine
+- `reason`: a short marker like `self`, `connect`, `node-connected`, `node-disconnected`, `periodic`, `instances-refresh`
+- `text`: legacy/debug summary string (kept for backwards compatibility and UI display)
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and then **merged**.
+
+### 1) Gateway self entry
+
+The Gateway seeds a “self” entry at startup so UIs always show at least the current gateway host.
+
+Implementation: `src/infra/system-presence.ts` (`initSelfPresence()`).
+
+### 2) WebSocket connect (connection-derived presence)
+
+Every WS client must begin with a `connect` request. On successful handshake, the Gateway upserts a presence entry for that connection.
+
+This is meant to answer: “Which clients are currently connected?”
+
+Implementation: `src/gateway/server.ts` (connect handling uses `connect.params.client.instanceId` when provided; otherwise falls back to `connId`).
+
+#### Why one-off CLI commands do not show up
+
+The CLI connects to the Gateway to execute one-off commands (health/status/send/agent/etc.). These are not “nodes” and would spam the Instances list, so the Gateway does not create presence entries for clients with `client.mode === "cli"`.
+
+### 3) `system-event` beacons (client-reported presence)
+
+Clients can publish richer periodic beacons via the `system-event` method. The mac app uses this to report:
+- a human-friendly host name
+- its best-known IP address
+- `lastInputSeconds`
+
+Implementation:
+- Gateway: `src/gateway/server.ts` handles method `system-event` by calling `updateSystemPresence(...)`.
+- mac app beaconing: `apps/macos/Sources/Clawdbot/PresenceReporter.swift`.
+
+### 4) Node bridge beacons (gateway-owned presence)
+
+When a node bridge connection authenticates, the Gateway emits a presence entry
+for that node and starts periodic refresh beacons so it does not expire.
+
+- Connect/disconnect markers: `node-connected`, `node-disconnected`
+- Periodic heartbeat: every 3 minutes (`reason: periodic`)
+
+Implementation: `src/gateway/server.ts` (node bridge handlers + timer beacons).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+All producers write into a single in-memory presence map.
+
+Key points:
+- Entries are **keyed** by a “presence key”. If two producers use the same key, they update the same entry.
+- The best key is a stable, opaque `instanceId` that does not change across restarts.
+- Keys are treated case-insensitively.
+
+Implementation: `src/infra/system-presence.ts` (`normalizePresenceKey()`).
+
+### mac app identity (stable UUID)
+
+The mac app uses a persisted UUID as `instanceId` so:
+- restarts/reconnects do not create duplicates
+- renaming the Mac does not create a new “instance”
+- debug/release builds can share the same identity
+
+Implementation: `apps/macos/Sources/Clawdbot/InstanceIdentity.swift`.
+
+`displayName` (machine name) is used for UI, while `instanceId` is used for dedupe.
+
+## TTL and bounded size (why stale rows disappear)
+
+Presence entries are not permanent:
+- TTL: entries older than 5 minutes are pruned
+- Max: map is capped at 200 entries (LRU by `ts`)
+
+Implementation: `src/infra/system-presence.ts` (`TTL_MS`, `MAX_ENTRIES`, pruning in `listSystemPresence()`).
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may see the remote address as loopback (`127.0.0.1`).
+
+To avoid degrading an otherwise-correct client beacon IP, the Gateway avoids writing loopback remote addresses into presence entries.
+
+Implementation: `src/gateway/server.ts` (`isLoopbackAddress()`).
+
+## Consumers (who reads presence)
+
+### macOS Instances tab
+
+The mac app’s Instances tab renders the result of `system-presence`.
+
+Implementation:
+- View: `apps/macos/Sources/Clawdbot/InstancesSettings.swift`
+- Store: `apps/macos/Sources/Clawdbot/InstancesStore.swift`
+
+The Instances rows show a small presence indicator (Active/Idle/Stale) based on
+the last beacon age. The label is derived from the entry timestamp (`ts`).
+
+The store refreshes periodically and also applies `presence` WS events.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the gateway.
+- If you see duplicates:
+  - confirm clients send a stable `instanceId` in the handshake (`connect.params.client.instanceId`)
+  - confirm beaconing uses the same `instanceId`
+  - check whether the connection-derived entry is missing `instanceId` (then it will be keyed by `connId` and duplicates are expected on reconnect)

package/docs/queue.md

@@ -0,0 +1,78 @@
+---
+summary: "Command queue design that serializes auto-reply command execution"
+read_when:
+  - Changing auto-reply execution or concurrency
+---
+# Command Queue (2026-01-03)
+
+We now serialize command-based auto-replies (WhatsApp Web listener) through a tiny in-process queue to prevent multiple commands from running at once, while allowing safe parallelism across sessions.
+
+## Why
+- Some auto-reply commands are expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
+- Serializing avoids competing for terminal/stdin, keeps logs readable, and reduces the chance of rate limits from upstream tools.
+
+## How it works
+- `src/process/command-queue.ts` holds a lane-aware FIFO queue and drains each lane synchronously.
+- `runEmbeddedPiAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
+- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agent.maxConcurrent`.
+- When verbose logging is enabled, queued commands emit a short notice if they waited more than ~2s before starting.
+- Typing indicators (`onReplyStart`) still fire immediately on enqueue so user experience is unchanged while we wait our turn.
+
+## Queue modes (per surface)
+Inbound messages can steer the current run, wait for a followup turn, or do both:
+- `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
+- `followup`: enqueue for the next agent turn after the current run ends.
+- `collect`: coalesce all queued messages into a **single** followup turn (default).
+- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the message for a followup turn.
+- `interrupt` (legacy): abort the active run for that session, then run the newest message.
+- `queue` (legacy alias): same as `steer`.
+
+Steer-backlog means you can get a followup response after the steered run, so
+streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
+one response per inbound message.
+Inline fix: `/queue collect` (per-session) or set `routing.queue.bySurface.discord: "collect"`.
+
+Defaults (when unset in config):
+- All surfaces → `collect`
+
+Configure globally or per surface via `routing.queue`:
+
+```json5
+{
+  routing: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      bySurface: { discord: "collect" }
+    }
+  }
+}
+```
+
+## Queue options
+Options apply to `followup`, `collect`, and `steer-backlog` (and to `steer` when it falls back to followup):
+- `debounceMs`: wait for quiet before starting a followup turn (prevents “continue, continue”).
+- `cap`: max queued messages per session.
+- `drop`: overflow policy (`old`, `new`, `summarize`).
+
+Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt.
+Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
+
+## Per-session overrides
+- `/queue <mode>` as a standalone command stores the mode for the current session.
+- `/queue <mode>` embedded in a message applies **once** (no persistence).
+- Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` or `/queue reset` clears the session override.
+
+## Scope and guarantees
+- Applies only to config-driven command replies; plain text replies are unaffected.
+- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agent.maxConcurrent` to allow multiple sessions in parallel.
+- Additional lanes may exist (e.g. `cron`) so background jobs can run in parallel without blocking inbound replies.
+- Per-session lanes guarantee that only one agent run touches a given session at a time.
+- No external dependencies or background worker threads; pure TypeScript + promises.
+
+## Troubleshooting
+- If commands seem stuck, enable verbose logs and look for “queued for …ms” lines to confirm the queue is draining.
+- `enqueueCommand` exposes a lightweight `getQueueSize()` helper if you need to surface queue depth in future diagnostics.

package/docs/refactor/browser-control-simplification.md

@@ -0,0 +1,58 @@
+---
+summary: "Refactor: simplify browser control API + implementation"
+read_when:
+  - Refactoring browser control routes, client, or CLI
+  - Auditing agent-facing browser tool surface
+date: 2025-12-20
+---
+
+# Refactor: Browser control simplification
+
+Goal: make the browser-control surface **small, stable, and agent-oriented**, and remove “implementation-shaped” APIs (Playwright/CDP specifics, one-off endpoints, and debugging helpers).
+
+## Why
+
+- The previous API accreted many narrow endpoints (`/click`, `/type`, `/press`, …) plus debug utilities.
+- Some actions are inherently racy when modeled as “do X *when* the event is already visible” (file chooser, dialogs).
+- We want a single, coherent contract that keeps “how it’s implemented” private.
+
+## Target contract (vNext)
+
+**Basics**
+- `GET /` status
+- `POST /start`, `POST /stop`
+- `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
+
+**Agent actions**
+- `POST /navigate` `{ url, targetId? }`
+- `POST /act` `{ kind, targetId?, ... }` where `kind` is one of:
+  - `click`, `type`, `press`, `hover`, `drag`, `select`, `fill`, `wait`, `resize`, `close`, `evaluate`
+- `POST /screenshot` `{ targetId?, fullPage?, ref?, element?, type? }`
+- `GET /snapshot` `?format=ai|aria&targetId?&limit?`
+- `GET /console` `?level?&targetId?`
+- `POST /pdf` `{ targetId? }`
+
+**Hooks (pre-setup / arming)**
+- `POST /hooks/file-chooser` `{ targetId?, paths, timeoutMs? }`
+- `POST /hooks/dialog` `{ targetId?, accept, promptText?, timeoutMs? }`
+
+Semantics:
+- Hook endpoints **arm** the next matching event within `timeoutMs` (default 2 minutes, clamped to max 2 minutes).
+- Last arm wins per page (new arm replaces previous).
+
+## Work checklist
+
+- [x] Replace action endpoints with `POST /act`
+- [x] Remove legacy endpoints (`/click`, `/type`, `/wait`, …) and any CLI wrappers that no longer make sense
+- [x] Remove `/back` and any history-specific routes
+- [x] Convert `upload` + `dialog` to hook/arming endpoints
+- [x] Unify screenshots behind `POST /screenshot` (no GET variant)
+- [x] Trim inspect/debug endpoints (`/query`, `/dom`) unless explicitly needed
+- [x] Update docs/browser.md to describe contract without implementation details
+- [x] Update tests (server + client) to cover vNext contract
+
+## Notes / decisions
+
+- Keep Playwright as an internal implementation detail for now.
+- Prefer ref-based interactions (`aria-ref`) over coordinate-based ones.
+- Keep the code split “routes vs. engine” small and obvious; avoid scattering logic across too many files.