clawdbot 2026.1.4-1

package/docs/gateway/pairing.md

@@ -0,0 +1,109 @@
+---
+summary: "Gateway-owned node pairing (Option B) for iOS and other remote nodes"
+read_when:
+  - Implementing node pairing approvals without macOS UI
+  - Adding CLI flows for approving remote nodes
+  - Extending gateway protocol with node management
+---
+# Gateway-owned pairing (Option B)
+
+Goal: The Gateway (`clawd`) is the **source of truth** for which nodes are allowed to join the network.
+
+This enables:
+- Headless approval via terminal/CLI (no Swift UI required).
+- Optional macOS UI approval (Swift app is just a frontend).
+- One consistent membership store for iOS, mac nodes, future hardware nodes.
+
+## Concepts
+- **Pending request**: a node asked to join; requires explicit approve/reject.
+- **Paired node**: node is allowed; gateway returns an auth token for subsequent connects.
+- **Bridge**: direct transport endpoint owned by the gateway. The bridge does not decide membership.
+
+## API surface (gateway protocol)
+These are conceptual method names; wire them into `src/gateway/protocol/schema.ts` and regenerate Swift types.
+
+### Events
+- `node.pair.requested`
+  - Emitted whenever a new pending pairing request is created.
+  - Payload:
+    - `requestId` (string)
+    - `nodeId` (string)
+    - `displayName?` (string)
+    - `platform?` (string)
+    - `version?` (string)
+    - `remoteIp?` (string)
+    - `silent?` (boolean) — hint that the UI may attempt auto-approval
+    - `ts` (ms since epoch)
+- `node.pair.resolved`
+  - Emitted when a pending request is approved/rejected.
+  - Payload:
+    - `requestId` (string)
+    - `nodeId` (string)
+    - `decision` ("approved" | "rejected" | "expired")
+    - `ts` (ms since epoch)
+
+### Methods
+- `node.pair.request`
+  - Creates (or returns) a pending request.
+  - Params: node metadata (same shape as `node.pair.requested` payload, minus `requestId`/`ts`).
+  - Optional `silent` flag hints that the UI can attempt an SSH auto-approve before showing an alert.
+  - Result:
+    - `status` ("pending")
+    - `created` (boolean) — whether this call created the pending request
+    - `request` (pending request object), including `isRepair` when the node was already paired
+  - Security: **never returns an existing token**. If a paired node “lost” its token, it must be approved again (token rotation).
+- `node.pair.list`
+  - Returns:
+    - `pending[]` (pending requests)
+    - `paired[]` (paired node records)
+- `node.pair.approve`
+  - Params: `{ requestId }`
+  - Result: `{ requestId, node: { nodeId, token, ... } }`
+  - Must be idempotent (first decision wins).
+- `node.pair.reject`
+  - Params: `{ requestId }`
+  - Result: `{ requestId, nodeId }`
+- `node.pair.verify`
+  - Params: `{ nodeId, token }`
+  - Result: `{ ok: boolean, node?: { nodeId, ... } }`
+
+## CLI flows
+CLI must be able to fully operate without any GUI:
+- `clawdbot nodes pending`
+- `clawdbot nodes approve <requestId>`
+- `clawdbot nodes reject <requestId>`
+- `clawdbot nodes status` (paired nodes + connection status/capabilities)
+
+Optional interactive helper:
+- `clawdbot nodes watch` (subscribe to `node.pair.requested` and prompt in-place)
+
+Implementation pointers:
+- CLI commands: `src/cli/nodes-cli.ts`
+- Gateway handlers + events: `src/gateway/server.ts`
+- Pairing store: `src/infra/node-pairing.ts` (under `~/.clawdbot/nodes/`)
+- Optional macOS UI prompt (frontend only): `apps/macos/Sources/Clawdbot/NodePairingApprovalPrompter.swift`
+  - Push-first: listens to `node.pair.requested`/`node.pair.resolved`, does a `node.pair.list` on startup/reconnect,
+    and only runs a slow safety poll while a request is pending/visible.
+
+## Storage (private, local)
+Gateway stores the authoritative state under `~/.clawdbot/`:
+- `~/.clawdbot/nodes/paired.json`
+- `~/.clawdbot/nodes/pending.json` (or `~/.clawdbot/nodes/pending/*.json`)
+
+Notes:
+- Tokens are secrets. Treat `paired.json` as sensitive.
+- Pending entries should have a TTL (e.g. 5 minutes) and expire automatically.
+
+## Bridge integration
+Target direction:
+- The gateway runs the bridge listener (LAN/tailnet-facing) and advertises discovery beacons (Bonjour).
+- The bridge is transport only; it forwards/scopes requests and enforces ACLs, but pairing decisions are made by the gateway.
+
+The macOS UI (Swift) can:
+- Subscribe to `node.pair.requested`, show an alert (including `remoteIp`), and call `node.pair.approve` or `node.pair.reject`.
+- Or ignore/dismiss (“Later”) and let CLI handle it.
+- When `silent` is set, it can try a short SSH probe (same user) and auto-approve if reachable; otherwise fall back to the normal alert.
+
+## Implementation note
+If the bridge is only provided by the macOS app, then “no Swift app running” cannot work end-to-end.
+The long-term goal is to move bridge hosting + Bonjour advertising into the Node gateway so headless pairing works by default.

package/docs/gateway-lock.md

@@ -0,0 +1,28 @@
+---
+summary: "Gateway singleton guard using the WebSocket listener bind"
+read_when:
+  - Running or debugging the gateway process
+  - Investigating single-instance enforcement
+---
+# Gateway lock
+
+Last updated: 2025-12-11
+
+## Why
+- Ensure only one gateway instance runs per host.
+- Survive crashes/SIGKILL without leaving stale lock files.
+- Fail fast with a clear error when the control port is already occupied.
+
+## Mechanism
+- The gateway binds the WebSocket listener (default `ws://127.0.0.1:18789`) immediately on startup using an exclusive TCP listener.
+- If the bind fails with `EADDRINUSE`, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
+- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
+
+## Error surface
+- If another process holds the port, startup throws `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
+- Other bind failures surface as `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
+
+## Operational notes
+- If the port is occupied by *another* process, the error is the same; free the port or choose another with `clawdbot gateway --port <port>`.
+- The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.

package/docs/gateway.md

@@ -0,0 +1,174 @@
+---
+summary: "Runbook for the Gateway daemon, lifecycle, and operations"
+read_when:
+  - Running or debugging the gateway process
+---
+# Gateway (daemon) runbook
+
+Last updated: 2025-12-09
+
+## What it is
+- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
+- Replaces the legacy `gateway` command. CLI entry point: `clawdbot gateway`.
+- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
+
+## How to run (local)
+```bash
+pnpm clawdbot gateway --port 18789
+# for full debug/trace logs in stdio:
+pnpm clawdbot gateway --port 18789 --verbose
+# if the port is busy, terminate listeners then start:
+pnpm clawdbot gateway --force
+# dev loop (auto-reload on TS changes):
+pnpm gateway:watch
+```
+- Config hot reload watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`).
+  - Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
+  - Hot reload uses in-process restart via **SIGUSR1** when needed.
+  - Disable with `gateway.reload.mode="off"`.
+- Binds WebSocket control plane to `127.0.0.1:<port>` (default 18789).
+- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
+- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__clawdbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
+- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
+- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
+- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
+- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
+- **SIGUSR1** triggers an in-process restart (no external supervisor required). This is what the `gateway` agent tool uses.
+- Optional shared secret: pass `--token <value>` or set `CLAWDBOT_GATEWAY_TOKEN` to require clients to send `connect.params.auth.token`.
+- Port precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`.
+
+## Remote access
+- Tailscale/VPN preferred; otherwise SSH tunnel:
+  ```bash
+  ssh -N -L 18789:127.0.0.1:18789 user@host
+  ```
+- Clients then connect to `ws://127.0.0.1:18789` through the tunnel.
+- If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel.
+
+## Multiple gateways (same host)
+
+Supported if you isolate state + config and use unique ports.
+
+Checklist per instance:
+- unique `gateway.port`
+- unique `CLAWDBOT_CONFIG_PATH`
+- unique `CLAWDBOT_STATE_DIR`
+- unique `agent.workspace`
+- separate WhatsApp numbers (if using WA)
+
+Example:
+```bash
+CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001
+CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbot gateway --port 19002
+```
+
+## Protocol (operator view)
+- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
+- Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes).
+- After handshake:
+  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
+  - Events: `{type:"event", event, payload, seq?, stateVersion?}`
+- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
+- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
+
+## Methods (initial set)
+- `health` — full health snapshot (same shape as `clawdbot health --json`).
+- `status` — short summary.
+- `system-presence` — current presence list.
+- `system-event` — post a presence/system note (structured).
+- `send` — send a message via the active provider(s).
+- `agent` — run an agent turn (streams events back on same connection).
+- `node.list` — list paired + currently-connected bridge nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`).
+- `node.describe` — describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes).
+- `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
+- `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
+
+See also: `docs/presence.md` for how presence is produced/deduped and why `instanceId` matters.
+
+## Events
+- `agent` — streamed tool/output events from the agent run (seq-tagged).
+- `presence` — presence updates (deltas with stateVersion) pushed to all connected clients.
+- `tick` — periodic keepalive/no-op to confirm liveness.
+- `shutdown` — Gateway is exiting; payload includes `reason` and optional `restartExpectedMs`. Clients should reconnect.
+
+## WebChat integration
+- WebChat is a native SwiftUI UI that talks directly to the Gateway WebSocket for history, sends, abort, and events.
+- Remote use goes through the same SSH/Tailscale tunnel; if a gateway token is configured, the client includes it during `connect`.
+- macOS app connects via a single WS (shared connection); it hydrates presence from the initial snapshot and listens for `presence` events to update the UI.
+
+## Typing and validation
+- Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
+- Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
+- Types live in `src/gateway/protocol/*.ts`; regenerate schemas/models with `pnpm protocol:gen` (writes `dist/protocol.schema.json`) and `pnpm protocol:gen:swift` (writes `apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`).
+
+## Connection snapshot
+- `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
+- `health`/`system-presence` remain available for manual refresh, but are not required at connect time.
+
+## Error codes (res.error shape)
+- Errors use `{ code, message, details?, retryable?, retryAfterMs? }`.
+- Standard codes:
+  - `NOT_LINKED` — WhatsApp not authenticated.
+  - `AGENT_TIMEOUT` — agent did not respond within the configured deadline.
+  - `INVALID_REQUEST` — schema/param validation failed.
+  - `UNAVAILABLE` — Gateway is shutting down or a dependency is unavailable.
+
+## Keepalive behavior
+- `tick` events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs.
+- Send/agent acknowledgements remain separate responses; do not overload ticks for sends.
+
+## Replay / gaps
+- Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap.
+
+## Supervision (macOS example)
+- Use launchd to keep the daemon alive:
+  - Program: path to `clawdbot`
+  - Arguments: `gateway`
+  - KeepAlive: true
+  - StandardOut/Err: file paths or `syslog`
+- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
+
+Bundled mac app:
+- Clawdbot.app can bundle a bun-compiled gateway binary and install a per-user LaunchAgent labeled `com.clawdbot.gateway`.
+
+## Supervision (systemd example)
+```
+[Unit]
+Description=Clawdbot Gateway
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/clawdbot gateway --port 18789
+Restart=on-failure
+RestartSec=5
+User=clawdbot
+Environment=CLAWDBOT_GATEWAY_TOKEN=
+WorkingDirectory=/home/clawdbot
+
+[Install]
+WantedBy=multi-user.target
+```
+Enable with `systemctl enable --now clawdbot-gateway.service`.
+
+## Operational checks
+- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
+- Readiness: call `health` → expect `ok: true` and `web.linked=true`.
+- Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.
+
+## Safety guarantees
+- Only one Gateway per host; all sends/agent calls must go through it.
+- No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
+- Non-connect first frames or malformed JSON are rejected and the socket is closed.
+- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
+
+## CLI helpers
+- `clawdbot gateway health|status` — request health/status over the Gateway WS.
+- `clawdbot gateway send --to <num> --message "hi" [--media-url ...]` — send via Gateway (idempotent).
+- `clawdbot gateway agent --message "hi" [--to ...]` — run an agent turn (waits for final by default).
+- `clawdbot gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
+- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
+
+## Migration guidance
+- Retire uses of `clawdbot gateway` and the legacy TCP control port.
+- Update clients to speak the WS protocol with mandatory connect and structured presence.

package/docs/gmail-pubsub.md

@@ -0,0 +1,191 @@
+---
+summary: "Gmail Pub/Sub push wired into Clawdbot webhooks via gogcli"
+read_when:
+  - Wiring Gmail inbox triggers to Clawdbot
+  - Setting up Pub/Sub push for agent wake
+---
+
+# Gmail Pub/Sub -> Clawdbot
+
+Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Clawdbot webhook.
+
+## Prereqs
+
+- `gcloud` installed and logged in.
+- `gog` (gogcli) installed and authorized for the Gmail account.
+- Clawdbot hooks enabled (see `docs/webhook.md`).
+- `tailscale` logged in if you want a public HTTPS endpoint via Funnel.
+
+Example hook config (enable Gmail preset mapping):
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "CLAWDBOT_HOOK_TOKEN",
+    path: "/hooks",
+    presets: ["gmail"]
+  }
+}
+```
+
+To customize payload handling, add `hooks.mappings` or a JS/TS transform module
+under `hooks.transformsDir` (see `docs/webhook.md`).
+
+## Wizard (recommended)
+
+Use the Clawdbot helper to wire everything together (installs deps on macOS via brew):
+
+```bash
+clawdbot hooks gmail setup \
+  --account clawdbot@gmail.com
+```
+
+Defaults:
+- Uses Tailscale Funnel for the public push endpoint.
+- Writes `hooks.gmail` config for `clawdbot hooks gmail run`.
+- Enables the Gmail hook preset (`hooks.presets: ["gmail"]`).
+
+Path note: when `tailscale.mode` is enabled, Clawdbot automatically sets
+`hooks.gmail.serve.path` to `/` and keeps the public path at
+`hooks.gmail.tailscale.path` (default `/gmail-pubsub`) because Tailscale
+strips the set-path prefix before proxying.
+
+Want a custom endpoint? Use `--push-endpoint <url>` or `--tailscale off`.
+
+Platform note: on macOS the wizard installs `gcloud`, `gogcli`, and `tailscale`
+via Homebrew; on Linux install them manually first.
+
+Gateway auto-start (recommended):
+- When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts
+  `gog gmail watch serve` on boot and auto-renews the watch.
+- Set `CLAWDBOT_SKIP_GMAIL_WATCHER=1` to opt out (useful if you run the daemon yourself).
+- Do not run the manual daemon at the same time, or you will hit
+  `listen tcp 127.0.0.1:8788: bind: address already in use`.
+
+Manual daemon (starts `gog gmail watch serve` + auto-renew):
+
+```bash
+clawdbot hooks gmail run
+```
+
+## One-time setup
+
+1) Select the GCP project **that owns the OAuth client** used by `gog`.
+
+```bash
+gcloud auth login
+gcloud config set project <project-id>
+```
+
+Note: Gmail watch requires the Pub/Sub topic to live in the same project as the OAuth client.
+
+2) Enable APIs:
+
+```bash
+gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+```
+
+3) Create a topic:
+
+```bash
+gcloud pubsub topics create gog-gmail-watch
+```
+
+4) Allow Gmail push to publish:
+
+```bash
+gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+  --role=roles/pubsub.publisher
+```
+
+## Start the watch
+
+```bash
+gog gmail watch start \
+  --account clawdbot@gmail.com \
+  --label INBOX \
+  --topic projects/<project-id>/topics/gog-gmail-watch
+```
+
+Save the `history_id` from the output (for debugging).
+
+## Run the push handler
+
+Local example (shared token auth):
+
+```bash
+gog gmail watch serve \
+  --account clawdbot@gmail.com \
+  --bind 127.0.0.1 \
+  --port 8788 \
+  --path /gmail-pubsub \
+  --token <shared> \
+  --hook-url http://127.0.0.1:18789/hooks/gmail \
+  --hook-token CLAWDBOT_HOOK_TOKEN \
+  --include-body \
+  --max-bytes 20000
+```
+
+Notes:
+- `--token` protects the push endpoint (`x-gog-token` or `?token=`).
+- `--hook-url` points to Clawdbot `/hooks/gmail` (mapped; isolated run + summary to main).
+- `--include-body` and `--max-bytes` control the body snippet sent to Clawdbot.
+
+Recommended: `clawdbot hooks gmail run` wraps the same flow and auto-renews the watch.
+
+## Expose the handler (dev)
+
+For local testing, tunnel the handler and use the public URL in the push subscription:
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:8788 --no-autoupdate
+```
+
+Use the generated URL as the push endpoint:
+
+```bash
+gcloud pubsub subscriptions create gog-gmail-watch-push \
+  --topic gog-gmail-watch \
+  --push-endpoint "https://<public-url>/gmail-pubsub?token=<shared>"
+```
+
+Production: use a stable HTTPS endpoint and configure Pub/Sub OIDC JWT, then run:
+
+```bash
+gog gmail watch serve --verify-oidc --oidc-email <svc@...>
+```
+
+## Test
+
+Send a message to the watched inbox:
+
+```bash
+gog gmail send \
+  --account clawdbot@gmail.com \
+  --to clawdbot@gmail.com \
+  --subject "watch test" \
+  --body "ping"
+```
+
+Check watch state and history:
+
+```bash
+gog gmail watch status --account clawdbot@gmail.com
+gog gmail history --account clawdbot@gmail.com --since <historyId>
+```
+
+## Troubleshooting
+
+- `Invalid topicName`: project mismatch (topic not in the OAuth client project).
+- `User not authorized`: missing `roles/pubsub.publisher` on the topic.
+- Empty messages: Gmail push only provides `historyId`; fetch via `gog gmail history`.
+
+## Cleanup
+
+```bash
+gog gmail watch stop --account clawdbot@gmail.com
+gcloud pubsub subscriptions delete gog-gmail-watch-push
+gcloud pubsub topics delete gog-gmail-watch
+```

package/docs/grammy.md

@@ -0,0 +1,27 @@
+---
+summary: "Telegram Bot API integration via grammY with setup notes"
+read_when:
+  - Working on Telegram or grammY pathways
+---
+# grammY Integration (Telegram Bot API)
+
+Updated: 2025-12-07
+
+# Why grammY
+- TS-first Bot API client with built-in long-poll + webhook helpers, middleware, error handling, rate limiter.
+- Cleaner media helpers than hand-rolling fetch + FormData; supports all Bot API methods.
+- Extensible: proxy support via custom fetch, session middleware (optional), type-safe context.
+
+# What we shipped
+- **Single client path:** fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default.
+- **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`.
+- **Proxy:** optional `telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
+- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `telegram.webhookUrl` is set (otherwise it long-polls).
+- **Sessions:** direct chats map to `main`; groups map to `telegram:group:<chatId>`; replies route back to the same surface.
+- **Config knobs:** `telegram.botToken`, `telegram.groups`, `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`.
+- **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
+
+Open questions
+- Optional grammY plugins (throttler) if we hit Bot API 429s.
+- Add more structured media tests (stickers, voice notes).
+- Make webhook listen port configurable (currently fixed to 8787 unless wired through the gateway).

package/docs/group-messages.md

@@ -0,0 +1,71 @@
+---
+summary: "Behavior and config for WhatsApp group message handling"
+read_when:
+  - Changing group message rules or mentions
+---
+# Group messages (web provider)
+
+Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
+
+## What’s implemented (2025-12-03)
+- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`whatsapp.groups`) and overridden per group via `/activation`.
+- Group allowlist bypass: we still enforce `whatsapp.allowFrom` on the participant at inbox ingest, but group JIDs themselves no longer block replies.
+- Per-group sessions: session keys look like `whatsapp:group:<jid>` so commands such as `/verbose on` or `/think:high` are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
+- Context injection: last N (default 50) group messages are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`.
+- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
+- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
+- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat.
+
+## Config for Clawd UK (+447700900123)
+Add a `groupChat` block to `~/.clawdbot/clawdbot.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
+
+```json5
+{
+  "whatsapp": {
+    "groups": {
+      "*": { "requireMention": true }
+    }
+  },
+  "routing": {
+    "groupChat": {
+      "historyLimit": 50,
+      "mentionPatterns": [
+        "@?clawd",
+        "@?clawd\\s*uk",
+        "@?clawdbot",
+        "\\+?447700900123"
+      ]
+    }
+  }
+}
+```
+
+Notes:
+- The regexes are case-insensitive; they cover `@clawd`, `@clawd uk`, `clawdbot`, and the raw number with or without `+`/spaces.
+- WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is rarely needed but is a good safety net.
+
+### Activation command (owner-only)
+
+Use the group chat command:
+- `/activation mention`
+- `/activation always`
+
+Only the owner number (from `whatsapp.allowFrom`, defaulting to the bot’s own E.164 when unset) can change this. `/status` in the group shows the current activation mode.
+
+## How to use
+1) Add Clawd UK (`+447700900123`) to the group.
+2) Say `@clawd …` (or `@clawd uk`, `@clawdbot`, or include the number). Anyone in the group can trigger it.
+3) The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
+4) Session-level directives (`/verbose on`, `/think:high`, `/new` or `/reset`) apply only to that group’s session; your personal DM session remains independent.
+
+## Testing / verification
+- Automated: `pnpm test -- src/web/auto-reply.test.ts --runInBand` (covers mention gating, history injection, sender suffix).
+- Manual smoke:
+  - Send an `@clawd` ping in the group and confirm a reply that references the sender name.
+  - Send a second ping and verify the history block is included then cleared on the next turn.
+- Check gateway logs (run with `--verbose`) to see `inbound web message` entries showing `from: <groupJid>` and the `[from: …]` suffix.
+
+## Known considerations
+- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
+- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
+- Session store entries will appear as `whatsapp:group:<jid>` in the session store (`~/.clawdbot/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.

package/docs/groups.md

@@ -0,0 +1,78 @@
+---
+summary: "Group chat behavior across surfaces (WhatsApp/Telegram/Discord/iMessage)"
+read_when:
+  - Changing group chat behavior or mention gating
+---
+# Groups
+
+Clawdbot treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, iMessage.
+
+## Session keys
+- Group sessions use `surface:group:<id>` session keys (rooms/channels use `surface:channel:<id>`).
+- Direct chats use the main session (or per-sender if configured).
+- Heartbeats are skipped for group sessions.
+
+## Display labels
+- UI labels use `displayName` when available, formatted as `surface:<token>`.
+- `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).
+
+## Mention gating (default)
+Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
+
+```json5
+{
+  whatsapp: {
+    groups: {
+      "*": { requireMention: true },
+      "123@g.us": { requireMention: false }
+    }
+  },
+  telegram: {
+    groups: {
+      "*": { requireMention: true },
+      "123456789": { requireMention: false }
+    }
+  },
+  imessage: {
+    groups: {
+      "*": { requireMention: true },
+      "123": { requireMention: false }
+    }
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@clawd", "clawdbot", "\\+15555550123"],
+      historyLimit: 50
+    }
+  }
+}
+```
+
+Notes:
+- `mentionPatterns` are case-insensitive regexes.
+- Surfaces that provide explicit mentions still pass; patterns are a fallback.
+- Discord defaults live in `discord.guilds."*"` (overridable per guild/channel).
+
+## Activation (owner-only)
+Group owners can toggle per-group activation:
+- `/activation mention`
+- `/activation always`
+
+Owner is determined by `whatsapp.allowFrom` (or the bot’s self E.164 when unset). Other surfaces currently ignore `/activation`.
+
+## Context fields
+Group inbound payloads set:
+- `ChatType=group`
+- `GroupSubject` (if known)
+- `GroupMembers` (if known)
+- `WasMentioned` (mention gating result)
+
+The agent system prompt includes a group intro on the first turn of a new group session.
+
+## iMessage specifics
+- Prefer `chat_id:<id>` when routing or allowlisting.
+- List chats: `imsg chats --limit 20`.
+- Group replies always go back to the same `chat_id`.
+
+## WhatsApp specifics
+See `docs/group-messages.md` for WhatsApp-only behavior (history injection, mention handling details).