From 14d7da6ec231a20cec21d74b743fcd69ae8a1603 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 20:59:54 +0100 Subject: [PATCH 001/110] docs: unify app docs --- docs/{android/connect.md => android.md} | 26 +-- docs/architecture.md | 2 +- docs/clawd.md | 6 +- docs/index.md | 6 + docs/{ios/spec.md => ios.md} | 236 +++++++++++++++++++----- docs/ios/connect.md | 177 ------------------ docs/linux.md | 11 ++ docs/mac/canvas.md | 2 +- docs/{clawdbot-mac.md => macos.md} | 0 docs/refactor/canvas-a2ui.md | 2 +- docs/setup.md | 2 +- docs/windows.md | 11 ++ 12 files changed, 237 insertions(+), 244 deletions(-) rename docs/{android/connect.md => android.md} (89%) rename docs/{ios/spec.md => ios.md} (54%) delete mode 100644 docs/ios/connect.md create mode 100644 docs/linux.md rename docs/{clawdbot-mac.md => macos.md} (100%) create mode 100644 docs/windows.md diff --git a/docs/android/connect.md b/docs/android.md similarity index 89% rename from docs/android/connect.md rename to docs/android.md index 75964a729..ea09269e5 100644 --- a/docs/android/connect.md +++ b/docs/android.md @@ -1,18 +1,20 @@ --- -summary: "Runbook: connect/pair the Android node to a Clawdbot Gateway and use Canvas/Chat/Camera" +summary: "Android app (node): connection runbook + Canvas/Chat/Camera" read_when: - Pairing or reconnecting the Android node - Debugging Android bridge discovery or auth - Verifying chat history parity across clients --- -# Android Node Connection Runbook +# Android App (Node) + +## Connection Runbook Android node app ⇄ (mDNS/NSD + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway** The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing. -## Prerequisites +### Prerequisites - You can run the Gateway on the “master” machine. - Android device/emulator can reach the gateway bridge: @@ -21,7 +23,7 @@ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talk - Manual bridge host/port (fallback) - You can run the CLI (`clawdbot`) on the gateway machine (or via SSH). -## 1) Start the Gateway (with bridge enabled) +### 1) Start the Gateway (with bridge enabled) Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`). @@ -37,7 +39,7 @@ For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to - Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host. - Restart the Gateway / macOS menubar app. -## 2) Verify discovery (optional) +### 2) Verify discovery (optional) From the gateway machine: @@ -47,7 +49,7 @@ dns-sd -B _clawdbot-bridge._tcp local. More debugging notes: `docs/bonjour.md`. -### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD +#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead: @@ -56,7 +58,7 @@ Android NSD/mDNS discovery won’t cross networks. If your Android node and the Details and example CoreDNS config: `docs/bonjour.md`. -## 3) Connect from Android +### 3) Connect from Android In the Android app: @@ -69,7 +71,7 @@ After the first successful pairing, Android auto-reconnects on launch: - Manual endpoint (if enabled), otherwise - The last discovered bridge (best-effort). -## 4) Approve pairing (CLI) +### 4) Approve pairing (CLI) On the gateway machine: @@ -80,7 +82,7 @@ clawdbot nodes approve Pairing details: `docs/gateway/pairing.md`. -## 5) Verify the node is connected +### 5) Verify the node is connected - Via nodes status: ```bash @@ -91,7 +93,7 @@ Pairing details: `docs/gateway/pairing.md`. clawdbot gateway call node.list --params "{}" ``` -## 6) Chat + history +### 6) Chat + history The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients: @@ -99,9 +101,9 @@ The Android node’s Chat sheet uses the gateway’s **primary session key** (`m - Send: `chat.send` - Push updates (best-effort): `chat.subscribe` → `event:"chat"` -## 7) Canvas + camera +### 7) Canvas + camera -### Gateway Canvas Host (recommended for web content) +#### Gateway Canvas Host (recommended for web content) If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host. diff --git a/docs/architecture.md b/docs/architecture.md index 720450732..fce9f0768 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -40,7 +40,7 @@ Last updated: 2026-01-05 - **Clients (mac app / CLI / web admin)** - One WS connection per client. - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`). - - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/clawdbot-mac.md`). + - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/macos.md`). - **Agent process (Pi)** - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection. - **WebChat** diff --git a/docs/clawd.md b/docs/clawd.md index 7bbadfaad..77a3cdf05 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -193,5 +193,9 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`). - WebChat: [WebChat](./webchat.md) - Gateway ops: [Gateway runbook](./gateway.md) - Cron + wakeups: [Cron + wakeups](./cron.md) -- macOS menu bar companion: [Clawdbot macOS app](./clawdbot-mac.md) +- macOS menu bar companion: [Clawdbot macOS app](./macos.md) +- iOS node app: [iOS app](./ios.md) +- Android node app: [Android app](./android.md) +- Windows status: [Windows app](./windows.md) +- Linux status: [Linux app](./linux.md) - Security: [Security](./security.md) diff --git a/docs/index.md b/docs/index.md index ea92072ac..156262657 100644 --- a/docs/index.md +++ b/docs/index.md @@ -149,6 +149,12 @@ Example: - [WhatsApp group messages](./group-messages.md) - [Media: images](./images.md) - [Media: audio](./audio.md) +- Companion apps: + - [macOS app](./macos.md) + - [iOS app](./ios.md) + - [Android app](./android.md) + - [Windows app](./windows.md) + - [Linux app](./linux.md) - Ops and safety: - [Sessions](./session.md) - [Cron + wakeups](./cron.md) diff --git a/docs/ios/spec.md b/docs/ios.md similarity index 54% rename from docs/ios/spec.md rename to docs/ios.md index 0baf04e52..ecdf3db01 100644 --- a/docs/ios/spec.md +++ b/docs/ios.md @@ -1,17 +1,182 @@ --- -summary: "Plan for an iOS voice + canvas node that connects via a secure Bonjour-discovered macOS bridge" +summary: "iOS app (node): architecture + connection runbook" read_when: + - Pairing or reconnecting the iOS node + - Debugging iOS bridge discovery or auth + - Sending screen/canvas commands to iOS - Designing iOS node + gateway integration - Extending the Gateway protocol for node/canvas commands - Implementing Bonjour pairing or transport security --- -# iOS Node (internal) — Voice Trigger + Canvas +# iOS App (Node) Status: prototype implemented (internal) · Date: 2025-12-13 -Runbook (how to connect/pair + drive Canvas): `docs/ios/connect.md` +## Connection Runbook -## Goals +This is the practical “how do I connect the iOS node” guide: + +**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway** + +The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing. + +### Prerequisites + +- You can run the Gateway on the “master” machine. +- iOS node app can reach the gateway bridge: + - Same LAN with Bonjour/mDNS, **or** + - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or** + - Manual bridge host/port (fallback) +- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH). + +### 1) Start the Gateway (with bridge enabled) + +Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`). + +```bash +pnpm clawdbot gateway --port 18789 --verbose +``` + +Confirm in logs you see something like: +- `bridge listening on tcp://0.0.0.0:18790 (node)` + +For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead: + +- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host. +- Restart the Gateway / macOS menubar app. + +### 2) Verify Bonjour discovery (optional but recommended) + +From the gateway machine: + +```bash +dns-sd -B _clawdbot-bridge._tcp local. +``` + +You should see your gateway advertising `_clawdbot-bridge._tcp`. + +If browse works, but the iOS node can’t connect, try resolving one instance: + +```bash +dns-sd -L "" _clawdbot-bridge._tcp local. +``` + +More debugging notes: `docs/bonjour.md`. + +#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD + +If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead: + +1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records. +2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server. + +Details and example CoreDNS config: `docs/bonjour.md`. + +### 3) Connect from the iOS node app + +In the iOS node app: +- Pick the discovered bridge (or hit refresh). +- If not paired yet, it will initiate pairing automatically. +- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present. + +#### Connection indicator (always visible) + +The Settings tab icon shows a small status dot: +- **Green**: connected to the bridge +- **Yellow**: connecting (subtle pulse) +- **Red**: not connected / error + +### 4) Approve pairing (CLI) + +On the gateway machine: + +```bash +clawdbot nodes pending +``` + +Approve the request: + +```bash +clawdbot nodes approve +``` + +After approval, the iOS node receives/stores the token and reconnects authenticated. + +Pairing details: `docs/gateway/pairing.md`. + +### 5) Verify the node is connected + +- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect. +- Via nodes status (paired + connected): + ```bash + clawdbot nodes status + ``` +- Via Gateway (paired + connected): + ```bash + clawdbot gateway call node.list --params "{}" + ``` +- Via Gateway presence (legacy-ish, still useful): + ```bash + clawdbot gateway call system-presence --params "{}" + ``` + Look for the node `instanceId` (often a UUID). + +### 6) Drive the iOS Canvas (draw / snapshot) + +The iOS node runs a WKWebView “Canvas” scaffold which exposes: +- `window.__clawdbot.canvas` +- `window.__clawdbot.ctx` (2D context) +- `window.__clawdbot.setStatus(title, subtitle)` + +#### Gateway Canvas Host (recommended for web content) + +If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host. + +Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface. + +1) Create `~/clawd/canvas/index.html` on the gateway host. + +2) Navigate the node to it (LAN): + +```bash +clawdbot nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://.local:18793/__clawdbot__/canvas/"}' +``` + +Notes: +- The server injects a live-reload client into HTML and reloads on file changes. +- A2UI is hosted on the same canvas host at `http://:18793/__clawdbot__/a2ui/`. +- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://:18793/__clawdbot__/canvas/`. +- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config. + +#### Draw with `canvas.eval` + +```bash +clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON' +{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"} +JSON +)" +``` + +#### Snapshot with `canvas.snapshot` + +```bash +clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}' +``` + +The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG). + +### Common gotchas + +- **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground). +- **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page. +- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see `docs/discovery.md`). +- **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you. +- **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request. +- **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once. + +## Design + Architecture + +### Goals - Build an **iOS app** that acts as a **remote node** for Clawdbot: - **Voice trigger** (wake-word / always-listening intent) that forwards transcripts to the Gateway `agent` method. - **Canvas** surface that the agent can control: navigate, draw/render, evaluate JS, snapshot. @@ -28,13 +193,13 @@ Non-goals (v1): - Supporting arbitrary third-party “plugins” on iOS. - Perfect App Store compliance; this is **internal-only** initially. -## Current repo reality (constraints we respect) +### Current repo reality (constraints we respect) - The Gateway WebSocket server binds to `127.0.0.1:18789` (`src/gateway/server.ts`) with an optional `CLAWDBOT_GATEWAY_TOKEN`. - The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://:18793/__clawdbot__/canvas/` and auto-reload on file changes (`docs/configuration.md`). - macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android (`docs/mac/canvas.md`). - Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`). -## Recommended topology (B): Gateway-owned Bridge + loopback Gateway +### Recommended topology (B): Gateway-owned Bridge + loopback Gateway Keep the Node gateway loopback-only; expose a dedicated **gateway-owned bridge** to the LAN/tailnet. **iOS App** ⇄ (TLS + pairing) ⇄ **Bridge (in gateway)** ⇄ (loopback) ⇄ **Gateway WS** (`ws://127.0.0.1:18789`) @@ -44,12 +209,12 @@ Why: - Centralizes auth, rate limiting, and allowlisting in the bridge. - Lets us unify “canvas node” semantics across mac + iOS without exposing raw gateway methods. -## Security plan (internal, but still robust) -### Transport +### Security plan (internal, but still robust) +#### Transport - **Current (v0):** bridge is a LAN-facing **TCP** listener with token-based auth after pairing. - **Next:** wrap the bridge in **TLS** and prefer key-pinned or mTLS-like auth after pairing. -### Pairing +#### Pairing - Bonjour discovery shows a candidate “Clawdbot Bridge” on the LAN. - First connection: 1) iOS generates a keypair (Secure Enclave if available). @@ -62,7 +227,7 @@ Why: - Subsequent connections: - The bridge requires the paired identity. Unpaired clients get a structured “not paired” error and no access. -#### Gateway-owned pairing (Option B details) +##### Gateway-owned pairing (Option B details) Pairing decisions must be owned by the Gateway (`clawd` / Node) so nodes can be approved without the macOS app running. Key idea: @@ -79,7 +244,7 @@ CLI (headless approvals): - `clawdbot nodes approve ` - `clawdbot nodes reject ` -### Authorization / scope control (bridge-side ACL) +#### Authorization / scope control (bridge-side ACL) The bridge must not be a raw proxy to every gateway method. - Allow by default: @@ -93,15 +258,15 @@ The bridge must not be a raw proxy to every gateway method. - voice forwards per minute - snapshot frequency / payload size -## Protocol unification: add “node/canvas” to Gateway protocol -### Principle +### Protocol unification: add “node/canvas” to Gateway protocol +#### Principle Unify mac Canvas + iOS Canvas under a single conceptual surface: - The agent talks to the Gateway using a stable method set (typed protocol). - The Gateway routes node-targeted requests to: - local mac Canvas implementation, or - remote iOS node via the bridge -### Minimal protocol additions (v1) +#### Minimal protocol additions (v1) Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models): **Identity** @@ -117,7 +282,7 @@ Add to `src/gateway/protocol/schema.ts` (and regenerate Swift models): - `node.event` → async node status/errors - e.g. background/foreground transitions, voice availability, canvas availability -### Node command set (canvas) +#### Node command set (canvas) These are values for `node.invoke.command`: - `canvas.present` / `canvas.hide` - `canvas.navigate` with `{ url }` (loads a URL; use `""` or `"/"` to return to the default scaffold) @@ -133,7 +298,7 @@ Result pattern: - Request is a standard `req/res` with `ok` / `error`. - Long operations (loads, streaming drawing, etc.) may also emit `node.event` progress. -#### Current (implemented) +##### Current (implemented) As of 2025-12-13, the Gateway supports `node.invoke` for bridge-connected nodes. Example: draw a diagonal line on the iOS Canvas: @@ -199,38 +364,9 @@ open Clawdbot.xcodeproj - Credentials: - Keychain (paired identity + bridge trust anchor) -### macOS -- Keep current Canvas root (already implemented): - - `~/Library/Application Support/Clawdbot/canvas//...` -- Bridge state: - - No local pairing store (pairing is gateway-owned). - - Any local bridge-only state should remain private under Application Support. +## Related docs -### Gateway (node) -- Pairing (source of truth): - - `~/.clawdbot/nodes/paired.json` - - `~/.clawdbot/nodes/pending.json` (or `pending/*.json` for auditability) - -## Rollout plan (phased) -1) **Bridge discovery + pairing (mac + iOS)** - - Bonjour browse + resolve - - Approve prompt on mac - - Persist pairing in Keychain/App Support -2) **Voice-only node** - - iOS voice wake toggle - - Forward transcript to Gateway `agent` via bridge - - Presence beacons via `system-event` (or node.event) -3) **Protocol additions for nodes** - - Add `node.list` / `node.invoke` / `node.event` to Gateway - - Implement bridge routing + ACLs -4) **iOS canvas** - - WKWebView canvas surface - - `canvas.navigate/eval/snapshot` - - Background fast-fail for `canvas.*` -5) **Unify mac Canvas under the same node.invoke** - - Keep existing implementation, but expose it through the unified protocol path so the agent uses one API. - -## Open questions -- Should `connect.params.client.mode` be `"node"` with `platform="ios ..."` or a distinct mode `"ios-node"`? (Presence filtering currently excludes `"cli"` only.) -- Do we want a “permissions” model per node (voice only vs voice+canvas) at pairing time? -- Should loading arbitrary websites via `canvas.navigate` allow any https URL, or enforce an allowlist to reduce risk? +- `docs/gateway.md` (gateway runbook) +- `docs/gateway/pairing.md` (approval + storage) +- `docs/bonjour.md` (discovery debugging) +- `docs/discovery.md` (LAN vs tailnet vs SSH) diff --git a/docs/ios/connect.md b/docs/ios/connect.md deleted file mode 100644 index b6a6f9ada..000000000 --- a/docs/ios/connect.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -summary: "Runbook: connect/pair the iOS node to a Clawdbot Gateway and drive its Canvas" -read_when: - - Pairing or reconnecting the iOS node - - Debugging iOS bridge discovery or auth - - Sending screen/canvas commands to iOS ---- - -# iOS Node Connection Runbook - -This is the practical “how do I connect the iOS node” guide: - -**iOS app** ⇄ (Bonjour + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway** - -The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). The iOS node talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing. - -## Prerequisites - -- You can run the Gateway on the “master” machine. -- iOS node app can reach the gateway bridge: - - Same LAN with Bonjour/mDNS, **or** - - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or** - - Manual bridge host/port (fallback) -- You can run the CLI (`clawdbot`) on the gateway machine (or via SSH). - -## 1) Start the Gateway (with bridge enabled) - -Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`). - -```bash -pnpm clawdbot gateway --port 18789 --verbose -``` - -Confirm in logs you see something like: -- `bridge listening on tcp://0.0.0.0:18790 (node)` - -For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead: - -- Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host. -- Restart the Gateway / macOS menubar app. - -## 2) Verify Bonjour discovery (optional but recommended) - -From the gateway machine: - -```bash -dns-sd -B _clawdbot-bridge._tcp local. -``` - -You should see your gateway advertising `_clawdbot-bridge._tcp`. - -If browse works, but the iOS node can’t connect, try resolving one instance: - -```bash -dns-sd -L "" _clawdbot-bridge._tcp local. -``` - -More debugging notes: `docs/bonjour.md`. - -### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD - -If the iOS node and the gateway are on different networks but connected via Tailscale, multicast mDNS won’t cross the boundary. Use Wide-Area Bonjour / unicast DNS-SD instead: - -1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records. -2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server. - -Details and example CoreDNS config: `docs/bonjour.md`. - -## 3) Connect from the iOS node app - -In the iOS node app: -- Pick the discovered bridge (or hit refresh). -- If not paired yet, it will initiate pairing automatically. -- After the first successful pairing, it will auto-reconnect **strictly to the last discovered gateway** on launch (including after reinstall), as long as the iOS Keychain entry is still present. - -### Connection indicator (always visible) - -The Settings tab icon shows a small status dot: -- **Green**: connected to the bridge -- **Yellow**: connecting (subtle pulse) -- **Red**: not connected / error - -## 4) Approve pairing (CLI) - -On the gateway machine: - -```bash -clawdbot nodes pending -``` - -Approve the request: - -```bash -clawdbot nodes approve -``` - -After approval, the iOS node receives/stores the token and reconnects authenticated. - -Pairing details: `docs/gateway/pairing.md`. - -## 5) Verify the node is connected - -- In the macOS app: **Instances** tab should show something like `iOS Node (...)` with a green “Active” presence dot shortly after connect. -- Via nodes status (paired + connected): - ```bash - clawdbot nodes status - ``` -- Via Gateway (paired + connected): - ```bash - clawdbot gateway call node.list --params "{}" - ``` -- Via Gateway presence (legacy-ish, still useful): - ```bash - clawdbot gateway call system-presence --params "{}" - ``` - Look for the node `instanceId` (often a UUID). - -## 6) Drive the iOS Canvas (draw / snapshot) - -The iOS node runs a WKWebView “Canvas” scaffold which exposes: -- `window.__clawdbot.canvas` -- `window.__clawdbot.ctx` (2D context) -- `window.__clawdbot.setStatus(title, subtitle)` - -### Gateway Canvas Host (recommended for web content) - -If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point it at the Gateway canvas host. - -Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface. - -1) Create `~/clawd/canvas/index.html` on the gateway host. - -2) Navigate the node to it (LAN): - -```bash -clawdbot nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://.local:18793/__clawdbot__/canvas/"}' -``` - -Notes: -- The server injects a live-reload client into HTML and reloads on file changes. -- A2UI is hosted on the same canvas host at `http://:18793/__clawdbot__/a2ui/`. -- Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://:18793/__clawdbot__/canvas/`. -- iOS may require App Transport Security allowances to load plain `http://` URLs; if it fails to load, prefer HTTPS or adjust the iOS app’s ATS config. - -### Draw with `canvas.eval` - -```bash -clawdbot nodes invoke --node "iOS Node" --command canvas.eval --params "$(cat <<'JSON' -{"javaScript":"(() => { const {ctx,setStatus} = window.__clawdbot; setStatus('Drawing','…'); ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle='#ff2d55'; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); setStatus(null,null); return 'ok'; })()"} -JSON -)" -``` - -### Snapshot with `canvas.snapshot` - -```bash -clawdbot nodes invoke --node 192.168.0.88 --command canvas.snapshot --params '{"maxWidth":900}' -``` - -The response includes `{ format, base64 }` image data (default `format="jpeg"`; pass `{"format":"png"}` when you specifically need lossless PNG). - -## Common gotchas - -- **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground). -- **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page. -- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see `docs/discovery.md`). -- **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you. -- **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request. -- **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once. - -## Related docs - -- `docs/ios/spec.md` (design + architecture) -- `docs/gateway.md` (gateway runbook) -- `docs/gateway/pairing.md` (approval + storage) -- `docs/bonjour.md` (discovery debugging) -- `docs/discovery.md` (LAN vs tailnet vs SSH) diff --git a/docs/linux.md b/docs/linux.md new file mode 100644 index 000000000..b5e27e4cb --- /dev/null +++ b/docs/linux.md @@ -0,0 +1,11 @@ +--- +summary: "Linux app status + contribution call" +read_when: + - Looking for Linux companion app status + - Planning platform coverage or contributions +--- +# Linux App + +Clawdbot core is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node runs. + +We do not have a Linux companion app yet. It is planned, and we would love contributions to make it happen. diff --git a/docs/mac/canvas.md b/docs/mac/canvas.md index 56fcf9428..3dc2458aa 100644 --- a/docs/mac/canvas.md +++ b/docs/mac/canvas.md @@ -81,7 +81,7 @@ Canvas is exposed via the Gateway **node bridge**, so the agent can: This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs. Related: -- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/clawdbot-mac.md`. +- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See `docs/macos.md`. ## Agent commands (current) diff --git a/docs/clawdbot-mac.md b/docs/macos.md similarity index 100% rename from docs/clawdbot-mac.md rename to docs/macos.md diff --git a/docs/refactor/canvas-a2ui.md b/docs/refactor/canvas-a2ui.md index d79ce1733..bca37c1d5 100644 --- a/docs/refactor/canvas-a2ui.md +++ b/docs/refactor/canvas-a2ui.md @@ -86,7 +86,7 @@ If `canvasHostUrl` is missing or unreachable: - TS: verify `/__clawdbot__/a2ui/` responds with HTML + JS. - Node: verify A2UI fails when host is unreachable and succeeds when reachable. 4) Docs - - Update `docs/mac/canvas.md`, `docs/ios/spec.md`, `docs/android/connect.md` + - Update `docs/mac/canvas.md`, `docs/ios.md`, `docs/android.md` to remove local fallback assumptions and point to gateway-hosted A2UI. ## Notes diff --git a/docs/setup.md b/docs/setup.md index 9a187e111..e8d230c5c 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -115,4 +115,4 @@ pnpm clawdbot health - `docs/configuration.md` (config schema + examples) - `docs/discord.md` and `docs/telegram.md` (reply tags + replyToMode settings) - `docs/clawd.md` (personal assistant setup) -- `docs/clawdbot-mac.md` (macOS app behavior; gateway lifecycle + “Attach only”) +- `docs/macos.md` (macOS app behavior; gateway lifecycle + “Attach only”) diff --git a/docs/windows.md b/docs/windows.md new file mode 100644 index 000000000..5987541a3 --- /dev/null +++ b/docs/windows.md @@ -0,0 +1,11 @@ +--- +summary: "Windows app status + contribution call" +read_when: + - Looking for Windows companion app status + - Planning platform coverage or contributions +--- +# Windows App + +Clawdbot core is fully supported on Windows. The core is written in TypeScript, so it runs anywhere Node runs. + +We do not have a Windows companion app yet. It is planned, and we would love contributions to make it happen. From 70f38400c070af40875d2c2cf744794e99389f93 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:02:02 +0100 Subject: [PATCH 002/110] docs: expand README platform + subsystem links --- README.md | 131 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 73 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 48bd07f11..bb50b902b 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,19 @@

**Clawdbot** is a *personal AI assistant* you run on your own devices. -It answers you on the surfaces you already use (WhatsApp, Telegram, Slack, Discord, iMessage, WebChat), can speak and listen on macOS/iOS, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant. +It answers you on the surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant. If you want a personal, single-user assistant that feels local, fast, and always-on, this is it. -Website: [clawdbot.com](https://clawdbot.com) · Docs: [docs.clawdbot.com](https://docs.clawdbot.com/) · FAQ: [FAQ](https://docs.clawdbot.com/faq) · Wizard: [Wizard](https://docs.clawdbot.com/wizard) · Nix: [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [Docker](https://docs.clawdbot.com/docker) · Discord: [discord.gg/clawd](https://discord.gg/clawd) +Website: [https://clawdbot.com](https://clawdbot.com) · Docs: [https://docs.clawdbot.com](https://docs.clawdbot.com/) · FAQ: [https://docs.clawdbot.com/faq](https://docs.clawdbot.com/faq) · Wizard: [https://docs.clawdbot.com/wizard](https://docs.clawdbot.com/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawdbot.com/docker](https://docs.clawdbot.com/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**. -Subscriptions: **Anthropic (Claude Pro/Max)** and **OpenAI (ChatGPT/Codex)** are supported via OAuth. See [Onboarding](https://docs.clawdbot.com/onboarding). +**Subscriptions (OAuth):** +- **Anthropic** (Claude Pro/Max) +- **OpenAI** (ChatGPT/Codex) + +Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑context strength and better prompt‑injection resistance. See [Onboarding](https://docs.clawdbot.com/onboarding). ## Recommended setup (from source) @@ -75,64 +79,74 @@ If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`). ## Highlights -- **Local-first Gateway** — single control plane for sessions, providers, tools, and events. -- **Multi-surface inbox** — WhatsApp, Telegram, Slack, Discord, iMessage, WebChat, macOS, iOS/Android. -- **Voice Wake + Talk Mode** — always-on speech for macOS/iOS/Android with ElevenLabs. -- **Live Canvas** — agent-driven visual workspace with A2UI. -- **First-class tools** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions. -- **Companion apps** — macOS menu bar app + iOS/Android nodes. -- **Onboarding + skills** — wizard-driven setup with bundled/managed/workspace skills. +- **[Local-first Gateway](https://docs.clawdbot.com/gateway)** — single control plane for sessions, providers, tools, and events. +- **[Multi-surface inbox](https://docs.clawdbot.com/surface)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat, macOS, iOS/Android. +- **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs. +- **[Live Canvas](https://docs.clawdbot.com/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui). +- **[First-class tools](https://docs.clawdbot.com/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions. +- **[Companion apps](https://docs.clawdbot.com/clawdbot-mac)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawdbot.com/nodes). +- **[Onboarding](https://docs.clawdbot.com/wizard) + [skills](https://docs.clawdbot.com/skills)** — wizard-driven setup with bundled/managed/workspace skills. ## Everything we built so far ### Core platform -- Gateway WS control plane with sessions, presence, config, cron, webhooks, control UI, and Canvas host. -- CLI surface: gateway, agent, send, wizard, doctor/update, and TUI. -- Pi agent runtime in RPC mode with tool streaming and block streaming. -- Session model: `main` for direct chats, group isolation, activation modes, queue modes, reply-back. -- Media pipeline: images/audio/video, transcription hooks, size caps, temp file lifecycle. +- [Gateway WS control plane](https://docs.clawdbot.com/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawdbot.com/web), and [Canvas host](https://docs.clawdbot.com/refactor/canvas-a2ui). +- [CLI surface](https://docs.clawdbot.com/agent-send): gateway, agent, send, [wizard](https://docs.clawdbot.com/wizard), [doctor](https://docs.clawdbot.com/doctor), and [TUI](https://docs.clawdbot.com/tui). +- [Pi agent runtime](https://docs.clawdbot.com/agent) in RPC mode with tool streaming and block streaming. +- [Session model](https://docs.clawdbot.com/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawdbot.com/groups). +- [Media pipeline](https://docs.clawdbot.com/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawdbot.com/audio). ### Surfaces + providers -- WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Signal (signal-cli), iMessage (imsg), WebChat. -- Group mention gating, reply tags, per-surface chunking and routing. +- [Providers](https://docs.clawdbot.com/surface): [WhatsApp](https://docs.clawdbot.com/whatsapp) (Baileys), [Telegram](https://docs.clawdbot.com/telegram) (grammY), [Slack](https://docs.clawdbot.com/slack) (Bolt), [Discord](https://docs.clawdbot.com/discord) (discord.js), [Signal](https://docs.clawdbot.com/signal) (signal-cli), [iMessage](https://docs.clawdbot.com/imessage) (imsg), [WebChat](https://docs.clawdbot.com/webchat). +- [Group routing](https://docs.clawdbot.com/group-messages): mention gating, reply tags, per-surface chunking and routing. Surface rules: [Surface routing](https://docs.clawdbot.com/surface). ### Apps + nodes -- macOS app: menu bar control plane, Voice Wake/PTT, Talk Mode overlay, WebChat, Debug tools, SSH remote gateway control. -- iOS node: Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing. -- Android node: Canvas, Talk Mode, camera, screen recording, optional SMS. -- macOS node mode: system.run/notify + canvas/camera exposure. +- [macOS app](https://docs.clawdbot.com/clawdbot-mac): menu bar control plane, [Voice Wake](https://docs.clawdbot.com/voicewake)/PTT, [Talk Mode](https://docs.clawdbot.com/talk) overlay, [WebChat](https://docs.clawdbot.com/webchat), debug tools, [remote gateway](https://docs.clawdbot.com/remote) control. +- [iOS node](https://docs.clawdbot.com/ios/connect): [Canvas](https://docs.clawdbot.com/mac/canvas), [Voice Wake](https://docs.clawdbot.com/voicewake), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, Bonjour pairing. +- [Android node](https://docs.clawdbot.com/android/connect): [Canvas](https://docs.clawdbot.com/mac/canvas), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, optional SMS. +- [macOS node mode](https://docs.clawdbot.com/nodes): system.run/notify + canvas/camera exposure. ### Tools + automation -- Browser control: dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles. -- Canvas: A2UI push/reset, eval, snapshot. -- Nodes: camera snap/clip, screen record, location.get, notifications. -- Cron + wakeups; webhooks; Gmail Pub/Sub triggers. -- Skills platform: bundled, managed, and workspace skills with install gating + UI. +- [Browser control](https://docs.clawdbot.com/browser): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles. +- [Canvas](https://docs.clawdbot.com/mac/canvas): [A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui) push/reset, eval, snapshot. +- [Nodes](https://docs.clawdbot.com/nodes): camera snap/clip, screen record, [location.get](https://docs.clawdbot.com/location-command), notifications. +- [Cron + wakeups](https://docs.clawdbot.com/cron); [webhooks](https://docs.clawdbot.com/webhook); [Gmail Pub/Sub](https://docs.clawdbot.com/gmail-pubsub). +- [Skills platform](https://docs.clawdbot.com/skills): bundled, managed, and workspace skills with install gating + UI. ### Ops + packaging -- Control UI + WebChat served directly from the Gateway. -- Tailscale Serve/Funnel or SSH tunnels with token/password auth. -- Nix mode for declarative config; Docker-based installs. -- Health, doctor migrations, structured logging, release tooling. +- [Control UI](https://docs.clawdbot.com/web) + [WebChat](https://docs.clawdbot.com/webchat) served directly from the Gateway. +- [Tailscale Serve/Funnel](https://docs.clawdbot.com/tailscale) or [SSH tunnels](https://docs.clawdbot.com/remote) with token/password auth. +- [Nix mode](https://docs.clawdbot.com/nix) for declarative config; [Docker](https://docs.clawdbot.com/docker)-based installs. +- [Doctor](https://docs.clawdbot.com/doctor) migrations, [logging](https://docs.clawdbot.com/logging), release tooling: [Releasing](https://docs.clawdbot.com/releasing). ## How it works (short) ``` -Your surfaces - │ - ▼ +WhatsApp / Telegram / Slack / Discord / Signal +iMessage / WebChat + │ + ▼ ┌───────────────────────────────┐ │ Gateway │ ws://127.0.0.1:18789 -│ (control plane) │ tcp://0.0.0.0:18790 (optional Bridge) +│ (control plane) │ bridge: tcp://0.0.0.0:18790 └──────────────┬────────────────┘ │ ├─ Pi agent (RPC) ├─ CLI (clawdbot …) - ├─ WebChat (browser) - ├─ macOS app (Clawdbot.app) - └─ iOS node (Canvas + voice) + ├─ WebChat UI + ├─ macOS app + └─ iOS/Android nodes ``` +## Key subsystems + +- **[Gateway WebSocket network](https://docs.clawdbot.com/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.clawdbot.com/gateway)). +- **[Tailscale exposure](https://docs.clawdbot.com/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.clawdbot.com/remote)). +- **[Browser control](https://docs.clawdbot.com/browser)** — clawd‑managed Chrome/Chromium with CDP control. +- **[Canvas + A2UI](https://docs.clawdbot.com/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui)). +- **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always‑on speech and continuous conversation. +- **[Nodes](https://docs.clawdbot.com/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`. + ## Skills registry (ClawdHub) ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed. @@ -154,6 +168,12 @@ Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only): The Gateway alone delivers a great experience. All apps are optional and add extra features. +If you plan to build/run companion apps, initialize submodules first: + +```bash +git submodule update --init --recursive +``` + ### macOS (Clawdbot.app) (optional) - Menu bar control for the Gateway and health. @@ -197,16 +217,20 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults): [Full configuration reference (all keys + examples).](https://docs.clawdbot.com/configuration) -### WhatsApp +## Security model (important) -[Read the WhatsApp provider guide in docs/whatsapp.md.](docs/whatsapp.md) +- **Default:** tools run on the host for the **main** session, so the agent has full access when it’s just you. +- **Group/channel safety:** set `agent.sandbox.mode: "non-main"` to run **non‑main sessions** (groups/channels) inside per‑session Docker sandboxes; bash then runs in Docker for those sessions. +- **Sandbox defaults:** allowlist `bash`, `process`, `read`, `write`, `edit`; denylist `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`. + +Details: [Security guide](https://docs.clawdbot.com/security) · [Docker + sandboxing](https://docs.clawdbot.com/docker) · [Sandbox config](https://docs.clawdbot.com/configuration) + +### [WhatsApp](docs/whatsapp.md) - Link the device: `pnpm clawdbot login` (stores creds in `~/.clawdbot/credentials`). - Allowlist who can talk to the assistant via `whatsapp.allowFrom`. -### Telegram - -[Read the Telegram provider guide in docs/telegram.md.](docs/telegram.md) +### [Telegram](docs/telegram.md) - Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins). - Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`), `telegram.allowFrom`, or `telegram.webhookUrl` as needed. @@ -219,15 +243,11 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults): } ``` -### Slack - -[Read the Slack provider guide in docs/slack.md.](docs/slack.md) +### [Slack](docs/slack.md) - Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`). -### Discord - -[Read the Discord provider guide in docs/discord.md.](docs/discord.md) +### [Discord](docs/discord.md) - Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins). - Optional: set `discord.slashCommand`, `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed. @@ -240,21 +260,15 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults): } ``` -### Signal - -[Read the Signal provider guide in docs/signal.md.](docs/signal.md) +### [Signal](docs/signal.md) - Requires `signal-cli` and a `signal` config section. -### iMessage - -[Read the iMessage provider guide in docs/imessage.md.](docs/imessage.md) +### [iMessage](docs/imessage.md) - macOS only; Messages must be signed in. -### WebChat - -[Read the WebChat guide in docs/webchat.md.](docs/webchat.md) +### [WebChat](docs/webchat.md) - Uses the Gateway WebSocket; no separate WebChat port/config. @@ -281,7 +295,8 @@ Browser control (optional): - [Follow the onboarding wizard flow for a guided setup.](https://docs.clawdbot.com/wizard) - [Wire external triggers via the webhook surface.](https://docs.clawdbot.com/webhook) - [Set up Gmail Pub/Sub triggers.](https://docs.clawdbot.com/gmail-pubsub) -- [Learn the macOS menu bar companion details.](https://clawdbot.com/clawdbot-mac.html) +- [Learn the macOS menu bar companion details.](https://docs.clawdbot.com/macos) +- [Platform guides: Windows](https://docs.clawdbot.com/windows), [Linux](https://docs.clawdbot.com/linux), [macOS](https://docs.clawdbot.com/macos), [iOS](https://docs.clawdbot.com/ios), [Android](https://docs.clawdbot.com/android) - [Debug common failures with the troubleshooting guide.](https://docs.clawdbot.com/troubleshooting) - [Review security guidance before exposing anything.](https://docs.clawdbot.com/security) From 60adfecdfa6f4822140cf0aeda44d7a37584a2ee Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:30:19 +0100 Subject: [PATCH 003/110] docs: sync platform docs + nav --- docs/_config.yml | 10 ++++++---- docs/architecture.md | 6 ++++++ docs/docs.json | 5 +++-- docs/index.md | 4 +++- docs/mac/peekaboo.md | 2 +- docs/macos.md | 2 +- 6 files changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 35036163c..cf13847ad 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,5 +1,5 @@ title: "CLAWDBOT Docs" -description: "A TypeScript/Node gateway + macOS/iOS companions for WhatsApp (web) and Telegram (bot)." +description: "A TypeScript/Node gateway + macOS/iOS/Android companions for WhatsApp (web) and Telegram (bot)." markdown: kramdown highlighter: rouge @@ -35,9 +35,11 @@ nav: - title: "WebChat" url: "/webchat.html" - title: "macOS App" - url: "/clawdbot-mac.html" - - title: "iOS Node" - url: "/ios/connect.html" + url: "/macos.html" + - title: "iOS App" + url: "/ios.html" + - title: "Android App" + url: "/android.html" - title: "Telegram" url: "/telegram.html" - title: "Security" diff --git a/docs/architecture.md b/docs/architecture.md index fce9f0768..ee98631ae 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -32,6 +32,12 @@ Last updated: 2026-01-05 - Canvas + actions: `WKWebView` with A2UI action bridge; accepts actions from local-network or trusted file URLs; intercepts `clawdbot://` deep links and forwards `agent.request` to the bridge. - Voice/talk: voice wake sends `voice.transcript` events and syncs triggers via `voicewake.get` + `voicewake.changed`; Talk Mode attaches to the bridge. +### Android node (`apps/android`) +- Discovery + pairing: `BridgeDiscovery` uses mDNS/NSD to find `_clawdbot-bridge._tcp`, with manual host/port fallback. +- Auto-connect: `NodeRuntime` restores a stored token, performs `pair-and-hello`, and reconnects to the last discovered or manual bridge. +- Bridge runtime: `BridgeSession` owns the TCP JSONL session (`hello`/`hello-ok`, ping/pong, `req/res`, `event`, `invoke`); stores `canvasHostUrl`. +- Commands: `NodeRuntime` executes `canvas.*`, `canvas.a2ui.*`, `camera.*`, and chat/session events; foreground-only for canvas/camera. + ## Components and flows - **Gateway (daemon)** - Maintains WhatsApp (Baileys), Telegram (grammY), Slack (Bolt), Discord (discord.js), Signal (signal-cli), and iMessage (imsg) connections. diff --git a/docs/docs.json b/docs/docs.json index 2a6c4b5a2..9d10e946c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -70,8 +70,9 @@ "mac/dev-setup", "mac/menu-bar", "mac/voicewake", - "ios/connect", - "android/connect", + "macos", + "ios", + "android", "webchat", "web" ] diff --git a/docs/index.md b/docs/index.md index 156262657..704447c69 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,7 +42,8 @@ WhatsApp / Telegram / Discord ├─ CLI (clawdbot …) ├─ Chat UI (SwiftUI) ├─ macOS app (Clawdbot.app) - └─ iOS node via Bridge + pairing + ├─ iOS node via Bridge + pairing + └─ Android node via Bridge + pairing ``` Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns provider connections and the WebSocket control plane. @@ -70,6 +71,7 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long - 🎤 **Voice notes** — Optional transcription hook - 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake - 📱 **iOS node** — Pairs as a node and exposes a Canvas surface +- 📱 **Android node** — Pairs as a node and exposes Canvas + Chat + Camera Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path. diff --git a/docs/mac/peekaboo.md b/docs/mac/peekaboo.md index 913d5545b..50511bea6 100644 --- a/docs/mac/peekaboo.md +++ b/docs/mac/peekaboo.md @@ -23,7 +23,7 @@ Peekaboo’s privileged execution moved from “CLI → XPC helper” to “CLI - It lets us piggyback on **either** Peekaboo.app’s permissions **or** Clawdbot.app’s permissions (whichever is running). - It avoids “two apps with two TCC bubbles” unless needed. -Reference (Peekaboo submodule): `docs/bridge-host.md`. +Reference (Peekaboo submodule): `Peekaboo/docs/bridge-host.md`. ## Architecture ### Processes diff --git a/docs/macos.md b/docs/macos.md index 318f3c741..7412a2fc8 100644 --- a/docs/macos.md +++ b/docs/macos.md @@ -94,7 +94,7 @@ Notes: - In remote mode, Clawdbot will use the configured remote tunnel/endpoint. ## Build & dev workflow (native) -- `cd native && swift build` (debug) / `swift build -c release`. +- `cd apps/macos && swift build` (debug) / `swift build -c release`. - Run app for dev: `swift run Clawdbot` (or Xcode scheme). - Package app + CLI: `scripts/package-mac-app.sh` (builds bun CLI + gateway). - Tests: add Swift Testing suites under `apps/macos/Tests`. From 055b497332b702c38004caab3ce2bae81df372b3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:46:52 +0100 Subject: [PATCH 004/110] docs: add hubs index and clawdibuted --- README.md | 39 ++++++------ docs/docs.json | 1 + docs/hubs.md | 158 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 4 files changed, 179 insertions(+), 20 deletions(-) create mode 100644 docs/hubs.md diff --git a/README.md b/README.md index bb50b902b..8fdb5dcb9 100644 --- a/README.md +++ b/README.md @@ -84,14 +84,14 @@ If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`). - **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs. - **[Live Canvas](https://docs.clawdbot.com/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawdbot.com/refactor/canvas-a2ui). - **[First-class tools](https://docs.clawdbot.com/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions. -- **[Companion apps](https://docs.clawdbot.com/clawdbot-mac)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawdbot.com/nodes). +- **[Companion apps](https://docs.clawdbot.com/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawdbot.com/nodes). - **[Onboarding](https://docs.clawdbot.com/wizard) + [skills](https://docs.clawdbot.com/skills)** — wizard-driven setup with bundled/managed/workspace skills. ## Everything we built so far ### Core platform - [Gateway WS control plane](https://docs.clawdbot.com/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawdbot.com/web), and [Canvas host](https://docs.clawdbot.com/refactor/canvas-a2ui). -- [CLI surface](https://docs.clawdbot.com/agent-send): gateway, agent, send, [wizard](https://docs.clawdbot.com/wizard), [doctor](https://docs.clawdbot.com/doctor), and [TUI](https://docs.clawdbot.com/tui). +- [CLI surface](https://docs.clawdbot.com/agent-send): gateway, agent, send, [wizard](https://docs.clawdbot.com/wizard), and [doctor](https://docs.clawdbot.com/doctor). - [Pi agent runtime](https://docs.clawdbot.com/agent) in RPC mode with tool streaming and block streaming. - [Session model](https://docs.clawdbot.com/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawdbot.com/groups). - [Media pipeline](https://docs.clawdbot.com/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawdbot.com/audio). @@ -101,9 +101,9 @@ If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`). - [Group routing](https://docs.clawdbot.com/group-messages): mention gating, reply tags, per-surface chunking and routing. Surface rules: [Surface routing](https://docs.clawdbot.com/surface). ### Apps + nodes -- [macOS app](https://docs.clawdbot.com/clawdbot-mac): menu bar control plane, [Voice Wake](https://docs.clawdbot.com/voicewake)/PTT, [Talk Mode](https://docs.clawdbot.com/talk) overlay, [WebChat](https://docs.clawdbot.com/webchat), debug tools, [remote gateway](https://docs.clawdbot.com/remote) control. -- [iOS node](https://docs.clawdbot.com/ios/connect): [Canvas](https://docs.clawdbot.com/mac/canvas), [Voice Wake](https://docs.clawdbot.com/voicewake), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, Bonjour pairing. -- [Android node](https://docs.clawdbot.com/android/connect): [Canvas](https://docs.clawdbot.com/mac/canvas), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, optional SMS. +- [macOS app](https://docs.clawdbot.com/macos): menu bar control plane, [Voice Wake](https://docs.clawdbot.com/voicewake)/PTT, [Talk Mode](https://docs.clawdbot.com/talk) overlay, [WebChat](https://docs.clawdbot.com/webchat), debug tools, [remote gateway](https://docs.clawdbot.com/remote) control. +- [iOS node](https://docs.clawdbot.com/ios): [Canvas](https://docs.clawdbot.com/mac/canvas), [Voice Wake](https://docs.clawdbot.com/voicewake), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, Bonjour pairing. +- [Android node](https://docs.clawdbot.com/android): [Canvas](https://docs.clawdbot.com/mac/canvas), [Talk Mode](https://docs.clawdbot.com/talk), camera, screen recording, optional SMS. - [macOS node mode](https://docs.clawdbot.com/nodes): system.run/notify + canvas/camera exposure. ### Tools + automation @@ -117,13 +117,12 @@ If you run from source, prefer `pnpm clawdbot …` (not global `clawdbot`). - [Control UI](https://docs.clawdbot.com/web) + [WebChat](https://docs.clawdbot.com/webchat) served directly from the Gateway. - [Tailscale Serve/Funnel](https://docs.clawdbot.com/tailscale) or [SSH tunnels](https://docs.clawdbot.com/remote) with token/password auth. - [Nix mode](https://docs.clawdbot.com/nix) for declarative config; [Docker](https://docs.clawdbot.com/docker)-based installs. -- [Doctor](https://docs.clawdbot.com/doctor) migrations, [logging](https://docs.clawdbot.com/logging), release tooling: [Releasing](https://docs.clawdbot.com/releasing). +- [Doctor](https://docs.clawdbot.com/doctor) migrations, [logging](https://docs.clawdbot.com/logging). ## How it works (short) ``` -WhatsApp / Telegram / Slack / Discord / Signal -iMessage / WebChat +WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat │ ▼ ┌───────────────────────────────┐ @@ -151,7 +150,7 @@ iMessage / WebChat ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed. -https://clawdhub.com +https://ClawdHub.com ## Chat commands @@ -189,13 +188,13 @@ Build/run: `./scripts/restart-mac.sh` (packages + launches). - Voice trigger forwarding + Canvas surface. - Controlled via `clawdbot nodes …`. -Runbook: [iOS connect](https://docs.clawdbot.com/ios/connect). +Runbook: [iOS connect](https://docs.clawdbot.com/ios). ### Android node (optional) - Pairs via the same Bridge + pairing flow as iOS. - Exposes Canvas, Camera, and Screen capture commands. -- Runbook: [Android connect](https://docs.clawdbot.com/android/connect). +- Runbook: [Android connect](https://docs.clawdbot.com/android). ## Agent workspace + skills @@ -225,12 +224,12 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults): Details: [Security guide](https://docs.clawdbot.com/security) · [Docker + sandboxing](https://docs.clawdbot.com/docker) · [Sandbox config](https://docs.clawdbot.com/configuration) -### [WhatsApp](docs/whatsapp.md) +### [WhatsApp](https://docs.clawdbot.com/whatsapp) - Link the device: `pnpm clawdbot login` (stores creds in `~/.clawdbot/credentials`). - Allowlist who can talk to the assistant via `whatsapp.allowFrom`. -### [Telegram](docs/telegram.md) +### [Telegram](https://docs.clawdbot.com/telegram) - Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins). - Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`), `telegram.allowFrom`, or `telegram.webhookUrl` as needed. @@ -243,11 +242,11 @@ Details: [Security guide](https://docs.clawdbot.com/security) · [Docker + sandb } ``` -### [Slack](docs/slack.md) +### [Slack](https://docs.clawdbot.com/slack) - Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`). -### [Discord](docs/discord.md) +### [Discord](https://docs.clawdbot.com/discord) - Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins). - Optional: set `discord.slashCommand`, `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed. @@ -260,15 +259,15 @@ Details: [Security guide](https://docs.clawdbot.com/security) · [Docker + sandb } ``` -### [Signal](docs/signal.md) +### [Signal](https://docs.clawdbot.com/signal) - Requires `signal-cli` and a `signal` config section. -### [iMessage](docs/imessage.md) +### [iMessage](https://docs.clawdbot.com/imessage) - macOS only; Messages must be signed in. -### [WebChat](docs/webchat.md) +### [WebChat](https://docs.clawdbot.com/webchat) - Uses the Gateway WebSocket; no separate WebChat port/config. @@ -295,7 +294,7 @@ Browser control (optional): - [Follow the onboarding wizard flow for a guided setup.](https://docs.clawdbot.com/wizard) - [Wire external triggers via the webhook surface.](https://docs.clawdbot.com/webhook) - [Set up Gmail Pub/Sub triggers.](https://docs.clawdbot.com/gmail-pubsub) -- [Learn the macOS menu bar companion details.](https://docs.clawdbot.com/macos) +- [Learn the macOS menu bar companion details.](https://docs.clawdbot.com/mac/menu-bar) - [Platform guides: Windows](https://docs.clawdbot.com/windows), [Linux](https://docs.clawdbot.com/linux), [macOS](https://docs.clawdbot.com/macos), [iOS](https://docs.clawdbot.com/ios), [Android](https://docs.clawdbot.com/android) - [Debug common failures with the troubleshooting guide.](https://docs.clawdbot.com/troubleshooting) - [Review security guidance before exposing anything.](https://docs.clawdbot.com/security) @@ -325,7 +324,7 @@ by Peter Steinberger and the community. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs. AI/vibe-coded PRs welcome! 🤖 -Thanks to everyone who has contributed: +Thanks to everyone who has clawdibuted:

steipete thewilloftheshadow mcinteerj joshp123 joaohlisboa petter-b mukhtharcm dan-dr Nachx639 jeffersonwarrior diff --git a/docs/docs.json b/docs/docs.json index 9d10e946c..ea2a4b20b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -26,6 +26,7 @@ "group": "Getting Started", "pages": [ "index", + "hubs", "onboarding", "clawd", "faq" diff --git a/docs/hubs.md b/docs/hubs.md new file mode 100644 index 000000000..73e92442f --- /dev/null +++ b/docs/hubs.md @@ -0,0 +1,158 @@ +--- +summary: "Hubs that link to every Clawdbot doc" +read_when: + - You want a complete map of the documentation +--- +# Docs hubs + +Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav. + +## Start here + +- [Index](./index.md) +- [Onboarding](./onboarding.md) +- [Wizard](./wizard.md) +- [Setup](./setup.md) +- [FAQ](./faq.md) +- [Configuration](./configuration.md) +- [Clawd (personal assistant)](./clawd.md) +- [Lore](./lore.md) + +## Installation + distribution + +- [Docker](./docker.md) +- [Nix](./nix.md) + +## Core concepts + +- [Architecture](./architecture.md) +- [Agent runtime](./agent.md) +- [Agent loop](./agent-loop.md) +- [Sessions](./session.md) +- [Sessions (alias)](./sessions.md) +- [Session tools](./session-tool.md) +- [Queue](./queue.md) +- [RPC adapters](./rpc.md) +- [TypeBox schemas](./typebox.md) +- [Presence](./presence.md) +- [Discovery + transports](./discovery.md) +- [Bonjour](./bonjour.md) +- [Surface routing](./surface.md) +- [Groups](./groups.md) +- [Group messages](./group-messages.md) + +## Providers + ingress + +- [WhatsApp](./whatsapp.md) +- [Telegram](./telegram.md) +- [Telegram (grammY notes)](./grammy.md) +- [Slack](./slack.md) +- [Discord](./discord.md) +- [Signal](./signal.md) +- [iMessage](./imessage.md) +- [WebChat](./webchat.md) +- [Webhooks](./webhook.md) +- [Gmail Pub/Sub](./gmail-pubsub.md) + +## Gateway + operations + +- [Gateway runbook](./gateway.md) +- [Gateway pairing](./gateway/pairing.md) +- [Gateway lock](./gateway-lock.md) +- [Background process](./background-process.md) +- [Health](./health.md) +- [Heartbeat](./heartbeat.md) +- [Doctor](./doctor.md) +- [Logging](./logging.md) +- [Dashboard](./dashboard.md) +- [Control UI](./control-ui.md) +- [Control API (legacy)](./control-api.md) +- [Remote access](./remote.md) +- [Remote gateway README](./remote-gateway-readme.md) +- [Tailscale](./tailscale.md) +- [Security](./security.md) +- [Troubleshooting](./troubleshooting.md) + +## Tools + automation + +- [Tools surface](./tools.md) +- [Bash tool](./bash.md) +- [Elevated mode](./elevated.md) +- [Cron + wakeups](./cron.md) +- [Thinking + verbose](./thinking.md) +- [Models](./models.md) +- [Agent send CLI](./agent-send.md) +- [Terminal UI](./tui.md) +- [Browser control](./browser.md) +- [Browser (Linux troubleshooting)](./browser-linux-troubleshooting.md) + +## Nodes, media, voice + +- [Nodes overview](./nodes.md) +- [Camera](./camera.md) +- [Images](./images.md) +- [Audio](./audio.md) +- [Location command](./location-command.md) +- [Voice wake](./voicewake.md) +- [Talk mode](./talk.md) + +## Platforms + +- [macOS app overview](./macos.md) +- [macOS dev setup](./mac/dev-setup.md) +- [macOS menu bar](./mac/menu-bar.md) +- [macOS voice wake](./mac/voicewake.md) +- [macOS voice overlay](./mac/voice-overlay.md) +- [macOS WebChat](./mac/webchat.md) +- [macOS Canvas](./mac/canvas.md) +- [macOS child process](./mac/child-process.md) +- [macOS health](./mac/health.md) +- [macOS icon](./mac/icon.md) +- [macOS logging](./mac/logging.md) +- [macOS permissions](./mac/permissions.md) +- [macOS remote](./mac/remote.md) +- [macOS signing](./mac/signing.md) +- [macOS release](./mac/release.md) +- [macOS bun gateway](./mac/bun.md) +- [macOS XPC](./mac/xpc.md) +- [macOS skills](./mac/skills.md) +- [macOS Peekaboo plan](./mac/peekaboo.md) +- [iOS node](./ios.md) +- [Android node](./android.md) +- [Windows app](./windows.md) +- [Linux app](./linux.md) +- [Web surfaces](./web.md) + +## Workspace + templates + +- [Skills](./skills.md) +- [Skills config](./skills-config.md) +- [Default AGENTS](./AGENTS.default.md) +- [Templates: AGENTS](./templates/AGENTS.md) +- [Templates: BOOTSTRAP](./templates/BOOTSTRAP.md) +- [Templates: IDENTITY](./templates/IDENTITY.md) +- [Templates: SOUL](./templates/SOUL.md) +- [Templates: TOOLS](./templates/TOOLS.md) +- [Templates: USER](./templates/USER.md) + +## Experiments + proposals + +- [Onboarding config protocol](./onboarding-config-protocol.md) +- [Research: memory](./research/memory.md) +- [Proposal: model config](./proposals/model-config.md) +- [Refactor: agent loop](./refactor/agent-loop.md) +- [Refactor: browser control simplification](./refactor/browser-control-simplification.md) +- [Refactor: Canvas A2UI](./refactor/canvas-a2ui.md) +- [Refactor: CLI unification](./refactor/cli-unification.md) +- [Refactor: gateway client](./refactor/gateway-client.md) +- [Refactor: gateway](./refactor/gateway.md) +- [Refactor: new arch](./refactor/new-arch.md) +- [Refactor: TUI](./refactor/tui.md) +- [Refactor: web gateway troubleshooting](./refactor/web-gateway-troubleshooting.md) +- [Refactor: webagent session](./refactor/webagent-session.md) + +## Testing + release + +- [Testing](./test.md) +- [Release checklist](./RELEASING.md) +- [Device models](./device-models.md) diff --git a/docs/index.md b/docs/index.md index 704447c69..76893a0b7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -128,6 +128,7 @@ Example: ## Docs - Start here: + - [Docs hubs (all pages linked)](./hubs.md) - [FAQ](./faq.md) ← *common questions answered* - [Configuration](./configuration.md) - [Nix mode](./nix.md) From 872f30fee0cbfbc05158ae204ab50b65aad0b9e9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:47:56 +0100 Subject: [PATCH 005/110] docs: clawtributors line --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8fdb5dcb9..45a97b218 100644 --- a/README.md +++ b/README.md @@ -324,7 +324,7 @@ by Peter Steinberger and the community. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs. AI/vibe-coded PRs welcome! 🤖 -Thanks to everyone who has clawdibuted: +Thanks to all clawtributors:

steipete thewilloftheshadow mcinteerj joshp123 joaohlisboa petter-b mukhtharcm dan-dr Nachx639 jeffersonwarrior From 1e9d7e0d7973ac3a54d6a88e21898aa1fdcff15c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:53:37 +0100 Subject: [PATCH 006/110] docs: fix oauth path references --- docs/configuration.md | 18 +++++++++--------- docs/faq.md | 8 ++++---- docs/onboarding.md | 20 ++++++++++---------- docs/wizard.md | 2 +- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6d1ad7563..917bda69d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -91,18 +91,18 @@ Env var equivalent: ### Auth storage (OAuth + API keys) -Clawdbot keeps subscription OAuth tokens + API keys in the **agent auth store**: +Clawdbot stores **OAuth credentials** in: +- `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`) + +Clawdbot stores **API keys** in the agent auth store: - `~/.clawdbot/agent/auth.json` -The agent directory can be overridden with: -- `CLAWDBOT_AGENT_DIR` (preferred) -- `PI_CODING_AGENT_DIR` (legacy) +Overrides: +- OAuth dir: `CLAWDBOT_OAUTH_DIR` +- Agent dir: `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy) -Legacy OAuth storage is still supported for migration: -- Default: `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`) -- Override: `CLAWDBOT_OAUTH_DIR` - -On first use, Clawdbot auto‑migrates legacy `oauth.json` entries into `auth.json`. +On first use, Clawdbot imports `oauth.json` entries into `auth.json` so the embedded +agent can use them. `oauth.json` remains the source of truth for OAuth refresh. ### `identity` diff --git a/docs/faq.md b/docs/faq.md index 6ec58618f..a6128ac37 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,9 +14,9 @@ Everything lives under `~/.clawdbot/`: | Path | Purpose | |------|---------| | `~/.clawdbot/clawdbot.json` | Main config (JSON5) | -| `~/.clawdbot/agent/auth.json` | OAuth + API key store (Anthropic/OpenAI, etc.) | +| `~/.clawdbot/credentials/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) | +| `~/.clawdbot/agent/auth.json` | API key store | | `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens | -| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth store (auto‑migrated) | | `~/.clawdbot/sessions/` | Conversation history & state | | `~/.clawdbot/sessions/sessions.json` | Session metadata | @@ -118,7 +118,7 @@ They're **separate billing**! An API key does NOT use your subscription. pnpm clawdbot login ``` -**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agent/auth.json` to your server. The auth is just a JSON file. +**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/credentials/oauth.json` to your server. The auth is just a JSON file. ### How are env vars loaded? @@ -148,7 +148,7 @@ Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=1500 OAuth needs the callback to reach the machine running the CLI. Options: -1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agent/auth.json` to the container. +1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/credentials/oauth.json` to the container. 2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server` 3. **Tailscale** — Put both machines on your tailnet. diff --git a/docs/onboarding.md b/docs/onboarding.md index 39edd2278..948d1c2c2 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -19,7 +19,7 @@ This doc describes the intended **first-run onboarding** for Clawdbot. The goal First question: where does the **Gateway** run? -- **Local (this Mac):** onboarding can run OAuth flows and write the Clawdbot auth store locally. +- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally. - **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**. Gateway auth tip: @@ -38,10 +38,10 @@ 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/agent/auth.json` (file mode `0600`, directory mode `0700`) + - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`) -Why this location matters: it’s the Clawdbot-owned auth store (OAuth + API keys). -Clawdbot auto-migrates legacy OAuth tokens from `~/.clawdbot/credentials/oauth.json` (and older pi/Claude locations) into `auth.json` on first use. +Why this location matters: it’s the Clawdbot-owned OAuth store. +Clawdbot also imports `oauth.json` into the agent auth store (`~/.clawdbot/agent/auth.json`) on first use. ### Recommended: OAuth (OpenAI Codex) @@ -49,7 +49,7 @@ The macOS app should: - Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser. - Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible. - If the callback fails, prompt the user to paste the redirect URL or code. -- Store credentials in `~/.clawdbot/agent/auth.json` (same auth store as Anthropic). +- Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic). ### Alternative: API key (instructions only) @@ -148,12 +148,12 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored For now, remote onboarding should: - explain why OAuth isn't shown -- point the user at the credential location (`~/.clawdbot/agent/auth.json`) and the workspace location on the gateway host +- 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/agent/auth.json` with this exact format: +On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format: ```json { @@ -162,7 +162,7 @@ On the gateway host, create `~/.clawdbot/agent/auth.json` with this exact format } ``` -Set permissions: `chmod 600 ~/.clawdbot/agent/auth.json` +Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json` **Note:** Clawdbot auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format. @@ -177,8 +177,8 @@ cat ~/.claude/.credentials.json | jq '{ refresh: .claudeAiOauth.refreshToken, expires: .claudeAiOauth.expiresAt } -}' > ~/.clawdbot/agent/auth.json -chmod 600 ~/.clawdbot/agent/auth.json +}' > ~/.clawdbot/credentials/oauth.json +chmod 600 ~/.clawdbot/credentials/oauth.json ``` | Claude Code field | Clawdbot field | diff --git a/docs/wizard.md b/docs/wizard.md index d4ec67028..ae10f3785 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -52,7 +52,7 @@ It does **not** install or change anything on the remote host. - **API key**: stores the key for you. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Skip**: no auth configured yet. - - OAuth + API keys are stored in `~/.clawdbot/agent/auth.json`. + - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; API keys live in `~/.clawdbot/agent/auth.json`. 3) **Workspace** - Default `~/clawd` (configurable). From ab27b98f7b82aad0b2f3695bcfd64ea08923de6e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:13:21 +0100 Subject: [PATCH 007/110] docs: fix front matter + workspace defaults --- docs/AGENTS.default.md | 14 +++++++------- docs/browser-linux-troubleshooting.md | 5 +++++ docs/onboarding-config-protocol.md | 5 +++++ docs/onboarding.md | 4 ++-- docs/remote-gateway-readme.md | 5 +++++ docs/slack.md | 5 +++++ 6 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/AGENTS.default.md b/docs/AGENTS.default.md index a1044ba0d..cdbb83258 100644 --- a/docs/AGENTS.default.md +++ b/docs/AGENTS.default.md @@ -8,26 +8,26 @@ read_when: ## First run (recommended) -Clawdbot uses a dedicated workspace directory for the agent. Default: `~/.clawdbot/workspace`. +Clawdbot uses a dedicated workspace directory for the agent. Default: `~/clawd` (configurable via `agent.workspace`). 1) Create the workspace (if it doesn’t already exist): ```bash -mkdir -p ~/.clawdbot/workspace +mkdir -p ~/clawd ``` 2) Copy the default workspace templates into the workspace: ```bash -cp docs/templates/AGENTS.md ~/.clawdbot/workspace/AGENTS.md -cp docs/templates/SOUL.md ~/.clawdbot/workspace/SOUL.md -cp docs/templates/TOOLS.md ~/.clawdbot/workspace/TOOLS.md +cp docs/templates/AGENTS.md ~/clawd/AGENTS.md +cp docs/templates/SOUL.md ~/clawd/SOUL.md +cp docs/templates/TOOLS.md ~/clawd/TOOLS.md ``` 3) Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file: ```bash -cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md +cp docs/AGENTS.default.md ~/clawd/AGENTS.md ``` 4) Optional: choose a different workspace by setting `agent.workspace` (supports `~`): @@ -73,7 +73,7 @@ cp docs/AGENTS.default.md ~/.clawdbot/workspace/AGENTS.md If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up. ```bash -cd ~/.clawdbot/workspace +cd ~/clawd git init git add AGENTS.md git commit -m "Add Clawd workspace" diff --git a/docs/browser-linux-troubleshooting.md b/docs/browser-linux-troubleshooting.md index 33643634a..3cbd4dbe1 100644 --- a/docs/browser-linux-troubleshooting.md +++ b/docs/browser-linux-troubleshooting.md @@ -1,3 +1,8 @@ +--- +summary: "Fix Chrome/Chromium CDP startup issues for Clawdbot browser control on Linux" +read_when: "Browser control fails on Linux, especially with snap Chromium" +--- + # Browser Troubleshooting (Linux) ## Problem: "Failed to start Chrome CDP on port 18800" diff --git a/docs/onboarding-config-protocol.md b/docs/onboarding-config-protocol.md index 64da823b6..58eb2fa1e 100644 --- a/docs/onboarding-config-protocol.md +++ b/docs/onboarding-config-protocol.md @@ -1,3 +1,8 @@ +--- +summary: "RPC protocol notes for onboarding wizard and config schema" +read_when: "Changing onboarding wizard steps or config schema endpoints" +--- + # Onboarding + Config Protocol Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI. diff --git a/docs/onboarding.md b/docs/onboarding.md index 948d1c2c2..200fd267e 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -102,7 +102,7 @@ Once setup is complete, the user can switch to the normal chat (`main`) via the 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, +- Workspace is created implicitly (default `~/clawd`, configurable via `agent.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: @@ -131,7 +131,7 @@ The workspace is created automatically as part of agent bootstrap (no dedicated 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 +cd ~/clawd git init git add AGENTS.md git commit -m "Add agent workspace" diff --git a/docs/remote-gateway-readme.md b/docs/remote-gateway-readme.md index 98193a866..039955a6d 100644 --- a/docs/remote-gateway-readme.md +++ b/docs/remote-gateway-readme.md @@ -1,3 +1,8 @@ +--- +summary: "SSH tunnel setup for Clawdbot.app connecting to a remote gateway" +read_when: "Connecting the macOS app to a remote gateway over SSH" +--- + # Running Clawdbot.app with a Remote Gateway Clawdbot.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up. diff --git a/docs/slack.md b/docs/slack.md index 22f6654ba..a42b7cd53 100644 --- a/docs/slack.md +++ b/docs/slack.md @@ -1,3 +1,8 @@ +--- +summary: "Slack socket mode setup and Clawdbot config" +read_when: "Setting up Slack or debugging Slack socket mode" +--- + # Slack (socket mode) ## Setup From 57abcba08a9ca665dd185c0f40ab82121e07e496 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:15:26 +0100 Subject: [PATCH 008/110] docs: add remote gateway and elevated notes --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index 45a97b218..5e8e62203 100644 --- a/README.md +++ b/README.md @@ -146,6 +146,46 @@ WhatsApp / Telegram / Slack / Discord / Signal / iMessage / WebChat - **[Voice Wake](https://docs.clawdbot.com/voicewake) + [Talk Mode](https://docs.clawdbot.com/talk)** — always‑on speech and continuous conversation. - **[Nodes](https://docs.clawdbot.com/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`. +## Tailscale access (Gateway dashboard) + +Clawdbot can auto-configure Tailscale **Serve** (tailnet-only) or **Funnel** (public) while the Gateway stays bound to loopback. Configure `gateway.tailscale.mode`: + +- `off`: no Tailscale automation (default). +- `serve`: tailnet-only HTTPS via `tailscale serve` (uses Tailscale identity headers by default). +- `funnel`: public HTTPS via `tailscale funnel` (requires shared password auth). + +Notes: +- `gateway.bind` must stay `loopback` when Serve/Funnel is enabled (Clawdbot enforces this). +- Serve can be forced to require a password by setting `gateway.auth.mode: "password"` or `gateway.auth.allowTailscale: false`. +- Funnel refuses to start unless `gateway.auth.mode: "password"` is set. +- Optional: `gateway.tailscale.resetOnExit` to undo Serve/Funnel on shutdown. + +Details: [Tailscale guide](https://docs.clawdbot.com/tailscale) · [Web surfaces](https://docs.clawdbot.com/web) + +## Remote Gateway (Linux is great) + +It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed. + +- **Gateway host** runs the bash tool and provider connections by default. +- **Device nodes** run device‑local actions (`system.run`, camera, screen recording, notifications) via `node.invoke`. + +Details: [Remote access](https://docs.clawdbot.com/remote) · [Nodes](https://docs.clawdbot.com/nodes) · [Security](https://docs.clawdbot.com/security) + +## macOS permissions via the Gateway protocol + +The macOS app can run in **node mode** and advertises its capabilities + permission map over the Gateway WebSocket (`node.list` / `node.describe`). Clients can then execute local actions via `node.invoke`: + +- `system.run` runs a local command and returns stdout/stderr/exit code; set `needsScreenRecording: true` to require screen-recording permission (otherwise you’ll get `PERMISSION_MISSING`). +- `system.notify` posts a user notification and fails if notifications are denied. +- `canvas.*`, `camera.*`, `screen.record`, and `location.get` are also routed via `node.invoke` and follow TCC permission status. + +Elevated bash (host permissions) is separate from macOS TCC: + +- Use `/elevated on|off` to toggle per‑session elevated access when enabled + allowlisted. +- Gateway persists the per‑session toggle via `sessions.patch` (WS method) alongside `thinkingLevel`, `verboseLevel`, `model`, `sendPolicy`, and `groupActivation`. + +Details: [Nodes](https://docs.clawdbot.com/nodes) · [macOS app](https://docs.clawdbot.com/macos) · [Gateway protocol](https://docs.clawdbot.com/architecture) + ## Skills registry (ClawdHub) ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed. From 949ea38ef5ea7d745952d5900ccfb07befa853d9 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:17:14 +0100 Subject: [PATCH 009/110] docs: clarify bun + browser enablement --- docs/faq.md | 6 +++--- docs/tools.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index a6128ac37..163a5f51d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -42,10 +42,10 @@ Some features are platform-specific: - **CPU:** 1 core is fine for personal use - **Disk:** ~500MB for Clawdbot + deps, plus space for logs/media -The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. You can also use **Bun** instead of Node for even lower memory footprint: +The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For the CLI, prefer the Node runtime (most stable): ```bash -bun clawdbot gateway +pnpm clawdbot gateway ``` ### How do I install on Linux without Homebrew? @@ -229,7 +229,7 @@ Yes! The terminal QR code login works fine over SSH. For long-running operation: ### bun binary vs Node runtime? Clawdbot can run as: -- **bun binary** — Single executable, easy distribution, auto-restarts via launchd +- **bun binary (macOS app)** — Single executable, easy distribution, auto-restarts via launchd - **Node runtime** (`pnpm clawdbot gateway`) — More stable for WhatsApp If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys). diff --git a/docs/tools.md b/docs/tools.md index 9cbbdc218..d9d87649d 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -73,7 +73,7 @@ Common parameters: - `controlUrl` (defaults from config) - `profile` (optional; defaults to `browser.defaultProfile`) Notes: -- Requires `browser.enabled=true` in `~/.clawdbot/clawdbot.json`. +- Requires `browser.enabled=true` (default is `true`; set `false` to disable). - Uses `browser.controlUrl` unless `controlUrl` is passed explicitly. - All actions accept optional `profile` parameter for multi-instance support. - When `profile` is omitted, uses `browser.defaultProfile` (defaults to "clawd"). From de153a40d0d5a0ef90c50aead8295aa599036792 Mon Sep 17 00:00:00 2001 From: Tobias Bischoff <> Date: Mon, 5 Jan 2026 20:33:34 +0100 Subject: [PATCH 010/110] Onboard: auto-enable systemd lingering on Linux --- docs/gateway.md | 8 ++++++++ docs/setup.md | 12 ++++++++++++ src/commands/systemd-linger.ts | 13 +++++++++++-- src/wizard/onboarding.ts | 21 +++++++++++---------- 4 files changed, 42 insertions(+), 12 deletions(-) diff --git a/docs/gateway.md b/docs/gateway.md index e20badea3..8b53b38fd 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -188,6 +188,14 @@ Then enable the service: systemctl --user enable --now clawdbot-gateway.service ``` +**Alternative (system service)** - for always-on or multi-user servers, you can +install a systemd **system** unit instead of a user unit (no lingering needed). +Create `/etc/systemd/system/clawdbot-gateway.service`, set `User=` and +`WorkingDirectory=`, then enable with: +``` +sudo systemctl enable --now clawdbot-gateway.service +``` + ## Supervision (Windows scheduled task) - Onboarding installs a Scheduled Task named `Clawdbot Gateway` (runs on user logon). - Requires a logged-in user session; for headless setups use a system service or a task configured to run without a logged-in user (not shipped). diff --git a/docs/setup.md b/docs/setup.md index e8d230c5c..5a580df8f 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -109,6 +109,18 @@ pnpm clawdbot health - Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo. - Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`. +## Linux (systemd user service) + +Linux installs use a systemd **user** service. By default, systemd stops user +services on logout/idle, which kills the Gateway. Enable lingering: + +```bash +sudo loginctl enable-linger $USER +``` + +For always-on or multi-user servers, consider a **system** service instead of a +user service (no lingering needed). See `docs/gateway.md` for the systemd notes. + ## Related docs - `docs/gateway.md` (Gateway runbook; flags, supervision, ports) diff --git a/src/commands/systemd-linger.ts b/src/commands/systemd-linger.ts index c1043e73e..5f6af2abb 100644 --- a/src/commands/systemd-linger.ts +++ b/src/commands/systemd-linger.ts @@ -42,8 +42,8 @@ export async function ensureSystemdUserLingerInteractive(params: { params.reason ?? "Systemd user services stop when you log out or go idle, which kills the Gateway."; const actionNote = params.requireConfirm - ? "We can enable lingering now (needs sudo; writes /var/lib/systemd/linger)." - : "Enabling lingering now (needs sudo; writes /var/lib/systemd/linger)."; + ? "We can enable lingering now (may require sudo; writes /var/lib/systemd/linger)." + : "Enabling lingering now (may require sudo; writes /var/lib/systemd/linger)."; await prompter.note(`${reason}\n${actionNote}`, title); if (params.requireConfirm && prompter.confirm) { @@ -60,6 +60,15 @@ export async function ensureSystemdUserLingerInteractive(params: { } } + const resultNoSudo = await enableSystemdUserLinger({ + env, + user: status.user, + }); + if (resultNoSudo.ok) { + await prompter.note(`Enabled systemd lingering for ${status.user}.`, title); + return; + } + const result = await enableSystemdUserLinger({ env, user: status.user, diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index 576a5a466..9ad0ef2f7 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -489,6 +489,17 @@ export async function runOnboardingWizard( nextConfig = applyWizardMetadata(nextConfig, { command: "onboard", mode }); await writeConfigFile(nextConfig); + await ensureSystemdUserLingerInteractive({ + runtime, + prompter: { + confirm: prompter.confirm, + note: prompter.note, + }, + reason: + "Linux installs use a systemd user service by default. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.", + requireConfirm: false, + }); + const installDaemon = await prompter.confirm({ message: "Install Gateway daemon (recommended)", initialValue: true, @@ -539,16 +550,6 @@ export async function runOnboardingWizard( }); } - await ensureSystemdUserLingerInteractive({ - runtime, - prompter: { - confirm: prompter.confirm, - note: prompter.note, - }, - reason: - "Linux installs use a systemd user service. Without lingering, systemd stops the user session on logout/idle and kills the Gateway.", - requireConfirm: true, - }); } await sleep(1500); From dbea8eb69efc50294530fcdfcf7acc5b9bc0f28e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:19:49 +0000 Subject: [PATCH 011/110] docs: clarify lingering onboarding notes --- CHANGELOG.md | 2 +- docs/faq.md | 2 +- docs/gateway.md | 7 ++++--- docs/setup.md | 3 ++- docs/wizard.md | 4 ++-- 5 files changed, 10 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14a727498..ee10954a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. -- Linux: prompt to enable systemd lingering when installing/restarting the gateway user service (prevents logout/idle shutdowns). +- Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. - macOS: prefer gateway config reads/writes in local mode (fall back to disk if the gateway is unavailable). - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`. diff --git a/docs/faq.md b/docs/faq.md index 163a5f51d..d59caef6a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -471,7 +471,7 @@ codex --full-auto "debug why clawdbot gateway won't start" Linux installs use a systemd **user** service. By default, systemd stops user services on logout/idle, which kills the Gateway. -Fix: +Onboarding attempts to enable lingering; if it’s still off, run: ```bash sudo loginctl enable-linger $USER ``` diff --git a/docs/gateway.md b/docs/gateway.md index 8b53b38fd..f278f4756 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -182,7 +182,7 @@ Enable lingering (required so the user service survives logout/idle): ``` sudo loginctl enable-linger youruser ``` -Requires sudo (writes `/var/lib/systemd/linger`). +Onboarding runs this on Linux (may prompt for sudo; writes `/var/lib/systemd/linger`). Then enable the service: ``` systemctl --user enable --now clawdbot-gateway.service @@ -190,9 +190,10 @@ systemctl --user enable --now clawdbot-gateway.service **Alternative (system service)** - for always-on or multi-user servers, you can install a systemd **system** unit instead of a user unit (no lingering needed). -Create `/etc/systemd/system/clawdbot-gateway.service`, set `User=` and -`WorkingDirectory=`, then enable with: +Create `/etc/systemd/system/clawdbot-gateway.service` (copy the unit above, +switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then: ``` +sudo systemctl daemon-reload sudo systemctl enable --now clawdbot-gateway.service ``` diff --git a/docs/setup.md b/docs/setup.md index 5a580df8f..d053da7e3 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -112,7 +112,8 @@ pnpm clawdbot health ## Linux (systemd user service) Linux installs use a systemd **user** service. By default, systemd stops user -services on logout/idle, which kills the Gateway. Enable lingering: +services on logout/idle, which kills the Gateway. Onboarding attempts to enable +lingering for you (may prompt for sudo). If it’s still off, run: ```bash sudo loginctl enable-linger $USER diff --git a/docs/wizard.md b/docs/wizard.md index ae10f3785..1682cf9ec 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -74,8 +74,8 @@ It does **not** install or change anything on the remote host. - macOS: LaunchAgent - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped). - Linux: systemd user unit - - Wizard enables lingering via `loginctl enable-linger ` so the Gateway stays up after logout. - - Requires sudo (writes `/var/lib/systemd/linger`). + - Wizard attempts to enable lingering via `loginctl enable-linger ` so the Gateway stays up after logout. + - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first. - Windows: Scheduled Task - Runs on user logon; headless/system services are not configured by default. From 1b6c8178aeb824bb98ab4d431e1e97ed82828113 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 21:21:53 +0000 Subject: [PATCH 012/110] style: apply biome formatting --- src/wizard/onboarding.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index 9ad0ef2f7..38e126e9b 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -549,7 +549,6 @@ export async function runOnboardingWizard( environment, }); } - } await sleep(1500); From b5c2c724dd6d303052c92c341fcae92721baaf0f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:23:14 +0100 Subject: [PATCH 013/110] docs: clarify sessions tools --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 5e8e62203..8f4cdd718 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ If you want a personal, single-user assistant that feels local, fast, and always Website: [https://clawdbot.com](https://clawdbot.com) · Docs: [https://docs.clawdbot.com](https://docs.clawdbot.com/) · FAQ: [https://docs.clawdbot.com/faq](https://docs.clawdbot.com/faq) · Wizard: [https://docs.clawdbot.com/wizard](https://docs.clawdbot.com/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawdbot.com/docker](https://docs.clawdbot.com/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**. +Works with npm, pnpm, or bun. **Subscriptions (OAuth):** - **Anthropic** (Claude Pro/Max) @@ -186,6 +187,14 @@ Elevated bash (host permissions) is separate from macOS TCC: Details: [Nodes](https://docs.clawdbot.com/nodes) · [macOS app](https://docs.clawdbot.com/macos) · [Gateway protocol](https://docs.clawdbot.com/architecture) +## Agent to Agent (sessions_* tools) + +- `sessions_list` — discover active sessions (agents) and their metadata. +- `sessions_history` — fetch transcript logs for a session. +- `sessions_send` — message another session; optional reply‑back ping‑pong + announce step (`REPLY_SKIP`, `ANNOUNCE_SKIP`). + +Details: [Session tools](https://docs.clawdbot.com/session-tool) + ## Skills registry (ClawdHub) ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed. From d787316e656a7803db4a382009c30a79f53fd5f0 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:24:31 +0100 Subject: [PATCH 014/110] docs: prune refactor notes + update README --- README.md | 3 +- docs/faq.md | 6 +- docs/hubs.md | 10 - docs/refactor/agent-loop.md | 65 ------- .../browser-control-simplification.md | 58 ------ docs/refactor/canvas-a2ui.md | 93 ---------- docs/refactor/cli-unification.md | 64 ------- docs/refactor/gateway-client.md | 31 ---- docs/refactor/gateway.md | 99 ---------- docs/refactor/new-arch.md | 171 ------------------ docs/refactor/tui.md | 26 --- docs/refactor/web-gateway-troubleshooting.md | 37 ---- docs/refactor/webagent-session.md | 44 ----- docs/troubleshooting.md | 4 +- docs/whatsapp.md | 2 +- 15 files changed, 8 insertions(+), 705 deletions(-) delete mode 100644 docs/refactor/agent-loop.md delete mode 100644 docs/refactor/browser-control-simplification.md delete mode 100644 docs/refactor/canvas-a2ui.md delete mode 100644 docs/refactor/cli-unification.md delete mode 100644 docs/refactor/gateway-client.md delete mode 100644 docs/refactor/gateway.md delete mode 100644 docs/refactor/new-arch.md delete mode 100644 docs/refactor/tui.md delete mode 100644 docs/refactor/web-gateway-troubleshooting.md delete mode 100644 docs/refactor/webagent-session.md diff --git a/README.md b/README.md index 8f4cdd718..f9b26e780 100644 --- a/README.md +++ b/README.md @@ -220,6 +220,7 @@ If you plan to build/run companion apps, initialize submodules first: ```bash git submodule update --init --recursive +./scripts/restart-mac.sh ``` ### macOS (Clawdbot.app) (optional) @@ -229,7 +230,7 @@ git submodule update --init --recursive - WebChat + debug tools. - Remote gateway control over SSH. -Build/run: `./scripts/restart-mac.sh` (packages + launches). +Note: signed builds required for macOS permissions to stick across rebuilds (see `docs/mac/permissions.md`). ### iOS node (optional) diff --git a/docs/faq.md b/docs/faq.md index d59caef6a..956cf5e3c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -78,7 +78,7 @@ This creates `~/.clawdbot/clawdbot.json` with your API keys, workspace path, and cp -r ~/.clawdbot ~/.clawdbot-backup # Remove config and credentials -rm -rf ~/.clawdbot +trash ~/.clawdbot # Re-run onboarding pnpm clawdbot onboard @@ -531,10 +531,10 @@ sudo systemctl disable --now clawdbot pkill -f "clawdbot" # Remove data -rm -rf ~/.clawdbot +trash ~/.clawdbot # Remove repo and re-clone -rm -rf ~/clawdbot +trash ~/clawdbot git clone https://github.com/clawdbot/clawdbot.git cd clawdbot && pnpm install && pnpm build pnpm clawdbot onboard diff --git a/docs/hubs.md b/docs/hubs.md index 73e92442f..cd9a9e16d 100644 --- a/docs/hubs.md +++ b/docs/hubs.md @@ -140,16 +140,6 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Onboarding config protocol](./onboarding-config-protocol.md) - [Research: memory](./research/memory.md) - [Proposal: model config](./proposals/model-config.md) -- [Refactor: agent loop](./refactor/agent-loop.md) -- [Refactor: browser control simplification](./refactor/browser-control-simplification.md) -- [Refactor: Canvas A2UI](./refactor/canvas-a2ui.md) -- [Refactor: CLI unification](./refactor/cli-unification.md) -- [Refactor: gateway client](./refactor/gateway-client.md) -- [Refactor: gateway](./refactor/gateway.md) -- [Refactor: new arch](./refactor/new-arch.md) -- [Refactor: TUI](./refactor/tui.md) -- [Refactor: web gateway troubleshooting](./refactor/web-gateway-troubleshooting.md) -- [Refactor: webagent session](./refactor/webagent-session.md) ## Testing + release diff --git a/docs/refactor/agent-loop.md b/docs/refactor/agent-loop.md deleted file mode 100644 index 6693d6086..000000000 --- a/docs/refactor/agent-loop.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -summary: "Refactor plan: unify agent lifecycle events and wait semantics" -read_when: - - Refactoring agent lifecycle events or wait behavior ---- -# Refactor: Agent Loop - -Goal: align Clawdis run lifecycle with pi/mom semantics, remove ambiguity between "job" and "agent_end". - -## Problem -- Two lifecycles today: - - `job` (gateway wrapper) => used by `agent.wait` + chat final - - pi-agent `agent_end` (inner loop) => only logged -- This can finalize early (job done) while late assistant deltas still arrive. -- `afterMs` and timeouts can cause false timeouts in `agent.wait`. - -## Reference (mom) -- Single lifecycle: `agent_start`/`agent_end` from pi-agent-core event stream. -- `waitForIdle()` resolves on `agent_end`. -- No separate job state exposed to clients. - -## Proposed refactor (breaking allowed) -1) Replace public `job` stream with `lifecycle` stream - - `stream: "lifecycle"` - - `data: { phase: "start" | "end" | "error", startedAt, endedAt, error? }` -2) `agent.wait` waits on lifecycle end/error only - - remove `afterMs` - - return `{ runId, status, startedAt, endedAt, error? }` -3) Chat final emitted on lifecycle end only - - deltas still from `assistant` stream -4) Centralize run registry - - one map keyed by runId: sessionKey, startedAt, lastSeq, bufferedText - - clear on lifecycle end - -## Implementation outline -- `src/agents/pi-embedded-subscribe.ts` - - emit lifecycle start/end events (translate pi `agent_start`/`agent_end`) -- `src/infra/agent-events.ts` - - add `"lifecycle"` to stream type -- `src/gateway/protocol/schema.ts` - - update AgentEvent schema; update AgentWait params (remove afterMs, add status) -- `src/gateway/server-methods/agent-job.ts` - - rename to `agent-wait.ts` or similar; wait on lifecycle end/error -- `src/gateway/server-chat.ts` - - finalize on lifecycle end (not job) -- `src/commands/agent.ts` - - stop emitting `job` externally (keep internal log if needed) - -## Migration notes (breaking) -- Update all callers of `agent.wait` to new response shape. -- Update tests that expect `timeout` based on job events. -- If any UI relies on job state, map lifecycle instead. - -## Risks -- If lifecycle events are dropped, wait/chat could hang; add timeout in `agent.wait` to fail fast. -- Late deltas after lifecycle end should be ignored; keep seq tracking + drop. - -## Acceptance -- One lifecycle visible to clients. -- `agent.wait` resolves when agent loop ends, not wrapper completion. -- Chat final never emits before last assistant delta. - -## Rollout (if we wanted safety) -- Gate with config flag `agent.lifecycleMode = "legacy"|"refactor"`. -- Remove legacy after one release. diff --git a/docs/refactor/browser-control-simplification.md b/docs/refactor/browser-control-simplification.md deleted file mode 100644 index 834ac03b8..000000000 --- a/docs/refactor/browser-control-simplification.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -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. diff --git a/docs/refactor/canvas-a2ui.md b/docs/refactor/canvas-a2ui.md deleted file mode 100644 index bca37c1d5..000000000 --- a/docs/refactor/canvas-a2ui.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -summary: "Refactor: host A2UI from the Gateway (HTTP), remove app-bundled shells" -read_when: - - Refactoring Canvas/A2UI ownership or assets - - Moving UI rendering from native bundles into the Gateway - - Updating node canvas navigation or A2UI command flows ---- - -# Canvas / A2UI — HTTP-hosted from Gateway - -Status: Implemented · Date: 2025-12-20 - -## Goal -- Make the **Gateway (TypeScript)** the single owner of A2UI. -- Remove **app-bundled A2UI shells** (macOS, iOS, Android). -- A2UI renders only when the **Gateway is reachable** (acceptable failure mode). - -## Decision -All A2UI HTML/JS assets are **served by the Gateway canvas host** on -`canvasHost.port` (default `18793`), bound to the **bridge interface**. Nodes -(mac/iOS/Android) **navigate to the advertised `canvasHostUrl`** before applying -A2UI messages. No local custom-scheme or bundled fallback remains. - -## Why -- One source of truth (TS) for A2UI rendering. -- Faster iteration (no app release required for A2UI updates). -- iOS/Android/macOS all behave identically. - -## New behavior (summary) -1) `canvas.a2ui.*` on any node: - - Ensure Canvas is visible. - - Navigate the node WebView to the Gateway A2UI URL. - - Apply/reset A2UI messages once the page is ready. -2) If Gateway is unreachable: - - A2UI fails with an explicit error (no fallback). - -## Gateway changes - -### Serve A2UI assets -Add A2UI HTML/JS to the Gateway Canvas host (standalone HTTP server on -`canvasHost.port`), e.g.: - -``` -/__clawdbot__/a2ui/ -> index.html -/__clawdbot__/a2ui/a2ui.bundle.js -> bundled A2UI runtime -``` - -Serve Canvas files at `/__clawdbot__/canvas/` and A2UI at `/__clawdbot__/a2ui/`. -Use the shared Canvas host handler (`src/canvas-host/server.ts`) to serve these -assets and inject the action bridge + live reload if desired. - -### Canonical host URL -The Gateway exposes a **canonical** `canvasHostUrl` in hello/bridge payloads -so nodes don’t need to guess. - -## Node changes (mac/iOS/Android) - -### Navigation path -Before applying A2UI: -- Navigate to `${canvasHostUrl}/__clawdbot__/a2ui/`. - -### Remove bundled shells -Remove all fallback logic that serves A2UI from local bundles: -- macOS: remove custom-scheme fallback for `/__clawdbot__/a2ui/` -- iOS/Android: remove packaged A2UI assets and "default scaffold" assumptions - -### Error behavior -If `canvasHostUrl` is missing or unreachable: -- `canvas.a2ui.push/reset` returns a clear error: - - `A2UI_HOST_UNAVAILABLE` or `A2UI_HOST_NOT_CONFIGURED` - -## Security / transport -- For non-TLS Gateway URLs (http), iOS/Android will need ATS exceptions. -- For TLS (https), prefer WSS + HTTPS with a valid cert. - -## Implementation plan -1) Gateway - - Add A2UI assets under `src/canvas-host/`. - - Serve them at `/__clawdbot__/a2ui/` (align with existing naming). - - Serve Canvas files at `/__clawdbot__/canvas/` on `canvasHost.port`. - - Expose `canvasHostUrl` in handshake + bridge hello payloads. -2) Node runtimes - - Update `canvas.a2ui.*` to navigate to `canvasHostUrl`. - - Remove custom-scheme A2UI fallback and bundled assets. -3) Tests - - TS: verify `/__clawdbot__/a2ui/` responds with HTML + JS. - - Node: verify A2UI fails when host is unreachable and succeeds when reachable. -4) Docs - - Update `docs/mac/canvas.md`, `docs/ios.md`, `docs/android.md` - to remove local fallback assumptions and point to gateway-hosted A2UI. - -## Notes -- iOS/Android may still require ATS exceptions for `http://` canvas hosts. diff --git a/docs/refactor/cli-unification.md b/docs/refactor/cli-unification.md deleted file mode 100644 index 4f094f0d4..000000000 --- a/docs/refactor/cli-unification.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -summary: "Refactor: unify on the clawdbot CLI + gateway-first control; retire clawdbot-mac" -read_when: - - Removing or replacing the macOS CLI helper - - Adding node capabilities or permissions metadata - - Updating macOS app packaging/install flows ---- - -# CLI unification (clawdbot-only) - -Status: active refactor · Date: 2025-12-20 - -## Goals -- **Single CLI**: use `clawdbot` for all automation (local + remote). Retire `clawdbot-mac`. -- **Gateway-first**: all agent actions flow through the Gateway WebSocket + node.invoke. -- **Permission awareness**: nodes advertise permission state so the agent can decide what to run. -- **No duplicate paths**: remove macOS control socket + Swift CLI surface. - -## Non-goals -- Keep legacy `clawdbot-mac` compatibility. -- Support agent control when no Gateway is running. - -## Key decisions -1) **No Gateway → no control** - - If the macOS app is running but the Gateway is not, remote commands (canvas/run/notify) are unavailable. - - This is acceptable to keep one network surface. - -2) **Remove ensure-permissions CLI** - - Permissions are **advertised by the node** (e.g., screen recording granted/denied). - - Commands will still fail with explicit errors when permissions are missing. - -3) **Mac app installs/symlinks `clawdbot`** - - Bundle a standalone `clawdbot` binary in the app (bun-compiled). - - Install/symlink that binary to `/usr/local/bin/clawdbot` and `/opt/homebrew/bin/clawdbot`. - - No `clawdbot-mac` helper remains. - -4) **Canvas parity across node types** - - Use `node.invoke` commands consistently (`canvas.present|navigate|eval|snapshot|a2ui.*`). - - The TS CLI provides convenient wrappers so agents never have to craft raw `node.invoke` calls. - -## Command surface (new/normalized) -- `clawdbot nodes invoke --command canvas.*` remains valid. -- New CLI wrappers for convenience: - - `clawdbot canvas present|navigate|eval|snapshot|a2ui push|a2ui reset` -- New node commands (mac-only initially): - - `system.run` (shell execution) - - `system.notify` (local notifications) - -## Permission advertising -- Node hello/pairing includes a `permissions` map: - - Example keys: `screenRecording`, `accessibility`, `microphone`, `notifications`, `speechRecognition`. - - Values: boolean (`true` = granted, `false` = not granted). -- Gateway `node.list` / `node.describe` surfaces the map. - -## Gateway mode + config -- Gateways should only auto-start when explicitly configured for **local** mode. -- When config is missing or explicitly remote, `clawdbot gateway` should refuse to auto-start unless forced. - -## Implementation checklist -- Add bun-compiled `clawdbot` binary to macOS app bundle; update codesign + install flows. -- Remove `ClawdbotCLI` target and control socket server. -- Add node command(s) for `system.run` and `system.notify` on macOS. -- Add permission map to node hello/pairing + gateway responses. -- Update TS CLI + docs to use `clawdbot` only. diff --git a/docs/refactor/gateway-client.md b/docs/refactor/gateway-client.md deleted file mode 100644 index fb9e5c6a9..000000000 --- a/docs/refactor/gateway-client.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -summary: "Refactor notes for the macOS gateway client typed API migration (Dec 2025)." -read_when: - - Refactoring macOS gateway client or typed gateway methods - - Auditing agent routing or channel semantics ---- - -# Gateway Client Refactor (Dec 2025) - -Goal: remove stringly-typed gateway calls from the macOS app, centralize routing/channel semantics, and improve error handling. - -## Progress - -- [x] Fold legacy “AgentRPC” into `GatewayConnection` (single layer; no separate client object). -- [x] Typed gateway API: `GatewayConnection.Method` + `requestDecoded/requestVoid` + typed helpers (status/agent/chat/cron/etc). -- [x] Centralize agent routing/channel semantics via `GatewayAgentChannel` + `GatewayAgentInvocation`. -- [x] Improve gateway error model (structured `GatewayResponseError` + decoding errors include method). -- [x] Migrate mac call sites to typed helpers (leave only intentionally dynamic forwarding paths). -- [x] Convert remaining UI raw channel strings to `GatewayAgentChannel` (Cron editor). -- [x] Cleanup naming: rename remaining tests/docs that still reference “RPC/AgentRPC”. - -### Notes - -- Intentionally string-based: - - `BridgeServer` dynamic request forwarding (method is data-driven). - - `ControlChannel` request wrapper (generic escape hatch). - -## Notes / Non-goals - -- No functional behavior changes intended (beyond better errors and removing “magic strings”). -- Keep changes incremental: introduce typed APIs first, then migrate call sites, then remove old helpers. diff --git a/docs/refactor/gateway.md b/docs/refactor/gateway.md deleted file mode 100644 index 2d55c8cf6..000000000 --- a/docs/refactor/gateway.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -summary: "Refactor notes for the macOS gateway client: single shared websocket + follow-ups" -read_when: - - Investigating duplicate/stale Gateway WS connections - - Refactoring macOS gateway client architecture - - Debugging noisy reconnect storms on gateway restart ---- -# Gateway Refactor Notes (macOS client) - -Last updated: 2025-12-12 - -This document captures the rationale and outcome of the macOS app’s Gateway client refactor: **one shared websocket connection per app process**, with an in-process event bus for server push frames. - -Related docs: -- `docs/refactor/new-arch.md` (overall gateway protocol/server plan) -- `docs/gateway.md` (gateway operations/runbook) -- `docs/presence.md` (presence semantics and dedupe) -- `docs/mac/webchat.md` (WebChat surfaces and debugging) - ---- - -## Background: what was wrong - -Symptoms: -- Restarting the gateway produced a *storm* of reconnects/log spam (`gateway/ws in connect`, `hello`, `hello-ok`) and elevated `clients=` counts. -- Even with “one panel open”, the mac app could hold tens of websocket connections to `ws://127.0.0.1:18789`. - -Root cause (historical bug): -- The mac app was repeatedly “reconfiguring” a gateway client on a timer (via health polling), creating a new websocket owner each time. -- Old websocket owners were not fully torn down and could keep watchdog/tick tasks alive, leading to **connection accumulation** over time. - ---- - -## What changed - -- **One socket owner:** `GatewayConnection.shared` is the only supported entry point for gateway RPC. -- **No global notifications:** server push frames are delivered via `GatewayConnection.shared.subscribe(...) -> AsyncStream` (no `NotificationCenter` fan-out). -- **No tunnel side effects:** `GatewayConnection` does not create/ensure SSH tunnels in remote mode; it consumes the already-established forwarded port. - ---- - -## Current architecture (as of 2025-12-12) - -Goal: enforce the invariant **“one gateway websocket per app process (per effective config)”**. - -Key elements: -- `GatewayConnection.shared` owns the one websocket and is the *only* supported entry point for app code that needs gateway RPC. -- Consumers (e.g. Control UI, agent invocations, SwiftUI WebChat) call `GatewayConnection.shared.request(...)` and do not create their own sockets. -- If the effective connection config changes (local ↔ remote tunnel port, token change), `GatewayConnection` replaces the underlying connection. -- The transport (`GatewayChannelActor`) is an internal detail and forwards push frames back into `GatewayConnection`. -- Server-push frames are delivered via `GatewayConnection.shared.subscribe(...) -> AsyncStream` (in-process event bus). - -Notes: -- Remote mode requires an SSH control tunnel. `GatewayConnection` **does not** start tunnels; it consumes the already-established forwarded port (owned by `ConnectionModeCoordinator` / `RemoteTunnelManager`). - ---- - -## Design constraints / principles - -- **Single ownership:** Exactly one component owns the actual socket and reconnect policy. -- **Explicit config changes:** Recreate/reconnect only when config changes, not as a side effect of periodic work. -- **No implicit fan-out sockets:** Adding new UI features must not accidentally add new persistent gateway connections. -- **Testable seams:** Connection config and websocket session creation should be overridable in tests. - ---- - -## Status / remaining work - -- ✅ One shared websocket per app process (per config) -- ✅ Event streaming moved into `GatewayConnection` (`AsyncStream`) and replays latest snapshot to new subscribers -- ✅ `NotificationCenter` removed for in-process gateway events (ControlChannel / Instances / WebChatSwiftUI) -- ✅ Remote tunnel lifecycle is not started implicitly by random RPC calls -- ✅ Payload decoding helpers extracted so UI adapters stay thin -- ✅ Dedicated resolved-endpoint publisher for remote mode (`GatewayEndpointStore`) - ---- - -## Testing strategy (what we want to cover) - -Minimum invariants: -- Repeated requests under the same config do **not** create additional websocket tasks. -- Concurrent requests still create **exactly one** websocket and reuse it. -- Shutdown prevents any reconnect loop after failures. -- Config changes (token / endpoint) cancel the old socket and reconnect once. - -Nice-to-have integration coverage: -- Multiple “consumers” (Control UI + agent invocations + SwiftUI WebChat) all call through the shared connection and still produce only one websocket. - -Additional coverage added (macOS): -- Subscribing after connect replays the latest snapshot. -- Sequence gaps emit an explicit `GatewayPush.seqGap(...)` before the corresponding event. - ---- - -## Debug notes (operational) - -When diagnosing “too many connections”: -- Prefer counting actual TCP connections on port 18789 and grouping by PID to see which process is holding sockets. -- Gateway `--verbose` prints *every* connect/hello and event broadcast; use it only when needed and filter output if you’re just sanity-checking. diff --git a/docs/refactor/new-arch.md b/docs/refactor/new-arch.md deleted file mode 100644 index 27371b4b3..000000000 --- a/docs/refactor/new-arch.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -summary: "Implementation plan for the new gateway architecture and protocol" -read_when: - - Executing the gateway refactor ---- -# New Gateway Architecture – Implementation Plan (detailed) - -Last updated: 2025-12-09 - -Goal: replace legacy gateway/stdin/TCP control with a single WebSocket Gateway, typed protocol, and first-frame snapshot. No backward compatibility. - ---- - -## Phase 0 — Foundations -- **Naming**: CLI subcommand `clawdbot gateway`; internal namespace `Gateway`. -- **Protocol folder**: create `protocol/` for schemas and build artifacts. ✅ `src/gateway/protocol`. -- **Schema tooling**: - - Prefer **TypeBox** (or ArkType) as source-of-truth types. ✅ TypeBox in `schema.ts`. - - `pnpm protocol:gen`: emits JSON Schema (`dist/protocol.schema.json`). ✅ - - `pnpm protocol:gen:swift`: generates Swift `Codable` models (`apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift`). ✅ - - AJV compile step for server validators. ✅ -- **CI**: add a job that fails if schema or generated Swift is stale. ✅ `pnpm protocol:check` (runs gen + git diff). - -## Phase 1 — Protocol specification -- Frames (WS text JSON, all with explicit `type`): - - `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{name,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId}, caps, auth:{token?}, locale?, userAgent?}}` - - `res {type:"res", id, ok:true, payload: hello-ok }` (or `ok:false` then close) - - `hello-ok {type:"hello-ok", protocol:, server:{version,commit,host,connId}, features:{methods,events}, snapshot:{presence[], health, stateVersion:{presence,health}, uptimeMs}, policy:{maxPayload, maxBufferedBytes, tickIntervalMs}}` - - `req {type:"req", id, method, params?}` - - `res {type:"res", id, ok, payload?, error?}` where `error` = `{code,message,details?,retryable?,retryAfterMs?}` - - `event {type:"event", event, payload, seq?, stateVersion?}` (presence/tick/shutdown/agent) - - `close` (standard WS close codes; policy uses 1008 for slow consumer/unauthorized, 1012/1001 for restart) -- Payload types: - - `PresenceEntry {host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId?}` - - `HealthSnapshot` (match existing `clawdbot health --json` fields) - - `AgentEvent` (streamed tool/output; `{runId, seq, stream, data, ts}`) - - `TickEvent {ts}` - - `ShutdownEvent {reason, restartExpectedMs?}` - - Error codes: `NOT_LINKED`, `AGENT_TIMEOUT`, `INVALID_REQUEST`, `UNAVAILABLE`. -- Error shape: `{code, message, details?, retryable?, retryAfterMs?}` -- Rules: - - First frame must be `req` with `method:"connect"`; otherwise close. Add handshake timeout (e.g., 3s) for silent clients. - - Negotiate protocol: server picks within `[minProtocol,maxProtocol]`; if none, reply `res ok:false` and close. - - Protocol version bump on breaking changes; `hello-ok` must include `minClient` when needed. - - `stateVersion` increments for presence/health to drop stale deltas. - - Stable IDs: client sends `instanceId`; server issues per-connection `connId` in `hello-ok`; presence entries may include `instanceId` to dedupe reconnects. - - Token-based auth: bearer token in `auth.token`; required except for loopback development. - - Presence is primarily connection-derived; client may add hints (e.g., lastInputSeconds); entries expire via TTL to keep the map bounded (e.g., 5m TTL, max 200 entries). - - Idempotency keys: required for `send` and `agent` to safely retry after disconnects. - - Size limits: bound first-frame size by `maxPayload`; reject early if exceeded. - - Close on any non-JSON or wrong `type` before connect. - - Per-op idempotency keys: client SHOULD supply an explicit key per `send`/`agent`; if omitted, server may derive a scoped key from `instanceId+connId`, but explicit keys are safer across reconnects. - - Locale/userAgent are informational; server may log them for analytics but must not rely on them for access control. - -## Phase 2 — Gateway WebSocket server -- New module `src/gateway/server.ts`: - - Bind 127.0.0.1:18789 (configurable). - - On connect: validate `connect` params, send snapshot payload, start event pump. - - Per-connection queues with backpressure (bounded; drop oldest non-critical). - - WS-level caps: set `maxPayload` to cap frame size before JSON parse. - - Emit `tick` every N seconds when idle (or WS ping/pong if adequate). - - Emit `shutdown` before exit; then close sockets. -- Methods implemented: - - `health`, `status`, `system-presence`, `system-event`, `send`, `agent`. - - Optional: `set-heartbeats` removed/renamed if heartbeat concept is retired. -- Events implemented: - - `agent`, `presence` (deltas, with `stateVersion`), `tick`, `shutdown`. - - All events include `seq` for loss/out-of-order detection. -- Logging: structured logs on connect/close/error; include client fingerprint. -- Slow consumer policy: - - Per-connection outbound queue limit (bytes/messages). If exceeded, drop non-critical events (presence/tick) or close with a policy violation / retryable code; clients reconnect with backoff. -- Handshake edge cases: - - Close on handshake timeout. - - Close on over-limit first frame (maxPayload). - - Close immediately on non-JSON or wrong `type` before connect. - - Default guardrails: `maxPayload` ~512 KB, handshake timeout ~3 s, outbound buffered amount cap ~1.5 MB (tune as you implement). -- Dedupe cache: bound TTL (~5m) and max size (~1000 entries); evict oldest first (LRU) to prevent memory growth. - -## Phase 3 — Gateway CLI entrypoint -- Add `clawdbot gateway` command in CLI program: - - Reads config (port, WS options). - - Foreground process; exit non-zero on fatal errors. - - Flags: `--port`, `--no-tick` (optional), `--log-json` (optional). -- System supervision docs for launchd/systemd (see `gateway.md`). - -## Phase 4 — Presence/health snapshot & stateVersion -- `hello-ok.snapshot` includes: - - `presence[]` (current list) - - `health` (full snapshot) - - `stateVersion {presence:int, health:int}` - - `uptimeMs` - - `policy {maxPayload, maxBufferedBytes, tickIntervalMs}` -- Emit `presence` deltas with updated `stateVersion.presence`. -- Emit `tick` to indicate liveness when no other events occur. -- Keep `health` method for manual refresh; not required after connect. - - Presence expiry: prune entries older than TTL; enforce a max map size; include `stateVersion` in presence events. - -## Phase 5 — Clients migration -- **macOS app**: - - Replace stdio/SSH RPC with WS client (tunneled via SSH/Tailscale for remote). ✅ GatewayConnection/ControlChannel now use Gateway WS. - - Implement handshake, snapshot hydration, subscriptions to `presence`, `tick`, `agent`, `shutdown`. ✅ snapshot + presence events broadcast to InstancesStore; agent events still to wire to UI if desired. - - Remove immediate `health/system-presence` fetch on connect. ✅ presence hydrated from snapshot; periodic refresh kept as fallback. - - Handle connect failures (`res ok:false`) and retry with backoff if version/token mismatched. ✅ macOS GatewayChannel reconnects with exponential backoff. -- **CLI**: -- Add lightweight WS client helper for `status/health/send/agent` when Gateway is up. ✅ `gateway` subcommands use the Gateway over WS. - - Consider a “local only” flag to avoid accidental remote connects. (optional; not needed with tunnel-first model.) -- **WebChat backend**: - - Single WS to Gateway; seed UI from snapshot; forward `presence/tick/agent` to browser. ✅ implemented via the WebChat gateway client in `webchat/server.ts`. - - Fail fast if handshake fails; no fallback transports. ✅ (webchat returns gateway unavailable) - -## Phase 6 — Send/agent path hardening -- Ensure only the Gateway can open Baileys; no IPC fallback. -- `send` executes in-process; respond with explicit result/error, not via heartbeat. -- `agent` spawns Pi; respond quickly with `{runId,status:"accepted"}` (ack); stream `event:agent {runId, seq, stream, data, ts}`; final `res:agent {runId, status:"ok"|"error", summary}` completes request (idempotent via key). -- Idempotency: side-effecting methods (`send`, `agent`) accept an idempotency key; keep a short-lived dedupe cache to avoid double-send on client retries. Client retry flow: on timeout/close, retry with same key; Gateway returns cached result when available; cache TTL ~5m and bounded. -- Agent stream ordering: enforce monotonic `seq` per runId; if gap detected by server, terminate stream with error; if detected by client, issue a retry with same idempotency key. - - Send response shape: `{messageId?, toJid?, error?}` and always include `runId` when available for traceability. - -## Phase 7 — Keepalive and shutdown semantics -- Keepalive: `tick` events (or WS ping/pong) at fixed interval; clients treat missing ticks as disconnect and reconnect. -- Shutdown: send `event:shutdown {reason, restartExpectedMs?}` then close sockets; clients auto-reconnect. -- Restart semantics: close sockets with a standard retryable close code; on reconnect, `hello-ok` snapshot must be sufficient to rebuild UI without event replay. - - Use a standard close code (e.g., 1012 service restart or 1001 going away) for planned restart; 1008 policy violation for slow consumers. - - Include `policy` in `hello-ok` so clients know the tick interval and buffer limits to tune their expectations. - -## Phase 8 — Cleanup and deprecation -- Retire `clawdbot rpc` as default path; keep only if explicitly requested (documented as legacy). -- Remove reliance on `src/infra/control-channel.ts` for new clients; mark as legacy or delete after migration. ✅ file removed; mac app now uses Gateway WS. -- Update README, docs (`architecture.md`, `gateway.md`, `webchat.md`) to final shapes; remove `control-api.md` references if obsolete. -- Presence hygiene: - - Presence derived primarily from connection (server-fills host/ip/version/connId/instanceId); allow client hints (e.g., lastInputSeconds). - - Add TTL/expiry; prune to keep map bounded (e.g., 5m TTL, max 200 entries). - -## Edge cases and ordering -- Event ordering: all events carry `seq`; clients detect gaps and should re-fetch snapshot (or targeted refresh) on gap. -- Partial handshakes: if client connects and never sends `req:connect`, server closes after handshake timeout. -- Garbage/oversize first frame: bounded by `maxPayload`; server closes immediately on parse failure. -- Duplicate delivery on reconnect: clients must send idempotency keys; Gateway dedupe cache prevents double-send/agent execution. -- Snapshot sufficiency: `hello-ok.snapshot` must contain enough to render UI after reconnect without event replay. -- Client reconnect guidance: exponential backoff with jitter; reuse same `instanceId` across reconnects to avoid duplicate presence; resend idempotency keys for in-flight sends/agents; on seq gap, issue `health`/`system-presence` refresh. -- Presence TTL/defaults: set a concrete TTL (e.g., 5 minutes) and prune periodically; cap the presence map size with LRU if needed. -- Replay policy: if seq gap detected, server does not replay; clients must pull fresh `health` + `system-presence` and continue. - -## Phase 9 — Testing & validation -- Unit: frame validation, handshake failure, auth/token, stateVersion on presence events, agent stream fanout, send dedupe. ✅ -- Integration: connect → snapshot → req/res → streaming agent → shutdown. ✅ Covered in gateway WS tests (connect/health/status/presence, agent ack+final, shutdown broadcast). -- Load: multiple concurrent WS clients; backpressure behavior under burst. ✅ Basic fanout test with 3 clients receiving presence broadcast; heavier soak still recommended. -- Mac app smoke: presence/health render from snapshot; reconnect on tick loss. (Manual: open Instances tab, verify snapshot after connect, induce seq gap by toggling wifi, ensure UI refreshes.) -- WebChat smoke: snapshot seed + event updates; tunnel scenario. ✅ Offline snapshot harness in `src/webchat/server.test.ts` (mock gateway) now passes; live tunnel still recommended for manual. -- Idempotency tests: retry send/agent with same key after forced disconnect; expect deduped result. ✅ send + agent dedupe + reconnect retry covered in gateway tests. -- Seq-gap handling: ✅ clients now detect seq gaps (WebChat gateway client + mac `GatewayConnection/GatewayChannel`) and refresh health/presence (webchat) or trigger UI refresh (mac). Load-test still optional. - -## Phase 10 — Rollout -- Version bump; release notes: breaking change to control plane (WS only). -- Ship launchd/systemd templates for `clawdbot gateway`. -- Recommend Tailscale/SSH tunnel for remote access; no additional auth layer assumed in this model. - ---- - -- Quick checklist -- [x] Protocol types & schemas (TS + JSON Schema + Swift via quicktype) -- [x] AJV validators wired -- [x] WS server with connect → snapshot → events -- [x] Tick + shutdown events -- [x] stateVersion + presence deltas -- [x] Gateway CLI command -- [x] macOS app WS client (Gateway WS for control; presence events live; agent stream UI pending) -- [x] WebChat WS client -- [x] Remove legacy stdin/TCP paths from default flows (file removed; mac app/CLI on Gateway) -- [x] Tests (unit/integration/load) — unit + integration + basic fanout/reconnect; heavier load/soak optional -- [x] Docs updated and legacy docs flagged diff --git a/docs/refactor/tui.md b/docs/refactor/tui.md deleted file mode 100644 index f1177be4a..000000000 --- a/docs/refactor/tui.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -summary: "Refactor plan: Gateway TUI parity with pi-mono interactive UI" -read_when: - - Building or refactoring the Gateway TUI - - Syncing TUI slash commands with Clawdbot behavior ---- -# Gateway TUI refactor plan - -Updated: 2026-01-03 - -## Goals -- Match pi-mono interactive TUI feel (editor, streaming, tool cards, selectors). -- Keep Clawdbot semantics: Gateway WS only, session store owns state, no branching/export. -- Work locally or remotely via Gateway URL/token. - -## Non-goals -- Branching, export, OAuth flows, or hook UIs. -- File-system operations on the Gateway host from the TUI. - -## Checklist -- [x] Protocol + server: sessions.patch supports model overrides; agent events include tool results (text-only payloads). -- [x] Gateway TUI client: add session/model helpers + stricter typing. -- [x] TUI UI kit: theme + components (editor, message feed, tool cards, selectors). -- [x] TUI controller: keybindings + Clawdbot slash commands + history/stream wiring. -- [x] Docs + changelog updated for the new TUI behavior. -- [x] Gate: lint, build, tests, docs list. diff --git a/docs/refactor/web-gateway-troubleshooting.md b/docs/refactor/web-gateway-troubleshooting.md deleted file mode 100644 index 93db611ee..000000000 --- a/docs/refactor/web-gateway-troubleshooting.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -summary: "Troubleshooting guide for the web gateway/Baileys stack" -read_when: - - Diagnosing web gateway socket or login issues ---- -# Web Gateway Troubleshooting (Nov 26, 2025) - -## Symptoms & quick fixes -- **Stream Errored / Conflict / status 409–515:** WhatsApp closed the socket because another session is active or creds went stale. Run `clawdbot logout`, then `clawdbot login`, then restart the Gateway. -- **Logged out:** Console prints “session logged out”; re-link with `clawdbot login`. -- **Repeated retries then exit:** Tune reconnect behavior via config `web.reconnect` and restart the Gateway. -- **No inbound messages:** Ensure the QR-linked account is online in WhatsApp, and check logs for `web-heartbeat` to confirm auth age/connection. -- **Status 515 right after pairing:** The QR login flow now auto-restarts once; you should not need a manual gateway restart after scanning. -- **Fast nuke:** From an allowed WhatsApp sender you can send `/restart` to request a supervised restart (launchd/mac app setups); wait a few seconds for it to come back. - -## Helpful commands -- Start the Gateway: `clawdbot gateway --verbose` -- Logout (clear creds): `clawdbot logout` -- Relink (show QR): `clawdbot login --verbose` -- Tail logs (default): `tail -f /tmp/clawdbot/clawdbot-*.log` - -## Reading the logs -- `web-reconnect`: close reasons, retry/backoff, max-attempt exit. -- `web-heartbeat`: connectionId, messagesHandled, authAgeMs, uptimeMs (every 60s by default). -- `web-auto-reply`: inbound/outbound message records with correlation IDs. - -## When to tweak knobs -- High churn networks: increase `web.reconnect.maxAttempts`. -- Slow links: raise `web.reconnect.maxMs` to give more headroom before bailing. -- Chatty monitors: increase `web.heartbeatSeconds` if log volume is high. - -## If it keeps failing -1) `clawdbot logout` → `clawdbot login` (fresh QR link). -2) Ensure no other device/browser is using the same WA Web session. -3) Check WhatsApp mobile app is online and not in low-power mode. -4) If status is 515, let the client restart once after pairing (already handled automatically). -5) Capture the last `web-reconnect` entry and the status code before escalating. diff --git a/docs/refactor/webagent-session.md b/docs/refactor/webagent-session.md deleted file mode 100644 index ad769c193..000000000 --- a/docs/refactor/webagent-session.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -summary: "WebChat session migration notes (Gateway WS-only)" -read_when: - - Changing WebChat Gateway methods/events ---- -# WebAgent session migration (WS-only) - -Context: web chat currently lives in a WKWebView that loads the pi-web bundle. Sends go over HTTP `/rpc` to the webchat server, and updates come from `/socket` snapshots based on session JSONL file changes. The Gateway itself already speaks WebSocket to the webchat server, and Pi writes the session JSONL files. This doc tracks the plan to move WebChat to a single Gateway WebSocket and drop the HTTP shim/file-watching. - -## Target state -- Gateway WS adds methods: - - `chat.history { sessionKey }` → `{ sessionKey, messages[], thinkingLevel }` (reads the existing JSONL + session store). - - `chat.send { sessionKey, message, attachments?, thinking?, deliver?, timeoutMs<=30000, idempotencyKey }` → `res { runId, status:"accepted" }` or `res ok:false` on validation/timeout. -- Gateway WS emits `chat` events `{ runId, sessionKey, seq, state:"delta"|"final"|"error", message?, errorMessage?, usage?, stopReason? }`. Streaming is optional; minimum is a single `state:"final"` per send. -- Client consumes only WS: bootstrap via `chat.history`, send via `chat.send`, live updates via `chat` events. No file watchers. -- Health gate: client subscribes to `health` and blocks send when health is not OK; 30s client-side timeout for sends. -- Tunneling: only the Gateway WS port needs to be forwarded; HTTP server remains for static assets but no RPC endpoints. - -## Server work (Node) -- Implement `chat.history` and `chat.send` handlers in `src/gateway/server.ts`; update protocol schemas/tests. -- Emit `chat` events by plumbing `agentCommand`/`emitAgentEvent` outputs; include assistant text/tool results. -- Remove `/rpc` and `/socket` routes + file-watch broadcast from `src/webchat/server.ts`; leave static host only. - -## Client work (pi-web bundle) -- Replace `NativeTransport` with a Gateway WS client: - - `connect` → `chat.history` for initial state. - - Listen to `chat/presence/tick/health`; update UI from events only. - - Send via `chat.send`; mark pending until `chat state:final|error`. - - Enforce health gate + 30s timeout. -- Remove reliance on session file snapshots and `/rpc`. - -## Persistence -- Keep passing `--session <.../.clawdbot/sessions/{{SessionId}}.jsonl>` to Pi so it continues writing JSONL. The WS history reader uses the same file; no new store introduced. - -## Docs to update when shipping -- `docs/webchat.md` (WS-only flow, methods/events, health gate, tunnel WS port). -- `docs/mac/webchat.md` (WKWebView now talks Gateway WS; `/rpc`/file-watch removed). -- `docs/architecture.md` / `typebox.md` if protocol methods are listed. -- Optional: add a concise Gateway chat protocol appendix if needed. - -## Open decisions -- Streaming granularity: start with `state:"final"` only, or include token/tool deltas immediately? -- Attachments over WS: text-only initially is OK; confirm before wiring binary/upload path. -- Error shape: use `res ok:false` for validation/timeout, `chat state:"error"` for model/runtime failures. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 357d8b5ee..21e80c5ec 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -100,7 +100,7 @@ If you’re logged out / unlinked: ```bash clawdbot logout -rm -rf ~/.clawdbot/credentials # if logout can't cleanly remove everything +trash ~/.clawdbot/credentials # if logout can't cleanly remove everything clawdbot login --verbose # re-scan QR ``` @@ -203,7 +203,7 @@ tail -20 /tmp/clawdbot/clawdbot-*.log Nuclear option: ```bash -rm -rf ~/.clawdbot +trash ~/.clawdbot clawdbot login # re-pair WhatsApp clawdbot gateway # start the Gateway again ``` diff --git a/docs/whatsapp.md b/docs/whatsapp.md index e646f62b3..0594fb583 100644 --- a/docs/whatsapp.md +++ b/docs/whatsapp.md @@ -136,7 +136,7 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number ## Logs + troubleshooting - Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`. - Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable). -- Troubleshooting guide: `docs/refactor/web-gateway-troubleshooting.md`. +- Troubleshooting guide: `docs/troubleshooting.md`. ## Tests - `src/web/auto-reply.test.ts` (mention gating, history injection, reply flow) From 29748864a457f05c9f3760110673eed54e4934e7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:30:47 +0100 Subject: [PATCH 015/110] docs: expand README doc links --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index f9b26e780..d82e15ccd 100644 --- a/README.md +++ b/README.md @@ -349,6 +349,52 @@ Browser control (optional): - [Debug common failures with the troubleshooting guide.](https://docs.clawdbot.com/troubleshooting) - [Review security guidance before exposing anything.](https://docs.clawdbot.com/security) +## Advanced docs (discovery + control) + +- [Discovery + transports](https://docs.clawdbot.com/discovery) +- [Bonjour/mDNS](https://docs.clawdbot.com/bonjour) +- [Gateway pairing](https://docs.clawdbot.com/gateway/pairing) +- [Remote gateway README](https://docs.clawdbot.com/remote-gateway-readme) +- [Control UI](https://docs.clawdbot.com/control-ui) +- [Dashboard](https://docs.clawdbot.com/dashboard) + +## Operations & troubleshooting + +- [Health checks](https://docs.clawdbot.com/health) +- [Gateway lock](https://docs.clawdbot.com/gateway-lock) +- [Background process](https://docs.clawdbot.com/background-process) +- [Browser troubleshooting (Linux)](https://docs.clawdbot.com/browser-linux-troubleshooting) +- [Logging](https://docs.clawdbot.com/logging) + +## Deep dives + +- [Agent loop](https://docs.clawdbot.com/agent-loop) +- [Presence](https://docs.clawdbot.com/presence) +- [TypeBox schemas](https://docs.clawdbot.com/typebox) +- [RPC adapters](https://docs.clawdbot.com/rpc) +- [Queue](https://docs.clawdbot.com/queue) + +## Workspace & skills + +- [Skills config](https://docs.clawdbot.com/skills-config) +- [Default AGENTS](https://docs.clawdbot.com/AGENTS.default) +- [Templates: AGENTS](https://docs.clawdbot.com/templates/AGENTS) +- [Templates: BOOTSTRAP](https://docs.clawdbot.com/templates/BOOTSTRAP) +- [Templates: IDENTITY](https://docs.clawdbot.com/templates/IDENTITY) +- [Templates: SOUL](https://docs.clawdbot.com/templates/SOUL) +- [Templates: TOOLS](https://docs.clawdbot.com/templates/TOOLS) +- [Templates: USER](https://docs.clawdbot.com/templates/USER) + +## Platform internals + +- [macOS dev setup](https://docs.clawdbot.com/mac/dev-setup) +- [macOS menu bar](https://docs.clawdbot.com/mac/menu-bar) +- [macOS voice wake](https://docs.clawdbot.com/mac/voicewake) +- [iOS node](https://docs.clawdbot.com/ios) +- [Android node](https://docs.clawdbot.com/android) +- [Windows app](https://docs.clawdbot.com/windows) +- [Linux app](https://docs.clawdbot.com/linux) + ## Email hooks (Gmail) [Gmail Pub/Sub wiring (gcloud + gogcli), hook tokens, and auto-watch behavior are documented here.](https://docs.clawdbot.com/gmail-pubsub) From 7900d337014f31451316fd6ee0c2970539a76136 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:32:02 +0100 Subject: [PATCH 016/110] docs: add README clarifiers --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index d82e15ccd..ff9d7a21b 100644 --- a/README.md +++ b/README.md @@ -169,6 +169,7 @@ It’s perfectly fine to run the Gateway on a small Linux instance. Clients (mac - **Gateway host** runs the bash tool and provider connections by default. - **Device nodes** run device‑local actions (`system.run`, camera, screen recording, notifications) via `node.invoke`. +In short: bash runs where the Gateway lives; device actions run where the device lives. Details: [Remote access](https://docs.clawdbot.com/remote) · [Nodes](https://docs.clawdbot.com/nodes) · [Security](https://docs.clawdbot.com/security) @@ -189,6 +190,7 @@ Details: [Nodes](https://docs.clawdbot.com/nodes) · [macOS app](https://docs.cl ## Agent to Agent (sessions_* tools) +- Use these to coordinate work across sessions without jumping between chat surfaces. - `sessions_list` — discover active sessions (agents) and their metadata. - `sessions_history` — fetch transcript logs for a session. - `sessions_send` — message another session; optional reply‑back ping‑pong + announce step (`REPLY_SKIP`, `ANNOUNCE_SKIP`). @@ -335,6 +337,7 @@ Browser control (optional): ## Docs +Use these when you’re past the onboarding flow and want the deeper reference. - [Start with the docs index for navigation and “what’s where.”](https://docs.clawdbot.com/) - [Read the architecture overview for the gateway + protocol model.](https://docs.clawdbot.com/architecture) - [Use the full configuration reference when you need every key and example.](https://docs.clawdbot.com/configuration) From 5622dfe86b0b6062022508deb097873712775f52 Mon Sep 17 00:00:00 2001 From: CI <112553441+pcty-nextgen-ios-builder@users.noreply.github.com> Date: Mon, 5 Jan 2026 18:04:36 +0100 Subject: [PATCH 017/110] fix: retry model fallback on rate limits --- src/agents/pi-embedded-helpers.test.ts | 32 ++++++++++++++++++++++++++ src/agents/pi-embedded-helpers.ts | 9 ++++++++ src/agents/pi-embedded-runner.ts | 11 +++++++++ 3 files changed, 52 insertions(+) create mode 100644 src/agents/pi-embedded-helpers.test.ts diff --git a/src/agents/pi-embedded-helpers.test.ts b/src/agents/pi-embedded-helpers.test.ts new file mode 100644 index 000000000..a709351e6 --- /dev/null +++ b/src/agents/pi-embedded-helpers.test.ts @@ -0,0 +1,32 @@ +import type { AssistantMessage } from "@mariozechner/pi-ai"; +import { describe, expect, it } from "vitest"; + +import { isRateLimitAssistantError } from "./pi-embedded-helpers.js"; + +const asAssistant = (overrides: Partial) => + ({ role: "assistant", stopReason: "error", ...overrides }) as AssistantMessage; + +describe("isRateLimitAssistantError", () => { + it("detects 429 rate limit payloads", () => { + const msg = asAssistant({ + errorMessage: + '429 {"type":"error","error":{"type":"rate_limit_error","message":"This request would exceed your account\'s rate limit. Please try again later."}}', + }); + expect(isRateLimitAssistantError(msg)).toBe(true); + }); + + it("detects human-readable rate limit messages", () => { + const msg = asAssistant({ + errorMessage: "Too many requests. Rate limit exceeded.", + }); + expect(isRateLimitAssistantError(msg)).toBe(true); + }); + + it("returns false for non-error messages", () => { + const msg = asAssistant({ + stopReason: "end_turn", + errorMessage: "rate limit", + }); + expect(isRateLimitAssistantError(msg)).toBe(false); + }); +}); diff --git a/src/agents/pi-embedded-helpers.ts b/src/agents/pi-embedded-helpers.ts index 8d2debc70..e4d598463 100644 --- a/src/agents/pi-embedded-helpers.ts +++ b/src/agents/pi-embedded-helpers.ts @@ -109,3 +109,12 @@ export function formatAssistantErrorText( // Keep it short for WhatsApp. return raw.length > 600 ? `${raw.slice(0, 600)}…` : raw; } + +export function isRateLimitAssistantError( + msg: AssistantMessage | undefined, +): boolean { + if (!msg || msg.stopReason !== "error") return false; + const raw = (msg.errorMessage ?? "").toLowerCase(); + if (!raw) return false; + return /rate[_ ]limit|too many requests|429/.test(raw); +} diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index 18c29d6e7..b20c9d83f 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -32,6 +32,7 @@ import { buildBootstrapContextFiles, ensureSessionHeader, formatAssistantErrorText, + isRateLimitAssistantError, sanitizeSessionMessagesImages, } from "./pi-embedded-helpers.js"; import { @@ -551,6 +552,16 @@ export async function runEmbeddedPiAgent(params: { | AssistantMessage | undefined; + const fallbackConfigured = + (params.config?.agent?.modelFallbacks?.length ?? 0) > 0; + if (fallbackConfigured && isRateLimitAssistantError(lastAssistant)) { + const message = + lastAssistant?.errorMessage?.trim() || + (lastAssistant ? formatAssistantErrorText(lastAssistant) : "") || + "LLM request rate limited."; + throw new Error(message); + } + const usage = lastAssistant?.usage; const agentMeta: EmbeddedPiAgentMeta = { sessionId: sessionIdUsed, From c627efce3e0aef186b6a33b117f994af28036a59 Mon Sep 17 00:00:00 2001 From: CI <112553441+pcty-nextgen-ios-builder@users.noreply.github.com> Date: Mon, 5 Jan 2026 18:54:23 +0100 Subject: [PATCH 018/110] fix(model): retry with supported thinking level --- src/agents/pi-embedded-helpers.test.ts | 37 +++++++++++++- src/agents/pi-embedded-helpers.ts | 36 ++++++++++++++ src/agents/pi-embedded-runner.ts | 67 +++++++++++++++++++------- 3 files changed, 122 insertions(+), 18 deletions(-) diff --git a/src/agents/pi-embedded-helpers.test.ts b/src/agents/pi-embedded-helpers.test.ts index a709351e6..97a332224 100644 --- a/src/agents/pi-embedded-helpers.test.ts +++ b/src/agents/pi-embedded-helpers.test.ts @@ -1,7 +1,11 @@ import type { AssistantMessage } from "@mariozechner/pi-ai"; import { describe, expect, it } from "vitest"; -import { isRateLimitAssistantError } from "./pi-embedded-helpers.js"; +import { + isRateLimitAssistantError, + pickFallbackThinkingLevel, +} from "./pi-embedded-helpers.js"; +import type { ThinkLevel } from "../auto-reply/thinking.js"; const asAssistant = (overrides: Partial) => ({ role: "assistant", stopReason: "error", ...overrides }) as AssistantMessage; @@ -30,3 +34,34 @@ describe("isRateLimitAssistantError", () => { expect(isRateLimitAssistantError(msg)).toBe(false); }); }); + +describe("pickFallbackThinkingLevel", () => { + it("selects the first supported thinking level", () => { + const attempted = new Set(["low"]); + const next = pickFallbackThinkingLevel({ + message: + "Unsupported value: 'low' is not supported with the 'gpt-5.2-pro' model. Supported values are: 'medium', 'high', and 'xhigh'.", + attempted, + }); + expect(next).toBe("medium"); + }); + + it("skips already attempted levels", () => { + const attempted = new Set(["low", "medium"]); + const next = pickFallbackThinkingLevel({ + message: + "Supported values are: 'medium', 'high', and 'xhigh'.", + attempted, + }); + expect(next).toBe("high"); + }); + + it("returns undefined when no supported values are found", () => { + const attempted = new Set(["low"]); + const next = pickFallbackThinkingLevel({ + message: "Request failed.", + attempted, + }); + expect(next).toBeUndefined(); + }); +}); diff --git a/src/agents/pi-embedded-helpers.ts b/src/agents/pi-embedded-helpers.ts index e4d598463..79808d9e2 100644 --- a/src/agents/pi-embedded-helpers.ts +++ b/src/agents/pi-embedded-helpers.ts @@ -6,6 +6,7 @@ import type { AgentToolResult, } from "@mariozechner/pi-agent-core"; import type { AssistantMessage } from "@mariozechner/pi-ai"; +import { normalizeThinkLevel, type ThinkLevel } from "../auto-reply/thinking.js"; import { sanitizeContentBlocksImages } from "./tool-images.js"; import type { WorkspaceBootstrapFile } from "./workspace.js"; @@ -118,3 +119,38 @@ export function isRateLimitAssistantError( if (!raw) return false; return /rate[_ ]limit|too many requests|429/.test(raw); } + +function extractSupportedValues(raw: string): string[] { + const match = + raw.match(/supported values are:\s*([^\n.]+)/i) ?? + raw.match(/supported values:\s*([^\n.]+)/i); + if (!match?.[1]) return []; + const fragment = match[1]; + const quoted = Array.from(fragment.matchAll(/['"]([^'"]+)['"]/g)).map( + (entry) => entry[1]?.trim(), + ); + if (quoted.length > 0) { + return quoted.filter((entry): entry is string => Boolean(entry)); + } + return fragment + .split(/,|\band\b/gi) + .map((entry) => entry.replace(/^[^a-zA-Z]+|[^a-zA-Z]+$/g, "").trim()) + .filter(Boolean); +} + +export function pickFallbackThinkingLevel(params: { + message?: string; + attempted: Set; +}): ThinkLevel | undefined { + const raw = params.message?.trim(); + if (!raw) return undefined; + const supported = extractSupportedValues(raw); + if (supported.length === 0) return undefined; + for (const entry of supported) { + const normalized = normalizeThinkLevel(entry); + if (!normalized) continue; + if (params.attempted.has(normalized)) continue; + return normalized; + } + return undefined; +} diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index b20c9d83f..9b33fdda8 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -33,6 +33,7 @@ import { ensureSessionHeader, formatAssistantErrorText, isRateLimitAssistantError, + pickFallbackThinkingLevel, sanitizeSessionMessagesImages, } from "./pi-embedded-helpers.js"; import { @@ -319,22 +320,27 @@ export async function runEmbeddedPiAgent(params: { const apiKey = await getApiKeyForModel(model, authStorage); authStorage.setRuntimeApiKey(model.provider, apiKey); - const thinkingLevel = mapThinkingLevel(params.thinkLevel); + let thinkLevel = params.thinkLevel ?? "off"; + const attemptedThinking = new Set(); - log.debug( - `embedded run start: runId=${params.runId} sessionId=${params.sessionId} provider=${provider} model=${modelId} surface=${params.surface ?? "unknown"}`, - ); + while (true) { + const thinkingLevel = mapThinkingLevel(thinkLevel); + attemptedThinking.add(thinkLevel); - await fs.mkdir(resolvedWorkspace, { recursive: true }); - await ensureSessionHeader({ - sessionFile: params.sessionFile, - sessionId: params.sessionId, - cwd: resolvedWorkspace, - }); + log.debug( + `embedded run start: runId=${params.runId} sessionId=${params.sessionId} provider=${provider} model=${modelId} thinking=${thinkLevel} surface=${params.surface ?? "unknown"}`, + ); - let restoreSkillEnv: (() => void) | undefined; - process.chdir(resolvedWorkspace); - try { + await fs.mkdir(resolvedWorkspace, { recursive: true }); + await ensureSessionHeader({ + sessionFile: params.sessionFile, + sessionId: params.sessionId, + cwd: resolvedWorkspace, + }); + + let restoreSkillEnv: (() => void) | undefined; + process.chdir(resolvedWorkspace); + try { const shouldLoadSkillEntries = !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills; const skillEntries = shouldLoadSkillEntries @@ -391,7 +397,7 @@ export async function runEmbeddedPiAgent(params: { const systemPrompt = buildSystemPrompt({ appendPrompt: buildAgentSystemPromptAppend({ workspaceDir: resolvedWorkspace, - defaultThinkLevel: params.thinkLevel, + defaultThinkLevel: thinkLevel, extraSystemPrompt: params.extraSystemPrompt, ownerNumbers: params.ownerNumbers, reasoningTagHint, @@ -542,6 +548,20 @@ export async function runEmbeddedPiAgent(params: { params.abortSignal?.removeEventListener?.("abort", onAbort); } if (promptError && !aborted) { + const fallbackThinking = pickFallbackThinkingLevel({ + message: + promptError instanceof Error + ? promptError.message + : String(promptError), + attempted: attemptedThinking, + }); + if (fallbackThinking) { + log.warn( + `unsupported thinking level for ${provider}/${modelId}; retrying with ${fallbackThinking}`, + ); + thinkLevel = fallbackThinking; + continue; + } throw promptError; } @@ -552,6 +572,18 @@ export async function runEmbeddedPiAgent(params: { | AssistantMessage | undefined; + const fallbackThinking = pickFallbackThinkingLevel({ + message: lastAssistant?.errorMessage, + attempted: attemptedThinking, + }); + if (fallbackThinking && !aborted) { + log.warn( + `unsupported thinking level for ${provider}/${modelId}; retrying with ${fallbackThinking}`, + ); + thinkLevel = fallbackThinking; + continue; + } + const fallbackConfigured = (params.config?.agent?.modelFallbacks?.length ?? 0) > 0; if (fallbackConfigured && isRateLimitAssistantError(lastAssistant)) { @@ -631,9 +663,10 @@ export async function runEmbeddedPiAgent(params: { aborted, }, }; - } finally { - restoreSkillEnv?.(); - process.chdir(prevCwd); + } finally { + restoreSkillEnv?.(); + process.chdir(prevCwd); + } } }), ); From d9cdf3b8acc6ea92578804eaa9865f01d1d7a0e2 Mon Sep 17 00:00:00 2001 From: CI <112553441+pcty-nextgen-ios-builder@users.noreply.github.com> Date: Mon, 5 Jan 2026 19:16:38 +0100 Subject: [PATCH 019/110] fix(model): treat quota errors as rate limits --- src/agents/pi-embedded-helpers.test.ts | 8 ++++++++ src/agents/pi-embedded-helpers.ts | 5 ++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/agents/pi-embedded-helpers.test.ts b/src/agents/pi-embedded-helpers.test.ts index 97a332224..1fb719c2b 100644 --- a/src/agents/pi-embedded-helpers.test.ts +++ b/src/agents/pi-embedded-helpers.test.ts @@ -26,6 +26,14 @@ describe("isRateLimitAssistantError", () => { expect(isRateLimitAssistantError(msg)).toBe(true); }); + it("detects quota exceeded messages", () => { + const msg = asAssistant({ + errorMessage: + "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors.", + }); + expect(isRateLimitAssistantError(msg)).toBe(true); + }); + it("returns false for non-error messages", () => { const msg = asAssistant({ stopReason: "end_turn", diff --git a/src/agents/pi-embedded-helpers.ts b/src/agents/pi-embedded-helpers.ts index 79808d9e2..4cb5f86a2 100644 --- a/src/agents/pi-embedded-helpers.ts +++ b/src/agents/pi-embedded-helpers.ts @@ -117,7 +117,10 @@ export function isRateLimitAssistantError( if (!msg || msg.stopReason !== "error") return false; const raw = (msg.errorMessage ?? "").toLowerCase(); if (!raw) return false; - return /rate[_ ]limit|too many requests|429/.test(raw); + return ( + /rate[_ ]limit|too many requests|429/.test(raw) || + raw.includes("exceeded your current quota") + ); } function extractSupportedValues(raw: string): string[] { From e5058a4cf9bf6f6b8a55ec7c0790ed8b519275f7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:58:38 +0100 Subject: [PATCH 020/110] docs: add showcase page --- README.md | 2 +- docs/docs.json | 1 + docs/showcase.md | 38 ++++++++++++++++++++++++++++++++++++++ showcase.md | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/showcase.md create mode 100644 showcase.md diff --git a/README.md b/README.md index ff9d7a21b..e68a5be0f 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ It answers you on the surfaces you already use (WhatsApp, Telegram, Slack, Disco If you want a personal, single-user assistant that feels local, fast, and always-on, this is it. -Website: [https://clawdbot.com](https://clawdbot.com) · Docs: [https://docs.clawdbot.com](https://docs.clawdbot.com/) · FAQ: [https://docs.clawdbot.com/faq](https://docs.clawdbot.com/faq) · Wizard: [https://docs.clawdbot.com/wizard](https://docs.clawdbot.com/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawdbot.com/docker](https://docs.clawdbot.com/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) +Website: [https://clawdbot.com](https://clawdbot.com) · Docs: [https://docs.clawdbot.com](https://docs.clawdbot.com/) · Showcase: [https://docs.clawdbot.com/showcase](https://docs.clawdbot.com/showcase) · FAQ: [https://docs.clawdbot.com/faq](https://docs.clawdbot.com/faq) · Wizard: [https://docs.clawdbot.com/wizard](https://docs.clawdbot.com/wizard) · Nix: [https://github.com/clawdbot/nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) · Docker: [https://docs.clawdbot.com/docker](https://docs.clawdbot.com/docker) · Discord: [https://discord.gg/clawd](https://discord.gg/clawd) Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Windows, and Linux**. Works with npm, pnpm, or bun. diff --git a/docs/docs.json b/docs/docs.json index ea2a4b20b..26ceef64b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -26,6 +26,7 @@ "group": "Getting Started", "pages": [ "index", + "showcase", "hubs", "onboarding", "clawd", diff --git a/docs/showcase.md b/docs/showcase.md new file mode 100644 index 000000000..40abc9af9 --- /dev/null +++ b/docs/showcase.md @@ -0,0 +1,38 @@ +--- +summary: "Real-world showcases of what Clawdbot can do" +read_when: + - You want inspiration or proof of capability +--- +# Showcase + +Real projects from the community. Highlights from #showcase (Jan 2–5, 2026). + +## Automation & real-world outcomes +- **Grocery autopilot (Picnic)** — Skill built around an unofficial Picnic API client. Pulls order history, infers preferred brands, maps recipes to cart, completes order in minutes. https://github.com/timkrase/clawdis-picnic-skill +- **Grocery autopilot (Picnic, alt)** — Another Picnic-based skill built via the `picnic-api` package. https://github.com/MRVDH/picnic-api +- **German rail planning** — Go CLI for Deutsche Bahn; skill picks best connections given time windows and preferences. https://github.com/timkrase/dbrest-cli + https://github.com/timkrase/clawdis-skills/tree/main/db-bahn +- **Accounting intake** — Collect PDFs from email, prep for tax consultant (monthly accounting batch). (No link shared.) + +## Knowledge & memory systems +- **WhatsApp memory vault** — Ingests full exports, transcribes 1k+ voice notes, cross‑checks with git logs, outputs linked MD reports + ongoing indexing. (No link shared.) +- **Karakeep semantic search** — Sidecar adds vector search to Karakeep bookmarks (Qdrant + OpenAI/Ollama), includes Clawdis skill. https://github.com/jamesbrooksco/karakeep-semantic-search +- **Inside‑Out‑2 style memory** — Separate memory manager app turns session files into memories → beliefs → self model. (No link shared.) + +## Voice, docs, and assistants on the phone +- **Clawdia phone bridge** — Vapi voice assistant ↔ Clawdis HTTP bridge; near‑real‑time phone calls. https://github.com/alejandroOPI/clawdia-bridge +- **Google Docs edit skill** — Rich‑text editing skill built fast with Claude Code. (No link shared.) +- **OpenRouter transcription skill** — Multi‑lingual audio transcription via OpenRouter (Gemini etc). ClawdHub: https://clawdhub.com/obviyus/openrouter-transcribe (user/slug link) + +## Infrastructure & deployment +- **Home Assistant OS gateway add‑on** — Clawdbot gateway running on HA OS (Raspberry Pi), with SSH tunnel support + persistent state in /config. https://github.com/ngutman/clawdbot-ha-addon +- **Home Assistant skill** — Control/automate HA via ClawdHub. https://clawdhub.com/skills/homeassistant +- **Nix packaging** — Batteries‑included nixified clawdis config. https://github.com/joshp123/nix-clawdis +- **CalDAV skill** — khal/vdirsyncer based calendar skill. ClawdHub: caldav-calendar → https://clawdhub.com/skills/caldav-calendar + +## Home + hardware +- **Roborock integration** — Plugin for robot vacuum control. https://github.com/joshp123/gohome/tree/main/plugins/roborock + +## Community builds (non‑Clawdis but made with/around it) +- **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/ + +If you want more items or a tighter curation, open an issue with links and a short blurb. diff --git a/showcase.md b/showcase.md new file mode 100644 index 000000000..060c22e70 --- /dev/null +++ b/showcase.md @@ -0,0 +1,35 @@ +# Showcase: what your personal assistant can do + +Highlights from #showcase (Jan 2–5, 2026). Curated for “wow” factor + concrete links. + +## Automation & real-world outcomes +- **Grocery autopilot (Picnic)** — Skill built around an unofficial Picnic API client. Pulls order history, infers preferred brands, maps recipes to cart, completes order in minutes. https://github.com/timkrase/clawdis-picnic-skill +- **Grocery autopilot (Picnic, alt)** — Another Picnic-based skill built via the `picnic-api` package. https://github.com/MRVDH/picnic-api +- **German rail planning** — Go CLI for Deutsche Bahn; skill picks best connections given time windows and preferences. https://github.com/timkrase/dbrest-cli + https://github.com/timkrase/clawdis-skills/tree/main/db-bahn (link check pending) +- **Accounting intake** — Collect PDFs from email, prep for tax consultant (monthly accounting batch). (No link shared.) + +## Knowledge & memory systems +- **WhatsApp memory vault** — Ingests full exports, transcribes 1k+ voice notes, cross‑checks with git logs, outputs linked MD reports + ongoing indexing. (No link shared.) +- **Karakeep semantic search** — Sidecar adds vector search to Karakeep bookmarks (Qdrant + OpenAI/Ollama), includes Clawdis skill. https://github.com/jamesbrooksco/karakeep-semantic-search +- **Inside‑Out‑2 style memory** — Separate memory manager app turns session files into memories → beliefs → self model. (No link shared.) + +## Voice, docs, and assistants on the phone +- **Clawdia phone bridge** — Vapi voice assistant ↔ Clawdis HTTP bridge; near‑real‑time phone calls. https://github.com/alejandroOPI/clawdia-bridge +- **Google Docs edit skill** — Rich‑text editing skill built fast with Claude Code. (No link shared.) +- **OpenRouter transcription skill** — Multi‑lingual audio transcription via OpenRouter (Gemini etc). ClawdHub: https://clawdhub.com/obviyus/openrouter-transcribe (user/slug link) + +## Infrastructure & deployment +- **Home Assistant OS gateway add‑on** — Clawdbot gateway running on HA OS (Raspberry Pi), with SSH tunnel support + persistent state in /config. https://github.com/ngutman/clawdbot-ha-addon +- **Home Assistant skill** — Control/automate HA via ClawdHub. https://clawdhub.com/skills/homeassistant +- **Nix packaging** — Batteries‑included nixified clawdis config. https://github.com/joshp123/nix-clawdis +- **CalDAV skill** — khal/vdirsyncer based calendar skill. ClawdHub: caldav-calendar → https://clawdhub.com/skills/caldav-calendar + +## Home + hardware +- **Roborock integration** — Plugin for robot vacuum control. https://github.com/joshp123/gohome/tree/main/plugins/roborock + +## Community builds (non‑Clawdis but made with/around it) +- **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/ + +--- + +If you want more items (or tighter curation), tell me the target length and audience. From 53bf8b7b801e279985ba1beb51e11f0a08fb9173 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 23:00:37 +0100 Subject: [PATCH 021/110] fix: avoid duplicate missing auth label --- CHANGELOG.md | 1 + src/auto-reply/reply.directive.test.ts | 25 ++++++++++++++++++++++ src/auto-reply/reply/directive-handling.ts | 9 +++++++- 3 files changed, 34 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee10954a7..1efdec700 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ - Model: `/model` list shows auth source (masked key or OAuth email) per provider. - Model: `/model list` is an alias for `/model`. - Model: `/model` output now includes auth source location (env/auth.json/models.json). +- Model: avoid duplicate `missing (missing)` auth labels in `/model` list output. - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding. - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments. - Control UI: show a reading indicator bubble while the assistant is responding. diff --git a/src/auto-reply/reply.directive.test.ts b/src/auto-reply/reply.directive.test.ts index 082c05a71..92ffdc410 100644 --- a/src/auto-reply/reply.directive.test.ts +++ b/src/auto-reply/reply.directive.test.ts @@ -636,6 +636,31 @@ describe("directive parsing", () => { }); }); + it("does not repeat missing auth labels on /model list", async () => { + await withTempHome(async (home) => { + vi.mocked(runEmbeddedPiAgent).mockReset(); + const storePath = path.join(home, "sessions.json"); + + const res = await getReplyFromConfig( + { Body: "/model list", From: "+1222", To: "+1222" }, + {}, + { + agent: { + model: "anthropic/claude-opus-4-5", + workspace: path.join(home, "clawd"), + allowedModels: ["anthropic/claude-opus-4-5"], + }, + session: { store: storePath }, + }, + ); + + const text = Array.isArray(res) ? res[0]?.text : res?.text; + expect(text).toContain("auth:"); + expect(text).not.toContain("missing (missing)"); + expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + }); + }); + it("sets model override on /model directive", async () => { await withTempHome(async (home) => { vi.mocked(runEmbeddedPiAgent).mockReset(); diff --git a/src/auto-reply/reply/directive-handling.ts b/src/auto-reply/reply/directive-handling.ts index 541345e6b..5ccae73e8 100644 --- a/src/auto-reply/reply/directive-handling.ts +++ b/src/auto-reply/reply/directive-handling.ts @@ -93,6 +93,13 @@ const resolveAuthLabel = async ( return { label: "missing", source: "missing" }; }; +const formatAuthLabel = (auth: { label: string; source: string }) => { + if (!auth.source || auth.source === auth.label || auth.source === "missing") { + return auth.label; + } + return `${auth.label} (${auth.source})`; +}; + export type InlineDirectives = { cleaned: string; hasThinkDirective: boolean; @@ -272,7 +279,7 @@ export async function handleDirectiveOnly(params: { authStorage, authPaths, ); - authByProvider.set(entry.provider, `${auth.label} (${auth.source})`); + authByProvider.set(entry.provider, formatAuthLabel(auth)); } const current = `${params.provider}/${params.model}`; const defaultLabel = `${defaultProvider}/${defaultModel}`; From 4c6302d0f46b07515c5068184fc62e0beb1c78a8 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 23:06:14 +0100 Subject: [PATCH 022/110] docs: refine showcase page --- docs/assets/terminal.css | 90 ++++++++++++++-------------------------- docs/showcase.md | 2 - showcase.md | 2 - 3 files changed, 30 insertions(+), 64 deletions(-) diff --git a/docs/assets/terminal.css b/docs/assets/terminal.css index 58bb59578..00242acb1 100644 --- a/docs/assets/terminal.css +++ b/docs/assets/terminal.css @@ -29,40 +29,40 @@ html[data-theme="auto"] { } html[data-theme="dark"] { - --bg0: #06141f; - --bg1: #031019; - --panel: #061a16; - --panel2: #071f19; - --text: #d6f6ea; - --muted: #95c9b9; - --faint: #66a391; - --link: #79ffd0; - --link2: #ff775f; + --bg0: #0b1a22; + --bg1: #0a1720; + --panel: #0e231f; + --panel2: #102a24; + --text: #c9eadc; + --muted: #8ab8aa; + --faint: #699b8d; + --link: #6fe8c7; + --link2: #ff7b63; --accent: #ff4f40; - --accent2: #67ff9b; - --frame-border: #b7ffe6; - --code-bg: #04110d; - --code-fg: #dcfff1; - --code-accent: #67ff9b; + --accent2: #5fdfa2; + --frame-border: #6fbfa8; + --code-bg: #091814; + --code-fg: #d7f5e8; + --code-accent: #5fdfa2; } @media (prefers-color-scheme: dark) { html[data-theme="auto"] { - --bg0: #06141f; - --bg1: #031019; - --panel: #061a16; - --panel2: #071f19; - --text: #d6f6ea; - --muted: #95c9b9; - --faint: #66a391; - --link: #79ffd0; - --link2: #ff775f; + --bg0: #0b1a22; + --bg1: #0a1720; + --panel: #0e231f; + --panel2: #102a24; + --text: #c9eadc; + --muted: #8ab8aa; + --faint: #699b8d; + --link: #6fe8c7; + --link2: #ff7b63; --accent: #ff4f40; - --accent2: #67ff9b; - --frame-border: #b7ffe6; - --code-bg: #04110d; - --code-fg: #dcfff1; - --code-accent: #67ff9b; + --accent2: #5fdfa2; + --frame-border: #6fbfa8; + --code-bg: #091814; + --code-fg: #d7f5e8; + --code-accent: #5fdfa2; } } @@ -87,39 +87,9 @@ body { overflow-x: hidden; } -body::before { - content: ""; - position: fixed; - inset: 0; - pointer-events: none; - opacity: 0.45; - background-image: - linear-gradient(to right, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px), - linear-gradient(to bottom, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px); - background-size: 28px 28px; - mix-blend-mode: overlay; -} - +body::before, body::after { - content: ""; - position: fixed; - inset: 0; - pointer-events: none; - background: repeating-linear-gradient( - to bottom, - rgba(0, 0, 0, var(--scanline-opacity)), - rgba(0, 0, 0, var(--scanline-opacity)) 1px, - transparent 1px, - transparent var(--scanline-size) - ); - opacity: 0.8; - mix-blend-mode: multiply; -} - -@media (prefers-reduced-motion: reduce) { - body::after { - display: none; - } + display: none; } .skip-link { diff --git a/docs/showcase.md b/docs/showcase.md index 40abc9af9..1e64dc7aa 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -34,5 +34,3 @@ Real projects from the community. Highlights from #showcase (Jan 2–5, 2026). ## Community builds (non‑Clawdis but made with/around it) - **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/ - -If you want more items or a tighter curation, open an issue with links and a short blurb. diff --git a/showcase.md b/showcase.md index 060c22e70..91ec938ce 100644 --- a/showcase.md +++ b/showcase.md @@ -31,5 +31,3 @@ Highlights from #showcase (Jan 2–5, 2026). Curated for “wow” factor + conc - **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/ --- - -If you want more items (or tighter curation), tell me the target length and audience. From dae7f560a52693d8c30e45d7677b167dcae4798e Mon Sep 17 00:00:00 2001 From: Josh Lehman Date: Mon, 5 Jan 2026 14:16:28 -0800 Subject: [PATCH 023/110] cron: skip delivery for HEARTBEAT_OK responses (#238) When an isolated cron job has deliver:true, skip message delivery if the response is just HEARTBEAT_OK (or contains HEARTBEAT_OK at edges with short remaining content <= 30 chars). This allows cron jobs to silently ack when nothing to report but still deliver actual content when there is something meaningful to say. Media is still delivered even if text is HEARTBEAT_OK, since the presence of media indicates there's something to share. --- src/cron/isolated-agent.test.ts | 176 ++++++++++++++++++++++++++++++++ src/cron/isolated-agent.ts | 27 ++++- 2 files changed, 202 insertions(+), 1 deletion(-) diff --git a/src/cron/isolated-agent.test.ts b/src/cron/isolated-agent.test.ts index 916385441..4c93ee04b 100644 --- a/src/cron/isolated-agent.test.ts +++ b/src/cron/isolated-agent.test.ts @@ -377,4 +377,180 @@ describe("runCronIsolatedAgentTurn", () => { ); }); }); + + it("skips delivery when response is exactly HEARTBEAT_OK", async () => { + await withTempHome(async (home) => { + const storePath = await writeSessionStore(home); + const deps: CliDeps = { + sendMessageWhatsApp: vi.fn(), + sendMessageTelegram: vi.fn().mockResolvedValue({ + messageId: "t1", + chatId: "123", + }), + sendMessageDiscord: vi.fn(), + sendMessageSignal: vi.fn(), + sendMessageIMessage: vi.fn(), + }; + vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ + payloads: [{ text: "HEARTBEAT_OK" }], + meta: { + durationMs: 5, + agentMeta: { sessionId: "s", provider: "p", model: "m" }, + }, + }); + + const res = await runCronIsolatedAgentTurn({ + cfg: makeCfg(home, storePath), + deps, + job: makeJob({ + kind: "agentTurn", + message: "do it", + deliver: true, + channel: "telegram", + to: "123", + }), + message: "do it", + sessionKey: "cron:job-1", + lane: "cron", + }); + + // Job still succeeds, but no delivery happens. + expect(res.status).toBe("ok"); + expect(res.summary).toBe("HEARTBEAT_OK"); + expect(deps.sendMessageTelegram).not.toHaveBeenCalled(); + }); + }); + + it("skips delivery when response has HEARTBEAT_OK with short padding", async () => { + await withTempHome(async (home) => { + const storePath = await writeSessionStore(home); + const deps: CliDeps = { + sendMessageWhatsApp: vi.fn().mockResolvedValue({ + messageId: "w1", + chatId: "+1234", + }), + sendMessageTelegram: vi.fn(), + sendMessageDiscord: vi.fn(), + sendMessageSignal: vi.fn(), + sendMessageIMessage: vi.fn(), + }; + // Short junk around HEARTBEAT_OK (<=30 chars) should still skip delivery. + vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ + payloads: [{ text: "HEARTBEAT_OK 🦞" }], + meta: { + durationMs: 5, + agentMeta: { sessionId: "s", provider: "p", model: "m" }, + }, + }); + + const res = await runCronIsolatedAgentTurn({ + cfg: makeCfg(home, storePath, { whatsapp: { allowFrom: ["+1234"] } }), + deps, + job: makeJob({ + kind: "agentTurn", + message: "do it", + deliver: true, + channel: "whatsapp", + to: "+1234", + }), + message: "do it", + sessionKey: "cron:job-1", + lane: "cron", + }); + + expect(res.status).toBe("ok"); + expect(deps.sendMessageWhatsApp).not.toHaveBeenCalled(); + }); + }); + + it("delivers when response has HEARTBEAT_OK but also substantial content", async () => { + await withTempHome(async (home) => { + const storePath = await writeSessionStore(home); + const deps: CliDeps = { + sendMessageWhatsApp: vi.fn(), + sendMessageTelegram: vi.fn().mockResolvedValue({ + messageId: "t1", + chatId: "123", + }), + sendMessageDiscord: vi.fn(), + sendMessageSignal: vi.fn(), + sendMessageIMessage: vi.fn(), + }; + // Long content after HEARTBEAT_OK should still be delivered. + const longContent = `Important alert: ${"a".repeat(50)}`; + vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ + payloads: [{ text: `HEARTBEAT_OK ${longContent}` }], + meta: { + durationMs: 5, + agentMeta: { sessionId: "s", provider: "p", model: "m" }, + }, + }); + + const res = await runCronIsolatedAgentTurn({ + cfg: makeCfg(home, storePath), + deps, + job: makeJob({ + kind: "agentTurn", + message: "do it", + deliver: true, + channel: "telegram", + to: "123", + }), + message: "do it", + sessionKey: "cron:job-1", + lane: "cron", + }); + + expect(res.status).toBe("ok"); + expect(deps.sendMessageTelegram).toHaveBeenCalled(); + }); + }); + + it("delivers when response has HEARTBEAT_OK but includes media", async () => { + await withTempHome(async (home) => { + const storePath = await writeSessionStore(home); + const deps: CliDeps = { + sendMessageWhatsApp: vi.fn(), + sendMessageTelegram: vi.fn().mockResolvedValue({ + messageId: "t1", + chatId: "123", + }), + sendMessageDiscord: vi.fn(), + sendMessageSignal: vi.fn(), + sendMessageIMessage: vi.fn(), + }; + // Media should still be delivered even if text is just HEARTBEAT_OK. + vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ + payloads: [ + { text: "HEARTBEAT_OK", mediaUrl: "https://example.com/img.png" }, + ], + meta: { + durationMs: 5, + agentMeta: { sessionId: "s", provider: "p", model: "m" }, + }, + }); + + const res = await runCronIsolatedAgentTurn({ + cfg: makeCfg(home, storePath), + deps, + job: makeJob({ + kind: "agentTurn", + message: "do it", + deliver: true, + channel: "telegram", + to: "123", + }), + message: "do it", + sessionKey: "cron:job-1", + lane: "cron", + }); + + expect(res.status).toBe("ok"); + expect(deps.sendMessageTelegram).toHaveBeenCalledWith( + "123", + "HEARTBEAT_OK", + expect.objectContaining({ mediaUrl: "https://example.com/img.png" }), + ); + }); + }); }); diff --git a/src/cron/isolated-agent.ts b/src/cron/isolated-agent.ts index 66b26b390..da5a95c81 100644 --- a/src/cron/isolated-agent.ts +++ b/src/cron/isolated-agent.ts @@ -18,6 +18,7 @@ import { ensureAgentWorkspace, } from "../agents/workspace.js"; import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; +import { stripHeartbeatToken } from "../auto-reply/heartbeat.js"; import { normalizeThinkLevel } from "../auto-reply/thinking.js"; import type { CliDeps } from "../cli/deps.js"; import type { ClawdbotConfig } from "../config/config.js"; @@ -57,6 +58,25 @@ function pickSummaryFromPayloads( return undefined; } +/** + * Check if all payloads are just heartbeat ack responses (HEARTBEAT_OK). + * Returns true if delivery should be skipped because there's no real content. + */ +function isHeartbeatOnlyResponse( + payloads: Array<{ text?: string; mediaUrl?: string; mediaUrls?: string[] }>, +) { + if (payloads.length === 0) return true; + return payloads.every((payload) => { + // If there's media, we should deliver regardless of text content. + const hasMedia = + (payload.mediaUrls?.length ?? 0) > 0 || Boolean(payload.mediaUrl); + if (hasMedia) return false; + // Use heartbeat mode to check if text is just HEARTBEAT_OK or short ack. + const result = stripHeartbeatToken(payload.text, { mode: "heartbeat" }); + return result.shouldSkip; + }); +} + function resolveDeliveryTarget( cfg: ClawdbotConfig, jobPayload: { @@ -343,7 +363,12 @@ export async function runCronIsolatedAgentTurn(params: { const summary = pickSummaryFromPayloads(payloads) ?? pickSummaryFromOutput(firstText); - if (delivery) { + // Skip delivery for heartbeat-only responses (HEARTBEAT_OK with no real content). + // This allows cron jobs to silently ack when nothing to report but still deliver + // actual content when there is something to say. + const skipHeartbeatDelivery = delivery && isHeartbeatOnlyResponse(payloads); + + if (delivery && !skipHeartbeatDelivery) { if (resolvedDelivery.channel === "whatsapp") { if (!resolvedDelivery.to) { if (!bestEffortDeliver) From f790f3f3ba47cffaeb0dc2dc66092e3eb56c6b3e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 22:52:13 +0000 Subject: [PATCH 024/110] fix/heartbeat ok delivery filter (#246) * cron: skip delivery for HEARTBEAT_OK responses When an isolated cron job has deliver:true, skip message delivery if the response is just HEARTBEAT_OK (or contains HEARTBEAT_OK at edges with short remaining content <= 30 chars). This allows cron jobs to silently ack when nothing to report but still deliver actual content when there is something meaningful to say. Media is still delivered even if text is HEARTBEAT_OK, since the presence of media indicates there's something to share. * fix(heartbeat): make ack padding configurable * chore(deps): update to latest --------- Co-authored-by: Josh Lehman --- CHANGELOG.md | 2 + docs/clawd.md | 2 +- docs/configuration.md | 1 + docs/heartbeat.md | 8 +- package.json | 6 +- pnpm-lock.yaml | 154 +++---- src/agents/pi-embedded-helpers.test.ts | 12 +- src/agents/pi-embedded-helpers.ts | 5 +- src/agents/pi-embedded-runner.ts | 606 +++++++++++++------------ src/auto-reply/heartbeat.ts | 6 +- src/config/types.ts | 2 + src/config/zod-schema.ts | 1 + src/cron/isolated-agent.test.ts | 44 ++ src/cron/isolated-agent.ts | 17 +- src/infra/heartbeat-runner.test.ts | 58 +++ src/infra/heartbeat-runner.ts | 15 +- src/web/auto-reply.ts | 7 +- 17 files changed, 549 insertions(+), 397 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1efdec700..75425cd7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,11 +28,13 @@ - Block streaming: preserve leading indentation in block replies (lists, indented fences). - Docs: document systemd lingering and logged-in session requirements on macOS/Windows. - Auto-reply: unify tool/block/final delivery across providers and apply consistent heartbeat/prefix handling. Thanks @MSch for PR #225 (superseded commit 92c953d0749143eb2a3f31f3cd6ad0e8eabf48c3). +- Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. - Skills: add CodexBar model usage helper with macOS requirement metadata. - Lint: organize imports and wrap long lines in reply commands. +- Deps: update to latest across the repo. ## 2026.1.5-3 diff --git a/docs/clawd.md b/docs/clawd.md index 77a3cdf05..21eb2c2af 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -152,7 +152,7 @@ Example: When `agent.heartbeat.every` is set to a positive interval, CLAWDBOT periodically runs a heartbeat prompt (default: `HEARTBEAT`). -- If the agent replies with `HEARTBEAT_OK` (exact token), CLAWDBOT suppresses outbound delivery for that heartbeat. +- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agent.heartbeat.ackMaxChars`), CLAWDBOT suppresses outbound delivery for that heartbeat. ```json5 { diff --git a/docs/configuration.md b/docs/configuration.md index 917bda69d..deb2a0eda 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -560,6 +560,7 @@ Z.AI models are available as `zai/` (e.g. `zai/glm-4.7`) and require - `target`: optional delivery channel (`last`, `whatsapp`, `telegram`, `discord`, `imessage`, `none`). Default: `last`. - `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram). - `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`). +- `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30). `agent.bash` configures background bash defaults: - `backgroundMs`: time before auto-background (ms, default 10000) diff --git a/docs/heartbeat.md b/docs/heartbeat.md index 4a2ab923b..fee828592 100644 --- a/docs/heartbeat.md +++ b/docs/heartbeat.md @@ -10,10 +10,10 @@ surface anything that needs attention without spamming the user. ## Prompt contract - Heartbeat body defaults to `HEARTBEAT` (configurable via `agent.heartbeat.prompt`). -- If nothing needs attention, the model should reply **exactly** `HEARTBEAT_OK`. +- If nothing needs attention, the model should reply `HEARTBEAT_OK`. - During heartbeat runs, Clawdbot treats `HEARTBEAT_OK` as an ack when it appears at the **start or end** of the reply. Clawdbot strips the token and discards the - reply if the remaining content is **≤ 30 characters**. + reply if the remaining content is **≤ `ackMaxChars`** (default: 30). - If `HEARTBEAT_OK` is in the **middle** of a reply, it is not treated specially. - For alerts, do **not** include `HEARTBEAT_OK`; return only the alert text. @@ -39,7 +39,8 @@ and final replies: model: "anthropic/claude-opus-4-5", target: "last", // last | whatsapp | telegram | none to: "+15551234567", // optional override for whatsapp/telegram - prompt: "HEARTBEAT" // optional override + prompt: "HEARTBEAT", // optional override + ackMaxChars: 30 // max chars allowed after HEARTBEAT_OK } } } @@ -55,6 +56,7 @@ and final replies: - `none`: do not deliver externally; output stays in the session (WebChat-visible). - `to`: optional recipient override (E.164 for WhatsApp, chat id for Telegram). - `prompt`: optional override for the heartbeat body (default: `HEARTBEAT`). +- `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery (default: 30). ## Behavior - Runs in the main session (`main`, or `global` when scope is global). diff --git a/package.json b/package.json index d94352b1f..23e044de8 100644 --- a/package.json +++ b/package.json @@ -111,8 +111,8 @@ "qrcode-terminal": "^0.12.0", "sharp": "^0.34.5", "tslog": "^4.10.2", - "undici": "^7.16.0", - "ws": "^8.18.3", + "undici": "^7.18.0", + "ws": "^8.19.0", "zod": "^4.3.5" }, "devDependencies": { @@ -133,7 +133,7 @@ "lucide": "^0.562.0", "markdown-it": "^14.1.0", "ollama": "^0.6.3", - "oxlint": "^1.36.0", + "oxlint": "^1.37.0", "oxlint-tsgolint": "^0.10.1", "quicktype-core": "^23.2.6", "rolldown": "1.0.0-beta.58", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 54d27a002..11815c700 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -27,13 +27,13 @@ importers: version: 1.3.4 '@mariozechner/pi-agent-core': specifier: ^0.36.0 - version: 0.36.0(ws@8.18.3)(zod@4.3.5) + version: 0.36.0(ws@8.19.0)(zod@4.3.5) '@mariozechner/pi-ai': specifier: ^0.36.0 - version: 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.5) + version: 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5) '@mariozechner/pi-coding-agent': specifier: ^0.36.0 - version: 0.36.0(ws@8.18.3)(zod@4.3.5) + version: 0.36.0(ws@8.19.0)(zod@4.3.5) '@mariozechner/pi-tui': specifier: ^0.36.0 version: 0.36.0 @@ -110,11 +110,11 @@ importers: specifier: ^4.10.2 version: 4.10.2 undici: - specifier: ^7.16.0 - version: 7.16.0 + specifier: ^7.18.0 + version: 7.18.0 ws: - specifier: ^8.18.3 - version: 8.18.3 + specifier: ^8.19.0 + version: 8.19.0 zod: specifier: ^4.3.5 version: 4.3.5 @@ -171,8 +171,8 @@ importers: specifier: ^0.6.3 version: 0.6.3 oxlint: - specifier: ^1.36.0 - version: 1.36.0(oxlint-tsgolint@0.10.1) + specifier: ^1.37.0 + version: 1.37.0(oxlint-tsgolint@0.10.1) oxlint-tsgolint: specifier: ^0.10.1 version: 0.10.1 @@ -870,43 +870,43 @@ packages: cpu: [x64] os: [win32] - '@oxlint/darwin-arm64@1.36.0': - resolution: {integrity: sha512-MJkj82GH+nhvWKJhSIM6KlZ8tyGKdogSQXtNdpIyP02r/tTayFJQaAEWayG2Jhsn93kske+nimg5MYFhwO/rlg==} + '@oxlint/darwin-arm64@1.37.0': + resolution: {integrity: sha512-qDa8qf4Th3sbk6P6wRbsv5paGeZ8EEOy8PtnT2IkAYSzjDHavw8nMK/lQvf6uS7LArjcmOfM1Y3KnZUFoNZZqg==} cpu: [arm64] os: [darwin] - '@oxlint/darwin-x64@1.36.0': - resolution: {integrity: sha512-VvEhfkqj/99dCTqOcfkyFXOSbx4lIy5u2m2GHbK4WCMDySokOcMTNRHGw8fH/WgQ5cDrDMSTYIGQTmnBGi9tiQ==} + '@oxlint/darwin-x64@1.37.0': + resolution: {integrity: sha512-FM0h0KyOQ4HCdhIX1ne6d80BxRra75h1ORce0jYNwQ49HT4RU8+9ywSMC7rQ79xWsmaahvkQPB7tMPyfjsQwAg==} cpu: [x64] os: [darwin] - '@oxlint/linux-arm64-gnu@1.36.0': - resolution: {integrity: sha512-EMx92X5q+hHc3olTuj/kgkx9+yP0p/AVs4yvHbUfzZhBekXNpUWxWvg4hIKmQWn+Ee2j4o80/0ACGO0hDYJ9mg==} + '@oxlint/linux-arm64-gnu@1.37.0': + resolution: {integrity: sha512-2axK0lftGwM6Q7wOuY2sassUqa4MKrG3iemVVyEpXzJ6g5QosxhCoFPp9v81/gmLT5kAdd2gskoDcfpDJliDNw==} cpu: [arm64] os: [linux] - '@oxlint/linux-arm64-musl@1.36.0': - resolution: {integrity: sha512-7YCxtrPIctVYLqWrWkk8pahdCxch6PtsaucfMLC7TOlDt4nODhnQd4yzEscKqJ8Gjrw1bF4g+Ngob1gB+Qr9Fw==} + '@oxlint/linux-arm64-musl@1.37.0': + resolution: {integrity: sha512-f3YROyGMIdUeXx0yD7RsAUBzBvD222D4l2GQRYF3AMxyp9mya17Rq/3wNLR4JDnAnboOul3DAEKNm+09lo3uZw==} cpu: [arm64] os: [linux] - '@oxlint/linux-x64-gnu@1.36.0': - resolution: {integrity: sha512-lnaJVlx5r3NWmoOMesfQXJSf78jHTn8Z+sdAf795Kgteo72+qGC1Uax2SToCJVN2J8PNG3oRV5bLriiCNR2i6Q==} + '@oxlint/linux-x64-gnu@1.37.0': + resolution: {integrity: sha512-FANOdOVQ2c4acYLM0dvtSoKELHSSnDBxDdm8OlXNzSRanQILrNpLgUqCXHFsfiHipFfNzz3Z417PxV6X4aBYog==} cpu: [x64] os: [linux] - '@oxlint/linux-x64-musl@1.36.0': - resolution: {integrity: sha512-AhuEU2Qdl66lSfTGu/Htirq8r/8q2YnZoG3yEXLMQWnPMn7efy8spD/N1NA7kH0Hll+cdfwgQkQqC2G4MS2lPQ==} + '@oxlint/linux-x64-musl@1.37.0': + resolution: {integrity: sha512-eYnSKT9knXdOQ9h+6nSjEHSx0+pW8PkGwtMNGXtCYR+/ZPKYIbtZVS0nZsFy+qizP+TRVSJrgc/JY3Xr0wjcQg==} cpu: [x64] os: [linux] - '@oxlint/win32-arm64@1.36.0': - resolution: {integrity: sha512-GlWCBjUJY2QgvBFuNRkiRJu7K/djLmM0UQKfZV8IN+UXbP/JbjZHWKRdd4LXlQmzoz7M5Hd6p+ElCej8/90FCg==} + '@oxlint/win32-arm64@1.37.0': + resolution: {integrity: sha512-2oHxNc4jcocfNWGWVVWQdEG+reZ5ncBZsmDoICJQ1rbCDx4Yimx8VUf1Ub9cCoJRcPiSLBxMqaeMaDClKixJIQ==} cpu: [arm64] os: [win32] - '@oxlint/win32-x64@1.36.0': - resolution: {integrity: sha512-J+Vc00Utcf8p77lZPruQgb0QnQXuKnFogN88kCnOqs2a83I+vTBB8ILr0+L9sTwVRvIDMSC0pLdeQH4svWGFZg==} + '@oxlint/win32-x64@1.37.0': + resolution: {integrity: sha512-w+pBuTjGmGCGPhDjFhj/97K2tlGyq5LKAU6S7FHxROPuJRWJD6uio1L75Lsb8fKhwtw2rm54LLOX30Yi+nILxw==} cpu: [x64] os: [win32] @@ -1951,8 +1951,8 @@ packages: resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==} engines: {node: '>=12.0.0'} - hookified@1.14.0: - resolution: {integrity: sha512-pi1ynXIMFx/uIIwpWJ/5CEtOHLGtnUB0WhGeeYT+fKcQ+WCQbm3/rrkAXnpfph++PgepNqPdTC2WTj8A6k6zoQ==} + hookified@1.15.0: + resolution: {integrity: sha512-51w+ZZGt7Zw5q7rM3nC4t3aLn/xvKDETsXqMczndvwyVQhAHfUmUuFBRFcos8Iyebtk7OAE9dL26wFNzZVVOkw==} html-escaper@2.0.2: resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==} @@ -2418,8 +2418,8 @@ packages: resolution: {integrity: sha512-EEHNdo5cW2w1xwYdBQ7d3IXDqWAtMkfVFrh+9gQ4kYbYJwygY4QXSh1eH80/xVipZdVKujAwBgg/nNNHk56kxQ==} hasBin: true - oxlint@1.36.0: - resolution: {integrity: sha512-IicUdXfXgI8OKrDPnoSjvBfeEF8PkKtm+CoLlg4LYe4ypc8U+T4r7730XYshdBGZdelg+JRw8GtCb2w/KaaZvw==} + oxlint@1.37.0: + resolution: {integrity: sha512-MAw0JH8M5/vt9E2WxSsmJu53bVLmG6qNlVw1OXFenJYItTPbMBtW7j3n53+tgNhNuxFPundM1DR7V8E39qOOrg==} engines: {node: ^20.19.0 || >=22.12.0} hasBin: true peerDependencies: @@ -2436,8 +2436,8 @@ packages: resolution: {integrity: sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ==} engines: {node: '>=8'} - p-queue@9.0.1: - resolution: {integrity: sha512-RhBdVhSwJb7Ocn3e8ULk4NMwBEuOxe+1zcgphUy9c2e5aR/xbEsdVXxHJ3lynw6Qiqu7OINEyHlZkiblEpaq7w==} + p-queue@9.1.0: + resolution: {integrity: sha512-O/ZPaXuQV29uSLbxWBGGZO1mCQXV2BLIwUr59JUU9SoH76mnYvtms7aafH/isNSNGwuEfP6W/4xD0/TJXxrizw==} engines: {node: '>=20'} p-retry@4.6.2: @@ -2933,8 +2933,8 @@ packages: resolution: {integrity: sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==} engines: {node: '>=18.17'} - undici@7.16.0: - resolution: {integrity: sha512-QEg3HPMll0o3t2ourKwOeUAZ159Kn9mx5pnzHRQO8+Wixmh88YdZRiIwat0iNzNNXn0yoEtXJqFpyW7eM8BV7g==} + undici@7.18.0: + resolution: {integrity: sha512-CfPufgPFHCYu0W4h1NiKW9+tNJ39o3kWm7Cm29ET1enSJx+AERfz7A2wAr26aY0SZbYzZlTBQtcHy15o60VZfQ==} engines: {node: '>=20.18.1'} unicode-properties@1.4.1: @@ -3073,8 +3073,8 @@ packages: wrappy@1.0.2: resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==} - ws@8.18.3: - resolution: {integrity: sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==} + ws@8.19.0: + resolution: {integrity: sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==} engines: {node: '>=10.0.0'} peerDependencies: bufferutil: ^4.0.1 @@ -3186,13 +3186,13 @@ snapshots: dependencies: '@cacheable/utils': 2.3.3 '@keyv/bigmap': 1.3.0(keyv@5.5.5) - hookified: 1.14.0 + hookified: 1.15.0 keyv: 5.5.5 '@cacheable/node-cache@1.7.6': dependencies: cacheable: 2.3.1 - hookified: 1.14.0 + hookified: 1.15.0 keyv: 5.5.5 '@cacheable/utils@2.3.3': @@ -3290,7 +3290,7 @@ snapshots: '@vladfrangu/async_event_emitter': 2.4.7 discord-api-types: 0.38.37 tslib: 2.8.1 - ws: 8.18.3 + ws: 8.19.0 transitivePeerDependencies: - bufferutil - utf-8-validate @@ -3397,7 +3397,7 @@ snapshots: '@google/genai@1.34.0': dependencies: google-auth-library: 10.5.0 - ws: 8.18.3 + ws: 8.19.0 transitivePeerDependencies: - bufferutil - supports-color @@ -3548,7 +3548,7 @@ snapshots: '@keyv/bigmap@1.3.0(keyv@5.5.5)': dependencies: hashery: 1.4.0 - hookified: 1.14.0 + hookified: 1.15.0 keyv: 5.5.5 '@keyv/serialize@1.1.1': {} @@ -3585,9 +3585,9 @@ snapshots: transitivePeerDependencies: - tailwindcss - '@mariozechner/pi-agent-core@0.36.0(ws@8.18.3)(zod@4.3.5)': + '@mariozechner/pi-agent-core@0.36.0(ws@8.19.0)(zod@4.3.5)': dependencies: - '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.5) + '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5) '@mariozechner/pi-tui': 0.36.0 transitivePeerDependencies: - '@modelcontextprotocol/sdk' @@ -3597,7 +3597,7 @@ snapshots: - ws - zod - '@mariozechner/pi-ai@0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.5)': + '@mariozechner/pi-ai@0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5)': dependencies: '@anthropic-ai/sdk': 0.71.2(zod@4.3.5) '@google/genai': 1.34.0 @@ -3606,7 +3606,7 @@ snapshots: ajv: 8.17.1 ajv-formats: 3.0.1(ajv@8.17.1) chalk: 5.6.2 - openai: 6.10.0(ws@8.18.3)(zod@4.3.5) + openai: 6.10.0(ws@8.19.0)(zod@4.3.5) partial-json: 0.1.7 zod-to-json-schema: 3.25.1(zod@4.3.5) transitivePeerDependencies: @@ -3617,11 +3617,11 @@ snapshots: - ws - zod - '@mariozechner/pi-coding-agent@0.36.0(ws@8.18.3)(zod@4.3.5)': + '@mariozechner/pi-coding-agent@0.36.0(ws@8.19.0)(zod@4.3.5)': dependencies: '@crosscopy/clipboard': 0.2.8 - '@mariozechner/pi-agent-core': 0.36.0(ws@8.18.3)(zod@4.3.5) - '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.18.3)(zod@4.3.5) + '@mariozechner/pi-agent-core': 0.36.0(ws@8.19.0)(zod@4.3.5) + '@mariozechner/pi-ai': 0.36.0(patch_hash=628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5)(ws@8.19.0)(zod@4.3.5) '@mariozechner/pi-tui': 0.36.0 chalk: 5.6.2 cli-highlight: 2.1.11 @@ -3691,28 +3691,28 @@ snapshots: '@oxlint-tsgolint/win32-x64@0.10.1': optional: true - '@oxlint/darwin-arm64@1.36.0': + '@oxlint/darwin-arm64@1.37.0': optional: true - '@oxlint/darwin-x64@1.36.0': + '@oxlint/darwin-x64@1.37.0': optional: true - '@oxlint/linux-arm64-gnu@1.36.0': + '@oxlint/linux-arm64-gnu@1.37.0': optional: true - '@oxlint/linux-arm64-musl@1.36.0': + '@oxlint/linux-arm64-musl@1.37.0': optional: true - '@oxlint/linux-x64-gnu@1.36.0': + '@oxlint/linux-x64-gnu@1.37.0': optional: true - '@oxlint/linux-x64-musl@1.36.0': + '@oxlint/linux-x64-musl@1.37.0': optional: true - '@oxlint/win32-arm64@1.36.0': + '@oxlint/win32-arm64@1.37.0': optional: true - '@oxlint/win32-x64@1.36.0': + '@oxlint/win32-x64@1.37.0': optional: true '@pinojs/redact@0.4.0': {} @@ -3907,7 +3907,7 @@ snapshots: '@types/node': 25.0.3 '@types/ws': 8.18.1 eventemitter3: 5.0.1 - ws: 8.18.3 + ws: 8.19.0 transitivePeerDependencies: - bufferutil - debug @@ -4094,7 +4094,7 @@ snapshots: sirv: 3.0.2 tinyrainbow: 3.0.3 vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(@vitest/browser-preview@4.0.16)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.2) - ws: 8.18.3 + ws: 8.19.0 transitivePeerDependencies: - bufferutil - msw @@ -4196,11 +4196,11 @@ snapshots: libsignal: '@whiskeysockets/libsignal-node@https://codeload.github.com/whiskeysockets/libsignal-node/tar.gz/1c30d7d7e76a3b0aa120b04dc6a26f5a12dccf67' lru-cache: 11.2.4 music-metadata: 11.10.4 - p-queue: 9.0.1 + p-queue: 9.1.0 pino: 9.14.0 protobufjs: 7.5.4 sharp: 0.34.5 - ws: 8.18.3 + ws: 8.19.0 optionalDependencies: audio-decode: 2.2.3 transitivePeerDependencies: @@ -4361,7 +4361,7 @@ snapshots: dependencies: '@cacheable/memory': 2.0.7 '@cacheable/utils': 2.3.3 - hookified: 1.14.0 + hookified: 1.15.0 keyv: 5.5.5 qified: 0.5.3 @@ -4838,7 +4838,7 @@ snapshots: hashery@1.4.0: dependencies: - hookified: 1.14.0 + hookified: 1.15.0 hasown@2.0.2: dependencies: @@ -4848,7 +4848,7 @@ snapshots: highlight.js@11.11.1: {} - hookified@1.14.0: {} + hookified@1.15.0: {} html-escaper@2.0.2: {} @@ -5256,9 +5256,9 @@ snapshots: dependencies: wrappy: 1.0.2 - openai@6.10.0(ws@8.18.3)(zod@4.3.5): + openai@6.10.0(ws@8.19.0)(zod@4.3.5): optionalDependencies: - ws: 8.18.3 + ws: 8.19.0 zod: 4.3.5 opus-decoder@0.7.11: @@ -5275,16 +5275,16 @@ snapshots: '@oxlint-tsgolint/win32-arm64': 0.10.1 '@oxlint-tsgolint/win32-x64': 0.10.1 - oxlint@1.36.0(oxlint-tsgolint@0.10.1): + oxlint@1.37.0(oxlint-tsgolint@0.10.1): optionalDependencies: - '@oxlint/darwin-arm64': 1.36.0 - '@oxlint/darwin-x64': 1.36.0 - '@oxlint/linux-arm64-gnu': 1.36.0 - '@oxlint/linux-arm64-musl': 1.36.0 - '@oxlint/linux-x64-gnu': 1.36.0 - '@oxlint/linux-x64-musl': 1.36.0 - '@oxlint/win32-arm64': 1.36.0 - '@oxlint/win32-x64': 1.36.0 + '@oxlint/darwin-arm64': 1.37.0 + '@oxlint/darwin-x64': 1.37.0 + '@oxlint/linux-arm64-gnu': 1.37.0 + '@oxlint/linux-arm64-musl': 1.37.0 + '@oxlint/linux-x64-gnu': 1.37.0 + '@oxlint/linux-x64-musl': 1.37.0 + '@oxlint/win32-arm64': 1.37.0 + '@oxlint/win32-x64': 1.37.0 oxlint-tsgolint: 0.10.1 p-finally@1.0.0: {} @@ -5294,7 +5294,7 @@ snapshots: eventemitter3: 4.0.7 p-timeout: 3.2.0 - p-queue@9.0.1: + p-queue@9.1.0: dependencies: eventemitter3: 5.0.1 p-timeout: 7.0.1 @@ -5453,7 +5453,7 @@ snapshots: qified@0.5.3: dependencies: - hookified: 1.14.0 + hookified: 1.15.0 qoa-format@1.0.1: dependencies: @@ -5876,7 +5876,7 @@ snapshots: undici@6.21.3: {} - undici@7.16.0: {} + undici@7.18.0: {} unicode-properties@1.4.1: dependencies: @@ -5995,7 +5995,7 @@ snapshots: wrappy@1.0.2: {} - ws@8.18.3: {} + ws@8.19.0: {} y18n@5.0.8: {} diff --git a/src/agents/pi-embedded-helpers.test.ts b/src/agents/pi-embedded-helpers.test.ts index 1fb719c2b..124965014 100644 --- a/src/agents/pi-embedded-helpers.test.ts +++ b/src/agents/pi-embedded-helpers.test.ts @@ -1,14 +1,17 @@ import type { AssistantMessage } from "@mariozechner/pi-ai"; import { describe, expect, it } from "vitest"; - +import type { ThinkLevel } from "../auto-reply/thinking.js"; import { isRateLimitAssistantError, pickFallbackThinkingLevel, } from "./pi-embedded-helpers.js"; -import type { ThinkLevel } from "../auto-reply/thinking.js"; const asAssistant = (overrides: Partial) => - ({ role: "assistant", stopReason: "error", ...overrides }) as AssistantMessage; + ({ + role: "assistant", + stopReason: "error", + ...overrides, + }) as AssistantMessage; describe("isRateLimitAssistantError", () => { it("detects 429 rate limit payloads", () => { @@ -57,8 +60,7 @@ describe("pickFallbackThinkingLevel", () => { it("skips already attempted levels", () => { const attempted = new Set(["low", "medium"]); const next = pickFallbackThinkingLevel({ - message: - "Supported values are: 'medium', 'high', and 'xhigh'.", + message: "Supported values are: 'medium', 'high', and 'xhigh'.", attempted, }); expect(next).toBe("high"); diff --git a/src/agents/pi-embedded-helpers.ts b/src/agents/pi-embedded-helpers.ts index 4cb5f86a2..7a03e02e8 100644 --- a/src/agents/pi-embedded-helpers.ts +++ b/src/agents/pi-embedded-helpers.ts @@ -6,7 +6,10 @@ import type { AgentToolResult, } from "@mariozechner/pi-agent-core"; import type { AssistantMessage } from "@mariozechner/pi-ai"; -import { normalizeThinkLevel, type ThinkLevel } from "../auto-reply/thinking.js"; +import { + normalizeThinkLevel, + type ThinkLevel, +} from "../auto-reply/thinking.js"; import { sanitizeContentBlocksImages } from "./tool-images.js"; import type { WorkspaceBootstrapFile } from "./workspace.js"; diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index 9b33fdda8..aec17853b 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -341,328 +341,336 @@ export async function runEmbeddedPiAgent(params: { let restoreSkillEnv: (() => void) | undefined; process.chdir(resolvedWorkspace); try { - const shouldLoadSkillEntries = - !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills; - const skillEntries = shouldLoadSkillEntries - ? loadWorkspaceSkillEntries(resolvedWorkspace) - : []; - const skillsSnapshot = - params.skillsSnapshot ?? - buildWorkspaceSkillSnapshot(resolvedWorkspace, { + const shouldLoadSkillEntries = + !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills; + const skillEntries = shouldLoadSkillEntries + ? loadWorkspaceSkillEntries(resolvedWorkspace) + : []; + const skillsSnapshot = + params.skillsSnapshot ?? + buildWorkspaceSkillSnapshot(resolvedWorkspace, { + config: params.config, + entries: skillEntries, + }); + const sandboxSessionKey = + params.sessionKey?.trim() || params.sessionId; + const sandbox = await resolveSandboxContext({ config: params.config, - entries: skillEntries, - }); - const sandboxSessionKey = params.sessionKey?.trim() || params.sessionId; - const sandbox = await resolveSandboxContext({ - config: params.config, - sessionKey: sandboxSessionKey, - workspaceDir: resolvedWorkspace, - }); - restoreSkillEnv = params.skillsSnapshot - ? applySkillEnvOverridesFromSnapshot({ - snapshot: params.skillsSnapshot, - config: params.config, - }) - : applySkillEnvOverrides({ - skills: skillEntries ?? [], - config: params.config, - }); - - const bootstrapFiles = - await loadWorkspaceBootstrapFiles(resolvedWorkspace); - const contextFiles = buildBootstrapContextFiles(bootstrapFiles); - const promptSkills = resolvePromptSkills(skillsSnapshot, skillEntries); - // Tool schemas must be provider-compatible (OpenAI requires top-level `type: "object"`). - // `createClawdbotCodingTools()` normalizes schemas so the session can pass them through unchanged. - const tools = createClawdbotCodingTools({ - bash: { - ...params.config?.agent?.bash, - elevated: params.bashElevated, - }, - sandbox, - surface: params.surface, - sessionKey: params.sessionKey ?? params.sessionId, - config: params.config, - }); - const machineName = await getMachineDisplayName(); - const runtimeInfo = { - host: machineName, - os: `${os.type()} ${os.release()}`, - arch: os.arch(), - node: process.version, - model: `${provider}/${modelId}`, - }; - const sandboxInfo = buildEmbeddedSandboxInfo(sandbox); - const reasoningTagHint = provider === "ollama"; - const systemPrompt = buildSystemPrompt({ - appendPrompt: buildAgentSystemPromptAppend({ + sessionKey: sandboxSessionKey, workspaceDir: resolvedWorkspace, - defaultThinkLevel: thinkLevel, - extraSystemPrompt: params.extraSystemPrompt, - ownerNumbers: params.ownerNumbers, - reasoningTagHint, - runtimeInfo, - sandboxInfo, - toolNames: tools.map((tool) => tool.name), - }), - contextFiles, - skills: promptSkills, - cwd: resolvedWorkspace, - tools, - }); + }); + restoreSkillEnv = params.skillsSnapshot + ? applySkillEnvOverridesFromSnapshot({ + snapshot: params.skillsSnapshot, + config: params.config, + }) + : applySkillEnvOverrides({ + skills: skillEntries ?? [], + config: params.config, + }); - const sessionManager = SessionManager.open(params.sessionFile); - const settingsManager = SettingsManager.create( - resolvedWorkspace, - agentDir, - ); - - // Split tools into built-in (recognized by pi-coding-agent SDK) and custom (clawdbot-specific) - const builtInToolNames = new Set(["read", "bash", "edit", "write"]); - const builtInTools = tools.filter((t) => builtInToolNames.has(t.name)); - const customTools = toToolDefinitions( - tools.filter((t) => !builtInToolNames.has(t.name)), - ); - - const { session } = await createAgentSession({ - cwd: resolvedWorkspace, - agentDir, - authStorage, - modelRegistry, - model, - thinkingLevel, - systemPrompt, - // Built-in tools recognized by pi-coding-agent SDK - tools: builtInTools, - // Custom clawdbot tools (browser, canvas, nodes, cron, etc.) - customTools, - sessionManager, - settingsManager, - skills: promptSkills, - contextFiles, - }); - - const prior = await sanitizeSessionMessagesImages( - session.messages, - "session:history", - ); - if (prior.length > 0) { - session.agent.replaceMessages(prior); - } - let aborted = Boolean(params.abortSignal?.aborted); - const abortRun = () => { - aborted = true; - void session.abort(); - }; - const queueHandle: EmbeddedPiQueueHandle = { - queueMessage: async (text: string) => { - await session.steer(text); - }, - isStreaming: () => session.isStreaming, - abort: abortRun, - }; - ACTIVE_EMBEDDED_RUNS.set(params.sessionId, queueHandle); - - const { - assistantTexts, - toolMetas, - unsubscribe, - waitForCompactionRetry, - } = subscribeEmbeddedPiSession({ - session, - runId: params.runId, - verboseLevel: params.verboseLevel, - shouldEmitToolResult: params.shouldEmitToolResult, - onToolResult: params.onToolResult, - onBlockReply: params.onBlockReply, - blockReplyBreak: params.blockReplyBreak, - blockReplyChunking: params.blockReplyChunking, - onPartialReply: params.onPartialReply, - onAgentEvent: params.onAgentEvent, - enforceFinalTag: params.enforceFinalTag, - }); - - let abortWarnTimer: NodeJS.Timeout | undefined; - const abortTimer = setTimeout( - () => { - log.warn( - `embedded run timeout: runId=${params.runId} sessionId=${params.sessionId} timeoutMs=${params.timeoutMs}`, - ); - abortRun(); - if (!abortWarnTimer) { - abortWarnTimer = setTimeout(() => { - if (!session.isStreaming) return; - log.warn( - `embedded run abort still streaming: runId=${params.runId} sessionId=${params.sessionId}`, - ); - }, 10_000); - } - }, - Math.max(1, params.timeoutMs), - ); - - let messagesSnapshot: AgentMessage[] = []; - let sessionIdUsed = session.sessionId; - const onAbort = () => { - abortRun(); - }; - if (params.abortSignal) { - if (params.abortSignal.aborted) { - onAbort(); - } else { - params.abortSignal.addEventListener("abort", onAbort, { - once: true, - }); - } - } - let promptError: unknown = null; - try { - const promptStartedAt = Date.now(); - log.debug( - `embedded run prompt start: runId=${params.runId} sessionId=${params.sessionId}`, + const bootstrapFiles = + await loadWorkspaceBootstrapFiles(resolvedWorkspace); + const contextFiles = buildBootstrapContextFiles(bootstrapFiles); + const promptSkills = resolvePromptSkills( + skillsSnapshot, + skillEntries, ); + // Tool schemas must be provider-compatible (OpenAI requires top-level `type: "object"`). + // `createClawdbotCodingTools()` normalizes schemas so the session can pass them through unchanged. + const tools = createClawdbotCodingTools({ + bash: { + ...params.config?.agent?.bash, + elevated: params.bashElevated, + }, + sandbox, + surface: params.surface, + sessionKey: params.sessionKey ?? params.sessionId, + config: params.config, + }); + const machineName = await getMachineDisplayName(); + const runtimeInfo = { + host: machineName, + os: `${os.type()} ${os.release()}`, + arch: os.arch(), + node: process.version, + model: `${provider}/${modelId}`, + }; + const sandboxInfo = buildEmbeddedSandboxInfo(sandbox); + const reasoningTagHint = provider === "ollama"; + const systemPrompt = buildSystemPrompt({ + appendPrompt: buildAgentSystemPromptAppend({ + workspaceDir: resolvedWorkspace, + defaultThinkLevel: thinkLevel, + extraSystemPrompt: params.extraSystemPrompt, + ownerNumbers: params.ownerNumbers, + reasoningTagHint, + runtimeInfo, + sandboxInfo, + toolNames: tools.map((tool) => tool.name), + }), + contextFiles, + skills: promptSkills, + cwd: resolvedWorkspace, + tools, + }); + + const sessionManager = SessionManager.open(params.sessionFile); + const settingsManager = SettingsManager.create( + resolvedWorkspace, + agentDir, + ); + + // Split tools into built-in (recognized by pi-coding-agent SDK) and custom (clawdbot-specific) + const builtInToolNames = new Set(["read", "bash", "edit", "write"]); + const builtInTools = tools.filter((t) => + builtInToolNames.has(t.name), + ); + const customTools = toToolDefinitions( + tools.filter((t) => !builtInToolNames.has(t.name)), + ); + + const { session } = await createAgentSession({ + cwd: resolvedWorkspace, + agentDir, + authStorage, + modelRegistry, + model, + thinkingLevel, + systemPrompt, + // Built-in tools recognized by pi-coding-agent SDK + tools: builtInTools, + // Custom clawdbot tools (browser, canvas, nodes, cron, etc.) + customTools, + sessionManager, + settingsManager, + skills: promptSkills, + contextFiles, + }); + + const prior = await sanitizeSessionMessagesImages( + session.messages, + "session:history", + ); + if (prior.length > 0) { + session.agent.replaceMessages(prior); + } + let aborted = Boolean(params.abortSignal?.aborted); + const abortRun = () => { + aborted = true; + void session.abort(); + }; + const queueHandle: EmbeddedPiQueueHandle = { + queueMessage: async (text: string) => { + await session.steer(text); + }, + isStreaming: () => session.isStreaming, + abort: abortRun, + }; + ACTIVE_EMBEDDED_RUNS.set(params.sessionId, queueHandle); + + const { + assistantTexts, + toolMetas, + unsubscribe, + waitForCompactionRetry, + } = subscribeEmbeddedPiSession({ + session, + runId: params.runId, + verboseLevel: params.verboseLevel, + shouldEmitToolResult: params.shouldEmitToolResult, + onToolResult: params.onToolResult, + onBlockReply: params.onBlockReply, + blockReplyBreak: params.blockReplyBreak, + blockReplyChunking: params.blockReplyChunking, + onPartialReply: params.onPartialReply, + onAgentEvent: params.onAgentEvent, + enforceFinalTag: params.enforceFinalTag, + }); + + let abortWarnTimer: NodeJS.Timeout | undefined; + const abortTimer = setTimeout( + () => { + log.warn( + `embedded run timeout: runId=${params.runId} sessionId=${params.sessionId} timeoutMs=${params.timeoutMs}`, + ); + abortRun(); + if (!abortWarnTimer) { + abortWarnTimer = setTimeout(() => { + if (!session.isStreaming) return; + log.warn( + `embedded run abort still streaming: runId=${params.runId} sessionId=${params.sessionId}`, + ); + }, 10_000); + } + }, + Math.max(1, params.timeoutMs), + ); + + let messagesSnapshot: AgentMessage[] = []; + let sessionIdUsed = session.sessionId; + const onAbort = () => { + abortRun(); + }; + if (params.abortSignal) { + if (params.abortSignal.aborted) { + onAbort(); + } else { + params.abortSignal.addEventListener("abort", onAbort, { + once: true, + }); + } + } + let promptError: unknown = null; try { - await session.prompt(params.prompt); - } catch (err) { - promptError = err; - } finally { + const promptStartedAt = Date.now(); log.debug( - `embedded run prompt end: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - promptStartedAt}`, + `embedded run prompt start: runId=${params.runId} sessionId=${params.sessionId}`, ); + try { + await session.prompt(params.prompt); + } catch (err) { + promptError = err; + } finally { + log.debug( + `embedded run prompt end: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - promptStartedAt}`, + ); + } + await waitForCompactionRetry(); + messagesSnapshot = session.messages.slice(); + sessionIdUsed = session.sessionId; + } finally { + clearTimeout(abortTimer); + if (abortWarnTimer) { + clearTimeout(abortWarnTimer); + abortWarnTimer = undefined; + } + unsubscribe(); + if (ACTIVE_EMBEDDED_RUNS.get(params.sessionId) === queueHandle) { + ACTIVE_EMBEDDED_RUNS.delete(params.sessionId); + notifyEmbeddedRunEnded(params.sessionId); + } + session.dispose(); + params.abortSignal?.removeEventListener?.("abort", onAbort); } - await waitForCompactionRetry(); - messagesSnapshot = session.messages.slice(); - sessionIdUsed = session.sessionId; - } finally { - clearTimeout(abortTimer); - if (abortWarnTimer) { - clearTimeout(abortWarnTimer); - abortWarnTimer = undefined; + if (promptError && !aborted) { + const fallbackThinking = pickFallbackThinkingLevel({ + message: + promptError instanceof Error + ? promptError.message + : String(promptError), + attempted: attemptedThinking, + }); + if (fallbackThinking) { + log.warn( + `unsupported thinking level for ${provider}/${modelId}; retrying with ${fallbackThinking}`, + ); + thinkLevel = fallbackThinking; + continue; + } + throw promptError; } - unsubscribe(); - if (ACTIVE_EMBEDDED_RUNS.get(params.sessionId) === queueHandle) { - ACTIVE_EMBEDDED_RUNS.delete(params.sessionId); - notifyEmbeddedRunEnded(params.sessionId); - } - session.dispose(); - params.abortSignal?.removeEventListener?.("abort", onAbort); - } - if (promptError && !aborted) { + + const lastAssistant = messagesSnapshot + .slice() + .reverse() + .find((m) => (m as AgentMessage)?.role === "assistant") as + | AssistantMessage + | undefined; + const fallbackThinking = pickFallbackThinkingLevel({ - message: - promptError instanceof Error - ? promptError.message - : String(promptError), + message: lastAssistant?.errorMessage, attempted: attemptedThinking, }); - if (fallbackThinking) { + if (fallbackThinking && !aborted) { log.warn( `unsupported thinking level for ${provider}/${modelId}; retrying with ${fallbackThinking}`, ); thinkLevel = fallbackThinking; continue; } - throw promptError; - } - const lastAssistant = messagesSnapshot - .slice() - .reverse() - .find((m) => (m as AgentMessage)?.role === "assistant") as - | AssistantMessage - | undefined; - - const fallbackThinking = pickFallbackThinkingLevel({ - message: lastAssistant?.errorMessage, - attempted: attemptedThinking, - }); - if (fallbackThinking && !aborted) { - log.warn( - `unsupported thinking level for ${provider}/${modelId}; retrying with ${fallbackThinking}`, - ); - thinkLevel = fallbackThinking; - continue; - } - - const fallbackConfigured = - (params.config?.agent?.modelFallbacks?.length ?? 0) > 0; - if (fallbackConfigured && isRateLimitAssistantError(lastAssistant)) { - const message = - lastAssistant?.errorMessage?.trim() || - (lastAssistant ? formatAssistantErrorText(lastAssistant) : "") || - "LLM request rate limited."; - throw new Error(message); - } - - const usage = lastAssistant?.usage; - const agentMeta: EmbeddedPiAgentMeta = { - sessionId: sessionIdUsed, - provider: lastAssistant?.provider ?? provider, - model: lastAssistant?.model ?? model.id, - usage: usage - ? { - input: usage.input, - output: usage.output, - cacheRead: usage.cacheRead, - cacheWrite: usage.cacheWrite, - total: usage.totalTokens, - } - : undefined, - }; - - const replyItems: Array<{ text: string; media?: string[] }> = []; - - const errorText = lastAssistant - ? formatAssistantErrorText(lastAssistant) - : undefined; - if (errorText) replyItems.push({ text: errorText }); - - const inlineToolResults = - params.verboseLevel === "on" && - !params.onPartialReply && - !params.onToolResult && - toolMetas.length > 0; - if (inlineToolResults) { - for (const { toolName, meta } of toolMetas) { - const agg = formatToolAggregate(toolName, meta ? [meta] : []); - const { text: cleanedText, mediaUrls } = splitMediaFromOutput(agg); - if (cleanedText) - replyItems.push({ text: cleanedText, media: mediaUrls }); + const fallbackConfigured = + (params.config?.agent?.modelFallbacks?.length ?? 0) > 0; + if (fallbackConfigured && isRateLimitAssistantError(lastAssistant)) { + const message = + lastAssistant?.errorMessage?.trim() || + (lastAssistant ? formatAssistantErrorText(lastAssistant) : "") || + "LLM request rate limited."; + throw new Error(message); } - } - for (const text of assistantTexts.length - ? assistantTexts - : lastAssistant - ? [extractAssistantText(lastAssistant)] - : []) { - const { text: cleanedText, mediaUrls } = splitMediaFromOutput(text); - if (!cleanedText && (!mediaUrls || mediaUrls.length === 0)) continue; - replyItems.push({ text: cleanedText, media: mediaUrls }); - } + const usage = lastAssistant?.usage; + const agentMeta: EmbeddedPiAgentMeta = { + sessionId: sessionIdUsed, + provider: lastAssistant?.provider ?? provider, + model: lastAssistant?.model ?? model.id, + usage: usage + ? { + input: usage.input, + output: usage.output, + cacheRead: usage.cacheRead, + cacheWrite: usage.cacheWrite, + total: usage.totalTokens, + } + : undefined, + }; - const payloads = replyItems - .map((item) => ({ - text: item.text?.trim() ? item.text.trim() : undefined, - mediaUrls: item.media?.length ? item.media : undefined, - mediaUrl: item.media?.[0], - })) - .filter( - (p) => - p.text || p.mediaUrl || (p.mediaUrls && p.mediaUrls.length > 0), + const replyItems: Array<{ text: string; media?: string[] }> = []; + + const errorText = lastAssistant + ? formatAssistantErrorText(lastAssistant) + : undefined; + if (errorText) replyItems.push({ text: errorText }); + + const inlineToolResults = + params.verboseLevel === "on" && + !params.onPartialReply && + !params.onToolResult && + toolMetas.length > 0; + if (inlineToolResults) { + for (const { toolName, meta } of toolMetas) { + const agg = formatToolAggregate(toolName, meta ? [meta] : []); + const { text: cleanedText, mediaUrls } = + splitMediaFromOutput(agg); + if (cleanedText) + replyItems.push({ text: cleanedText, media: mediaUrls }); + } + } + + for (const text of assistantTexts.length + ? assistantTexts + : lastAssistant + ? [extractAssistantText(lastAssistant)] + : []) { + const { text: cleanedText, mediaUrls } = splitMediaFromOutput(text); + if (!cleanedText && (!mediaUrls || mediaUrls.length === 0)) + continue; + replyItems.push({ text: cleanedText, media: mediaUrls }); + } + + const payloads = replyItems + .map((item) => ({ + text: item.text?.trim() ? item.text.trim() : undefined, + mediaUrls: item.media?.length ? item.media : undefined, + mediaUrl: item.media?.[0], + })) + .filter( + (p) => + p.text || p.mediaUrl || (p.mediaUrls && p.mediaUrls.length > 0), + ); + + log.debug( + `embedded run done: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - started} aborted=${aborted}`, ); - - log.debug( - `embedded run done: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - started} aborted=${aborted}`, - ); - return { - payloads: payloads.length ? payloads : undefined, - meta: { - durationMs: Date.now() - started, - agentMeta, - aborted, - }, - }; + return { + payloads: payloads.length ? payloads : undefined, + meta: { + durationMs: Date.now() - started, + agentMeta, + aborted, + }, + }; } finally { restoreSkillEnv?.(); process.chdir(prevCwd); diff --git a/src/auto-reply/heartbeat.ts b/src/auto-reply/heartbeat.ts index ba0fa9868..d4b57bfe2 100644 --- a/src/auto-reply/heartbeat.ts +++ b/src/auto-reply/heartbeat.ts @@ -1,6 +1,7 @@ import { HEARTBEAT_TOKEN } from "./tokens.js"; export const HEARTBEAT_PROMPT = "HEARTBEAT"; +export const DEFAULT_HEARTBEAT_ACK_MAX_CHARS = 30; export type StripHeartbeatMode = "heartbeat" | "message"; @@ -44,7 +45,10 @@ export function stripHeartbeatToken( if (!trimmed) return { shouldSkip: true, text: "", didStrip: false }; const mode: StripHeartbeatMode = opts.mode ?? "message"; - const maxAckChars = Math.max(0, opts.maxAckChars ?? 30); + const maxAckChars = Math.max( + 0, + opts.maxAckChars ?? DEFAULT_HEARTBEAT_ACK_MAX_CHARS, + ); if (!trimmed.includes(HEARTBEAT_TOKEN)) { return { shouldSkip: false, text: trimmed, didStrip: false }; diff --git a/src/config/types.ts b/src/config/types.ts index 0eec44357..ee1b4a332 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -726,6 +726,8 @@ export type ClawdbotConfig = { to?: string; /** Override the heartbeat prompt body (default: "HEARTBEAT"). */ prompt?: string; + /** Max chars allowed after HEARTBEAT_OK before delivery (default: 30). */ + ackMaxChars?: number; }; /** Max concurrent agent runs across all conversations. Default: 1 (sequential). */ maxConcurrent?: number; diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index 8a598ff5c..cce97db56 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -172,6 +172,7 @@ const HeartbeatSchema = z .optional(), to: z.string().optional(), prompt: z.string().optional(), + ackMaxChars: z.number().int().nonnegative().optional(), }) .superRefine((val, ctx) => { if (!val.every) return; diff --git a/src/cron/isolated-agent.test.ts b/src/cron/isolated-agent.test.ts index 4c93ee04b..23b29e6b2 100644 --- a/src/cron/isolated-agent.test.ts +++ b/src/cron/isolated-agent.test.ts @@ -553,4 +553,48 @@ describe("runCronIsolatedAgentTurn", () => { ); }); }); + + it("delivers when heartbeat ack padding exceeds configured limit", async () => { + await withTempHome(async (home) => { + const storePath = await writeSessionStore(home); + const deps: CliDeps = { + sendMessageWhatsApp: vi.fn(), + sendMessageTelegram: vi.fn().mockResolvedValue({ + messageId: "t1", + chatId: "123", + }), + sendMessageDiscord: vi.fn(), + sendMessageSignal: vi.fn(), + sendMessageIMessage: vi.fn(), + }; + vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ + payloads: [{ text: "HEARTBEAT_OK 🦞" }], + meta: { + durationMs: 5, + agentMeta: { sessionId: "s", provider: "p", model: "m" }, + }, + }); + + const cfg = makeCfg(home, storePath); + cfg.agent = { ...cfg.agent, heartbeat: { ackMaxChars: 0 } }; + + const res = await runCronIsolatedAgentTurn({ + cfg, + deps, + job: makeJob({ + kind: "agentTurn", + message: "do it", + deliver: true, + channel: "telegram", + to: "123", + }), + message: "do it", + sessionKey: "cron:job-1", + lane: "cron", + }); + + expect(res.status).toBe("ok"); + expect(deps.sendMessageTelegram).toHaveBeenCalled(); + }); + }); }); diff --git a/src/cron/isolated-agent.ts b/src/cron/isolated-agent.ts index da5a95c81..93c24083a 100644 --- a/src/cron/isolated-agent.ts +++ b/src/cron/isolated-agent.ts @@ -18,7 +18,10 @@ import { ensureAgentWorkspace, } from "../agents/workspace.js"; import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; -import { stripHeartbeatToken } from "../auto-reply/heartbeat.js"; +import { + DEFAULT_HEARTBEAT_ACK_MAX_CHARS, + stripHeartbeatToken, +} from "../auto-reply/heartbeat.js"; import { normalizeThinkLevel } from "../auto-reply/thinking.js"; import type { CliDeps } from "../cli/deps.js"; import type { ClawdbotConfig } from "../config/config.js"; @@ -64,6 +67,7 @@ function pickSummaryFromPayloads( */ function isHeartbeatOnlyResponse( payloads: Array<{ text?: string; mediaUrl?: string; mediaUrls?: string[] }>, + ackMaxChars: number, ) { if (payloads.length === 0) return true; return payloads.every((payload) => { @@ -72,11 +76,13 @@ function isHeartbeatOnlyResponse( (payload.mediaUrls?.length ?? 0) > 0 || Boolean(payload.mediaUrl); if (hasMedia) return false; // Use heartbeat mode to check if text is just HEARTBEAT_OK or short ack. - const result = stripHeartbeatToken(payload.text, { mode: "heartbeat" }); + const result = stripHeartbeatToken(payload.text, { + mode: "heartbeat", + maxAckChars: ackMaxChars, + }); return result.shouldSkip; }); } - function resolveDeliveryTarget( cfg: ClawdbotConfig, jobPayload: { @@ -366,7 +372,10 @@ export async function runCronIsolatedAgentTurn(params: { // Skip delivery for heartbeat-only responses (HEARTBEAT_OK with no real content). // This allows cron jobs to silently ack when nothing to report but still deliver // actual content when there is something to say. - const skipHeartbeatDelivery = delivery && isHeartbeatOnlyResponse(payloads); + const ackMaxChars = + params.cfg.agent?.heartbeat?.ackMaxChars ?? DEFAULT_HEARTBEAT_ACK_MAX_CHARS; + const skipHeartbeatDelivery = + delivery && isHeartbeatOnlyResponse(payloads, Math.max(0, ackMaxChars)); if (delivery && !skipHeartbeatDelivery) { if (resolvedDelivery.channel === "whatsapp") { diff --git a/src/infra/heartbeat-runner.test.ts b/src/infra/heartbeat-runner.test.ts index c555e237b..107c66b9e 100644 --- a/src/infra/heartbeat-runner.test.ts +++ b/src/infra/heartbeat-runner.test.ts @@ -181,6 +181,64 @@ describe("runHeartbeatOnce", () => { } }); + it("respects ackMaxChars for heartbeat acks", async () => { + const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-")); + const storePath = path.join(tmpDir, "sessions.json"); + const replySpy = vi.spyOn(replyModule, "getReplyFromConfig"); + try { + await fs.writeFile( + storePath, + JSON.stringify( + { + main: { + sessionId: "sid", + updatedAt: Date.now(), + lastChannel: "whatsapp", + lastTo: "+1555", + }, + }, + null, + 2, + ), + ); + + const cfg: ClawdbotConfig = { + agent: { + heartbeat: { + every: "5m", + target: "whatsapp", + to: "+1555", + ackMaxChars: 0, + }, + }, + whatsapp: { allowFrom: ["*"] }, + session: { store: storePath }, + }; + + replySpy.mockResolvedValue({ text: "HEARTBEAT_OK 🦞" }); + const sendWhatsApp = vi.fn().mockResolvedValue({ + messageId: "m1", + toJid: "jid", + }); + + await runHeartbeatOnce({ + cfg, + deps: { + sendWhatsApp, + getQueueSize: () => 0, + nowMs: () => 0, + webAuthExists: async () => true, + hasActiveWebListener: () => true, + }, + }); + + expect(sendWhatsApp).toHaveBeenCalled(); + } finally { + replySpy.mockRestore(); + await fs.rm(tmpDir, { recursive: true, force: true }); + } + }); + it("skips WhatsApp delivery when not linked or running", async () => { const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-hb-")); const storePath = path.join(tmpDir, "sessions.json"); diff --git a/src/infra/heartbeat-runner.ts b/src/infra/heartbeat-runner.ts index c78630ceb..9f136e3df 100644 --- a/src/infra/heartbeat-runner.ts +++ b/src/infra/heartbeat-runner.ts @@ -1,5 +1,6 @@ import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; import { + DEFAULT_HEARTBEAT_ACK_MAX_CHARS, HEARTBEAT_PROMPT, stripHeartbeatToken, } from "../auto-reply/heartbeat.js"; @@ -102,6 +103,13 @@ export function resolveHeartbeatPrompt(cfg: ClawdbotConfig) { return trimmed || HEARTBEAT_PROMPT; } +function resolveHeartbeatAckMaxChars(cfg: ClawdbotConfig) { + return Math.max( + 0, + cfg.agent?.heartbeat?.ackMaxChars ?? DEFAULT_HEARTBEAT_ACK_MAX_CHARS, + ); +} + function resolveHeartbeatSession(cfg: ClawdbotConfig) { const sessionCfg = cfg.session; const scope = sessionCfg?.scope ?? "per-sender"; @@ -277,11 +285,12 @@ async function restoreHeartbeatUpdatedAt(params: { function normalizeHeartbeatReply( payload: ReplyPayload, - responsePrefix?: string, + responsePrefix: string | undefined, + ackMaxChars: number, ) { const stripped = stripHeartbeatToken(payload.text, { mode: "heartbeat", - maxAckChars: 30, + maxAckChars: ackMaxChars, }); const hasMedia = Boolean( payload.mediaUrl || (payload.mediaUrls?.length ?? 0) > 0, @@ -478,9 +487,11 @@ export async function runHeartbeatOnce(opts: { return { status: "ran", durationMs: Date.now() - startedAt }; } + const ackMaxChars = resolveHeartbeatAckMaxChars(cfg); const normalized = normalizeHeartbeatReply( replyPayload, cfg.messages?.responsePrefix, + ackMaxChars, ); if (normalized.shouldSkip && !normalized.hasMedia) { await restoreHeartbeatUpdatedAt({ diff --git a/src/web/auto-reply.ts b/src/web/auto-reply.ts index 4600d6682..089723ed6 100644 --- a/src/web/auto-reply.ts +++ b/src/web/auto-reply.ts @@ -5,6 +5,7 @@ import { parseActivationCommand, } from "../auto-reply/group-activation.js"; import { + DEFAULT_HEARTBEAT_ACK_MAX_CHARS, HEARTBEAT_PROMPT, stripHeartbeatToken, } from "../auto-reply/heartbeat.js"; @@ -369,9 +370,13 @@ export async function runWebHeartbeatOnce(opts: { const hasMedia = Boolean( replyPayload.mediaUrl || (replyPayload.mediaUrls?.length ?? 0) > 0, ); + const ackMaxChars = Math.max( + 0, + cfg.agent?.heartbeat?.ackMaxChars ?? DEFAULT_HEARTBEAT_ACK_MAX_CHARS, + ); const stripped = stripHeartbeatToken(replyPayload.text, { mode: "heartbeat", - maxAckChars: 30, + maxAckChars: ackMaxChars, }); if (stripped.shouldSkip && !hasMedia) { // Don't let heartbeats keep sessions alive: restore previous updatedAt so idle expiry still works. From ac3dedaa1b0fc3d1b6fcabafaec56091fc5f9609 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 23:02:13 +0000 Subject: [PATCH 025/110] feat: standardize timestamps to UTC --- CHANGELOG.md | 3 +++ docs/configuration.md | 16 ++++++++--- docs/timezone.md | 40 +++++++++++++++++++++++++++ src/agents/pi-embedded-runner.ts | 46 ++++++++++++++++++++++++++++++++ src/agents/system-prompt.test.ts | 12 +++++++++ src/agents/system-prompt.ts | 8 ++++++ src/auto-reply/envelope.test.ts | 10 +++---- src/auto-reply/envelope.ts | 26 ++++++------------ src/config/types.ts | 3 ++- src/config/zod-schema.ts | 2 +- src/telegram/bot.test.ts | 2 +- src/web/auto-reply.test.ts | 12 ++------- src/web/inbound.media.test.ts | 1 - src/web/monitor-inbox.test.ts | 12 --------- src/web/test-helpers.ts | 1 - 15 files changed, 140 insertions(+), 54 deletions(-) create mode 100644 docs/timezone.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 75425cd7f..561d3b69d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ ## Unreleased +### Breaking +- Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only). + ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. diff --git a/docs/configuration.md b/docs/configuration.md index deb2a0eda..534e90d6b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -432,16 +432,26 @@ Default: `~/clawd`. If `agent.sandbox` is enabled, non-main sessions can override this with their own per-session workspaces under `agent.sandbox.workspaceRoot`. +### `agent.userTimezone` + +Sets the user’s timezone for **system prompt context** (not for timestamps in +message envelopes). If unset, Clawdbot uses the host timezone at runtime. + +```json5 +{ + agent: { userTimezone: "America/Chicago" } +} +``` + ### `messages` -Controls inbound/outbound prefixes and timestamps. +Controls inbound/outbound prefixes. ```json5 { messages: { messagePrefix: "[clawdbot]", - responsePrefix: "🦞", - timestampPrefix: "Europe/London" + responsePrefix: "🦞" } } ``` diff --git a/docs/timezone.md b/docs/timezone.md new file mode 100644 index 000000000..8a9d0ca6a --- /dev/null +++ b/docs/timezone.md @@ -0,0 +1,40 @@ +--- +summary: "Timezone handling for agents, envelopes, and prompts" +read_when: + - You need to understand how timestamps are normalized for the model + - Configuring the user timezone for system prompts +--- + +# Timezones + +Clawdbot standardizes timestamps so the model sees a **single reference time**. + +## Message envelopes (UTC) + +Inbound messages are wrapped in an envelope like: + +``` +[Surface ... 2026-01-05T21:26Z] message text +``` + +The timestamp in the envelope is **always UTC**, with minutes precision. + +## Tool payloads (raw provider data) + +Tool calls (`discord.readMessages`, `slack.readMessages`, etc.) return **raw provider timestamps**. +These are typically UTC ISO strings (Discord) or UTC epoch strings (Slack). We do not rewrite them. + +## User timezone for the system prompt + +Set `agent.userTimezone` to tell the model the user's local time zone. If it is +unset, Clawdbot resolves the **host timezone at runtime** (no config write). + +```json5 +{ + agent: { userTimezone: "America/Chicago" } +} +``` + +The system prompt includes: +- `User timezone: America/Chicago` +- `Current user time: 2026-01-05 15:26` diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index aec17853b..c1ec121c3 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -116,6 +116,46 @@ function resolveGlobalLane(lane?: string) { return cleaned ? cleaned : "main"; } +function resolveUserTimezone(configured?: string): string { + const trimmed = configured?.trim(); + if (trimmed) { + try { + new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).format( + new Date(), + ); + return trimmed; + } catch { + // ignore invalid timezone + } + } + const host = Intl.DateTimeFormat().resolvedOptions().timeZone; + return host?.trim() || "UTC"; +} + +function formatUserTime(date: Date, timeZone: string): string | undefined { + try { + const parts = new Intl.DateTimeFormat("en-CA", { + timeZone, + year: "numeric", + month: "2-digit", + day: "2-digit", + hour: "2-digit", + minute: "2-digit", + hourCycle: "h23", + }).formatToParts(date); + const map: Record = {}; + for (const part of parts) { + if (part.type !== "literal") map[part.type] = part.value; + } + if (!map.year || !map.month || !map.day || !map.hour || !map.minute) { + return undefined; + } + return `${map.year}-${map.month}-${map.day} ${map.hour}:${map.minute}`; + } catch { + return undefined; + } +} + export function buildEmbeddedSandboxInfo( sandbox?: Awaited>, ): EmbeddedSandboxInfo | undefined { @@ -398,6 +438,10 @@ export async function runEmbeddedPiAgent(params: { }; const sandboxInfo = buildEmbeddedSandboxInfo(sandbox); const reasoningTagHint = provider === "ollama"; + const userTimezone = resolveUserTimezone( + params.config?.agent?.userTimezone, + ); + const userTime = formatUserTime(new Date(), userTimezone); const systemPrompt = buildSystemPrompt({ appendPrompt: buildAgentSystemPromptAppend({ workspaceDir: resolvedWorkspace, @@ -408,6 +452,8 @@ export async function runEmbeddedPiAgent(params: { runtimeInfo, sandboxInfo, toolNames: tools.map((tool) => tool.name), + userTimezone, + userTime, }), contextFiles, skills: promptSkills, diff --git a/src/agents/system-prompt.test.ts b/src/agents/system-prompt.test.ts index 802feef77..e2bc2fe7b 100644 --- a/src/agents/system-prompt.test.ts +++ b/src/agents/system-prompt.test.ts @@ -46,4 +46,16 @@ describe("buildAgentSystemPromptAppend", () => { expect(prompt).toContain("sessions_send"); expect(prompt).toContain("Unavailable tools (do not call):"); }); + + it("includes user time when provided", () => { + const prompt = buildAgentSystemPromptAppend({ + workspaceDir: "/tmp/clawd", + userTimezone: "America/Chicago", + userTime: "2026-01-05 15:26", + }); + + expect(prompt).toContain("## Time"); + expect(prompt).toContain("User timezone: America/Chicago"); + expect(prompt).toContain("Current user time: 2026-01-05 15:26"); + }); }); diff --git a/src/agents/system-prompt.ts b/src/agents/system-prompt.ts index 7d97aff24..4528d372d 100644 --- a/src/agents/system-prompt.ts +++ b/src/agents/system-prompt.ts @@ -7,6 +7,8 @@ export function buildAgentSystemPromptAppend(params: { ownerNumbers?: string[]; reasoningTagHint?: boolean; toolNames?: string[]; + userTimezone?: string; + userTime?: string; runtimeInfo?: { host?: string; os?: string; @@ -109,6 +111,8 @@ export function buildAgentSystemPromptAppend(params: { "Hey there! What would you like to do next?", ].join(" ") : undefined; + const userTimezone = params.userTimezone?.trim(); + const userTime = params.userTime?.trim(); const runtimeInfo = params.runtimeInfo; const runtimeLines: string[] = []; if (runtimeInfo?.host) runtimeLines.push(`Host: ${runtimeInfo.host}`); @@ -182,6 +186,10 @@ export function buildAgentSystemPromptAppend(params: { "Never send streaming/partial replies to external messaging surfaces; only final replies should be delivered there.", "Clawdbot handles message transport automatically; respond normally and your reply will be delivered to the current chat.", "", + userTimezone || userTime ? "## Time" : "", + userTimezone ? `User timezone: ${userTimezone}` : "", + userTime ? `Current user time: ${userTime}` : "", + userTimezone || userTime ? "" : "", "## Reply Tags", "To request a native reply/quote on supported surfaces, include one tag in your reply:", "- [[reply_to_current]] replies to the triggering message.", diff --git a/src/auto-reply/envelope.test.ts b/src/auto-reply/envelope.test.ts index 90f8b9ef0..d5ae06674 100644 --- a/src/auto-reply/envelope.test.ts +++ b/src/auto-reply/envelope.test.ts @@ -19,12 +19,12 @@ describe("formatAgentEnvelope", () => { process.env.TZ = originalTz; - expect(body).toMatch( - /^\[WebChat user1 mac-mini 10\.0\.0\.5 2025-01-02T03:04\+00:00\{.+\}\] hello$/, + expect(body).toBe( + "[WebChat user1 mac-mini 10.0.0.5 2025-01-02T03:04Z] hello", ); }); - it("formats timestamps in local time (not UTC)", () => { + it("formats timestamps in UTC regardless of local timezone", () => { const originalTz = process.env.TZ; process.env.TZ = "America/Los_Angeles"; @@ -37,9 +37,7 @@ describe("formatAgentEnvelope", () => { process.env.TZ = originalTz; - expect(body).toBe( - "[WebChat 2025-01-01T19:04-08:00{America/Los_Angeles}] hello", - ); + expect(body).toBe("[WebChat 2025-01-02T03:04Z] hello"); }); it("handles missing optional fields", () => { diff --git a/src/auto-reply/envelope.ts b/src/auto-reply/envelope.ts index fc5ad21fe..6238e5c82 100644 --- a/src/auto-reply/envelope.ts +++ b/src/auto-reply/envelope.ts @@ -12,25 +12,15 @@ function formatTimestamp(ts?: number | Date): string | undefined { const date = ts instanceof Date ? ts : new Date(ts); if (Number.isNaN(date.getTime())) return undefined; - const yyyy = String(date.getFullYear()).padStart(4, "0"); - const mm = String(date.getMonth() + 1).padStart(2, "0"); - const dd = String(date.getDate()).padStart(2, "0"); - const hh = String(date.getHours()).padStart(2, "0"); - const min = String(date.getMinutes()).padStart(2, "0"); + const yyyy = String(date.getUTCFullYear()).padStart(4, "0"); + const mm = String(date.getUTCMonth() + 1).padStart(2, "0"); + const dd = String(date.getUTCDate()).padStart(2, "0"); + const hh = String(date.getUTCHours()).padStart(2, "0"); + const min = String(date.getUTCMinutes()).padStart(2, "0"); - // getTimezoneOffset() is minutes *behind* UTC. Flip sign to get ISO offset. - const offsetMinutes = -date.getTimezoneOffset(); - const sign = offsetMinutes >= 0 ? "+" : "-"; - const absOffsetMinutes = Math.abs(offsetMinutes); - const offsetH = String(Math.floor(absOffsetMinutes / 60)).padStart(2, "0"); - const offsetM = String(absOffsetMinutes % 60).padStart(2, "0"); - - const tz = Intl.DateTimeFormat().resolvedOptions().timeZone; - const tzSuffix = tz ? `{${tz}}` : ""; - - // Compact ISO-like *local* timestamp with minutes precision. - // Example: 2025-01-02T03:04-08:00{America/Los_Angeles} - return `${yyyy}-${mm}-${dd}T${hh}:${min}${sign}${offsetH}:${offsetM}${tzSuffix}`; + // Compact ISO-like UTC timestamp with minutes precision. + // Example: 2025-01-02T03:04Z + return `${yyyy}-${mm}-${dd}T${hh}:${min}Z`; } export function formatAgentEnvelope(params: AgentEnvelopeParams): string { diff --git a/src/config/types.ts b/src/config/types.ts index ee1b4a332..3db517bf1 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -445,7 +445,6 @@ export type RoutingConfig = { export type MessagesConfig = { messagePrefix?: string; // Prefix added to all inbound messages (default: "[clawdbot]" if no allowFrom, else "") responsePrefix?: string; // Prefix auto-added to all outbound replies (e.g., "🦞") - timestampPrefix?: boolean | string; // true/false or IANA timezone string (default: true with UTC) }; export type BridgeBindMode = "auto" | "lan" | "tailnet" | "loopback"; @@ -672,6 +671,8 @@ export type ClawdbotConfig = { imageModel?: string; /** Agent working directory (preferred). Used as the default cwd for agent runs. */ workspace?: string; + /** Optional IANA timezone for the user (used in system prompt; defaults to host timezone). */ + userTimezone?: string; /** Optional allowlist for /model (provider/model or model-only). */ allowedModels?: string[]; /** Optional model aliases for /model (alias -> provider/model). */ diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index cce97db56..c047b920e 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -150,7 +150,6 @@ const MessagesSchema = z .object({ messagePrefix: z.string().optional(), responsePrefix: z.string().optional(), - timestampPrefix: z.union([z.boolean(), z.string()]).optional(), }) .optional(); @@ -376,6 +375,7 @@ export const ClawdbotSchema = z.object({ model: z.string().optional(), imageModel: z.string().optional(), workspace: z.string().optional(), + userTimezone: z.string().optional(), allowedModels: z.array(z.string()).optional(), modelAliases: z.record(z.string(), z.string()).optional(), modelFallbacks: z.array(z.string()).optional(), diff --git a/src/telegram/bot.test.ts b/src/telegram/bot.test.ts index 26f82f659..594958389 100644 --- a/src/telegram/bot.test.ts +++ b/src/telegram/bot.test.ts @@ -101,7 +101,7 @@ describe("createTelegramBot", () => { expect(replySpy).toHaveBeenCalledTimes(1); const payload = replySpy.mock.calls[0][0]; expect(payload.Body).toMatch( - /^\[Telegram Ada Lovelace \(@ada_bot\) id:1234 2025-01-09T01:00\+01:00\{Europe\/Vienna\}\]/, + /^\[Telegram Ada Lovelace \(@ada_bot\) id:1234 2025-01-09T00:00Z\]/, ); expect(payload.Body).toContain("hello world"); } finally { diff --git a/src/web/auto-reply.test.ts b/src/web/auto-reply.test.ts index 05fd023a9..02f77c23d 100644 --- a/src/web/auto-reply.test.ts +++ b/src/web/auto-reply.test.ts @@ -465,9 +465,6 @@ describe("web auto-reply", () => { }; setLoadConfigMock(() => ({ - messages: { - timestampPrefix: "UTC", - }, session: { store: store.storePath }, })); @@ -500,11 +497,11 @@ describe("web auto-reply", () => { const firstArgs = resolver.mock.calls[0][0]; const secondArgs = resolver.mock.calls[1][0]; expect(firstArgs.Body).toContain( - "[WhatsApp +1 2025-01-01T01:00+01:00{Europe/Vienna}] [clawdbot] first", + "[WhatsApp +1 2025-01-01T00:00Z] [clawdbot] first", ); expect(firstArgs.Body).not.toContain("second"); expect(secondArgs.Body).toContain( - "[WhatsApp +1 2025-01-01T02:00+01:00{Europe/Vienna}] [clawdbot] second", + "[WhatsApp +1 2025-01-01T01:00Z] [clawdbot] second", ); expect(secondArgs.Body).not.toContain("first"); @@ -1350,7 +1347,6 @@ describe("web auto-reply", () => { messages: { messagePrefix: "[same-phone]", responsePrefix: undefined, - timestampPrefix: false, }, })); @@ -1475,7 +1471,6 @@ describe("web auto-reply", () => { messages: { messagePrefix: undefined, responsePrefix: "🦞", - timestampPrefix: false, }, })); @@ -1520,7 +1515,6 @@ describe("web auto-reply", () => { messages: { messagePrefix: undefined, responsePrefix: "🦞", - timestampPrefix: false, }, })); @@ -1565,7 +1559,6 @@ describe("web auto-reply", () => { messages: { messagePrefix: undefined, responsePrefix: "🦞", - timestampPrefix: false, }, })); @@ -1611,7 +1604,6 @@ describe("web auto-reply", () => { messages: { messagePrefix: undefined, responsePrefix: "🦞", - timestampPrefix: false, }, })); diff --git a/src/web/inbound.media.test.ts b/src/web/inbound.media.test.ts index a1cfb9a6b..fb4fd78ec 100644 --- a/src/web/inbound.media.test.ts +++ b/src/web/inbound.media.test.ts @@ -16,7 +16,6 @@ vi.mock("../config/config.js", async (importOriginal) => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }), }; diff --git a/src/web/monitor-inbox.test.ts b/src/web/monitor-inbox.test.ts index ab8aa4525..483121a3e 100644 --- a/src/web/monitor-inbox.test.ts +++ b/src/web/monitor-inbox.test.ts @@ -16,7 +16,6 @@ const mockLoadConfig = vi.fn().mockReturnValue({ messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -480,7 +479,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -536,7 +534,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -576,7 +573,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -592,7 +588,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -628,7 +623,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -643,7 +637,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -685,7 +678,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -720,7 +712,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -737,7 +728,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -773,7 +763,6 @@ describe("web monitor inbox", () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); @@ -840,7 +829,6 @@ it("defaults to self-only when no config is present", async () => { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }); diff --git a/src/web/test-helpers.ts b/src/web/test-helpers.ts index 968d7649c..e1c1597aa 100644 --- a/src/web/test-helpers.ts +++ b/src/web/test-helpers.ts @@ -13,7 +13,6 @@ const DEFAULT_CONFIG = { messages: { messagePrefix: undefined, responsePrefix: undefined, - timestampPrefix: false, }, }; From 20e00eb89b30368aa162628f99ba74f9abe230dc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 23:05:57 +0000 Subject: [PATCH 026/110] fix: normalize unknown prompt errors --- src/agents/pi-embedded-runner.ts | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index c1ec121c3..3663ad0b2 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -156,6 +156,17 @@ function formatUserTime(date: Date, timeZone: string): string | undefined { } } +function describeUnknownError(error: unknown): string { + if (error instanceof Error) return error.message; + if (typeof error === "string") return error; + try { + const serialized = JSON.stringify(error); + return serialized ?? "Unknown error"; + } catch { + return "Unknown error"; + } +} + export function buildEmbeddedSandboxInfo( sandbox?: Awaited>, ): EmbeddedSandboxInfo | undefined { @@ -601,10 +612,7 @@ export async function runEmbeddedPiAgent(params: { } if (promptError && !aborted) { const fallbackThinking = pickFallbackThinkingLevel({ - message: - promptError instanceof Error - ? promptError.message - : String(promptError), + message: describeUnknownError(promptError), attempted: attemptedThinking, }); if (fallbackThinking) { From 2ec9d75ac2d8ff7809c87323880382727048fb3e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 00:26:37 +0100 Subject: [PATCH 027/110] feat: add 1password skill --- CHANGELOG.md | 1 + skills/1password/SKILL.md | 30 +++++++++++++++++++++ skills/1password/references/cli-examples.md | 29 ++++++++++++++++++++ skills/1password/references/get-started.md | 17 ++++++++++++ 4 files changed, 77 insertions(+) create mode 100644 skills/1password/SKILL.md create mode 100644 skills/1password/references/cli-examples.md create mode 100644 skills/1password/references/get-started.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 561d3b69d..73e188275 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,7 @@ ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. - Skills: add CodexBar model usage helper with macOS requirement metadata. +- Skills: add 1Password CLI skill with op examples. - Lint: organize imports and wrap long lines in reply commands. - Deps: update to latest across the repo. diff --git a/skills/1password/SKILL.md b/skills/1password/SKILL.md new file mode 100644 index 000000000..35bcb5a34 --- /dev/null +++ b/skills/1password/SKILL.md @@ -0,0 +1,30 @@ +--- +name: 1password +description: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op. +homepage: https://developer.1password.com/docs/cli/get-started/ +metadata: {"clawdbot":{"emoji":"🔐","requires":{"bins":["op"]},"install":[{"id":"brew","kind":"brew","formula":"1password-cli","bins":["op"],"label":"Install 1Password CLI (brew)"}]}} +--- + +# 1Password CLI + +Follow the official CLI get-started steps. Don't guess install commands. + +## References + +- `references/get-started.md` (install + app integration + sign-in flow) +- `references/cli-examples.md` (real `op` examples) + +## Workflow + +1. Check OS + shell. +2. Verify CLI present: `op --version`. +3. Enable desktop app integration in 1Password app (per get-started). +4. Sign in: `op signin`. +5. If multiple accounts: use `--account` or `OP_ACCOUNT`. +6. Verify access: `op whoami` or `op account list`. + +## Guardrails + +- Never paste secrets into logs, chat, or code. +- Prefer `op run` / `op inject` over writing secrets to disk. +- If sign-in without app integration is needed, use `op account add`. diff --git a/skills/1password/references/cli-examples.md b/skills/1password/references/cli-examples.md new file mode 100644 index 000000000..c8da0972b --- /dev/null +++ b/skills/1password/references/cli-examples.md @@ -0,0 +1,29 @@ +# op CLI examples (from op help) + +## Sign in + +- `op signin` +- `op signin --account ` + +## Read + +- `op read op://app-prod/db/password` +- `op read "op://app-prod/db/one-time password?attribute=otp"` +- `op read "op://app-prod/ssh key/private key?ssh-format=openssh"` +- `op read --out-file ./key.pem op://app-prod/server/ssh/key.pem` + +## Run + +- `export DB_PASSWORD="op://app-prod/db/password"` +- `op run --no-masking -- printenv DB_PASSWORD` +- `op run --env-file="./.env" -- printenv DB_PASSWORD` + +## Inject + +- `echo "db_password: {{ op://app-prod/db/password }}" | op inject` +- `op inject -i config.yml.tpl -o config.yml` + +## Whoami / accounts + +- `op whoami` +- `op account list` diff --git a/skills/1password/references/get-started.md b/skills/1password/references/get-started.md new file mode 100644 index 000000000..3c60f75ce --- /dev/null +++ b/skills/1password/references/get-started.md @@ -0,0 +1,17 @@ +# 1Password CLI get-started (summary) + +- Works on macOS, Windows, and Linux. + - macOS/Linux shells: bash, zsh, sh, fish. + - Windows shell: PowerShell. +- Requires a 1Password subscription and the desktop app to use app integration. +- macOS requirement: Big Sur 11.0.0 or later. +- Linux app integration requires PolKit + an auth agent. +- Install the CLI per the official doc for your OS. +- Enable desktop app integration in the 1Password app: + - Open and unlock the app, then select your account/collection. + - macOS: Settings > Developer > Integrate with 1Password CLI (Touch ID optional). + - Windows: turn on Windows Hello, then Settings > Developer > Integrate. + - Linux: Settings > Security > Unlock using system authentication, then Settings > Developer > Integrate. +- After integration, run any command to sign in (example in docs: `op vault list`). +- If multiple accounts: use `op signin` to pick one, or `--account` / `OP_ACCOUNT`. +- For non-integration auth, use `op account add`. From 8be168b1807b7afb1d81c4c67c70b47e91236e93 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 00:41:12 +0100 Subject: [PATCH 028/110] fix: redact sensitive tokens in tool summaries --- CHANGELOG.md | 1 + docs/configuration.md | 11 +++- docs/logging.md | 11 ++++ src/agents/tool-display.ts | 3 +- src/config/defaults.ts | 13 ++++ src/config/io.ts | 9 ++- src/config/types.ts | 4 ++ src/config/zod-schema.ts | 2 + src/logging/redact.test.ts | 99 ++++++++++++++++++++++++++++ src/logging/redact.ts | 128 +++++++++++++++++++++++++++++++++++++ 10 files changed, 277 insertions(+), 4 deletions(-) create mode 100644 src/logging/redact.test.ts create mode 100644 src/logging/redact.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 73e188275..af18252c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. +- Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns). - macOS: prefer gateway config reads/writes in local mode (fall back to disk if the gateway is unavailable). - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`. - macOS: Connections settings now use a custom sidebar to avoid toolbar toggle issues, with rounded styling and full-width row hit targets. diff --git a/docs/configuration.md b/docs/configuration.md index 534e90d6b..a7d53405a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -141,6 +141,9 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`). - Console output can be tuned separately via: - `logging.consoleLevel` (defaults to `info`, bumps to `debug` when `--verbose`) - `logging.consoleStyle` (`pretty` | `compact` | `json`) +- Tool summaries can be redacted to avoid leaking secrets: + - `logging.redactSensitive` (`off` | `tools`, default: `tools`) + - `logging.redactPatterns` (array of regex strings; overrides defaults) ```json5 { @@ -148,7 +151,13 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`). level: "info", file: "/tmp/clawdbot/clawdbot.log", consoleLevel: "info", - consoleStyle: "pretty" + consoleStyle: "pretty", + redactSensitive: "tools", + redactPatterns: [ + // Example: override defaults with your own rules. + "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1", + "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi" + ] } } ``` diff --git a/docs/logging.md b/docs/logging.md index fdc7ad251..89ffab3a7 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -42,6 +42,17 @@ You can tune console verbosity independently via: - `logging.consoleLevel` (default `info`) - `logging.consoleStyle` (`pretty` | `compact` | `json`) +## Tool summary redaction + +Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the +console stream. This is **tools-only** and does not alter file logs. + +- `logging.redactSensitive`: `off` | `tools` (default: `tools`) +- `logging.redactPatterns`: array of regex strings (overrides defaults) + - Use raw regex strings (auto `gi`), or `/pattern/flags` if you need custom flags. + - Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise `***`. + - Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, and popular token prefixes. + ## Gateway WebSocket logs The gateway prints WebSocket protocol logs in two modes: diff --git a/src/agents/tool-display.ts b/src/agents/tool-display.ts index 6975675f5..1d531e8c5 100644 --- a/src/agents/tool-display.ts +++ b/src/agents/tool-display.ts @@ -1,4 +1,5 @@ import fs from "node:fs"; +import { redactToolDetail } from "../logging/redact.js"; import { shortenHomeInString } from "../utils.js"; type ToolDisplayActionSpec = { @@ -193,7 +194,7 @@ export function resolveToolDisplay(params: { export function formatToolDetail(display: ToolDisplay): string | undefined { const parts: string[] = []; if (display.verb) parts.push(display.verb); - if (display.detail) parts.push(display.detail); + if (display.detail) parts.push(redactToolDetail(display.detail)); if (parts.length === 0) return undefined; return parts.join(" · "); } diff --git a/src/config/defaults.ts b/src/config/defaults.ts index 725d71695..2fb0eba8d 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -142,6 +142,19 @@ export function applyModelAliasDefaults(cfg: ClawdbotConfig): ClawdbotConfig { }; } +export function applyLoggingDefaults(cfg: ClawdbotConfig): ClawdbotConfig { + const logging = cfg.logging; + if (!logging) return cfg; + if (logging.redactSensitive) return cfg; + return { + ...cfg, + logging: { + ...logging, + redactSensitive: "tools", + }, + }; +} + export function resetSessionDefaultsWarningForTests() { defaultWarnState = { warned: false }; } diff --git a/src/config/io.ts b/src/config/io.ts index ee4fb4cf5..ca04943b1 100644 --- a/src/config/io.ts +++ b/src/config/io.ts @@ -10,6 +10,7 @@ import { } from "../infra/shell-env.js"; import { applyIdentityDefaults, + applyLoggingDefaults, applyModelAliasDefaults, applySessionDefaults, applyTalkApiKey, @@ -115,7 +116,9 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { } const cfg = applyModelAliasDefaults( applySessionDefaults( - applyIdentityDefaults(validated.data as ClawdbotConfig), + applyLoggingDefaults( + applyIdentityDefaults(validated.data as ClawdbotConfig), + ), ), ); @@ -201,7 +204,9 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { parsed: parsedRes.parsed, valid: true, config: applyTalkApiKey( - applyModelAliasDefaults(applySessionDefaults(validated.config)), + applyModelAliasDefaults( + applySessionDefaults(applyLoggingDefaults(validated.config)), + ), ), issues: [], legacyIssues, diff --git a/src/config/types.ts b/src/config/types.ts index 3db517bf1..29633cb6c 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -44,6 +44,10 @@ export type LoggingConfig = { | "debug" | "trace"; consoleStyle?: "pretty" | "compact" | "json"; + /** Redact sensitive tokens in tool summaries. Default: "tools". */ + redactSensitive?: "off" | "tools"; + /** Regex patterns used to redact sensitive tokens (defaults apply when unset). */ + redactPatterns?: string[]; }; export type WebReconnectConfig = { diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index c047b920e..f7b671c79 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -330,6 +330,8 @@ export const ClawdbotSchema = z.object({ consoleStyle: z .union([z.literal("pretty"), z.literal("compact"), z.literal("json")]) .optional(), + redactSensitive: z.union([z.literal("off"), z.literal("tools")]).optional(), + redactPatterns: z.array(z.string()).optional(), }) .optional(), browser: z diff --git a/src/logging/redact.test.ts b/src/logging/redact.test.ts new file mode 100644 index 000000000..7783751d1 --- /dev/null +++ b/src/logging/redact.test.ts @@ -0,0 +1,99 @@ +import { describe, expect, it } from "vitest"; + +import { getDefaultRedactPatterns, redactSensitiveText } from "./redact.js"; + +const defaults = getDefaultRedactPatterns(); + +describe("redactSensitiveText", () => { + it("masks env assignments while keeping the key", () => { + const input = "OPENAI_API_KEY=sk-1234567890abcdef"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe("OPENAI_API_KEY=sk-123…cdef"); + }); + + it("masks CLI flags", () => { + const input = "curl --token abcdef1234567890ghij https://api.test"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe("curl --token abcdef…ghij https://api.test"); + }); + + it("masks JSON fields", () => { + const input = '{"token":"abcdef1234567890ghij"}'; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe('{"token":"abcdef…ghij"}'); + }); + + it("masks bearer tokens", () => { + const input = "Authorization: Bearer abcdef1234567890ghij"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe("Authorization: Bearer abcdef…ghij"); + }); + + it("masks Telegram-style tokens", () => { + const input = "123456:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe("123456…cdef"); + }); + + it("redacts short tokens fully", () => { + const input = "TOKEN=shortvalue"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe("TOKEN=***"); + }); + + it("redacts private key blocks", () => { + const input = [ + "-----BEGIN PRIVATE KEY-----", + "ABCDEF1234567890", + "ZYXWVUT987654321", + "-----END PRIVATE KEY-----", + ].join("\n"); + const output = redactSensitiveText(input, { + mode: "tools", + patterns: defaults, + }); + expect(output).toBe( + [ + "-----BEGIN PRIVATE KEY-----", + "…redacted…", + "-----END PRIVATE KEY-----", + ].join("\n"), + ); + }); + + it("honors custom patterns with flags", () => { + const input = "token=abcdef1234567890ghij"; + const output = redactSensitiveText(input, { + mode: "tools", + patterns: ["/token=([A-Za-z0-9]+)/i"], + }); + expect(output).toBe("token=abcdef…ghij"); + }); + + it("skips redaction when mode is off", () => { + const input = "OPENAI_API_KEY=sk-1234567890abcdef"; + const output = redactSensitiveText(input, { + mode: "off", + patterns: defaults, + }); + expect(output).toBe(input); + }); +}); diff --git a/src/logging/redact.ts b/src/logging/redact.ts new file mode 100644 index 000000000..be43177e4 --- /dev/null +++ b/src/logging/redact.ts @@ -0,0 +1,128 @@ +import { loadConfig } from "../config/config.js"; +import type { LoggingConfig } from "../config/types.js"; + +export type RedactSensitiveMode = "off" | "tools"; + +const DEFAULT_REDACT_MODE: RedactSensitiveMode = "tools"; +const DEFAULT_REDACT_MIN_LENGTH = 18; +const DEFAULT_REDACT_KEEP_START = 6; +const DEFAULT_REDACT_KEEP_END = 4; + +const DEFAULT_REDACT_PATTERNS: string[] = [ + // ENV-style assignments. + String.raw`\b[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD)\b\s*[=:]\s*(["']?)([^\s"'\\]+)\1`, + // JSON fields. + String.raw`"(?:apiKey|token|secret|password|passwd|accessToken|refreshToken)"\s*:\s*"([^"]+)"`, + // CLI flags. + String.raw`--(?:api[-_]?key|token|secret|password|passwd)\s+(["']?)([^\s"']+)\1`, + // Authorization headers. + String.raw`Authorization\s*[:=]\s*Bearer\s+([A-Za-z0-9._\-+=]+)`, + String.raw`\bBearer\s+([A-Za-z0-9._\-+=]{18,})\b`, + // PEM blocks. + String.raw`-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----`, + // Common token prefixes. + String.raw`\b(sk-[A-Za-z0-9_-]{8,})\b`, + String.raw`\b(ghp_[A-Za-z0-9]{20,})\b`, + String.raw`\b(github_pat_[A-Za-z0-9_]{20,})\b`, + String.raw`\b(xox[baprs]-[A-Za-z0-9-]{10,})\b`, + String.raw`\b(xapp-[A-Za-z0-9-]{10,})\b`, + String.raw`\b(gsk_[A-Za-z0-9_-]{10,})\b`, + String.raw`\b(AIza[0-9A-Za-z\-_]{20,})\b`, + String.raw`\b(pplx-[A-Za-z0-9_-]{10,})\b`, + String.raw`\b(npm_[A-Za-z0-9]{10,})\b`, + String.raw`\b(\d{6,}:[A-Za-z0-9_-]{20,})\b`, +]; + +type RedactOptions = { + mode?: RedactSensitiveMode; + patterns?: string[]; +}; + +function normalizeMode(value?: string): RedactSensitiveMode { + return value === "off" ? "off" : DEFAULT_REDACT_MODE; +} + +function parsePattern(raw: string): RegExp | null { + if (!raw.trim()) return null; + const match = raw.match(/^\/(.+)\/([gimsuy]*)$/); + try { + if (match) { + const flags = match[2].includes("g") ? match[2] : `${match[2]}g`; + return new RegExp(match[1], flags); + } + return new RegExp(raw, "gi"); + } catch { + return null; + } +} + +function resolvePatterns(value?: string[]): RegExp[] { + const source = value?.length ? value : DEFAULT_REDACT_PATTERNS; + return source.map(parsePattern).filter((re): re is RegExp => Boolean(re)); +} + +function maskToken(token: string): string { + if (token.length < DEFAULT_REDACT_MIN_LENGTH) return "***"; + const start = token.slice(0, DEFAULT_REDACT_KEEP_START); + const end = token.slice(-DEFAULT_REDACT_KEEP_END); + return `${start}…${end}`; +} + +function redactPemBlock(block: string): string { + const lines = block.split(/\r?\n/).filter(Boolean); + if (lines.length < 2) return "***"; + return `${lines[0]}\n…redacted…\n${lines[lines.length - 1]}`; +} + +function redactMatch(match: string, groups: string[]): string { + if (match.includes("PRIVATE KEY-----")) return redactPemBlock(match); + const token = + groups + .filter((value) => typeof value === "string" && value.length > 0) + .at(-1) ?? match; + const masked = maskToken(token); + if (token === match) return masked; + return match.replace(token, masked); +} + +function redactText(text: string, patterns: RegExp[]): string { + let next = text; + for (const pattern of patterns) { + next = next.replace( + pattern, + (...args: string[]) => + redactMatch(args[0], args.slice(1, args.length - 2)), + ); + } + return next; +} + +function resolveConfigRedaction(): RedactOptions { + const cfg = loadConfig().logging; + return { + mode: normalizeMode(cfg?.redactSensitive), + patterns: cfg?.redactPatterns, + }; +} + +export function redactSensitiveText( + text: string, + options?: RedactOptions, +): string { + if (!text) return text; + const resolved = options ?? resolveConfigRedaction(); + if (normalizeMode(resolved.mode) === "off") return text; + const patterns = resolvePatterns(resolved.patterns); + if (!patterns.length) return text; + return redactText(text, patterns); +} + +export function redactToolDetail(detail: string): string { + const resolved = resolveConfigRedaction(); + if (normalizeMode(resolved.mode) !== "tools") return detail; + return redactSensitiveText(detail, resolved); +} + +export function getDefaultRedactPatterns(): string[] { + return [...DEFAULT_REDACT_PATTERNS]; +} From a4fdfc241472987d6256173b1b18d4cc36cbcde4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 00:42:23 +0100 Subject: [PATCH 029/110] chore: fix redaction lint --- src/config/zod-schema.ts | 4 +++- src/logging/redact.ts | 7 ++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index f7b671c79..bc347f8d0 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -330,7 +330,9 @@ export const ClawdbotSchema = z.object({ consoleStyle: z .union([z.literal("pretty"), z.literal("compact"), z.literal("json")]) .optional(), - redactSensitive: z.union([z.literal("off"), z.literal("tools")]).optional(), + redactSensitive: z + .union([z.literal("off"), z.literal("tools")]) + .optional(), redactPatterns: z.array(z.string()).optional(), }) .optional(), diff --git a/src/logging/redact.ts b/src/logging/redact.ts index be43177e4..065b4e334 100644 --- a/src/logging/redact.ts +++ b/src/logging/redact.ts @@ -1,5 +1,4 @@ import { loadConfig } from "../config/config.js"; -import type { LoggingConfig } from "../config/types.js"; export type RedactSensitiveMode = "off" | "tools"; @@ -88,10 +87,8 @@ function redactMatch(match: string, groups: string[]): string { function redactText(text: string, patterns: RegExp[]): string { let next = text; for (const pattern of patterns) { - next = next.replace( - pattern, - (...args: string[]) => - redactMatch(args[0], args.slice(1, args.length - 2)), + next = next.replace(pattern, (...args: string[]) => + redactMatch(args[0], args.slice(1, args.length - 2)), ); } return next; From a6a45f4b84c75b9dfed9e2df748b3b9fae3cc4ad Mon Sep 17 00:00:00 2001 From: Xin <5097752+imfing@users.noreply.github.com> Date: Mon, 5 Jan 2026 23:54:35 +0000 Subject: [PATCH 030/110] fix(whatsapp): populate senderE164 for direct chats to enable owner commands (#247) --- src/web/inbound.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/web/inbound.ts b/src/web/inbound.ts index fe147e2fe..2043b0d39 100644 --- a/src/web/inbound.ts +++ b/src/web/inbound.ts @@ -144,10 +144,14 @@ export async function monitorWebInbox(options: { continue; const group = isJidGroup(remoteJid); const participantJid = msg.key?.participant ?? undefined; - const senderE164 = participantJid ? jidToE164(participantJid) : null; const from = group ? remoteJid : jidToE164(remoteJid); // Skip if we still can't resolve an id to key conversation if (!from) continue; + const senderE164 = group + ? participantJid + ? jidToE164(participantJid) + : null + : from; let groupSubject: string | undefined; let groupParticipants: string[] | undefined; if (group) { From 291c6f3b608e7bffb2ce8d595837cd24b88fe464 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 00:55:41 +0100 Subject: [PATCH 031/110] test: cover WhatsApp DM senderE164 --- CHANGELOG.md | 1 + src/web/monitor-inbox.test.ts | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index af18252c0..65f5ff03d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ - Docs: document systemd lingering and logged-in session requirements on macOS/Windows. - Auto-reply: unify tool/block/final delivery across providers and apply consistent heartbeat/prefix handling. Thanks @MSch for PR #225 (superseded commit 92c953d0749143eb2a3f31f3cd6ad0e8eabf48c3). - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman +- WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/src/web/monitor-inbox.test.ts b/src/web/monitor-inbox.test.ts index 483121a3e..3f285b6b0 100644 --- a/src/web/monitor-inbox.test.ts +++ b/src/web/monitor-inbox.test.ts @@ -701,7 +701,11 @@ describe("web monitor inbox", () => { // Should call onMessage for authorized senders expect(onMessage).toHaveBeenCalledWith( - expect.objectContaining({ body: "authorized message", from: "+999" }), + expect.objectContaining({ + body: "authorized message", + from: "+999", + senderE164: "+999", + }), ); // Reset mock for other tests From 5356adba8f7dafebb3954b89866d73702cbc671e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:09:25 +0100 Subject: [PATCH 032/110] fix: keep Slack thread replies in thread --- CHANGELOG.md | 1 + src/discord/monitor.tool-result.test.ts | 9 +++---- src/slack/monitor.tool-result.test.ts | 34 +++++++++++++++++++++++++ src/slack/monitor.ts | 11 +++++--- 4 files changed, 46 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65f5ff03d..2e4942cab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,7 @@ - Auto-reply: unify tool/block/final delivery across providers and apply consistent heartbeat/prefix handling. Thanks @MSch for PR #225 (superseded commit 92c953d0749143eb2a3f31f3cd6ad0e8eabf48c3). - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. +- Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/src/discord/monitor.tool-result.test.ts b/src/discord/monitor.tool-result.test.ts index 3b95db93b..867c592c3 100644 --- a/src/discord/monitor.tool-result.test.ts +++ b/src/discord/monitor.tool-result.test.ts @@ -31,12 +31,11 @@ vi.mock("../config/sessions.js", () => ({ vi.mock("discord.js", () => { const handlers = new Map void>>(); - let lastClient: Client | null = null; - class Client { + static lastClient: Client | null = null; user = { id: "bot-id", tag: "bot#1" }; constructor() { - lastClient = this; + Client.lastClient = this; } on(event: string, handler: (...args: unknown[]) => void) { if (!handlers.has(event)) handlers.set(event, new Set()); @@ -50,7 +49,7 @@ vi.mock("discord.js", () => { } emit(event: string, ...args: unknown[]) { for (const handler of handlers.get(event) ?? []) { - void handler(...args); + void Promise.resolve(handler(...args)); } } login = vi.fn().mockResolvedValue(undefined); @@ -59,7 +58,7 @@ vi.mock("discord.js", () => { return { Client, - __getLastClient: () => lastClient, + __getLastClient: () => Client.lastClient, Events: { ClientReady: "ready", Error: "error", diff --git a/src/slack/monitor.tool-result.test.ts b/src/slack/monitor.tool-result.test.ts index ade080f2b..99ec296dc 100644 --- a/src/slack/monitor.tool-result.test.ts +++ b/src/slack/monitor.tool-result.test.ts @@ -122,4 +122,38 @@ describe("monitorSlackProvider tool results", () => { expect(sendMock.mock.calls[0][1]).toBe("PFX tool update"); expect(sendMock.mock.calls[1][1]).toBe("PFX final reply"); }); + + it("threads replies when incoming message is in a thread", async () => { + replyMock.mockResolvedValue({ text: "thread reply" }); + + const controller = new AbortController(); + const run = monitorSlackProvider({ + botToken: "bot-token", + appToken: "app-token", + abortSignal: controller.signal, + }); + + await waitForEvent("message"); + const handler = getSlackHandlers()?.get("message"); + if (!handler) throw new Error("Slack message handler not registered"); + + await handler({ + event: { + type: "message", + user: "U1", + text: "hello", + ts: "123", + thread_ts: "456", + channel: "C1", + channel_type: "im", + }, + }); + + await flush(); + controller.abort(); + await run; + + expect(sendMock).toHaveBeenCalledTimes(1); + expect(sendMock.mock.calls[0][2]).toMatchObject({ threadTs: "456" }); + }); }); diff --git a/src/slack/monitor.ts b/src/slack/monitor.ts index 4e26961d8..f3929881f 100644 --- a/src/slack/monitor.ts +++ b/src/slack/monitor.ts @@ -700,6 +700,9 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) { ); } + // Only thread replies if the incoming message was in a thread. + const incomingThreadTs = message.thread_ts; + const dispatcher = createReplyDispatcher({ responsePrefix: cfg.messages?.responsePrefix, deliver: async (payload) => { @@ -709,6 +712,7 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) { token: botToken, runtime, textLimit, + threadTs: incomingThreadTs, }); }, onError: (err, info) => { @@ -1379,6 +1383,7 @@ async function deliverReplies(params: { token: string; runtime: RuntimeEnv; textLimit: number; + threadTs?: string; }) { const chunkLimit = Math.min(params.textLimit, 4000); for (const payload of params.replies) { @@ -1389,12 +1394,11 @@ async function deliverReplies(params: { if (mediaList.length === 0) { for (const chunk of chunkText(text, chunkLimit)) { - const threadTs = undefined; const trimmed = chunk.trim(); if (!trimmed || trimmed === SILENT_REPLY_TOKEN) continue; await sendMessageSlack(params.target, trimmed, { token: params.token, - threadTs, + threadTs: params.threadTs, }); } } else { @@ -1402,11 +1406,10 @@ async function deliverReplies(params: { for (const mediaUrl of mediaList) { const caption = first ? text : ""; first = false; - const threadTs = undefined; await sendMessageSlack(params.target, caption, { token: params.token, mediaUrl, - threadTs, + threadTs: params.threadTs, }); } } From df9005d64cb8dd597c9eb6b345f64b5b1fdb0296 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:16:25 +0100 Subject: [PATCH 033/110] fix(ui): handle slack config snapshot --- CHANGELOG.md | 1 + ui/src/ui/controllers/config.test.ts | 139 +++++++++++++++++++++++++++ ui/src/ui/controllers/config.ts | 1 + 3 files changed, 141 insertions(+) create mode 100644 ui/src/ui/controllers/config.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e4942cab..5d24ddf77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,7 @@ - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251. +- Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/ui/src/ui/controllers/config.test.ts b/ui/src/ui/controllers/config.test.ts new file mode 100644 index 000000000..f8ee03dc0 --- /dev/null +++ b/ui/src/ui/controllers/config.test.ts @@ -0,0 +1,139 @@ +import { describe, expect, it } from "vitest"; + +import { applyConfigSnapshot, type ConfigState } from "./config"; +import { + defaultDiscordActions, + defaultSlackActions, + type DiscordForm, + type IMessageForm, + type SignalForm, + type SlackForm, + type TelegramForm, +} from "../ui-types"; + +const baseTelegramForm: TelegramForm = { + token: "", + requireMention: true, + allowFrom: "", + proxy: "", + webhookUrl: "", + webhookSecret: "", + webhookPath: "", +}; + +const baseDiscordForm: DiscordForm = { + enabled: true, + token: "", + dmEnabled: true, + allowFrom: "", + groupEnabled: false, + groupChannels: "", + mediaMaxMb: "", + historyLimit: "", + textChunkLimit: "", + replyToMode: "off", + guilds: [], + actions: { ...defaultDiscordActions }, + slashEnabled: false, + slashName: "", + slashSessionPrefix: "", + slashEphemeral: true, +}; + +const baseSlackForm: SlackForm = { + enabled: true, + botToken: "", + appToken: "", + dmEnabled: true, + allowFrom: "", + groupEnabled: false, + groupChannels: "", + mediaMaxMb: "", + textChunkLimit: "", + reactionNotifications: "own", + reactionAllowlist: "", + slashEnabled: false, + slashName: "", + slashSessionPrefix: "", + slashEphemeral: true, + actions: { ...defaultSlackActions }, + channels: [], +}; + +const baseSignalForm: SignalForm = { + enabled: true, + account: "", + httpUrl: "", + httpHost: "", + httpPort: "", + cliPath: "", + autoStart: true, + receiveMode: "", + ignoreAttachments: false, + ignoreStories: false, + sendReadReceipts: false, + allowFrom: "", + mediaMaxMb: "", +}; + +const baseIMessageForm: IMessageForm = { + enabled: true, + cliPath: "", + dbPath: "", + service: "auto", + region: "", + allowFrom: "", + includeAttachments: false, + mediaMaxMb: "", +}; + +function createState(): ConfigState { + return { + client: null, + connected: false, + configLoading: false, + configRaw: "", + configValid: null, + configIssues: [], + configSaving: false, + configSnapshot: null, + configSchema: null, + configSchemaVersion: null, + configSchemaLoading: false, + configUiHints: {}, + configForm: null, + configFormDirty: false, + configFormMode: "form", + lastError: null, + telegramForm: { ...baseTelegramForm }, + discordForm: { ...baseDiscordForm }, + slackForm: { ...baseSlackForm }, + signalForm: { ...baseSignalForm }, + imessageForm: { ...baseIMessageForm }, + telegramConfigStatus: null, + discordConfigStatus: null, + slackConfigStatus: null, + signalConfigStatus: null, + imessageConfigStatus: null, + }; +} + +describe("applyConfigSnapshot", () => { + it("handles missing slack config without throwing", () => { + const state = createState(); + applyConfigSnapshot(state, { + config: { + telegram: {}, + discord: {}, + signal: {}, + imessage: {}, + }, + valid: true, + issues: [], + raw: "{}", + }); + + expect(state.slackForm.botToken).toBe(""); + expect(state.slackForm.actions).toEqual(defaultSlackActions); + }); +}); diff --git a/ui/src/ui/controllers/config.ts b/ui/src/ui/controllers/config.ts index afe4b88b5..760b1d452 100644 --- a/ui/src/ui/controllers/config.ts +++ b/ui/src/ui/controllers/config.ts @@ -100,6 +100,7 @@ export function applyConfigSnapshot(state: ConfigState, snapshot: ConfigSnapshot const config = snapshot.config ?? {}; const telegram = (config.telegram ?? {}) as Record; const discord = (config.discord ?? {}) as Record; + const slack = (config.slack ?? {}) as Record; const signal = (config.signal ?? {}) as Record; const imessage = (config.imessage ?? {}) as Record; const toList = (value: unknown) => From 48d52d13f1a1663eb6f623f34f6550cac1bd08eb Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:30:48 +0100 Subject: [PATCH 034/110] docs: clarify 1password tmux flow --- skills/1password/SKILL.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/skills/1password/SKILL.md b/skills/1password/SKILL.md index 35bcb5a34..7aea6b8c1 100644 --- a/skills/1password/SKILL.md +++ b/skills/1password/SKILL.md @@ -18,13 +18,32 @@ Follow the official CLI get-started steps. Don't guess install commands. 1. Check OS + shell. 2. Verify CLI present: `op --version`. -3. Enable desktop app integration in 1Password app (per get-started). -4. Sign in: `op signin`. +3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked. +4. Sign in / authorize this terminal: `op signin` (expect an app prompt). 5. If multiple accounts: use `--account` or `OP_ACCOUNT`. 6. Verify access: `op whoami` or `op account list`. +## Avoid repeated auth prompts (tmux) + +The bash tool uses a fresh TTY per command, so app integration may prompt every time. To reuse authorization, run multiple `op` commands inside a single tmux session. + +Example (see `tmux` skill for socket conventions): + +```bash +SOCKET_DIR="${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/clawdbot-tmux-sockets}" +mkdir -p "$SOCKET_DIR" +SOCKET="$SOCKET_DIR/clawdbot.sock" +SESSION=op-auth + +tmux -S "$SOCKET" new -d -s "$SESSION" -n shell +tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter +tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter +tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200 +``` + ## Guardrails - Never paste secrets into logs, chat, or code. - Prefer `op run` / `op inject` over writing secrets to disk. - If sign-in without app integration is needed, use `op account add`. +- If a command returns "account is not signed in", re-run `op signin` and authorize in the app. From 811ec8b78b76fbf547f77a3814a621fcd2730211 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:32:17 +0100 Subject: [PATCH 035/110] fix: unify mention gating across providers --- CHANGELOG.md | 1 + src/auto-reply/reply/mentions.ts | 29 +++++++++++ src/discord/monitor.tool-result.test.ts | 55 ++++++++++++++++++++ src/discord/monitor.ts | 16 ++++-- src/imessage/monitor.ts | 41 ++++++--------- src/slack/monitor.tool-result.test.ts | 45 +++++++++++++++++ src/slack/monitor.ts | 10 +++- src/telegram/bot.test.ts | 67 +++++++++++++++++++++++++ src/telegram/bot.ts | 14 ++++-- src/web/auto-reply.ts | 26 +++------- 10 files changed, 253 insertions(+), 51 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d24ddf77..7d3572d31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,7 @@ - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251. - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. +- Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/src/auto-reply/reply/mentions.ts b/src/auto-reply/reply/mentions.ts index c85914fd5..d9edcfa0f 100644 --- a/src/auto-reply/reply/mentions.ts +++ b/src/auto-reply/reply/mentions.ts @@ -1,6 +1,35 @@ import type { ClawdbotConfig } from "../../config/config.js"; import type { MsgContext } from "../templating.js"; +export function buildMentionRegexes(cfg: ClawdbotConfig | undefined): RegExp[] { + const patterns = cfg?.routing?.groupChat?.mentionPatterns ?? []; + return patterns + .map((pattern) => { + try { + return new RegExp(pattern, "i"); + } catch { + return null; + } + }) + .filter((value): value is RegExp => Boolean(value)); +} + +export function normalizeMentionText(text: string): string { + return (text ?? "") + .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "") + .toLowerCase(); +} + +export function matchesMentionPatterns( + text: string, + mentionRegexes: RegExp[], +): boolean { + if (mentionRegexes.length === 0) return false; + const cleaned = normalizeMentionText(text ?? ""); + if (!cleaned) return false; + return mentionRegexes.some((re) => re.test(cleaned)); +} + export function stripStructuralPrefixes(text: string): string { // Ignore wrapper labels, timestamps, and sender prefixes so directive-only // detection still works in group batches that include history/context. diff --git a/src/discord/monitor.tool-result.test.ts b/src/discord/monitor.tool-result.test.ts index 867c592c3..b9314b5a2 100644 --- a/src/discord/monitor.tool-result.test.ts +++ b/src/discord/monitor.tool-result.test.ts @@ -147,4 +147,59 @@ describe("monitorDiscordProvider tool results", () => { expect(sendMock.mock.calls[0][1]).toBe("PFX tool update"); expect(sendMock.mock.calls[1][1]).toBe("PFX final reply"); }); + + it("accepts guild messages when mentionPatterns match", async () => { + config = { + messages: { responsePrefix: "PFX" }, + discord: { + dm: { enabled: true }, + guilds: { "*": { requireMention: true } }, + }, + routing: { + allowFrom: [], + groupChat: { mentionPatterns: ["\\bclawd\\b"] }, + }, + }; + replyMock.mockResolvedValue({ text: "hi" }); + + const controller = new AbortController(); + const run = monitorDiscordProvider({ + token: "token", + abortSignal: controller.signal, + }); + + const discord = await import("discord.js"); + const client = await waitForClient(); + if (!client) throw new Error("Discord client not created"); + + client.emit(discord.Events.MessageCreate, { + id: "m2", + content: "clawd: hello", + author: { id: "u1", bot: false, username: "Ada", tag: "Ada#1" }, + member: { displayName: "Ada" }, + channelId: "c1", + channel: { + type: discord.ChannelType.GuildText, + name: "general", + isSendable: () => false, + }, + guild: { id: "g1", name: "Guild" }, + mentions: { + has: () => false, + everyone: false, + users: { size: 0 }, + roles: { size: 0 }, + }, + attachments: { first: () => undefined }, + type: discord.MessageType.Default, + createdTimestamp: Date.now(), + }); + + await flush(); + controller.abort(); + await run; + + expect(replyMock).toHaveBeenCalledTimes(1); + expect(replyMock.mock.calls[0][0].WasMentioned).toBe(true); + }); }); diff --git a/src/discord/monitor.ts b/src/discord/monitor.ts index 35bebbab5..4a8ecebf6 100644 --- a/src/discord/monitor.ts +++ b/src/discord/monitor.ts @@ -18,6 +18,10 @@ import { import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; import { hasControlCommand } from "../auto-reply/command-detection.js"; import { formatAgentEnvelope } from "../auto-reply/envelope.js"; +import { + buildMentionRegexes, + matchesMentionPatterns, +} from "../auto-reply/reply/mentions.js"; import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js"; import { getReplyFromConfig } from "../auto-reply/reply.js"; import type { ReplyPayload } from "../auto-reply/types.js"; @@ -140,6 +144,7 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) { const mediaMaxBytes = (opts.mediaMaxMb ?? cfg.discord?.mediaMaxMb ?? 8) * 1024 * 1024; const textLimit = resolveTextChunkLimit(cfg, "discord"); + const mentionRegexes = buildMentionRegexes(cfg); const historyLimit = Math.max( 0, opts.historyLimit ?? cfg.discord?.historyLimit ?? 20, @@ -202,13 +207,15 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) { return; } const botId = client.user?.id; - const wasMentioned = - !isDirectMessage && Boolean(botId && message.mentions.has(botId)); const forwardedSnapshot = resolveForwardedSnapshot(message); const forwardedText = forwardedSnapshot ? resolveDiscordSnapshotText(forwardedSnapshot.snapshot) : ""; const baseText = resolveDiscordMessageText(message, forwardedText); + const wasMentioned = + !isDirectMessage && + (Boolean(botId && message.mentions.has(botId)) || + matchesMentionPatterns(baseText, mentionRegexes)); if (shouldLogVerbose()) { logVerbose( `discord: inbound id=${message.id} guild=${message.guild?.id ?? "dm"} channel=${message.channelId} mention=${wasMentioned ? "yes" : "no"} type=${isDirectMessage ? "dm" : isGroupDm ? "group-dm" : "guild"} content=${baseText ? "yes" : "no"}`, @@ -309,8 +316,9 @@ export async function monitorDiscordProvider(opts: MonitorDiscordOpts = {}) { !hasAnyMention && commandAuthorized && hasControlCommand(baseText); - if (isGuildMessage && resolvedRequireMention) { - if (botId && !wasMentioned && !shouldBypassMention) { + const canDetectMention = Boolean(botId) || mentionRegexes.length > 0; + if (isGuildMessage && resolvedRequireMention && canDetectMention) { + if (!wasMentioned && !shouldBypassMention) { logVerbose( `discord: drop guild message (mention required, botId=${botId})`, ); diff --git a/src/imessage/monitor.ts b/src/imessage/monitor.ts index 300d27ed2..30f12e7ee 100644 --- a/src/imessage/monitor.ts +++ b/src/imessage/monitor.ts @@ -1,6 +1,10 @@ import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; import { hasControlCommand } from "../auto-reply/command-detection.js"; import { formatAgentEnvelope } from "../auto-reply/envelope.js"; +import { + buildMentionRegexes, + matchesMentionPatterns, +} from "../auto-reply/reply/mentions.js"; import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js"; import { getReplyFromConfig } from "../auto-reply/reply.js"; import type { ReplyPayload } from "../auto-reply/types.js"; @@ -67,20 +71,6 @@ function resolveAllowFrom(opts: MonitorIMessageOpts): string[] { return raw.map((entry) => String(entry).trim()).filter(Boolean); } -function resolveMentionRegexes(cfg: ReturnType): RegExp[] { - return ( - cfg.routing?.groupChat?.mentionPatterns - ?.map((pattern) => { - try { - return new RegExp(pattern, "i"); - } catch { - return null; - } - }) - .filter((val): val is RegExp => Boolean(val)) ?? [] - ); -} - function resolveGroupRequireMention( cfg: ReturnType, opts: MonitorIMessageOpts, @@ -99,14 +89,6 @@ function resolveGroupRequireMention( return true; } -function isMentioned(text: string, regexes: RegExp[]): boolean { - if (!text) return false; - const cleaned = text - .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "") - .toLowerCase(); - return regexes.some((re) => re.test(cleaned)); -} - async function deliverReplies(params: { replies: ReplyPayload[]; target: string; @@ -148,7 +130,7 @@ export async function monitorIMessageProvider( const cfg = loadConfig(); const textLimit = resolveTextChunkLimit(cfg, "imessage"); const allowFrom = resolveAllowFrom(opts); - const mentionRegexes = resolveMentionRegexes(cfg); + const mentionRegexes = buildMentionRegexes(cfg); const includeAttachments = opts.includeAttachments ?? cfg.imessage?.includeAttachments ?? false; const mediaMaxBytes = @@ -183,15 +165,24 @@ export async function monitorIMessageProvider( } const messageText = (message.text ?? "").trim(); - const mentioned = isGroup ? isMentioned(messageText, mentionRegexes) : true; + const mentioned = isGroup + ? matchesMentionPatterns(messageText, mentionRegexes) + : true; const requireMention = resolveGroupRequireMention(cfg, opts, chatId); + const canDetectMention = mentionRegexes.length > 0; const shouldBypassMention = isGroup && requireMention && !mentioned && commandAuthorized && hasControlCommand(messageText); - if (isGroup && requireMention && !mentioned && !shouldBypassMention) { + if ( + isGroup && + requireMention && + canDetectMention && + !mentioned && + !shouldBypassMention + ) { logVerbose(`imessage: skipping group message (no mention)`); return; } diff --git a/src/slack/monitor.tool-result.test.ts b/src/slack/monitor.tool-result.test.ts index 99ec296dc..4a19ca8fc 100644 --- a/src/slack/monitor.tool-result.test.ts +++ b/src/slack/monitor.tool-result.test.ts @@ -123,6 +123,51 @@ describe("monitorSlackProvider tool results", () => { expect(sendMock.mock.calls[1][1]).toBe("PFX final reply"); }); + it("accepts channel messages when mentionPatterns match", async () => { + config = { + messages: { responsePrefix: "PFX" }, + slack: { + dm: { enabled: true }, + groupDm: { enabled: false }, + channels: { C1: { allow: true, requireMention: true } }, + }, + routing: { + allowFrom: [], + groupChat: { mentionPatterns: ["\\bclawd\\b"] }, + }, + }; + replyMock.mockResolvedValue({ text: "hi" }); + + const controller = new AbortController(); + const run = monitorSlackProvider({ + botToken: "bot-token", + appToken: "app-token", + abortSignal: controller.signal, + }); + + await waitForEvent("message"); + const handler = getSlackHandlers()?.get("message"); + if (!handler) throw new Error("Slack message handler not registered"); + + await handler({ + event: { + type: "message", + user: "U1", + text: "clawd: hello", + ts: "123", + channel: "C1", + channel_type: "channel", + }, + }); + + await flush(); + controller.abort(); + await run; + + expect(replyMock).toHaveBeenCalledTimes(1); + expect(replyMock.mock.calls[0][0].WasMentioned).toBe(true); + }); + it("threads replies when incoming message is in a thread", async () => { replyMock.mockResolvedValue({ text: "thread reply" }); diff --git a/src/slack/monitor.ts b/src/slack/monitor.ts index f3929881f..e8509f774 100644 --- a/src/slack/monitor.ts +++ b/src/slack/monitor.ts @@ -6,6 +6,10 @@ import bolt from "@slack/bolt"; import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; import { hasControlCommand } from "../auto-reply/command-detection.js"; import { formatAgentEnvelope } from "../auto-reply/envelope.js"; +import { + buildMentionRegexes, + matchesMentionPatterns, +} from "../auto-reply/reply/mentions.js"; import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js"; import { getReplyFromConfig } from "../auto-reply/reply.js"; import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js"; @@ -379,6 +383,7 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) { opts.slashCommand ?? cfg.slack?.slashCommand, ); const textLimit = resolveTextChunkLimit(cfg, "slack"); + const mentionRegexes = buildMentionRegexes(cfg); const mediaMaxBytes = (opts.mediaMaxMb ?? cfg.slack?.mediaMaxMb ?? 20) * 1024 * 1024; @@ -581,7 +586,8 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) { const wasMentioned = opts.wasMentioned ?? (!isDirectMessage && - Boolean(botUserId && message.text?.includes(`<@${botUserId}>`))); + (Boolean(botUserId && message.text?.includes(`<@${botUserId}>`)) || + matchesMentionPatterns(message.text ?? "", mentionRegexes))); const sender = await resolveUserName(message.user); const senderName = sender?.name ?? message.user; const allowList = normalizeAllowListLower(allowFrom); @@ -600,9 +606,11 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) { !hasAnyMention && commandAuthorized && hasControlCommand(message.text ?? ""); + const canDetectMention = Boolean(botUserId) || mentionRegexes.length > 0; if ( isRoom && channelConfig?.requireMention && + canDetectMention && !wasMentioned && !shouldBypassMention ) { diff --git a/src/telegram/bot.test.ts b/src/telegram/bot.test.ts index 594958389..96fd5b85c 100644 --- a/src/telegram/bot.test.ts +++ b/src/telegram/bot.test.ts @@ -126,6 +126,73 @@ describe("createTelegramBot", () => { expect(sendChatActionSpy).toHaveBeenCalledWith(42, "typing"); }); + it("accepts group messages when mentionPatterns match (without @botUsername)", async () => { + onSpy.mockReset(); + const replySpy = replyModule.__replySpy as unknown as ReturnType< + typeof vi.fn + >; + replySpy.mockReset(); + + loadConfig.mockReturnValue({ + identity: { name: "Bert" }, + routing: { groupChat: { mentionPatterns: ["\\bbert\\b"] } }, + telegram: { groups: { "*": { requireMention: true } } }, + }); + + createTelegramBot({ token: "tok" }); + const handler = onSpy.mock.calls[0][1] as ( + ctx: Record, + ) => Promise; + + await handler({ + message: { + chat: { id: 7, type: "group", title: "Test Group" }, + text: "bert: introduce yourself", + date: 1736380800, + message_id: 1, + from: { id: 9, first_name: "Ada" }, + }, + me: { username: "clawdbot_bot" }, + getFile: async () => ({ download: async () => new Uint8Array() }), + }); + + expect(replySpy).toHaveBeenCalledTimes(1); + const payload = replySpy.mock.calls[0][0]; + expect(payload.WasMentioned).toBe(true); + }); + + it("skips group messages when requireMention is enabled and no mention matches", async () => { + onSpy.mockReset(); + const replySpy = replyModule.__replySpy as unknown as ReturnType< + typeof vi.fn + >; + replySpy.mockReset(); + + loadConfig.mockReturnValue({ + routing: { groupChat: { mentionPatterns: ["\\bbert\\b"] } }, + telegram: { groups: { "*": { requireMention: true } } }, + }); + + createTelegramBot({ token: "tok" }); + const handler = onSpy.mock.calls[0][1] as ( + ctx: Record, + ) => Promise; + + await handler({ + message: { + chat: { id: 7, type: "group", title: "Test Group" }, + text: "hello everyone", + date: 1736380800, + message_id: 2, + from: { id: 9, first_name: "Ada" }, + }, + me: { username: "clawdbot_bot" }, + getFile: async () => ({ download: async () => new Uint8Array() }), + }); + + expect(replySpy).not.toHaveBeenCalled(); + }); + it("includes reply-to context when a Telegram reply is received", async () => { onSpy.mockReset(); sendMessageSpy.mockReset(); diff --git a/src/telegram/bot.ts b/src/telegram/bot.ts index ff7722c17..f8022dc98 100644 --- a/src/telegram/bot.ts +++ b/src/telegram/bot.ts @@ -7,6 +7,10 @@ import { Bot, InputFile, webhookCallback } from "grammy"; import { chunkText, resolveTextChunkLimit } from "../auto-reply/chunk.js"; import { hasControlCommand } from "../auto-reply/command-detection.js"; import { formatAgentEnvelope } from "../auto-reply/envelope.js"; +import { + buildMentionRegexes, + matchesMentionPatterns, +} from "../auto-reply/reply/mentions.js"; import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js"; import { getReplyFromConfig } from "../auto-reply/reply.js"; import type { ReplyPayload } from "../auto-reply/types.js"; @@ -67,6 +71,7 @@ export function createTelegramBot(opts: TelegramBotOptions) { const mediaMaxBytes = (opts.mediaMaxMb ?? cfg.telegram?.mediaMaxMb ?? 5) * 1024 * 1024; const logger = getChildLogger({ module: "telegram-auto-reply" }); + const mentionRegexes = buildMentionRegexes(cfg); const resolveGroupRequireMention = (chatId: string | number) => { const groupId = String(chatId); const groupConfig = cfg.telegram?.groups?.[groupId]; @@ -132,7 +137,8 @@ export function createTelegramBot(opts: TelegramBotOptions) { entry.toLowerCase() === `@${senderUsername.toLowerCase()}`, )); const wasMentioned = - Boolean(botUsername) && hasBotMention(msg, botUsername); + (Boolean(botUsername) && hasBotMention(msg, botUsername)) || + matchesMentionPatterns(msg.text ?? msg.caption ?? "", mentionRegexes); const hasAnyMention = (msg.entities ?? msg.caption_entities ?? []).some( (ent) => ent.type === "mention", ); @@ -143,7 +149,9 @@ export function createTelegramBot(opts: TelegramBotOptions) { !hasAnyMention && commandAuthorized && hasControlCommand(msg.text ?? msg.caption ?? ""); - if (isGroup && resolveGroupRequireMention(chatId) && botUsername) { + const canDetectMention = + Boolean(botUsername) || mentionRegexes.length > 0; + if (isGroup && resolveGroupRequireMention(chatId) && canDetectMention) { if (!wasMentioned && !shouldBypassMention) { logger.info( { chatId, reason: "no-mention" }, @@ -196,7 +204,7 @@ export function createTelegramBot(opts: TelegramBotOptions) { ReplyToBody: replyTarget?.body, ReplyToSender: replyTarget?.sender, Timestamp: msg.date ? msg.date * 1000 : undefined, - WasMentioned: isGroup && botUsername ? wasMentioned : undefined, + WasMentioned: isGroup ? wasMentioned : undefined, MediaPath: media?.path, MediaType: media?.contentType, MediaUrl: media?.path, diff --git a/src/web/auto-reply.ts b/src/web/auto-reply.ts index 089723ed6..c46afcf66 100644 --- a/src/web/auto-reply.ts +++ b/src/web/auto-reply.ts @@ -9,6 +9,10 @@ import { HEARTBEAT_PROMPT, stripHeartbeatToken, } from "../auto-reply/heartbeat.js"; +import { + buildMentionRegexes, + normalizeMentionText, +} from "../auto-reply/reply/mentions.js"; import { createReplyDispatcher } from "../auto-reply/reply/reply-dispatcher.js"; import { getReplyFromConfig } from "../auto-reply/reply.js"; import { HEARTBEAT_TOKEN, SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js"; @@ -147,17 +151,7 @@ type MentionConfig = { }; function buildMentionConfig(cfg: ReturnType): MentionConfig { - const gc = cfg.routing?.groupChat; - const mentionRegexes = - gc?.mentionPatterns - ?.map((p) => { - try { - return new RegExp(p, "i"); - } catch { - return null; - } - }) - .filter((r): r is RegExp => Boolean(r)) ?? []; + const mentionRegexes = buildMentionRegexes(cfg); return { mentionRegexes, allowFrom: cfg.whatsapp?.allowFrom }; } @@ -166,10 +160,8 @@ function isBotMentioned( mentionCfg: MentionConfig, ): boolean { const clean = (text: string) => - text - // Remove zero-width and directionality markers WhatsApp injects around display names - .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "") - .toLowerCase(); + // Remove zero-width and directionality markers WhatsApp injects around display names + normalizeMentionText(text); const isSelfChat = isSelfChatMode(msg.selfE164, mentionCfg.allowFrom); @@ -212,9 +204,7 @@ function debugMention( const details = { from: msg.from, body: msg.body, - bodyClean: msg.body - .replace(/[\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, "") - .toLowerCase(), + bodyClean: normalizeMentionText(msg.body), mentionedJids: msg.mentionedJids ?? null, selfJid: msg.selfJid ?? null, selfE164: msg.selfE164 ?? null, From d813e14950b4d79ff4c88aeecef89b5c936c51e2 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:38:36 +0100 Subject: [PATCH 036/110] chore: update mention gating docs and tests --- docs/configuration.md | 3 ++- docs/discord.md | 1 + docs/group-messages.md | 4 +++- docs/groups.md | 1 + docs/imessage.md | 2 +- docs/slack.md | 2 +- docs/telegram.md | 4 ++-- docs/troubleshooting.md | 4 ++-- src/auto-reply/reply/mentions.test.ts | 30 +++++++++++++++++++++++ src/imessage/monitor.test.ts | 30 +++++++++++++++++++++++ src/telegram/bot.test.ts | 34 +++++++++++++++++++++++++++ 11 files changed, 107 insertions(+), 8 deletions(-) create mode 100644 src/auto-reply/reply/mentions.test.ts diff --git a/docs/configuration.md b/docs/configuration.md index a7d53405a..1959ee0ad 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -110,7 +110,7 @@ Optional agent identity used for defaults and UX. This is written by the macOS o If set, CLAWDBOT derives defaults (only when you haven’t set them explicitly): - `messages.responsePrefix` from `identity.emoji` -- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups) +- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups across Telegram/Slack/Discord/iMessage/WhatsApp) ```json5 { @@ -183,6 +183,7 @@ Group messages default to **require mention** (either metadata mention or regex **Mention types:** - **Metadata mentions**: Native platform @-mentions (e.g., WhatsApp tap-to-mention). Ignored in WhatsApp self-chat mode (see `whatsapp.allowFrom`). - **Text patterns**: Regex patterns defined in `mentionPatterns`. Always checked regardless of self-chat mode. +- Mention gating is enforced only when mention detection is possible (native mentions or at least one `mentionPattern`). ```json5 { diff --git a/docs/discord.md b/docs/discord.md index 7c68ef72b..a96bfff0b 100644 --- a/docs/discord.md +++ b/docs/discord.md @@ -123,6 +123,7 @@ Example “single server, only allow me, only allow #help”: Notes: - `requireMention: true` means the bot only replies when mentioned (recommended for shared channels). +- `routing.groupChat.mentionPatterns` also count as mentions for guild messages. - If `channels` is present, any channel not listed is denied by default. ### 6) Verify it works diff --git a/docs/group-messages.md b/docs/group-messages.md index 00563d39a..0c6701cd1 100644 --- a/docs/group-messages.md +++ b/docs/group-messages.md @@ -1,5 +1,5 @@ --- -summary: "Behavior and config for WhatsApp group message handling" +summary: "Behavior and config for WhatsApp group message handling (mentionPatterns are shared across surfaces)" read_when: - Changing group message rules or mentions --- @@ -7,6 +7,8 @@ read_when: Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session. +Note: `routing.groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior. + ## 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. diff --git a/docs/groups.md b/docs/groups.md index c80c02a4a..48a562ed4 100644 --- a/docs/groups.md +++ b/docs/groups.md @@ -51,6 +51,7 @@ Group messages require a mention unless overridden per group. Defaults live per Notes: - `mentionPatterns` are case-insensitive regexes. - Surfaces that provide explicit mentions still pass; patterns are a fallback. +- Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured). - Discord defaults live in `discord.guilds."*"` (overridable per guild/channel). ## Activation (owner-only) diff --git a/docs/imessage.md b/docs/imessage.md index 54d391f87..f602f6de7 100644 --- a/docs/imessage.md +++ b/docs/imessage.md @@ -55,7 +55,7 @@ imsg chats --limit 20 ## Group chat behavior - Group messages set `ChatType=group`, `GroupSubject`, and `GroupMembers`. -- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns`. +- Group activation respects `imessage.groups."*".requireMention` and `routing.groupChat.mentionPatterns` (patterns are required to detect mentions on iMessage). - Replies go back to the same `chat_id` (group or direct). ## Troubleshooting diff --git a/docs/slack.md b/docs/slack.md index a42b7cd53..40169515e 100644 --- a/docs/slack.md +++ b/docs/slack.md @@ -158,6 +158,6 @@ Slack tool actions can be gated with `slack.actions.*`: | emojiList | enabled | Custom emoji list | ## Notes -- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`). +- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`); `routing.groupChat.mentionPatterns` also count as mentions. - Reaction notifications follow `slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`). - Attachments are downloaded to the media store when permitted and under the size limit. diff --git a/docs/telegram.md b/docs/telegram.md index d6f868314..058a5c36e 100644 --- a/docs/telegram.md +++ b/docs/telegram.md @@ -35,7 +35,7 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup ## Planned implementation details - Library: grammY is the only client for send + gateway (fetch fallback removed); grammY throttler is enabled by default to stay under Bot API limits. -- Inbound normalization: maps Bot API updates to `MsgContext` with `Surface: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, `Timestamp`, and reply-to metadata (`ReplyToId`, `ReplyToBody`, `ReplyToSender`) when the user replies; reply context is appended to `Body` as a `[Replying to ...]` block (includes `id:` when available); groups require @bot mention by default (override per chat in config). +- Inbound normalization: maps Bot API updates to `MsgContext` with `Surface: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, `Timestamp`, and reply-to metadata (`ReplyToId`, `ReplyToBody`, `ReplyToSender`) when the user replies; reply context is appended to `Body` as a `[Replying to ...]` block (includes `id:` when available); groups require @bot mention or a `routing.groupChat.mentionPatterns` match by default (override per chat in config). - Outbound: text and media (photo/video/audio/document) with optional caption; chunked to limits. Typing cue sent best-effort. - Config: `TELEGRAM_BOT_TOKEN` env or `telegram.botToken` required; `telegram.groups`, `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.replyToMode`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`, `telegram.webhookPath` supported. - Mention gating precedence (most specific wins): `telegram.groups..requireMention` → `telegram.groups."*".requireMention` → default `true`. @@ -65,7 +65,7 @@ Example config: ## Group etiquette - Keep privacy mode off if you expect the bot to read all messages; with privacy on, it only sees commands/mentions. - Make the bot an admin if you need it to send in restricted groups or channels. -- Mention the bot (`@yourbot`) or use commands to trigger; per-group overrides live in `telegram.groups` if you want always-on behavior. +- Mention the bot (`@yourbot`) or use a `routing.groupChat.mentionPatterns` trigger; per-group overrides live in `telegram.groups` if you want always-on behavior. ## Reply tags To request a threaded reply, the model can include one tag in its output: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 21e80c5ec..ec56836eb 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -29,8 +29,8 @@ cat ~/.clawdbot/clawdbot.json | jq '.whatsapp.allowFrom' **Check 2:** For group chats, is mention required? ```bash -# The message must match mentionPatterns or explicit mentions; defaults live in whatsapp.groups -cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups' +# The message must match mentionPatterns or explicit mentions; defaults live in provider groups/guilds. +cat ~/.clawdbot/clawdbot.json | jq '.routing.groupChat, .whatsapp.groups, .telegram.groups, .imessage.groups, .discord.guilds' ``` **Check 3:** Check the logs diff --git a/src/auto-reply/reply/mentions.test.ts b/src/auto-reply/reply/mentions.test.ts new file mode 100644 index 000000000..34639c5aa --- /dev/null +++ b/src/auto-reply/reply/mentions.test.ts @@ -0,0 +1,30 @@ +import { describe, expect, it } from "vitest"; + +import { + buildMentionRegexes, + matchesMentionPatterns, + normalizeMentionText, +} from "./mentions.js"; + +describe("mention helpers", () => { + it("builds regexes and skips invalid patterns", () => { + const regexes = buildMentionRegexes({ + routing: { + groupChat: { mentionPatterns: ["\\bclawd\\b", "(invalid"] }, + }, + }); + expect(regexes).toHaveLength(1); + expect(regexes[0]?.test("clawd")).toBe(true); + }); + + it("normalizes zero-width characters", () => { + expect(normalizeMentionText("cl\u200bawd")).toBe("clawd"); + }); + + it("matches patterns case-insensitively", () => { + const regexes = buildMentionRegexes({ + routing: { groupChat: { mentionPatterns: ["\\bclawd\\b"] } }, + }); + expect(matchesMentionPatterns("CLAWD: hi", regexes)).toBe(true); + }); +}); diff --git a/src/imessage/monitor.test.ts b/src/imessage/monitor.test.ts index 6b9dac986..16810333c 100644 --- a/src/imessage/monitor.test.ts +++ b/src/imessage/monitor.test.ts @@ -139,6 +139,36 @@ describe("monitorIMessageProvider", () => { expect(replyMock).toHaveBeenCalled(); }); + it("allows group messages when requireMention is true but no mentionPatterns exist", async () => { + config = { + ...config, + routing: { groupChat: { mentionPatterns: [] }, allowFrom: [] }, + imessage: { groups: { "*": { requireMention: true } } }, + }; + const run = monitorIMessageProvider(); + await waitForSubscribe(); + + notificationHandler?.({ + method: "message", + params: { + message: { + id: 12, + chat_id: 777, + sender: "+15550001111", + is_from_me: false, + text: "hello group", + is_group: true, + }, + }, + }); + + await flush(); + closeResolve?.(); + await run; + + expect(replyMock).toHaveBeenCalled(); + }); + it("prefixes tool and final replies with responsePrefix", async () => { config = { ...config, diff --git a/src/telegram/bot.test.ts b/src/telegram/bot.test.ts index 96fd5b85c..bee9bd560 100644 --- a/src/telegram/bot.test.ts +++ b/src/telegram/bot.test.ts @@ -193,6 +193,40 @@ describe("createTelegramBot", () => { expect(replySpy).not.toHaveBeenCalled(); }); + it("allows group messages when requireMention is enabled but mentions cannot be detected", async () => { + onSpy.mockReset(); + const replySpy = replyModule.__replySpy as unknown as ReturnType< + typeof vi.fn + >; + replySpy.mockReset(); + + loadConfig.mockReturnValue({ + routing: { groupChat: { mentionPatterns: [] } }, + telegram: { groups: { "*": { requireMention: true } } }, + }); + + createTelegramBot({ token: "tok" }); + const handler = onSpy.mock.calls[0][1] as ( + ctx: Record, + ) => Promise; + + await handler({ + message: { + chat: { id: 7, type: "group", title: "Test Group" }, + text: "hello everyone", + date: 1736380800, + message_id: 3, + from: { id: 9, first_name: "Ada" }, + }, + me: {}, + getFile: async () => ({ download: async () => new Uint8Array() }), + }); + + expect(replySpy).toHaveBeenCalledTimes(1); + const payload = replySpy.mock.calls[0][0]; + expect(payload.WasMentioned).toBe(false); + }); + it("includes reply-to context when a Telegram reply is received", async () => { onSpy.mockReset(); sendMessageSpy.mockReset(); From f7074ea45fbf72e0d3a2a8f0acbad077150030bd Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:39:42 +0100 Subject: [PATCH 037/110] test: cover logging defaults --- src/config/model-alias-defaults.test.ts | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/config/model-alias-defaults.test.ts b/src/config/model-alias-defaults.test.ts index b2599f94f..352608ec9 100644 --- a/src/config/model-alias-defaults.test.ts +++ b/src/config/model-alias-defaults.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { applyModelAliasDefaults } from "./defaults.js"; +import { applyLoggingDefaults, applyModelAliasDefaults } from "./defaults.js"; import type { ClawdbotConfig } from "./types.js"; describe("applyModelAliasDefaults", () => { @@ -74,3 +74,17 @@ describe("applyModelAliasDefaults", () => { ); }); }); + +describe("applyLoggingDefaults", () => { + it("defaults redactSensitive to tools", () => { + const result = applyLoggingDefaults({ logging: {} }); + expect(result.logging?.redactSensitive).toBe("tools"); + }); + + it("preserves explicit redactSensitive", () => { + const result = applyLoggingDefaults({ + logging: { redactSensitive: "off" }, + }); + expect(result.logging?.redactSensitive).toBe("off"); + }); +}); From 6fe250cb46caa5fdcdf22c7aea5f84b12c05473d Mon Sep 17 00:00:00 2001 From: Jarvis Date: Tue, 6 Jan 2026 01:53:29 +0100 Subject: [PATCH 038/110] docs(slack): add missing scopes for DM replies (#235) The manifest was missing scopes required for conversations.open API, which is used to get DM channel IDs for replies. Added scopes: - im:write (required for DM replies) - im:read (list DM conversations) - mpim:write (reply to multi-person DMs) - mpim:read (list MPDMs) - groups:write (private channel interactions) - groups:read (list private channels) Without im:write, the example config (dm.enabled: true) cannot actually reply to DMs - fails with missing_scope error. Co-authored-by: Manuel Hettich <17690367+ManuelHettich@users.noreply.github.com> Co-authored-by: Peter Steinberger --- docs/slack.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/slack.md b/docs/slack.md index 40169515e..2a287176d 100644 --- a/docs/slack.md +++ b/docs/slack.md @@ -55,8 +55,14 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i "channels:history", "channels:read", "groups:history", + "groups:read", + "groups:write", "im:history", + "im:read", + "im:write", "mpim:history", + "mpim:read", + "mpim:write", "users:read", "app_mentions:read", "reactions:read", From bd2e0031718b92016a8cd65b4c59f8eb0c494502 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:52:01 +0100 Subject: [PATCH 039/110] docs: expand Slack scope notes --- CHANGELOG.md | 1 + docs/slack.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d3572d31..07afb65df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,7 @@ - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251. +- Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235. - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242. diff --git a/docs/slack.md b/docs/slack.md index 2a287176d..d68d4e1a7 100644 --- a/docs/slack.md +++ b/docs/slack.md @@ -98,6 +98,44 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i } ``` +## Scopes (current vs optional) +Slack's Conversations API is type-scoped: you only need the scopes for the +conversation types you actually touch (channels, groups, im, mpim). See +https://api.slack.com/docs/conversations-api for the overview. + +### Required by current code +- `chat:write` (send/update/delete messages via `chat.postMessage`) + https://api.slack.com/methods/chat.postMessage +- `im:write` (open DMs via `conversations.open` for user DMs) + https://api.slack.com/methods/conversations.open +- `channels:history`, `groups:history`, `im:history`, `mpim:history` + (`conversations.history` in `src/slack/actions.ts`) + https://api.slack.com/methods/conversations.history +- `channels:read`, `groups:read`, `im:read`, `mpim:read` + (`conversations.info` in `src/slack/monitor.ts`) + https://api.slack.com/methods/conversations.info +- `users:read` (`users.info` in `src/slack/monitor.ts` + `src/slack/actions.ts`) + https://api.slack.com/methods/users.info +- `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`) + https://api.slack.com/methods/reactions.get + https://api.slack.com/methods/reactions.add +- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`) + https://api.slack.com/scopes/pins:read + https://api.slack.com/scopes/pins:write +- `emoji:read` (`emoji.list`) + https://api.slack.com/scopes/emoji:read +- `files:write` (uploads via `files.uploadV2`) + https://api.slack.com/messaging/files/uploading + +### Not needed today (but likely future) +- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`) +- `groups:write` (only if we add private-channel management: create/rename/invite/archive) +- `chat:write.public` (only if we want to post to channels the bot isn't in) + https://api.slack.com/scopes/chat:write.public +- `users:read.email` (only if we need email fields from `users.info`) + https://api.slack.com/changelog/2017-04-narrowing-email-access +- `files:read` (only if we start listing/reading file metadata) + ## Config Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens: From b04c838c15e55ed9a184237e1173da7fea31bb86 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 00:56:29 +0000 Subject: [PATCH 040/110] feat!: redesign model config + auth profiles --- CHANGELOG.md | 5 +- docs/configuration.md | 104 ++++--- docs/doctor.md | 5 + docs/faq.md | 26 +- docs/models.md | 46 +-- docs/onboarding.md | 4 +- docs/proposals/model-config.md | 19 +- docs/tools.md | 2 +- docs/tui.md | 2 +- docs/wizard.md | 2 +- src/agents/agent-paths.ts | 7 +- src/agents/auth-profiles.test.ts | 42 +++ src/agents/auth-profiles.ts | 314 +++++++++++++++++++++ src/agents/model-auth.test.ts | 42 ++- src/agents/model-auth.ts | 308 +++++++++----------- src/agents/model-fallback.ts | 41 ++- src/agents/model-selection.test.ts | 28 +- src/agents/model-selection.ts | 29 +- src/agents/pi-embedded-helpers.ts | 32 ++- src/agents/pi-embedded-runner.ts | 118 +++++++- src/agents/tools/image-tool.ts | 21 +- src/auto-reply/model.ts | 13 +- src/auto-reply/reply.directive.test.ts | 119 ++++++-- src/auto-reply/reply.ts | 8 +- src/auto-reply/reply/agent-runner.ts | 1 + src/auto-reply/reply/commands.ts | 77 ++--- src/auto-reply/reply/directive-handling.ts | 171 ++++++++--- src/auto-reply/reply/followup-runner.ts | 1 + src/auto-reply/reply/model-selection.ts | 24 +- src/auto-reply/reply/queue.ts | 1 + src/commands/agent.test.ts | 3 +- src/commands/agent.ts | 17 +- src/commands/configure.ts | 48 +++- src/commands/models/aliases.ts | 49 +++- src/commands/models/fallbacks.ts | 39 ++- src/commands/models/image-fallbacks.ts | 37 ++- src/commands/models/list.ts | 124 ++++++-- src/commands/models/scan.ts | 102 +++---- src/commands/models/set-image.ts | 28 +- src/commands/models/set.ts | 28 +- src/commands/models/shared.ts | 3 +- src/commands/onboard-auth.test.ts | 34 ++- src/commands/onboard-auth.ts | 97 ++++--- src/commands/onboard-helpers.ts | 8 +- src/commands/onboard-non-interactive.ts | 11 +- src/commands/sessions.test.ts | 6 +- src/commands/setup.ts | 4 +- src/config/config.test.ts | 44 +++ src/config/defaults.ts | 46 +-- src/config/io.ts | 10 +- src/config/legacy.ts | 187 +++++++++++- src/config/model-alias-defaults.test.ts | 106 +++---- src/config/paths.ts | 10 +- src/config/schema.ts | 27 +- src/config/sessions.ts | 1 + src/config/types.ts | 39 ++- src/config/validation.ts | 4 +- src/config/zod-schema.ts | 41 ++- src/infra/shell-env.ts | 12 +- src/wizard/onboarding.ts | 50 +++- 60 files changed, 2037 insertions(+), 790 deletions(-) create mode 100644 src/agents/auth-profiles.test.ts create mode 100644 src/agents/auth-profiles.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 07afb65df..3b3c82b04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ ### Breaking - Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only). +- Model config schema changes (auth profiles + model lists); doctor auto-migrates and the gateway rewrites legacy configs on startup. ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. @@ -16,10 +17,10 @@ - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`. - macOS: Connections settings now use a custom sidebar to avoid toolbar toggle issues, with rounded styling and full-width row hit targets. - macOS: drop deprecated `afterMs` from agent wait params to match gateway schema. -- Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth.json. +- Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth-profiles.json. - Model: `/model` list shows auth source (masked key or OAuth email) per provider. - Model: `/model list` is an alias for `/model`. -- Model: `/model` output now includes auth source location (env/auth.json/models.json). +- Model: `/model` output now includes auth source location (env/auth-profiles.json/models.json). - Model: avoid duplicate `missing (missing)` auth labels in `/model` list output. - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding. - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments. diff --git a/docs/configuration.md b/docs/configuration.md index 1959ee0ad..70eabc4e7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -91,18 +91,40 @@ Env var equivalent: ### Auth storage (OAuth + API keys) -Clawdbot stores **OAuth credentials** in: +Clawdbot stores **auth profiles** (OAuth + API keys) in: +- `~/.clawdbot/agent/auth-profiles.json` + +Legacy OAuth imports: - `~/.clawdbot/credentials/oauth.json` (or `$CLAWDBOT_STATE_DIR/credentials/oauth.json`) -Clawdbot stores **API keys** in the agent auth store: -- `~/.clawdbot/agent/auth.json` +The embedded Pi agent maintains a runtime cache at: +- `~/.clawdbot/agent/auth.json` (managed automatically; don’t edit manually) Overrides: -- OAuth dir: `CLAWDBOT_OAUTH_DIR` +- OAuth dir (legacy import only): `CLAWDBOT_OAUTH_DIR` - Agent dir: `CLAWDBOT_AGENT_DIR` (preferred), `PI_CODING_AGENT_DIR` (legacy) -On first use, Clawdbot imports `oauth.json` entries into `auth.json` so the embedded -agent can use them. `oauth.json` remains the source of truth for OAuth refresh. +On first use, Clawdbot imports `oauth.json` entries into `auth-profiles.json`. + +### `auth` + +Optional metadata for auth profiles. This does **not** store secrets; it maps +profile IDs to a provider + mode (and optional email) and defines the provider +rotation order used for failover. + +```json5 +{ + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "oauth", email: "me@example.com" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" } + }, + order: { + anthropic: ["anthropic:default", "anthropic:work"] + } + } +} +``` ### `identity` @@ -494,14 +516,12 @@ Defaults for Talk mode (macOS/iOS/Android). Voice IDs fall back to `ELEVENLABS_V ### `agent` Controls the embedded agent runtime (model/thinking/verbose/timeouts). -`allowedModels` lets `/model` list/filter and enforce a per-session allowlist -(omit to show the full catalog). -`modelAliases` adds short names for `/model` (alias -> provider/model). -`modelFallbacks` lists ordered fallback models to try when the default fails. -`imageModel` selects an image-capable model for the `image` tool. -`imageModelFallbacks` lists ordered fallback image models for the `image` tool. +`agent.models` defines the configured model catalog (and acts as the allowlist for `/model`). +`agent.model.primary` sets the default model; `agent.model.fallbacks` are global failovers. +`agent.imageModel` is optional and is **only used if the primary model lacks image input**. -Clawdbot also ships a few built-in `modelAliases` shorthands (when an `agent` section exists): +Clawdbot also ships a few built-in alias shorthands. Defaults only apply when the model +is already present in `agent.models`: - `opus` -> `anthropic/claude-opus-4-5` - `sonnet` -> `anthropic/claude-sonnet-4-5` @@ -515,23 +535,24 @@ If you configure the same alias name (case-insensitive) yourself, your value win ```json5 { agent: { - model: "anthropic/claude-opus-4-5", - allowedModels: [ - "anthropic/claude-opus-4-5", - "anthropic/claude-sonnet-4-1" - ], - modelAliases: { - Opus: "anthropic/claude-opus-4-5", - Sonnet: "anthropic/claude-sonnet-4-1" + models: { + "anthropic/claude-opus-4-5": { alias: "Opus" }, + "anthropic/claude-sonnet-4-1": { alias: "Sonnet" }, + "openrouter/deepseek/deepseek-r1:free": {} + }, + model: { + primary: "anthropic/claude-opus-4-5", + fallbacks: [ + "openrouter/deepseek/deepseek-r1:free", + "openrouter/meta-llama/llama-3.3-70b-instruct:free" + ] + }, + imageModel: { + primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free", + fallbacks: [ + "openrouter/google/gemini-2.0-flash-vision:free" + ] }, - modelFallbacks: [ - "openrouter/deepseek/deepseek-r1:free", - "openrouter/meta-llama/llama-3.3-70b-instruct:free" - ], - imageModel: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free", - imageModelFallbacks: [ - "openrouter/google/gemini-2.0-flash-vision:free" - ], thinkingDefault: "low", verboseDefault: "off", elevatedDefault: "on", @@ -566,8 +587,8 @@ Block streaming: } ``` -`agent.model` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`). -If `modelAliases` is configured, you may also use the alias key (e.g. `Opus`). +`agent.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`). +Aliases come from `agent.models.*.alias` (e.g. `Opus`). If you omit the provider, CLAWDBOT currently assumes `anthropic` as a temporary deprecation fallback. Z.AI models are available as `zai/` (e.g. `zai/glm-4.7`) and require @@ -729,11 +750,16 @@ When `models.providers` is present, Clawdbot writes/merges a `models.json` into - default behavior: **merge** (keeps existing providers, overrides on name) - set `models.mode: "replace"` to overwrite the file contents -Select the model via `agent.model` (provider/model). +Select the model via `agent.model.primary` (provider/model). ```json5 { - agent: { model: "custom-proxy/llama-3.1-8b" }, + agent: { + model: { primary: "custom-proxy/llama-3.1-8b" }, + models: { + "custom-proxy/llama-3.1-8b": {} + } + }, models: { mode: "merge", providers: { @@ -766,14 +792,10 @@ via **LM Studio** using the **Responses API**. ```json5 { agent: { - model: "Minimax", - allowedModels: [ - "anthropic/claude-opus-4-5", - "lmstudio/minimax-m2.1-gs32" - ], - modelAliases: { - Opus: "anthropic/claude-opus-4-5", - Minimax: "lmstudio/minimax-m2.1-gs32" + model: { primary: "lmstudio/minimax-m2.1-gs32" }, + models: { + "anthropic/claude-opus-4-5": { alias: "Opus" }, + "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } } }, models: { diff --git a/docs/doctor.md b/docs/doctor.md index e07f15229..51292f5fa 100644 --- a/docs/doctor.md +++ b/docs/doctor.md @@ -27,8 +27,13 @@ Doctor will: - Show the migration it applied. - Rewrite `~/.clawdbot/clawdbot.json` with the updated schema. +The Gateway also auto-runs doctor migrations on startup when it detects a legacy +config format, so stale configs are repaired without manual intervention. + Current migrations: - `routing.allowFrom` → `whatsapp.allowFrom` +- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` + → `agent.models` + `agent.model.primary/fallbacks` + `agent.imageModel.primary/fallbacks` ## Usage diff --git a/docs/faq.md b/docs/faq.md index 956cf5e3c..d969916bc 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,7 +15,8 @@ Everything lives under `~/.clawdbot/`: |------|---------| | `~/.clawdbot/clawdbot.json` | Main config (JSON5) | | `~/.clawdbot/credentials/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) | -| `~/.clawdbot/agent/auth.json` | API key store | +| `~/.clawdbot/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | +| `~/.clawdbot/agent/auth.json` | Runtime API key cache (managed automatically) | | `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens | | `~/.clawdbot/sessions/` | Conversation history & state | | `~/.clawdbot/sessions/sessions.json` | Session metadata | @@ -576,21 +577,16 @@ List available models with `/model`, `/model list`, or `/model status`. Clawdbot ships a few default model shorthands (you can override them in config): `opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`. -**Setup:** Configure allowed models and aliases in `clawdbot.json`: +**Setup:** Configure models and aliases in `clawdbot.json`: ```json { "agent": { - "model": "anthropic/claude-opus-4-5", - "allowedModels": [ - "anthropic/claude-opus-4-5", - "anthropic/claude-sonnet-4-5", - "anthropic/claude-haiku-4-5" - ], - "modelAliases": { - "opus": "anthropic/claude-opus-4-5", - "sonnet": "anthropic/claude-sonnet-4-5", - "haiku": "anthropic/claude-haiku-4-5" + "model": { "primary": "anthropic/claude-opus-4-5" }, + "models": { + "anthropic/claude-opus-4-5": { "alias": "opus" }, + "anthropic/claude-sonnet-4-5": { "alias": "sonnet" }, + "anthropic/claude-haiku-4-5": { "alias": "haiku" } } } } @@ -606,7 +602,8 @@ If you don't want to use Anthropic directly, you can use alternative providers: ```json5 { agent: { - model: "openrouter/anthropic/claude-sonnet-4", + model: { primary: "openrouter/anthropic/claude-sonnet-4" }, + models: { "openrouter/anthropic/claude-sonnet-4": {} }, env: { OPENROUTER_API_KEY: "sk-or-..." } } } @@ -616,7 +613,8 @@ If you don't want to use Anthropic directly, you can use alternative providers: ```json5 { agent: { - model: "zai/glm-4.7", + model: { primary: "zai/glm-4.7" }, + models: { "zai/glm-4.7": {} }, env: { ZAI_API_KEY: "..." } } } diff --git a/docs/models.md b/docs/models.md index 32f6d0863..cf88065a5 100644 --- a/docs/models.md +++ b/docs/models.md @@ -16,35 +16,32 @@ that prefers tool-call + image-capable models and maintains ordered fallbacks. - default: configured models only - flags: `--all` (full catalog), `--local`, `--provider `, `--json`, `--plain` - `clawdbot models status` - - show default model + aliases + fallbacks + allowlist + - show default model + aliases + fallbacks + configured models - `clawdbot models set ` - - writes `agent.model` in config + - writes `agent.model.primary` and ensures `agent.models` entry - `clawdbot models set-image ` - - writes `agent.imageModel` in config + - writes `agent.imageModel.primary` and ensures `agent.models` entry - `clawdbot models aliases list|add|remove` - - writes `agent.modelAliases` + - writes `agent.models.*.alias` - `clawdbot models fallbacks list|add|remove|clear` - - writes `agent.modelFallbacks` + - writes `agent.model.fallbacks` - `clawdbot models image-fallbacks list|add|remove|clear` - - writes `agent.imageModelFallbacks` + - writes `agent.imageModel.fallbacks` - `clawdbot models scan` - OpenRouter :free scan; probe tool-call + image; interactive selection ## Config changes -- Add `agent.modelFallbacks: string[]` (ordered list of provider/model IDs). -- Add `agent.imageModel?: string` (optional image-capable model for image tool). -- Add `agent.imageModelFallbacks?: string[]` (ordered list for image tool). -- Keep existing: - - `agent.model` (default) - - `agent.allowedModels` (list filter) - - `agent.modelAliases` (shortcut names) +- `agent.models` (configured model catalog + aliases). +- `agent.model.primary` + `agent.model.fallbacks`. +- `agent.imageModel.primary` + `agent.imageModel.fallbacks` (optional). +- `auth.profiles` + `auth.order` for per-provider auth failover. ## Scan behavior (models scan) Input - OpenRouter `/models` list (filter `:free`) -- Requires `OPENROUTER_API_KEY` (or stored OpenRouter key in auth storage) +- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Probe controls: `--timeout`, `--concurrency` @@ -66,17 +63,20 @@ Interactive selection (TTY) - Non-TTY: auto-select; require `--yes`/`--no-input` to apply. Output -- Writes `agent.modelFallbacks` ordered. -- Writes `agent.imageModelFallbacks` ordered (image-capable models). -- Optional `--set-default` to set `agent.model`. -- Optional `--set-image` to set `agent.imageModel`. +- Writes `agent.model.fallbacks` ordered. +- Writes `agent.imageModel.fallbacks` ordered (image-capable models). +- Ensures `agent.models` entries exist for selected models. +- Optional `--set-default` to set `agent.model.primary`. +- Optional `--set-image` to set `agent.imageModel.primary`. ## Runtime fallback -- On model failure: try `agent.modelFallbacks` in order. -- Ignore fallback entries not in `agent.allowedModels` (if allowlist set). -- Persist last successful provider/model to session entry. -- `/status` shows last used model (not just default). +- On model failure: try `agent.model.fallbacks` in order. +- Per-provider auth failover uses `auth.order` (or stored profile order) **before** + moving to the next model. +- Image routing uses `agent.imageModel` **only when configured** and the primary + model lacks image input. +- Persist last successful provider/model to session entry; auth profile success is global. ## Tests @@ -86,5 +86,5 @@ Output ## Docs -- Update `docs/configuration.md` with `agent.modelFallbacks`. +- Update `docs/configuration.md` with `agent.models` + `agent.model` + `agent.imageModel`. - Keep this doc current when CLI surface or scan logic changes. diff --git a/docs/onboarding.md b/docs/onboarding.md index 200fd267e..d1b1c1dd1 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -41,7 +41,7 @@ The macOS app should: - `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`) Why this location matters: it’s the Clawdbot-owned OAuth store. -Clawdbot also imports `oauth.json` into the agent auth store (`~/.clawdbot/agent/auth.json`) on first use. +Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on first use. ### Recommended: OAuth (OpenAI Codex) @@ -148,7 +148,7 @@ If the Gateway runs on another machine, OAuth credentials must be created/stored 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 +- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agent/auth-profiles.json`) on the gateway host - mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files) ### Manual credential setup diff --git a/docs/proposals/model-config.md b/docs/proposals/model-config.md index 7de0d54d6..b7488378d 100644 --- a/docs/proposals/model-config.md +++ b/docs/proposals/model-config.md @@ -87,7 +87,7 @@ Model listing - alias - provider - auth order (from `auth.order`) - - auth source for the current provider (env/auth.json/models.json) + - auth source for the current provider (auth-profiles.json/env/shell env/models.json) ## Fallback behavior (global) @@ -121,19 +121,20 @@ Support detection ## Migration (doctor + gateway auto-run) Inputs -- `agent.model` (string) -- `agent.modelFallbacks` (string[]) -- `agent.imageModel` (string) -- `agent.imageModelFallbacks` (string[]) -- `agent.allowedModels` (string[]) -- `agent.modelAliases` (record) +- Legacy keys (pre-migration): + - `agent.model` (string) + - `agent.modelFallbacks` (string[]) + - `agent.imageModel` (string) + - `agent.imageModelFallbacks` (string[]) + - `agent.allowedModels` (string[]) + - `agent.modelAliases` (record) Outputs - `agent.models` map with keys for all referenced models - `agent.model.primary/fallbacks` - `agent.imageModel.primary/fallbacks` -- `auth.profiles` seeded from current auth.json + env (as `provider:default`) -- `auth.order` seeded with `["provider:default"]` +- Auth profile store seeded from current auth-profiles.json/auth.json + oauth.json + env (as `provider:default`) +- `auth.order` seeded with `["provider:default"]` when config is updated Auto-run - Gateway start detects legacy keys and runs doctor migration. diff --git a/docs/tools.md b/docs/tools.md index d9d87649d..94bd80a06 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -126,7 +126,7 @@ Core parameters: - `maxBytesMb` (optional size cap) Notes: -- Only available when `agent.imageModel` or `agent.imageModelFallbacks` is set. +- Only available when `agent.imageModel` is configured (primary or fallbacks). - Uses the image model directly (independent of the main chat model). ### `cron` diff --git a/docs/tui.md b/docs/tui.md index fbfbae82c..1585b75ec 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -48,7 +48,7 @@ Use SSH tunneling or Tailscale to reach the Gateway WS. - `/help` - `/status` - `/session ` (or `/sessions`) -- `/model ` (or `/models`) +- `/model ` (or `/model list`, `/models`) - `/think ` - `/verbose ` - `/elevated ` diff --git a/docs/wizard.md b/docs/wizard.md index 1682cf9ec..ccb885f7d 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -52,7 +52,7 @@ It does **not** install or change anything on the remote host. - **API key**: stores the key for you. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Skip**: no auth configured yet. - - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; API keys live in `~/.clawdbot/agent/auth.json`. + - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agent/auth-profiles.json` (API keys + OAuth). 3) **Workspace** - Default `~/clawd` (configurable). diff --git a/src/agents/agent-paths.ts b/src/agents/agent-paths.ts index 98a02d3b0..2fe019e75 100644 --- a/src/agents/agent-paths.ts +++ b/src/agents/agent-paths.ts @@ -1,14 +1,13 @@ import path from "node:path"; -import { CONFIG_DIR, resolveUserPath } from "../utils.js"; - -const DEFAULT_AGENT_DIR = path.join(CONFIG_DIR, "agent"); +import { resolveConfigDir, resolveUserPath } from "../utils.js"; export function resolveClawdbotAgentDir(): string { + const defaultAgentDir = path.join(resolveConfigDir(), "agent"); const override = process.env.CLAWDBOT_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim() || - DEFAULT_AGENT_DIR; + defaultAgentDir; return resolveUserPath(override); } diff --git a/src/agents/auth-profiles.test.ts b/src/agents/auth-profiles.test.ts new file mode 100644 index 000000000..c9bb4ec25 --- /dev/null +++ b/src/agents/auth-profiles.test.ts @@ -0,0 +1,42 @@ +import { describe, expect, it } from "vitest"; + +import { + type AuthProfileStore, + resolveAuthProfileOrder, +} from "./auth-profiles.js"; + +describe("resolveAuthProfileOrder", () => { + const store: AuthProfileStore = { + version: 1, + profiles: { + "anthropic:default": { + type: "api_key", + provider: "anthropic", + key: "sk-default", + }, + "anthropic:work": { + type: "api_key", + provider: "anthropic", + key: "sk-work", + }, + }, + }; + + it("prioritizes preferred profiles", () => { + const order = resolveAuthProfileOrder({ + store, + provider: "anthropic", + preferredProfile: "anthropic:work", + }); + expect(order[0]).toBe("anthropic:work"); + expect(order).toContain("anthropic:default"); + }); + + it("prioritizes last-good profile when no preferred override", () => { + const order = resolveAuthProfileOrder({ + store: { ...store, lastGood: { anthropic: "anthropic:work" } }, + provider: "anthropic", + }); + expect(order[0]).toBe("anthropic:work"); + }); +}); diff --git a/src/agents/auth-profiles.ts b/src/agents/auth-profiles.ts new file mode 100644 index 000000000..f3019f755 --- /dev/null +++ b/src/agents/auth-profiles.ts @@ -0,0 +1,314 @@ +import fs from "node:fs"; +import path from "node:path"; + +import { + getOAuthApiKey, + type OAuthCredentials, + type OAuthProvider, +} from "@mariozechner/pi-ai"; + +import type { ClawdbotConfig } from "../config/config.js"; +import { resolveOAuthPath } from "../config/paths.js"; +import { resolveUserPath } from "../utils.js"; +import { resolveClawdbotAgentDir } from "./agent-paths.js"; + +const AUTH_STORE_VERSION = 1; +const AUTH_PROFILE_FILENAME = "auth-profiles.json"; +const LEGACY_AUTH_FILENAME = "auth.json"; + +export type ApiKeyCredential = { + type: "api_key"; + provider: string; + key: string; + email?: string; +}; + +export type OAuthCredential = OAuthCredentials & { + type: "oauth"; + provider: OAuthProvider; + email?: string; +}; + +export type AuthProfileCredential = ApiKeyCredential | OAuthCredential; + +export type AuthProfileStore = { + version: number; + profiles: Record; + lastGood?: Record; +}; + +type LegacyAuthStore = Record; + +function resolveAuthStorePath(): string { + const agentDir = resolveClawdbotAgentDir(); + return path.join(agentDir, AUTH_PROFILE_FILENAME); +} + +function resolveLegacyAuthStorePath(): string { + const agentDir = resolveClawdbotAgentDir(); + return path.join(agentDir, LEGACY_AUTH_FILENAME); +} + +function loadJsonFile(pathname: string): unknown { + try { + if (!fs.existsSync(pathname)) return undefined; + const raw = fs.readFileSync(pathname, "utf8"); + return JSON.parse(raw) as unknown; + } catch { + return undefined; + } +} + +function saveJsonFile(pathname: string, data: unknown) { + const dir = path.dirname(pathname); + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); + } + fs.writeFileSync(pathname, `${JSON.stringify(data, null, 2)}\n`, "utf8"); + fs.chmodSync(pathname, 0o600); +} + +function coerceLegacyStore(raw: unknown): LegacyAuthStore | null { + if (!raw || typeof raw !== "object") return null; + const record = raw as Record; + if ("profiles" in record) return null; + const entries: LegacyAuthStore = {}; + for (const [key, value] of Object.entries(record)) { + if (!value || typeof value !== "object") continue; + const typed = value as Partial; + if (typed.type !== "api_key" && typed.type !== "oauth") continue; + entries[key] = { + ...typed, + provider: typed.provider ?? (key as OAuthProvider), + } as AuthProfileCredential; + } + return Object.keys(entries).length > 0 ? entries : null; +} + +function coerceAuthStore(raw: unknown): AuthProfileStore | null { + if (!raw || typeof raw !== "object") return null; + const record = raw as Record; + if (!record.profiles || typeof record.profiles !== "object") return null; + const profiles = record.profiles as Record; + const normalized: Record = {}; + for (const [key, value] of Object.entries(profiles)) { + if (!value || typeof value !== "object") continue; + const typed = value as Partial; + if (typed.type !== "api_key" && typed.type !== "oauth") continue; + if (!typed.provider) continue; + normalized[key] = typed as AuthProfileCredential; + } + return { + version: Number(record.version ?? AUTH_STORE_VERSION), + profiles: normalized, + lastGood: + record.lastGood && typeof record.lastGood === "object" + ? (record.lastGood as Record) + : undefined, + }; +} + +function mergeOAuthFileIntoStore(store: AuthProfileStore): boolean { + const oauthPath = resolveOAuthPath(); + const oauthRaw = loadJsonFile(oauthPath); + if (!oauthRaw || typeof oauthRaw !== "object") return false; + const oauthEntries = oauthRaw as Record; + let mutated = false; + for (const [provider, creds] of Object.entries(oauthEntries)) { + if (!creds || typeof creds !== "object") continue; + const profileId = `${provider}:default`; + if (store.profiles[profileId]) continue; + store.profiles[profileId] = { + type: "oauth", + provider: provider as OAuthProvider, + ...creds, + }; + mutated = true; + } + return mutated; +} + +export function loadAuthProfileStore(): AuthProfileStore { + const authPath = resolveAuthStorePath(); + const raw = loadJsonFile(authPath); + const asStore = coerceAuthStore(raw); + if (asStore) return asStore; + + const legacyRaw = loadJsonFile(resolveLegacyAuthStorePath()); + const legacy = coerceLegacyStore(legacyRaw); + if (legacy) { + const store: AuthProfileStore = { + version: AUTH_STORE_VERSION, + profiles: {}, + }; + for (const [provider, cred] of Object.entries(legacy)) { + const profileId = `${provider}:default`; + store.profiles[profileId] = { + ...cred, + provider: cred.provider ?? (provider as OAuthProvider), + }; + } + return store; + } + + return { version: AUTH_STORE_VERSION, profiles: {} }; +} + +export function ensureAuthProfileStore(): AuthProfileStore { + const authPath = resolveAuthStorePath(); + const raw = loadJsonFile(authPath); + const asStore = coerceAuthStore(raw); + if (asStore) return asStore; + + const legacyRaw = loadJsonFile(resolveLegacyAuthStorePath()); + const legacy = coerceLegacyStore(legacyRaw); + const store = legacy + ? { + version: AUTH_STORE_VERSION, + profiles: Object.fromEntries( + Object.entries(legacy).map(([provider, cred]) => [ + `${provider}:default`, + { ...cred, provider: cred.provider ?? (provider as OAuthProvider) }, + ]), + ), + } + : { version: AUTH_STORE_VERSION, profiles: {} }; + + const mergedOAuth = mergeOAuthFileIntoStore(store); + const shouldWrite = legacy !== null || mergedOAuth; + if (shouldWrite) { + saveJsonFile(authPath, store); + } + return store; +} + +export function saveAuthProfileStore(store: AuthProfileStore): void { + const authPath = resolveAuthStorePath(); + const payload = { + version: AUTH_STORE_VERSION, + profiles: store.profiles, + lastGood: store.lastGood ?? undefined, + } satisfies AuthProfileStore; + saveJsonFile(authPath, payload); +} + +export function upsertAuthProfile(params: { + profileId: string; + credential: AuthProfileCredential; +}): void { + const store = ensureAuthProfileStore(); + store.profiles[params.profileId] = params.credential; + saveAuthProfileStore(store); +} + +export function listProfilesForProvider( + store: AuthProfileStore, + provider: string, +): string[] { + return Object.entries(store.profiles) + .filter(([, cred]) => cred.provider === provider) + .map(([id]) => id); +} + +export function resolveAuthProfileOrder(params: { + cfg?: ClawdbotConfig; + store: AuthProfileStore; + provider: string; + preferredProfile?: string; +}): string[] { + const { cfg, store, provider, preferredProfile } = params; + const configuredOrder = cfg?.auth?.order?.[provider] ?? []; + const lastGood = store.lastGood?.[provider]; + const order = + configuredOrder.length > 0 + ? configuredOrder + : listProfilesForProvider(store, provider); + + const filtered = order.filter((profileId) => { + const cred = store.profiles[profileId]; + return cred ? cred.provider === provider : true; + }); + const deduped: string[] = []; + for (const entry of filtered) { + if (!deduped.includes(entry)) deduped.push(entry); + } + if (preferredProfile && deduped.includes(preferredProfile)) { + const rest = deduped.filter((entry) => entry !== preferredProfile); + if (lastGood && rest.includes(lastGood)) { + return [ + preferredProfile, + lastGood, + ...rest.filter((entry) => entry !== lastGood), + ]; + } + return [preferredProfile, ...rest]; + } + if (lastGood && deduped.includes(lastGood)) { + return [lastGood, ...deduped.filter((entry) => entry !== lastGood)]; + } + return deduped; +} + +export async function resolveApiKeyForProfile(params: { + cfg?: ClawdbotConfig; + store: AuthProfileStore; + profileId: string; +}): Promise<{ apiKey: string; provider: string; email?: string } | null> { + const { cfg, store, profileId } = params; + const cred = store.profiles[profileId]; + if (!cred) return null; + const profileConfig = cfg?.auth?.profiles?.[profileId]; + if (profileConfig && profileConfig.provider !== cred.provider) return null; + if (profileConfig && profileConfig.mode !== cred.type) return null; + + if (cred.type === "api_key") { + return { apiKey: cred.key, provider: cred.provider, email: cred.email }; + } + + const oauthCreds: Record = { + [cred.provider]: cred, + }; + const result = await getOAuthApiKey(cred.provider, oauthCreds); + if (!result) return null; + store.profiles[profileId] = { + ...cred, + ...result.newCredentials, + type: "oauth", + }; + saveAuthProfileStore(store); + return { + apiKey: result.apiKey, + provider: cred.provider, + email: cred.email, + }; +} + +export function markAuthProfileGood(params: { + store: AuthProfileStore; + provider: string; + profileId: string; +}): void { + const { store, provider, profileId } = params; + const profile = store.profiles[profileId]; + if (!profile || profile.provider !== provider) return; + store.lastGood = { ...(store.lastGood ?? {}), [provider]: profileId }; + saveAuthProfileStore(store); +} + +export function resolveAuthStorePathForDisplay(): string { + const pathname = resolveAuthStorePath(); + return pathname.startsWith("~") ? pathname : resolveUserPath(pathname); +} + +export function resolveAuthProfileDisplayLabel(params: { + cfg?: ClawdbotConfig; + store: AuthProfileStore; + profileId: string; +}): string { + const { cfg, store, profileId } = params; + const profile = store.profiles[profileId]; + const configEmail = cfg?.auth?.profiles?.[profileId]?.email?.trim(); + const email = configEmail || profile?.email?.trim(); + if (email) return `${profileId} (${email})`; + return profileId; +} diff --git a/src/agents/model-auth.test.ts b/src/agents/model-auth.test.ts index 5522a12ad..b8a41e3f4 100644 --- a/src/agents/model-auth.test.ts +++ b/src/agents/model-auth.test.ts @@ -2,7 +2,6 @@ import fs from "node:fs/promises"; import os from "node:os"; import path from "node:path"; import type { Api, Model } from "@mariozechner/pi-ai"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; import { describe, expect, it, vi } from "vitest"; const oauthFixture = { @@ -13,12 +12,16 @@ const oauthFixture = { }; describe("getApiKeyForModel", () => { - it("migrates legacy oauth.json into auth.json", async () => { + it("migrates legacy oauth.json into auth-profiles.json", async () => { const previousStateDir = process.env.CLAWDBOT_STATE_DIR; + const previousAgentDir = process.env.CLAWDBOT_AGENT_DIR; + const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR; const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-oauth-")); try { process.env.CLAWDBOT_STATE_DIR = tempDir; + process.env.CLAWDBOT_AGENT_DIR = path.join(tempDir, "agent"); + process.env.PI_CODING_AGENT_DIR = process.env.CLAWDBOT_AGENT_DIR; const oauthDir = path.join(tempDir, "credentials"); await fs.mkdir(oauthDir, { recursive: true, mode: 0o700 }); @@ -28,10 +31,6 @@ describe("getApiKeyForModel", () => { "utf8", ); - const agentDir = path.join(tempDir, "agent"); - await fs.mkdir(agentDir, { recursive: true, mode: 0o700 }); - const authStorage = discoverAuthStorage(agentDir); - vi.resetModules(); const { getApiKeyForModel } = await import("./model-auth.js"); @@ -41,18 +40,21 @@ describe("getApiKeyForModel", () => { api: "openai-codex-responses", } as Model; - const apiKey = await getApiKeyForModel(model, authStorage); - expect(apiKey).toBe(oauthFixture.access); + const apiKey = await getApiKeyForModel({ model }); + expect(apiKey.apiKey).toBe(oauthFixture.access); - const authJson = await fs.readFile( - path.join(agentDir, "auth.json"), + const authProfiles = await fs.readFile( + path.join(tempDir, "agent", "auth-profiles.json"), "utf8", ); - const authData = JSON.parse(authJson) as Record; - expect(authData["openai-codex"]).toMatchObject({ - type: "oauth", - access: oauthFixture.access, - refresh: oauthFixture.refresh, + const authData = JSON.parse(authProfiles) as Record; + expect(authData.profiles).toMatchObject({ + "openai-codex:default": { + type: "oauth", + provider: "openai-codex", + access: oauthFixture.access, + refresh: oauthFixture.refresh, + }, }); } finally { if (previousStateDir === undefined) { @@ -60,6 +62,16 @@ describe("getApiKeyForModel", () => { } else { process.env.CLAWDBOT_STATE_DIR = previousStateDir; } + if (previousAgentDir === undefined) { + delete process.env.CLAWDBOT_AGENT_DIR; + } else { + process.env.CLAWDBOT_AGENT_DIR = previousAgentDir; + } + if (previousPiAgentDir === undefined) { + delete process.env.PI_CODING_AGENT_DIR; + } else { + process.env.PI_CODING_AGENT_DIR = previousPiAgentDir; + } await fs.rm(tempDir, { recursive: true, force: true }); } }); diff --git a/src/agents/model-auth.ts b/src/agents/model-auth.ts index a497f8a1a..bf29e165b 100644 --- a/src/agents/model-auth.ts +++ b/src/agents/model-auth.ts @@ -1,179 +1,147 @@ -import fsSync from "node:fs"; -import os from "node:os"; -import path from "node:path"; - +import { type Api, getEnvApiKey, type Model } from "@mariozechner/pi-ai"; +import type { ClawdbotConfig } from "../config/config.js"; +import type { ModelProviderConfig } from "../config/types.js"; +import { getShellEnvAppliedKeys } from "../infra/shell-env.js"; import { - type Api, - getEnvApiKey, - getOAuthApiKey, - type Model, - type OAuthCredentials, - type OAuthProvider, -} from "@mariozechner/pi-ai"; -import type { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; + type AuthProfileStore, + ensureAuthProfileStore, + resolveApiKeyForProfile, + resolveAuthProfileOrder, +} from "./auth-profiles.js"; -import { CONFIG_DIR, resolveUserPath } from "../utils.js"; +export { + ensureAuthProfileStore, + resolveAuthProfileOrder, +} from "./auth-profiles.js"; -const OAUTH_FILENAME = "oauth.json"; -const DEFAULT_OAUTH_DIR = path.join(CONFIG_DIR, "credentials"); -let oauthStorageConfigured = false; -let oauthStorageMigrated = false; - -type OAuthStorage = Record; - -function resolveClawdbotOAuthPath(): string { - const overrideDir = - process.env.CLAWDBOT_OAUTH_DIR?.trim() || DEFAULT_OAUTH_DIR; - return path.join(resolveUserPath(overrideDir), OAUTH_FILENAME); +export function getCustomProviderApiKey( + cfg: ClawdbotConfig | undefined, + provider: string, +): string | undefined { + const providers = cfg?.models?.providers ?? {}; + const entry = providers[provider] as ModelProviderConfig | undefined; + const key = entry?.apiKey?.trim(); + return key || undefined; } -function loadOAuthStorageAt(pathname: string): OAuthStorage | null { - if (!fsSync.existsSync(pathname)) return null; - try { - const content = fsSync.readFileSync(pathname, "utf8"); - const json = JSON.parse(content) as OAuthStorage; - if (!json || typeof json !== "object") return null; - return json; - } catch { - return null; - } -} +export async function resolveApiKeyForProvider(params: { + provider: string; + cfg?: ClawdbotConfig; + profileId?: string; + preferredProfile?: string; + store?: AuthProfileStore; +}): Promise<{ apiKey: string; profileId?: string; source: string }> { + const { provider, cfg, profileId, preferredProfile } = params; + const store = params.store ?? ensureAuthProfileStore(); -function hasAnthropicOAuth(storage: OAuthStorage): boolean { - const entry = storage.anthropic as - | { - refresh?: string; - refresh_token?: string; - refreshToken?: string; - access?: string; - access_token?: string; - accessToken?: string; - } - | undefined; - if (!entry) return false; - const refresh = - entry.refresh ?? entry.refresh_token ?? entry.refreshToken ?? ""; - const access = entry.access ?? entry.access_token ?? entry.accessToken ?? ""; - return Boolean(refresh.trim() && access.trim()); -} - -function saveOAuthStorageAt(pathname: string, storage: OAuthStorage): void { - const dir = path.dirname(pathname); - fsSync.mkdirSync(dir, { recursive: true, mode: 0o700 }); - fsSync.writeFileSync( - pathname, - `${JSON.stringify(storage, null, 2)}\n`, - "utf8", - ); - fsSync.chmodSync(pathname, 0o600); -} - -function legacyOAuthPaths(): string[] { - const paths: string[] = []; - const piOverride = process.env.PI_CODING_AGENT_DIR?.trim(); - if (piOverride) { - paths.push(path.join(resolveUserPath(piOverride), OAUTH_FILENAME)); - } - paths.push(path.join(os.homedir(), ".pi", "agent", OAUTH_FILENAME)); - paths.push(path.join(os.homedir(), ".claude", OAUTH_FILENAME)); - paths.push(path.join(os.homedir(), ".config", "claude", OAUTH_FILENAME)); - paths.push(path.join(os.homedir(), ".config", "anthropic", OAUTH_FILENAME)); - return Array.from(new Set(paths)); -} - -function importLegacyOAuthIfNeeded(destPath: string): void { - if (fsSync.existsSync(destPath)) return; - for (const legacyPath of legacyOAuthPaths()) { - const storage = loadOAuthStorageAt(legacyPath); - if (!storage || !hasAnthropicOAuth(storage)) continue; - saveOAuthStorageAt(destPath, storage); - return; - } -} - -export function ensureOAuthStorage(): void { - if (oauthStorageConfigured) return; - oauthStorageConfigured = true; - const oauthPath = resolveClawdbotOAuthPath(); - importLegacyOAuthIfNeeded(oauthPath); -} - -function isValidOAuthCredential( - entry: OAuthCredentials | undefined, -): entry is OAuthCredentials { - if (!entry) return false; - return Boolean( - entry.access?.trim() && - entry.refresh?.trim() && - Number.isFinite(entry.expires), - ); -} - -function migrateOAuthStorageToAuthStorage( - authStorage: ReturnType, -): void { - if (oauthStorageMigrated) return; - oauthStorageMigrated = true; - const oauthPath = resolveClawdbotOAuthPath(); - const storage = loadOAuthStorageAt(oauthPath); - if (!storage) return; - for (const [provider, creds] of Object.entries(storage)) { - if (!isValidOAuthCredential(creds)) continue; - if (authStorage.get(provider)) continue; - authStorage.set(provider, { type: "oauth", ...creds }); - } -} - -export function hydrateAuthStorage( - authStorage: ReturnType, -): void { - ensureOAuthStorage(); - migrateOAuthStorageToAuthStorage(authStorage); -} - -function isOAuthProvider(provider: string): provider is OAuthProvider { - return ( - provider === "anthropic" || - provider === "anthropic-oauth" || - provider === "google" || - provider === "openai" || - provider === "openai-compatible" || - provider === "openai-codex" || - provider === "github-copilot" || - provider === "google-gemini-cli" || - provider === "google-antigravity" - ); -} - -export async function getApiKeyForModel( - model: Model, - authStorage: ReturnType, -): Promise { - ensureOAuthStorage(); - migrateOAuthStorageToAuthStorage(authStorage); - const storedKey = await authStorage.getApiKey(model.provider); - if (storedKey) return storedKey; - if (model.provider === "anthropic") { - const oauthEnv = process.env.ANTHROPIC_OAUTH_TOKEN; - if (oauthEnv?.trim()) return oauthEnv.trim(); - } - const envKey = getEnvApiKey(model.provider); - if (envKey) return envKey; - if (isOAuthProvider(model.provider)) { - const oauthPath = resolveClawdbotOAuthPath(); - const storage = loadOAuthStorageAt(oauthPath); - if (storage) { - try { - const result = await getOAuthApiKey(model.provider, storage); - if (result?.apiKey) { - storage[model.provider] = result.newCredentials; - saveOAuthStorageAt(oauthPath, storage); - return result.apiKey; - } - } catch { - // fall through to error below - } + if (profileId) { + const resolved = await resolveApiKeyForProfile({ + cfg, + store, + profileId, + }); + if (!resolved) { + throw new Error(`No credentials found for profile "${profileId}".`); } + return { + apiKey: resolved.apiKey, + profileId, + source: `profile:${profileId}`, + }; } - throw new Error(`No API key found for provider "${model.provider}"`); + + const order = resolveAuthProfileOrder({ + cfg, + store, + provider, + preferredProfile, + }); + for (const candidate of order) { + try { + const resolved = await resolveApiKeyForProfile({ + cfg, + store, + profileId: candidate, + }); + if (resolved) { + return { + apiKey: resolved.apiKey, + profileId: candidate, + source: `profile:${candidate}`, + }; + } + } catch {} + } + + const envResolved = resolveEnvApiKey(provider); + if (envResolved) { + return { apiKey: envResolved.apiKey, source: envResolved.source }; + } + + const customKey = getCustomProviderApiKey(cfg, provider); + if (customKey) { + return { apiKey: customKey, source: "models.json" }; + } + + throw new Error(`No API key found for provider "${provider}".`); +} + +export type EnvApiKeyResult = { apiKey: string; source: string }; + +export function resolveEnvApiKey(provider: string): EnvApiKeyResult | null { + const applied = new Set(getShellEnvAppliedKeys()); + const pick = (envVar: string): EnvApiKeyResult | null => { + const value = process.env[envVar]?.trim(); + if (!value) return null; + const source = applied.has(envVar) + ? `shell env: ${envVar}` + : `env: ${envVar}`; + return { apiKey: value, source }; + }; + + if (provider === "github-copilot") { + return ( + pick("COPILOT_GITHUB_TOKEN") ?? pick("GH_TOKEN") ?? pick("GITHUB_TOKEN") + ); + } + + if (provider === "anthropic") { + return pick("ANTHROPIC_OAUTH_TOKEN") ?? pick("ANTHROPIC_API_KEY"); + } + + if (provider === "google-vertex") { + const envKey = getEnvApiKey(provider); + if (!envKey) return null; + return { apiKey: envKey, source: "gcloud adc" }; + } + + const envMap: Record = { + openai: "OPENAI_API_KEY", + google: "GEMINI_API_KEY", + groq: "GROQ_API_KEY", + cerebras: "CEREBRAS_API_KEY", + xai: "XAI_API_KEY", + openrouter: "OPENROUTER_API_KEY", + zai: "ZAI_API_KEY", + mistral: "MISTRAL_API_KEY", + }; + const envVar = envMap[provider]; + if (!envVar) return null; + return pick(envVar); +} + +export async function getApiKeyForModel(params: { + model: Model; + cfg?: ClawdbotConfig; + profileId?: string; + preferredProfile?: string; + store?: AuthProfileStore; +}): Promise<{ apiKey: string; profileId?: string; source: string }> { + return resolveApiKeyForProvider({ + provider: params.model.provider, + cfg: params.cfg, + profileId: params.profileId, + preferredProfile: params.preferredProfile, + store: params.store, + }); } diff --git a/src/agents/model-fallback.ts b/src/agents/model-fallback.ts index a8c63d870..96d9abeb5 100644 --- a/src/agents/model-fallback.ts +++ b/src/agents/model-fallback.ts @@ -33,7 +33,10 @@ function buildAllowedModelKeys( cfg: ClawdbotConfig | undefined, defaultProvider: string, ): Set | null { - const rawAllowlist = cfg?.agent?.allowedModels ?? []; + const rawAllowlist = (() => { + const modelMap = cfg?.agent?.models ?? {}; + return Object.keys(modelMap); + })(); if (rawAllowlist.length === 0) return null; const keys = new Set(); for (const raw of rawAllowlist) { @@ -81,11 +84,28 @@ function resolveImageFallbackCandidates(params: { if (params.modelOverride?.trim()) { addRaw(params.modelOverride, false); - } else if (params.cfg?.agent?.imageModel?.trim()) { - addRaw(params.cfg.agent.imageModel, false); + } else { + const imageModel = params.cfg?.agent?.imageModel as + | { primary?: string } + | string + | undefined; + const primary = + typeof imageModel === "string" ? imageModel.trim() : imageModel?.primary; + if (primary?.trim()) addRaw(primary, false); } - for (const raw of params.cfg?.agent?.imageModelFallbacks ?? []) { + const imageFallbacks = (() => { + const imageModel = params.cfg?.agent?.imageModel as + | { fallbacks?: string[] } + | string + | undefined; + if (imageModel && typeof imageModel === "object") { + return imageModel.fallbacks ?? []; + } + return []; + })(); + + for (const raw of imageFallbacks) { addRaw(raw, true); } @@ -121,7 +141,16 @@ function resolveFallbackCandidates(params: { addCandidate({ provider, model }, false); - for (const raw of params.cfg?.agent?.modelFallbacks ?? []) { + const modelFallbacks = (() => { + const model = params.cfg?.agent?.model as + | { fallbacks?: string[] } + | string + | undefined; + if (model && typeof model === "object") return model.fallbacks ?? []; + return []; + })(); + + for (const raw of modelFallbacks) { const resolved = resolveModelRefFromString({ raw: String(raw ?? ""), defaultProvider: DEFAULT_PROVIDER, @@ -224,7 +253,7 @@ export async function runWithImageModelFallback(params: { }); if (candidates.length === 0) { throw new Error( - "No image model configured. Set agent.imageModel or agent.imageModelFallbacks.", + "No image model configured. Set agent.imageModel.primary or agent.imageModel.fallbacks.", ); } diff --git a/src/agents/model-selection.test.ts b/src/agents/model-selection.test.ts index d791763b8..5b107916d 100644 --- a/src/agents/model-selection.test.ts +++ b/src/agents/model-selection.test.ts @@ -5,9 +5,9 @@ import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js"; import { resolveConfiguredModelRef } from "./model-selection.js"; describe("resolveConfiguredModelRef", () => { - it("parses provider/model from agent.model", () => { + it("parses provider/model from agent.model.primary", () => { const cfg = { - agent: { model: "openai/gpt-4.1-mini" }, + agent: { model: { primary: "openai/gpt-4.1-mini" } }, } satisfies ClawdbotConfig; const resolved = resolveConfiguredModelRef({ @@ -19,9 +19,9 @@ describe("resolveConfiguredModelRef", () => { expect(resolved).toEqual({ provider: "openai", model: "gpt-4.1-mini" }); }); - it("falls back to anthropic when agent.model omits provider", () => { + it("falls back to anthropic when agent.model.primary omits provider", () => { const cfg = { - agent: { model: "claude-opus-4-5" }, + agent: { model: { primary: "claude-opus-4-5" } }, } satisfies ClawdbotConfig; const resolved = resolveConfiguredModelRef({ @@ -54,9 +54,9 @@ describe("resolveConfiguredModelRef", () => { it("resolves agent.model aliases when configured", () => { const cfg = { agent: { - model: "Opus", - modelAliases: { - Opus: "anthropic/claude-opus-4-5", + model: { primary: "Opus" }, + models: { + "anthropic/claude-opus-4-5": { alias: "Opus" }, }, }, } satisfies ClawdbotConfig; @@ -72,4 +72,18 @@ describe("resolveConfiguredModelRef", () => { model: "claude-opus-4-5", }); }); + + it("still resolves legacy agent.model string", () => { + const cfg = { + agent: { model: "openai/gpt-4.1-mini" }, + } satisfies ClawdbotConfig; + + const resolved = resolveConfiguredModelRef({ + cfg, + defaultProvider: DEFAULT_PROVIDER, + defaultModel: DEFAULT_MODEL, + }); + + expect(resolved).toEqual({ provider: "openai", model: "gpt-4.1-mini" }); + }); }); diff --git a/src/agents/model-selection.ts b/src/agents/model-selection.ts index 2cda180d1..f342700dd 100644 --- a/src/agents/model-selection.ts +++ b/src/agents/model-selection.ts @@ -41,18 +41,17 @@ export function buildModelAliasIndex(params: { cfg: ClawdbotConfig; defaultProvider: string; }): ModelAliasIndex { - const rawAliases = params.cfg.agent?.modelAliases ?? {}; const byAlias = new Map(); const byKey = new Map(); - for (const [aliasRaw, targetRaw] of Object.entries(rawAliases)) { - const alias = aliasRaw.trim(); - if (!alias) continue; - const parsed = parseModelRef( - String(targetRaw ?? ""), - params.defaultProvider, - ); + const rawModels = params.cfg.agent?.models ?? {}; + for (const [keyRaw, entryRaw] of Object.entries(rawModels)) { + const parsed = parseModelRef(String(keyRaw ?? ""), params.defaultProvider); if (!parsed) continue; + const alias = String( + (entryRaw as { alias?: string } | undefined)?.alias ?? "", + ).trim(); + if (!alias) continue; const aliasKey = normalizeAliasKey(alias); byAlias.set(aliasKey, { alias, ref: parsed }); const key = modelKey(parsed.provider, parsed.model); @@ -88,7 +87,14 @@ export function resolveConfiguredModelRef(params: { defaultProvider: string; defaultModel: string; }): ModelRef { - const rawModel = params.cfg.agent?.model?.trim() || ""; + const rawModel = (() => { + const raw = params.cfg.agent?.model as + | { primary?: string } + | string + | undefined; + if (typeof raw === "string") return raw.trim(); + return raw?.primary?.trim() ?? ""; + })(); if (rawModel) { const trimmed = rawModel.trim(); const aliasIndex = buildModelAliasIndex({ @@ -116,7 +122,10 @@ export function buildAllowedModelSet(params: { allowedCatalog: ModelCatalogEntry[]; allowedKeys: Set; } { - const rawAllowlist = params.cfg.agent?.allowedModels ?? []; + const rawAllowlist = (() => { + const modelMap = params.cfg.agent?.models ?? {}; + return Object.keys(modelMap); + })(); const allowAny = rawAllowlist.length === 0; const catalogKeys = new Set( params.catalog.map((entry) => modelKey(entry.provider, entry.id)), diff --git a/src/agents/pi-embedded-helpers.ts b/src/agents/pi-embedded-helpers.ts index 7a03e02e8..ef8049e3a 100644 --- a/src/agents/pi-embedded-helpers.ts +++ b/src/agents/pi-embedded-helpers.ts @@ -120,12 +120,40 @@ export function isRateLimitAssistantError( if (!msg || msg.stopReason !== "error") return false; const raw = (msg.errorMessage ?? "").toLowerCase(); if (!raw) return false; + return isRateLimitErrorMessage(raw); +} + +export function isRateLimitErrorMessage(raw: string): boolean { + const value = raw.toLowerCase(); return ( - /rate[_ ]limit|too many requests|429/.test(raw) || - raw.includes("exceeded your current quota") + /rate[_ ]limit|too many requests|429/.test(value) || + value.includes("exceeded your current quota") ); } +export function isAuthErrorMessage(raw: string): boolean { + const value = raw.toLowerCase(); + if (!value) return false; + return ( + /invalid[_ ]?api[_ ]?key/.test(value) || + value.includes("incorrect api key") || + value.includes("invalid token") || + value.includes("authentication") || + value.includes("unauthorized") || + value.includes("forbidden") || + value.includes("access denied") || + /\b401\b/.test(value) || + /\b403\b/.test(value) + ); +} + +export function isAuthAssistantError( + msg: AssistantMessage | undefined, +): boolean { + if (!msg || msg.stopReason !== "error") return false; + return isAuthErrorMessage(msg.errorMessage ?? ""); +} + function extractSupportedValues(raw: string): string[] { const match = raw.match(/supported values are:\s*([^\n.]+)/i) ?? diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index 3663ad0b2..28bd4bec6 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -24,15 +24,23 @@ import { } from "../process/command-queue.js"; import { resolveUserPath } from "../utils.js"; import { resolveClawdbotAgentDir } from "./agent-paths.js"; +import { markAuthProfileGood } from "./auth-profiles.js"; import type { BashElevatedDefaults } from "./bash-tools.js"; import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js"; -import { getApiKeyForModel } from "./model-auth.js"; +import { + ensureAuthProfileStore, + getApiKeyForModel, + resolveAuthProfileOrder, +} from "./model-auth.js"; import { ensureClawdbotModelsJson } from "./models-config.js"; import { buildBootstrapContextFiles, ensureSessionHeader, formatAssistantErrorText, + isAuthAssistantError, + isAuthErrorMessage, isRateLimitAssistantError, + isRateLimitErrorMessage, pickFallbackThinkingLevel, sanitizeSessionMessagesImages, } from "./pi-embedded-helpers.js"; @@ -311,6 +319,7 @@ export async function runEmbeddedPiAgent(params: { prompt: string; provider?: string; model?: string; + authProfileId?: string; thinkLevel?: ThinkLevel; verboseLevel?: VerboseLevel; bashElevated?: BashElevatedDefaults; @@ -368,11 +377,67 @@ export async function runEmbeddedPiAgent(params: { if (!model) { throw new Error(error ?? `Unknown model: ${provider}/${modelId}`); } - const apiKey = await getApiKeyForModel(model, authStorage); - authStorage.setRuntimeApiKey(model.provider, apiKey); - - let thinkLevel = params.thinkLevel ?? "off"; + const authStore = ensureAuthProfileStore(); + const explicitProfileId = params.authProfileId?.trim(); + const profileOrder = resolveAuthProfileOrder({ + cfg: params.config, + store: authStore, + provider, + preferredProfile: explicitProfileId, + }); + if (explicitProfileId && !profileOrder.includes(explicitProfileId)) { + throw new Error( + `Auth profile "${explicitProfileId}" is not configured for ${provider}.`, + ); + } + const profileCandidates = + profileOrder.length > 0 ? profileOrder : [undefined]; + let profileIndex = 0; + const initialThinkLevel = params.thinkLevel ?? "off"; + let thinkLevel = initialThinkLevel; const attemptedThinking = new Set(); + let apiKeyInfo: Awaited> | null = + null; + + const resolveApiKeyForCandidate = async (candidate?: string) => { + return getApiKeyForModel({ + model, + cfg: params.config, + profileId: candidate, + store: authStore, + }); + }; + + const applyApiKeyInfo = async (candidate?: string): Promise => { + apiKeyInfo = await resolveApiKeyForCandidate(candidate); + authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); + }; + + const advanceAuthProfile = async (): Promise => { + let nextIndex = profileIndex + 1; + while (nextIndex < profileCandidates.length) { + const candidate = profileCandidates[nextIndex]; + try { + await applyApiKeyInfo(candidate); + profileIndex = nextIndex; + thinkLevel = initialThinkLevel; + attemptedThinking.clear(); + return true; + } catch (err) { + if (candidate && candidate === explicitProfileId) throw err; + nextIndex += 1; + } + } + return false; + }; + + try { + await applyApiKeyInfo(profileCandidates[profileIndex]); + } catch (err) { + if (profileCandidates[profileIndex] === explicitProfileId) throw err; + const advanced = await advanceAuthProfile(); + if (!advanced) throw err; + } while (true) { const thinkingLevel = mapThinkingLevel(thinkLevel); @@ -611,8 +676,16 @@ export async function runEmbeddedPiAgent(params: { params.abortSignal?.removeEventListener?.("abort", onAbort); } if (promptError && !aborted) { + const errorText = describeUnknownError(promptError); + if ( + (isAuthErrorMessage(errorText) || + isRateLimitErrorMessage(errorText)) && + (await advanceAuthProfile()) + ) { + continue; + } const fallbackThinking = pickFallbackThinkingLevel({ - message: describeUnknownError(promptError), + message: errorText, attempted: attemptedThinking, }); if (fallbackThinking) { @@ -645,13 +718,25 @@ export async function runEmbeddedPiAgent(params: { } const fallbackConfigured = - (params.config?.agent?.modelFallbacks?.length ?? 0) > 0; - if (fallbackConfigured && isRateLimitAssistantError(lastAssistant)) { - const message = - lastAssistant?.errorMessage?.trim() || - (lastAssistant ? formatAssistantErrorText(lastAssistant) : "") || - "LLM request rate limited."; - throw new Error(message); + (params.config?.agent?.model?.fallbacks?.length ?? 0) > 0; + const authFailure = isAuthAssistantError(lastAssistant); + const rateLimitFailure = isRateLimitAssistantError(lastAssistant); + if (!aborted && (authFailure || rateLimitFailure)) { + const rotated = await advanceAuthProfile(); + if (rotated) { + continue; + } + if (fallbackConfigured) { + const message = + lastAssistant?.errorMessage?.trim() || + (lastAssistant + ? formatAssistantErrorText(lastAssistant) + : "") || + (rateLimitFailure + ? "LLM request rate limited." + : "LLM request unauthorized."); + throw new Error(message); + } } const usage = lastAssistant?.usage; @@ -717,6 +802,13 @@ export async function runEmbeddedPiAgent(params: { log.debug( `embedded run done: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - started} aborted=${aborted}`, ); + if (apiKeyInfo?.profileId) { + markAuthProfileGood({ + store: authStore, + provider, + profileId: apiKeyInfo.profileId, + }); + } return { payloads: payloads.length ? payloads : undefined, meta: { diff --git a/src/agents/tools/image-tool.ts b/src/agents/tools/image-tool.ts index 0f3ebd500..e39841972 100644 --- a/src/agents/tools/image-tool.ts +++ b/src/agents/tools/image-tool.ts @@ -24,9 +24,15 @@ import type { AnyAgentTool } from "./common.js"; const DEFAULT_PROMPT = "Describe the image."; function ensureImageToolConfigured(cfg?: ClawdbotConfig): boolean { - const primary = cfg?.agent?.imageModel?.trim(); - const fallbacks = cfg?.agent?.imageModelFallbacks ?? []; - return Boolean(primary || fallbacks.length > 0); + const imageModel = cfg?.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | string + | undefined; + const primary = + typeof imageModel === "string" ? imageModel.trim() : imageModel?.primary; + const fallbacks = + typeof imageModel === "object" ? (imageModel?.fallbacks ?? []) : []; + return Boolean(primary?.trim() || fallbacks.length > 0); } function pickMaxBytes( @@ -95,15 +101,18 @@ async function runImagePrompt(params: { `Model does not support images: ${provider}/${modelId}`, ); } - const apiKey = await getApiKeyForModel(model, authStorage); - authStorage.setRuntimeApiKey(model.provider, apiKey); + const apiKeyInfo = await getApiKeyForModel({ + model, + cfg: params.cfg, + }); + authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); const context = buildImageContext( params.prompt, params.base64, params.mimeType, ); const message = (await complete(model, context, { - apiKey, + apiKey: apiKeyInfo.apiKey, maxTokens: 512, temperature: 0, })) as AssistantMessage; diff --git a/src/auto-reply/model.ts b/src/auto-reply/model.ts index 834e3daa8..56bb6e19e 100644 --- a/src/auto-reply/model.ts +++ b/src/auto-reply/model.ts @@ -1,19 +1,28 @@ export function extractModelDirective(body?: string): { cleaned: string; rawModel?: string; + rawProfile?: string; hasDirective: boolean; } { if (!body) return { cleaned: "", hasDirective: false }; const match = body.match( - /(?:^|\s)\/model(?=$|\s|:)\s*:?\s*([A-Za-z0-9_.:-]+(?:\/[A-Za-z0-9_.:-]+)?)?/i, + /(?:^|\s)\/model(?=$|\s|:)\s*:?\s*([A-Za-z0-9_.:@-]+(?:\/[A-Za-z0-9_.:@-]+)?)?/i, ); - const rawModel = match?.[1]?.trim(); + const raw = match?.[1]?.trim(); + let rawModel = raw; + let rawProfile: string | undefined; + if (raw?.includes("@")) { + const parts = raw.split("@"); + rawModel = parts[0]?.trim(); + rawProfile = parts.slice(1).join("@").trim() || undefined; + } const cleaned = match ? body.replace(match[0], "").replace(/\s+/g, " ").trim() : body.trim(); return { cleaned, rawModel, + rawProfile, hasDirective: !!match, }; } diff --git a/src/auto-reply/reply.directive.test.ts b/src/auto-reply/reply.directive.test.ts index 92ffdc410..062c2099c 100644 --- a/src/auto-reply/reply.directive.test.ts +++ b/src/auto-reply/reply.directive.test.ts @@ -37,11 +37,24 @@ vi.mock("../agents/model-catalog.js", () => ({ async function withTempHome(fn: (home: string) => Promise): Promise { const base = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-reply-")); const previousHome = process.env.HOME; + const previousStateDir = process.env.CLAWDBOT_STATE_DIR; + const previousAgentDir = process.env.CLAWDBOT_AGENT_DIR; + const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR; process.env.HOME = base; + process.env.CLAWDBOT_STATE_DIR = path.join(base, ".clawdbot"); + process.env.CLAWDBOT_AGENT_DIR = path.join(base, ".clawdbot", "agent"); + process.env.PI_CODING_AGENT_DIR = process.env.CLAWDBOT_AGENT_DIR; try { return await fn(base); } finally { process.env.HOME = previousHome; + if (previousStateDir === undefined) delete process.env.CLAWDBOT_STATE_DIR; + else process.env.CLAWDBOT_STATE_DIR = previousStateDir; + if (previousAgentDir === undefined) delete process.env.CLAWDBOT_AGENT_DIR; + else process.env.CLAWDBOT_AGENT_DIR = previousAgentDir; + if (previousPiAgentDir === undefined) + delete process.env.PI_CODING_AGENT_DIR; + else process.env.PI_CODING_AGENT_DIR = previousPiAgentDir; await fs.rm(base, { recursive: true, force: true }); } } @@ -566,9 +579,12 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["anthropic/claude-opus-4-5", "openai/gpt-4.1-mini"], + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-4.1-mini": {}, + }, }, session: { store: storePath }, }, @@ -593,9 +609,12 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["anthropic/claude-opus-4-5", "openai/gpt-4.1-mini"], + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-4.1-mini": {}, + }, }, session: { store: storePath }, }, @@ -620,9 +639,12 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["anthropic/claude-opus-4-5", "openai/gpt-4.1-mini"], + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-4.1-mini": {}, + }, }, session: { store: storePath }, }, @@ -646,9 +668,11 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["anthropic/claude-opus-4-5"], + models: { + "anthropic/claude-opus-4-5": {}, + }, }, session: { store: storePath }, }, @@ -671,9 +695,12 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["openai/gpt-4.1-mini"], + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-4.1-mini": {}, + }, }, session: { store: storePath }, }, @@ -699,11 +726,11 @@ describe("directive parsing", () => { {}, { agent: { - model: "openai/gpt-4.1-mini", + model: { primary: "openai/gpt-4.1-mini" }, workspace: path.join(home, "clawd"), - allowedModels: ["openai/gpt-4.1-mini", "anthropic/claude-opus-4-5"], - modelAliases: { - Opus: "anthropic/claude-opus-4-5", + models: { + "openai/gpt-4.1-mini": {}, + "anthropic/claude-opus-4-5": { alias: "Opus" }, }, }, session: { store: storePath }, @@ -721,6 +748,55 @@ describe("directive parsing", () => { }); }); + it("stores auth profile overrides on /model directive", async () => { + await withTempHome(async (home) => { + vi.mocked(runEmbeddedPiAgent).mockReset(); + const storePath = path.join(home, "sessions.json"); + const authDir = path.join(home, ".clawdbot", "agent"); + await fs.mkdir(authDir, { recursive: true, mode: 0o700 }); + await fs.writeFile( + path.join(authDir, "auth-profiles.json"), + JSON.stringify( + { + version: 1, + profiles: { + "anthropic:work": { + type: "api_key", + provider: "anthropic", + key: "sk-test-1234567890", + }, + }, + }, + null, + 2, + ), + ); + + const res = await getReplyFromConfig( + { Body: "/model Opus@anthropic:work", From: "+1222", To: "+1222" }, + {}, + { + agent: { + model: { primary: "openai/gpt-4.1-mini" }, + workspace: path.join(home, "clawd"), + models: { + "openai/gpt-4.1-mini": {}, + "anthropic/claude-opus-4-5": { alias: "Opus" }, + }, + }, + session: { store: storePath }, + }, + ); + + const text = Array.isArray(res) ? res[0]?.text : res?.text; + expect(text).toContain("Auth profile set to anthropic:work"); + const store = loadSessionStore(storePath); + const entry = store.main; + expect(entry.authProfileOverride).toBe("anthropic:work"); + expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + }); + }); + it("queues a system event when switching models", async () => { await withTempHome(async (home) => { drainSystemEvents(); @@ -732,11 +808,11 @@ describe("directive parsing", () => { {}, { agent: { - model: "openai/gpt-4.1-mini", + model: { primary: "openai/gpt-4.1-mini" }, workspace: path.join(home, "clawd"), - allowedModels: ["openai/gpt-4.1-mini", "anthropic/claude-opus-4-5"], - modelAliases: { - Opus: "anthropic/claude-opus-4-5", + models: { + "openai/gpt-4.1-mini": {}, + "anthropic/claude-opus-4-5": { alias: "Opus" }, }, }, session: { store: storePath }, @@ -771,9 +847,12 @@ describe("directive parsing", () => { {}, { agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, workspace: path.join(home, "clawd"), - allowedModels: ["openai/gpt-4.1-mini"], + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-4.1-mini": {}, + }, }, whatsapp: { allowFrom: ["*"], diff --git a/src/auto-reply/reply.ts b/src/auto-reply/reply.ts index 703884bfb..26144ef64 100644 --- a/src/auto-reply/reply.ts +++ b/src/auto-reply/reply.ts @@ -361,7 +361,9 @@ export async function getReplyFromConfig( : `Model switched to ${label}.`; const isModelListAlias = directives.hasModelDirective && - directives.rawModelDirective?.trim().toLowerCase() === "status"; + ["status", "list"].includes( + directives.rawModelDirective?.trim().toLowerCase() ?? "", + ); const effectiveModelDirective = isModelListAlias ? undefined : directives.rawModelDirective; @@ -376,6 +378,7 @@ export async function getReplyFromConfig( }) ) { const directiveReply = await handleDirectiveOnly({ + cfg, directives, sessionEntry, sessionStore, @@ -401,6 +404,7 @@ export async function getReplyFromConfig( const persisted = await persistInlineDirectives({ directives, effectiveModelDirective, + cfg, sessionEntry, sessionStore, sessionKey, @@ -634,6 +638,7 @@ export async function getReplyFromConfig( resolvedQueue.mode === "followup" || resolvedQueue.mode === "collect" || resolvedQueue.mode === "steer-backlog"; + const authProfileId = sessionEntry?.authProfileOverride; const followupRun = { prompt: queuedBody, summaryLine: baseBodyTrimmedRaw, @@ -648,6 +653,7 @@ export async function getReplyFromConfig( skillsSnapshot, provider, model, + authProfileId, thinkLevel: resolvedThinkLevel, verboseLevel: resolvedVerboseLevel, elevatedLevel: resolvedElevatedLevel, diff --git a/src/auto-reply/reply/agent-runner.ts b/src/auto-reply/reply/agent-runner.ts index 5ad34c387..fd2a8eef1 100644 --- a/src/auto-reply/reply/agent-runner.ts +++ b/src/auto-reply/reply/agent-runner.ts @@ -195,6 +195,7 @@ export async function runReplyAgent(params: { enforceFinalTag: followupRun.run.enforceFinalTag, provider, model, + authProfileId: followupRun.run.authProfileId, thinkLevel: followupRun.run.thinkLevel, verboseLevel: followupRun.run.verboseLevel, bashElevated: followupRun.run.bashElevated, diff --git a/src/auto-reply/reply/commands.ts b/src/auto-reply/reply/commands.ts index d225e28bf..d8042911b 100644 --- a/src/auto-reply/reply/commands.ts +++ b/src/auto-reply/reply/commands.ts @@ -1,10 +1,12 @@ -import fs from "node:fs"; - -import { getEnvApiKey } from "@mariozechner/pi-ai"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; -import { resolveClawdbotAgentDir } from "../../agents/agent-paths.js"; +import { + ensureAuthProfileStore, + listProfilesForProvider, +} from "../../agents/auth-profiles.js"; +import { + getCustomProviderApiKey, + resolveEnvApiKey, +} from "../../agents/model-auth.js"; import type { ClawdbotConfig } from "../../config/config.js"; -import { resolveOAuthPath } from "../../config/paths.js"; import { type SessionEntry, type SessionScope, @@ -42,55 +44,32 @@ export type CommandContext = { to?: string; }; -function hasOAuthCredentials(provider: string): boolean { - try { - const oauthPath = resolveOAuthPath(); - if (!fs.existsSync(oauthPath)) return false; - const raw = fs.readFileSync(oauthPath, "utf8"); - const parsed = JSON.parse(raw) as Record; - const entry = parsed?.[provider] as - | { - refresh?: string; - refresh_token?: string; - refreshToken?: string; - access?: string; - access_token?: string; - accessToken?: string; - } - | undefined; - if (!entry) return false; - const refresh = - entry.refresh ?? entry.refresh_token ?? entry.refreshToken ?? ""; - const access = - entry.access ?? entry.access_token ?? entry.accessToken ?? ""; - return Boolean(refresh.trim() && access.trim()); - } catch { - return false; - } -} - -function resolveModelAuthLabel(provider?: string): string | undefined { +function resolveModelAuthLabel( + provider?: string, + cfg?: ClawdbotConfig, +): string | undefined { const resolved = provider?.trim(); if (!resolved) return undefined; - try { - const authStorage = discoverAuthStorage(resolveClawdbotAgentDir()); - const stored = authStorage.get(resolved); - if (stored?.type === "oauth") return "oauth"; - if (stored?.type === "api_key") return "api-key"; - } catch { - // ignore auth storage errors + const store = ensureAuthProfileStore(); + const profiles = listProfilesForProvider(store, resolved); + if (profiles.length > 0) { + const modes = new Set( + profiles + .map((id) => store.profiles[id]?.type) + .filter((mode): mode is "api_key" | "oauth" => Boolean(mode)), + ); + if (modes.has("oauth") && modes.has("api_key")) return "mixed"; + if (modes.has("oauth")) return "oauth"; + if (modes.has("api_key")) return "api-key"; } - if (resolved === "anthropic") { - const oauthEnv = process.env.ANTHROPIC_OAUTH_TOKEN; - if (oauthEnv?.trim()) return "oauth"; + const envKey = resolveEnvApiKey(resolved); + if (envKey?.apiKey) { + return envKey.source.includes("OAUTH_TOKEN") ? "oauth" : "api-key"; } - if (hasOAuthCredentials(resolved)) return "oauth"; - - const envKey = getEnvApiKey(resolved); - if (envKey?.trim()) return "api-key"; + if (getCustomProviderApiKey(cfg, resolved)) return "api-key"; return "unknown"; } @@ -374,7 +353,7 @@ export async function handleCommands(params: { resolvedThinkLevel ?? (await resolveDefaultThinkingLevel()), resolvedVerbose: resolvedVerboseLevel, resolvedElevated: resolvedElevatedLevel, - modelAuth: resolveModelAuthLabel(provider), + modelAuth: resolveModelAuthLabel(provider, cfg), webLinked, webAuthAgeMs, heartbeatSeconds, diff --git a/src/auto-reply/reply/directive-handling.ts b/src/auto-reply/reply/directive-handling.ts index 5ccae73e8..7b3c240ae 100644 --- a/src/auto-reply/reply/directive-handling.ts +++ b/src/auto-reply/reply/directive-handling.ts @@ -1,13 +1,20 @@ -import { getEnvApiKey } from "@mariozechner/pi-ai"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; import { resolveClawdbotAgentDir } from "../../agents/agent-paths.js"; +import { + resolveAuthProfileDisplayLabel, + resolveAuthStorePathForDisplay, +} from "../../agents/auth-profiles.js"; import { lookupContextTokens } from "../../agents/context.js"; import { DEFAULT_CONTEXT_TOKENS, DEFAULT_MODEL, DEFAULT_PROVIDER, } from "../../agents/defaults.js"; -import { hydrateAuthStorage } from "../../agents/model-auth.js"; +import { + ensureAuthProfileStore, + getCustomProviderApiKey, + resolveAuthProfileOrder, + resolveEnvApiKey, +} from "../../agents/model-auth.js"; import { buildModelAliasIndex, type ModelAliasIndex, @@ -53,43 +60,63 @@ const maskApiKey = (value: string): string => { const resolveAuthLabel = async ( provider: string, - authStorage: ReturnType, - authPaths: { authPath: string; modelsPath: string }, + cfg: ClawdbotConfig, + modelsPath: string, ): Promise<{ label: string; source: string }> => { const formatPath = (value: string) => shortenHomePath(value); - const stored = authStorage.get(provider); - if (stored?.type === "oauth") { - const email = stored.email?.trim(); + const store = ensureAuthProfileStore(); + const order = resolveAuthProfileOrder({ cfg, store, provider }); + if (order.length > 0) { + const labels = order.map((profileId) => { + const profile = store.profiles[profileId]; + const configProfile = cfg.auth?.profiles?.[profileId]; + if ( + !profile || + (configProfile?.provider && + configProfile.provider !== profile.provider) || + (configProfile?.mode && configProfile.mode !== profile.type) + ) { + return `${profileId}=missing`; + } + if (profile.type === "api_key") { + return `${profileId}=${maskApiKey(profile.key)}`; + } + const display = resolveAuthProfileDisplayLabel({ + cfg, + store, + profileId, + }); + const suffix = + display === profileId + ? "" + : display.startsWith(profileId) + ? display.slice(profileId.length).trim() + : `(${display})`; + return `${profileId}=OAuth${suffix ? ` ${suffix}` : ""}`; + }); return { - label: email ? `OAuth ${email}` : "OAuth (unknown)", - source: `auth.json: ${formatPath(authPaths.authPath)}`, + label: labels.join(", "), + source: `auth-profiles.json: ${formatPath( + resolveAuthStorePathForDisplay(), + )}`, }; } - if (stored?.type === "api_key") { + + const envKey = resolveEnvApiKey(provider); + if (envKey) { + const isOAuthEnv = + envKey.source.includes("ANTHROPIC_OAUTH_TOKEN") || + envKey.source.toLowerCase().includes("oauth"); + const label = isOAuthEnv ? "OAuth (env)" : maskApiKey(envKey.apiKey); + return { label, source: envKey.source }; + } + const customKey = getCustomProviderApiKey(cfg, provider); + if (customKey) { return { - label: maskApiKey(stored.key), - source: `auth.json: ${formatPath(authPaths.authPath)}`, + label: maskApiKey(customKey), + source: `models.json: ${formatPath(modelsPath)}`, }; } - const envKey = getEnvApiKey(provider); - if (envKey) return { label: maskApiKey(envKey), source: "env" }; - if (provider === "anthropic") { - const oauthEnv = process.env.ANTHROPIC_OAUTH_TOKEN?.trim(); - if (oauthEnv) { - return { label: "OAuth (env)", source: "env: ANTHROPIC_OAUTH_TOKEN" }; - } - } - try { - const key = await authStorage.getApiKey(provider); - if (key) { - return { - label: maskApiKey(key), - source: `models.json: ${formatPath(authPaths.modelsPath)}`, - }; - } - } catch { - // ignore missing auth - } return { label: "missing", source: "missing" }; }; @@ -100,6 +127,26 @@ const formatAuthLabel = (auth: { label: string; source: string }) => { return `${auth.label} (${auth.source})`; }; +const resolveProfileOverride = (params: { + rawProfile?: string; + provider: string; + cfg: ClawdbotConfig; +}): { profileId?: string; error?: string } => { + const raw = params.rawProfile?.trim(); + if (!raw) return {}; + const store = ensureAuthProfileStore(); + const profile = store.profiles[raw]; + if (!profile) { + return { error: `Auth profile "${raw}" not found.` }; + } + if (profile.provider !== params.provider) { + return { + error: `Auth profile "${raw}" is for ${profile.provider}, not ${params.provider}.`, + }; + } + return { profileId: raw }; +}; + export type InlineDirectives = { cleaned: string; hasThinkDirective: boolean; @@ -114,6 +161,7 @@ export type InlineDirectives = { hasStatusDirective: boolean; hasModelDirective: boolean; rawModelDirective?: string; + rawModelProfile?: string; hasQueueDirective: boolean; queueMode?: QueueMode; queueReset: boolean; @@ -151,6 +199,7 @@ export function parseInlineDirectives(body: string): InlineDirectives { const { cleaned: modelCleaned, rawModel, + rawProfile, hasDirective: hasModelDirective, } = extractModelDirective(statusCleaned); const { @@ -182,6 +231,7 @@ export function parseInlineDirectives(body: string): InlineDirectives { hasStatusDirective, hasModelDirective, rawModelDirective: rawModel, + rawModelProfile: rawProfile, hasQueueDirective, queueMode, queueReset, @@ -218,6 +268,7 @@ export function isDirectiveOnly(params: { } export async function handleDirectiveOnly(params: { + cfg: ClawdbotConfig; directives: InlineDirectives; sessionEntry?: SessionEntry; sessionStore?: Record; @@ -265,19 +316,14 @@ export async function handleDirectiveOnly(params: { return { text: "No models available." }; } const agentDir = resolveClawdbotAgentDir(); - const authStorage = discoverAuthStorage(agentDir); - const authPaths = { - authPath: `${agentDir}/auth.json`, - modelsPath: `${agentDir}/models.json`, - }; - hydrateAuthStorage(authStorage); + const modelsPath = `${agentDir}/models.json`; const authByProvider = new Map(); for (const entry of allowedModelCatalog) { if (authByProvider.has(entry.provider)) continue; const auth = await resolveAuthLabel( entry.provider, - authStorage, - authPaths, + params.cfg, + modelsPath, ); authByProvider.set(entry.provider, formatAuthLabel(auth)); } @@ -306,6 +352,9 @@ export async function handleDirectiveOnly(params: { } return { text: lines.join("\n") }; } + if (directives.rawModelProfile && !modelDirective) { + throw new Error("Auth profile override requires a model selection."); + } } if (directives.hasThinkDirective && !directives.thinkLevel) { @@ -378,6 +427,7 @@ export async function handleDirectiveOnly(params: { } let modelSelection: ModelDirectiveSelection | undefined; + let profileOverride: string | undefined; if (directives.hasModelDirective && directives.rawModelDirective) { const resolved = resolveModelDirectiveSelection({ raw: directives.rawModelDirective, @@ -391,6 +441,17 @@ export async function handleDirectiveOnly(params: { } modelSelection = resolved.selection; if (modelSelection) { + if (directives.rawModelProfile) { + const profileResolved = resolveProfileOverride({ + rawProfile: directives.rawModelProfile, + provider: modelSelection.provider, + cfg: params.cfg, + }); + if (profileResolved.error) { + return { text: profileResolved.error }; + } + profileOverride = profileResolved.profileId; + } const nextLabel = `${modelSelection.provider}/${modelSelection.model}`; if (nextLabel !== initialModelLabel) { enqueueSystemEvent( @@ -402,6 +463,9 @@ export async function handleDirectiveOnly(params: { } } } + if (directives.rawModelProfile && !modelSelection) { + return { text: "Auth profile override requires a model selection." }; + } if (sessionEntry && sessionStore && sessionKey) { if (directives.hasThinkDirective && directives.thinkLevel) { @@ -424,6 +488,11 @@ export async function handleDirectiveOnly(params: { sessionEntry.providerOverride = modelSelection.provider; sessionEntry.modelOverride = modelSelection.model; } + if (profileOverride) { + sessionEntry.authProfileOverride = profileOverride; + } else if (directives.hasModelDirective) { + delete sessionEntry.authProfileOverride; + } } if (directives.hasQueueDirective && directives.queueReset) { delete sessionEntry.queueMode; @@ -481,6 +550,9 @@ export async function handleDirectiveOnly(params: { ? `Model reset to default (${labelWithAlias}).` : `Model set to ${labelWithAlias}.`, ); + if (profileOverride) { + parts.push(`Auth profile set to ${profileOverride}.`); + } } if (directives.hasQueueDirective && directives.queueMode) { parts.push(`${SYSTEM_MARK} Queue mode set to ${directives.queueMode}.`); @@ -508,6 +580,7 @@ export async function handleDirectiveOnly(params: { export async function persistInlineDirectives(params: { directives: InlineDirectives; effectiveModelDirective?: string; + cfg: ClawdbotConfig; sessionEntry?: SessionEntry; sessionStore?: Record; sessionKey?: string; @@ -526,6 +599,7 @@ export async function persistInlineDirectives(params: { }): Promise<{ provider: string; model: string; contextTokens: number }> { const { directives, + cfg, sessionEntry, sessionStore, sessionKey, @@ -586,6 +660,18 @@ export async function persistInlineDirectives(params: { if (resolved) { const key = modelKey(resolved.ref.provider, resolved.ref.model); if (allowedModelKeys.size === 0 || allowedModelKeys.has(key)) { + let profileOverride: string | undefined; + if (directives.rawModelProfile) { + const profileResolved = resolveProfileOverride({ + rawProfile: directives.rawModelProfile, + provider: resolved.ref.provider, + cfg, + }); + if (profileResolved.error) { + throw new Error(profileResolved.error); + } + profileOverride = profileResolved.profileId; + } const isDefault = resolved.ref.provider === defaultProvider && resolved.ref.model === defaultModel; @@ -596,6 +682,11 @@ export async function persistInlineDirectives(params: { sessionEntry.providerOverride = resolved.ref.provider; sessionEntry.modelOverride = resolved.ref.model; } + if (profileOverride) { + sessionEntry.authProfileOverride = profileOverride; + } else if (directives.hasModelDirective) { + delete sessionEntry.authProfileOverride; + } provider = resolved.ref.provider; model = resolved.ref.model; const nextLabel = `${provider}/${model}`; diff --git a/src/auto-reply/reply/followup-runner.ts b/src/auto-reply/reply/followup-runner.ts index 86f978ec3..ebb6d5cfa 100644 --- a/src/auto-reply/reply/followup-runner.ts +++ b/src/auto-reply/reply/followup-runner.ts @@ -84,6 +84,7 @@ export function createFollowupRunner(params: { enforceFinalTag: queued.run.enforceFinalTag, provider, model, + authProfileId: queued.run.authProfileId, thinkLevel: queued.run.thinkLevel, verboseLevel: queued.run.verboseLevel, bashElevated: queued.run.bashElevated, diff --git a/src/auto-reply/reply/model-selection.ts b/src/auto-reply/reply/model-selection.ts index 5ee553208..a4cb67359 100644 --- a/src/auto-reply/reply/model-selection.ts +++ b/src/auto-reply/reply/model-selection.ts @@ -57,7 +57,8 @@ export async function createModelSelectionState(params: { let provider = params.provider; let model = params.model; - const hasAllowlist = (agentCfg?.allowedModels?.length ?? 0) > 0; + const hasAllowlist = + agentCfg?.models && Object.keys(agentCfg.models).length > 0; const hasStoredOverride = Boolean( sessionEntry?.modelOverride || sessionEntry?.providerOverride, ); @@ -110,6 +111,27 @@ export async function createModelSelectionState(params: { } } + if ( + sessionEntry && + sessionStore && + sessionKey && + sessionEntry.authProfileOverride + ) { + const { ensureAuthProfileStore } = await import( + "../../agents/auth-profiles.js" + ); + const store = ensureAuthProfileStore(); + const profile = store.profiles[sessionEntry.authProfileOverride]; + if (!profile || profile.provider !== provider) { + delete sessionEntry.authProfileOverride; + sessionEntry.updatedAt = Date.now(); + sessionStore[sessionKey] = sessionEntry; + if (storePath) { + await saveSessionStore(storePath, sessionStore); + } + } + } + let defaultThinkingLevel: ThinkLevel | undefined; const resolveDefaultThinkingLevel = async () => { if (defaultThinkingLevel) return defaultThinkingLevel; diff --git a/src/auto-reply/reply/queue.ts b/src/auto-reply/reply/queue.ts index 074089a4e..47b0dc432 100644 --- a/src/auto-reply/reply/queue.ts +++ b/src/auto-reply/reply/queue.ts @@ -32,6 +32,7 @@ export type FollowupRun = { skillsSnapshot?: SkillSnapshot; provider: string; model: string; + authProfileId?: string; thinkLevel?: ThinkLevel; verboseLevel?: VerboseLevel; elevatedLevel?: ElevatedLevel; diff --git a/src/commands/agent.test.ts b/src/commands/agent.test.ts index c407d9666..b25a95304 100644 --- a/src/commands/agent.test.ts +++ b/src/commands/agent.test.ts @@ -59,7 +59,8 @@ function mockConfig( ) { configSpy.mockReturnValue({ agent: { - model: "anthropic/claude-opus-4-5", + model: { primary: "anthropic/claude-opus-4-5" }, + models: { "anthropic/claude-opus-4-5": {} }, workspace: path.join(home, "clawd"), ...agentOverrides, }, diff --git a/src/commands/agent.ts b/src/commands/agent.ts index e6306ae66..18599c6a0 100644 --- a/src/commands/agent.ts +++ b/src/commands/agent.ts @@ -1,4 +1,5 @@ import crypto from "node:crypto"; +import { ensureAuthProfileStore } from "../agents/auth-profiles.js"; import { lookupContextTokens } from "../agents/context.js"; import { DEFAULT_CONTEXT_TOKENS, @@ -289,7 +290,8 @@ export async function agentCommand( }); let provider = defaultProvider; let model = defaultModel; - const hasAllowlist = (agentCfg?.allowedModels?.length ?? 0) > 0; + const hasAllowlist = + agentCfg?.models && Object.keys(agentCfg.models).length > 0; const hasStoredOverride = Boolean( sessionEntry?.modelOverride || sessionEntry?.providerOverride, ); @@ -335,6 +337,18 @@ export async function agentCommand( model = storedModelOverride; } } + if (sessionEntry?.authProfileOverride) { + const store = ensureAuthProfileStore(); + const profile = store.profiles[sessionEntry.authProfileOverride]; + if (!profile || profile.provider !== provider) { + delete sessionEntry.authProfileOverride; + sessionEntry.updatedAt = Date.now(); + if (sessionStore && sessionKey) { + sessionStore[sessionKey] = sessionEntry; + await saveSessionStore(storePath, sessionStore); + } + } + } if (!resolvedThinkLevel) { let catalogForThinking = modelCatalog ?? allowedModelCatalog; @@ -381,6 +395,7 @@ export async function agentCommand( prompt: body, provider: providerOverride, model: modelOverride, + authProfileId: sessionEntry?.authProfileOverride, thinkLevel: resolvedThinkLevel, verboseLevel: resolvedVerboseLevel, timeoutMs, diff --git a/src/commands/configure.ts b/src/commands/configure.ts index dda13dc83..9d61541d4 100644 --- a/src/commands/configure.ts +++ b/src/commands/configure.ts @@ -32,6 +32,7 @@ import { } from "./antigravity-oauth.js"; import { healthCommand } from "./health.js"; import { + applyAuthProfileConfig, applyMinimaxConfig, setAnthropicApiKey, writeOAuthCredentials, @@ -275,6 +276,11 @@ async function promptAuthConfig( spin.stop("OAuth complete"); if (oauthCreds) { await writeOAuthCredentials("anthropic", oauthCreds); + next = applyAuthProfileConfig(next, { + profileId: "anthropic:default", + provider: "anthropic", + mode: "oauth", + }); } } catch (err) { spin.stop("OAuth failed"); @@ -316,12 +322,30 @@ async function promptAuthConfig( spin.stop("Antigravity OAuth complete"); if (oauthCreds) { await writeOAuthCredentials("google-antigravity", oauthCreds); + next = applyAuthProfileConfig(next, { + profileId: "google-antigravity:default", + provider: "google-antigravity", + mode: "oauth", + }); // Set default model to Claude Opus 4.5 via Antigravity next = { ...next, agent: { ...next.agent, - model: "google-antigravity/claude-opus-4-5-thinking", + model: { + ...((next.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + primary: "google-antigravity/claude-opus-4-5-thinking", + }, + models: { + ...next.agent?.models, + "google-antigravity/claude-opus-4-5-thinking": + next.agent?.models?.[ + "google-antigravity/claude-opus-4-5-thinking" + ] ?? {}, + }, }, }; note( @@ -342,6 +366,11 @@ async function promptAuthConfig( runtime, ); await setAnthropicApiKey(String(key).trim()); + next = applyAuthProfileConfig(next, { + profileId: "anthropic:default", + provider: "anthropic", + mode: "api_key", + }); } else if (authChoice === "minimax") { next = applyMinimaxConfig(next); } @@ -349,7 +378,10 @@ async function promptAuthConfig( const modelInput = guardCancel( await text({ message: "Default model (blank to keep)", - initialValue: next.agent?.model ?? "", + initialValue: + typeof next.agent?.model === "string" + ? next.agent?.model + : (next.agent?.model?.primary ?? ""), }), runtime, ); @@ -359,7 +391,17 @@ async function promptAuthConfig( ...next, agent: { ...next.agent, - model, + model: { + ...((next.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + primary: model, + }, + models: { + ...next.agent?.models, + [model]: next.agent?.models?.[model] ?? {}, + }, }, }; } diff --git a/src/commands/models/aliases.ts b/src/commands/models/aliases.ts index fe670e9f0..9600b7494 100644 --- a/src/commands/models/aliases.ts +++ b/src/commands/models/aliases.ts @@ -13,7 +13,15 @@ export async function modelsAliasesListCommand( ) { ensureFlagCompatibility(opts); const cfg = loadConfig(); - const aliases = cfg.agent?.modelAliases ?? {}; + const models = cfg.agent?.models ?? {}; + const aliases = Object.entries(models).reduce>( + (acc, [modelKey, entry]) => { + const alias = entry?.alias?.trim(); + if (alias) acc[alias] = modelKey; + return acc; + }, + {}, + ); if (opts.json) { runtime.log(JSON.stringify({ aliases }, null, 2)); @@ -42,21 +50,29 @@ export async function modelsAliasesAddCommand( runtime: RuntimeEnv, ) { const alias = normalizeAlias(aliasRaw); - const updated = await updateConfig((cfg) => { - const resolved = resolveModelTarget({ raw: modelRaw, cfg }); - const nextAliases = { ...cfg.agent?.modelAliases }; - nextAliases[alias] = `${resolved.provider}/${resolved.model}`; + const resolved = resolveModelTarget({ raw: modelRaw, cfg: loadConfig() }); + const _updated = await updateConfig((cfg) => { + const modelKey = `${resolved.provider}/${resolved.model}`; + const nextModels = { ...cfg.agent?.models }; + for (const [key, entry] of Object.entries(nextModels)) { + const existing = entry?.alias?.trim(); + if (existing && existing === alias && key !== modelKey) { + throw new Error(`Alias ${alias} already points to ${key}.`); + } + } + const existing = nextModels[modelKey] ?? {}; + nextModels[modelKey] = { ...existing, alias }; return { ...cfg, agent: { ...cfg.agent, - modelAliases: nextAliases, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); - runtime.log(`Alias ${alias} -> ${updated.agent?.modelAliases?.[alias]}`); + runtime.log(`Alias ${alias} -> ${resolved.provider}/${resolved.model}`); } export async function modelsAliasesRemoveCommand( @@ -65,24 +81,31 @@ export async function modelsAliasesRemoveCommand( ) { const alias = normalizeAlias(aliasRaw); const updated = await updateConfig((cfg) => { - const nextAliases = { ...cfg.agent?.modelAliases }; - if (!nextAliases[alias]) { + const nextModels = { ...cfg.agent?.models }; + let found = false; + for (const [key, entry] of Object.entries(nextModels)) { + if (entry?.alias?.trim() === alias) { + nextModels[key] = { ...entry, alias: undefined }; + found = true; + break; + } + } + if (!found) { throw new Error(`Alias not found: ${alias}`); } - delete nextAliases[alias]; return { ...cfg, agent: { ...cfg.agent, - modelAliases: nextAliases, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); if ( - !updated.agent?.modelAliases || - Object.keys(updated.agent.modelAliases).length === 0 + !updated.agent?.models || + Object.values(updated.agent.models).every((entry) => !entry?.alias?.trim()) ) { runtime.log("No aliases configured."); } diff --git a/src/commands/models/fallbacks.ts b/src/commands/models/fallbacks.ts index 81f825abb..3722fabfa 100644 --- a/src/commands/models/fallbacks.ts +++ b/src/commands/models/fallbacks.ts @@ -18,7 +18,7 @@ export async function modelsFallbacksListCommand( ) { ensureFlagCompatibility(opts); const cfg = loadConfig(); - const fallbacks = cfg.agent?.modelFallbacks ?? []; + const fallbacks = cfg.agent?.model?.fallbacks ?? []; if (opts.json) { runtime.log(JSON.stringify({ fallbacks }, null, 2)); @@ -44,11 +44,13 @@ export async function modelsFallbacksAddCommand( const updated = await updateConfig((cfg) => { const resolved = resolveModelTarget({ raw: modelRaw, cfg }); const targetKey = modelKey(resolved.provider, resolved.model); + const nextModels = { ...cfg.agent?.models }; + if (!nextModels[targetKey]) nextModels[targetKey] = {}; const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: DEFAULT_PROVIDER, }); - const existing = cfg.agent?.modelFallbacks ?? []; + const existing = cfg.agent?.model?.fallbacks ?? []; const existingKeys = existing .map((entry) => resolveModelRefFromString({ @@ -66,13 +68,22 @@ export async function modelsFallbacksAddCommand( ...cfg, agent: { ...cfg.agent, - modelFallbacks: [...existing, targetKey], + model: { + ...((cfg.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: [...existing, targetKey], + }, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); - runtime.log(`Fallbacks: ${(updated.agent?.modelFallbacks ?? []).join(", ")}`); + runtime.log( + `Fallbacks: ${(updated.agent?.model?.fallbacks ?? []).join(", ")}`, + ); } export async function modelsFallbacksRemoveCommand( @@ -86,7 +97,7 @@ export async function modelsFallbacksRemoveCommand( cfg, defaultProvider: DEFAULT_PROVIDER, }); - const existing = cfg.agent?.modelFallbacks ?? []; + const existing = cfg.agent?.model?.fallbacks ?? []; const filtered = existing.filter((entry) => { const resolvedEntry = resolveModelRefFromString({ raw: String(entry ?? ""), @@ -108,13 +119,21 @@ export async function modelsFallbacksRemoveCommand( ...cfg, agent: { ...cfg.agent, - modelFallbacks: filtered, + model: { + ...((cfg.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: filtered, + }, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); - runtime.log(`Fallbacks: ${(updated.agent?.modelFallbacks ?? []).join(", ")}`); + runtime.log( + `Fallbacks: ${(updated.agent?.model?.fallbacks ?? []).join(", ")}`, + ); } export async function modelsFallbacksClearCommand(runtime: RuntimeEnv) { @@ -122,7 +141,11 @@ export async function modelsFallbacksClearCommand(runtime: RuntimeEnv) { ...cfg, agent: { ...cfg.agent, - modelFallbacks: [], + model: { + ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? + {}), + fallbacks: [], + }, }, })); diff --git a/src/commands/models/image-fallbacks.ts b/src/commands/models/image-fallbacks.ts index f4a941b8a..5fcff8bd4 100644 --- a/src/commands/models/image-fallbacks.ts +++ b/src/commands/models/image-fallbacks.ts @@ -18,7 +18,7 @@ export async function modelsImageFallbacksListCommand( ) { ensureFlagCompatibility(opts); const cfg = loadConfig(); - const fallbacks = cfg.agent?.imageModelFallbacks ?? []; + const fallbacks = cfg.agent?.imageModel?.fallbacks ?? []; if (opts.json) { runtime.log(JSON.stringify({ fallbacks }, null, 2)); @@ -44,11 +44,13 @@ export async function modelsImageFallbacksAddCommand( const updated = await updateConfig((cfg) => { const resolved = resolveModelTarget({ raw: modelRaw, cfg }); const targetKey = modelKey(resolved.provider, resolved.model); + const nextModels = { ...cfg.agent?.models }; + if (!nextModels[targetKey]) nextModels[targetKey] = {}; const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: DEFAULT_PROVIDER, }); - const existing = cfg.agent?.imageModelFallbacks ?? []; + const existing = cfg.agent?.imageModel?.fallbacks ?? []; const existingKeys = existing .map((entry) => resolveModelRefFromString({ @@ -66,14 +68,21 @@ export async function modelsImageFallbacksAddCommand( ...cfg, agent: { ...cfg.agent, - imageModelFallbacks: [...existing, targetKey], + imageModel: { + ...((cfg.agent?.imageModel as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: [...existing, targetKey], + }, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); runtime.log( - `Image fallbacks: ${(updated.agent?.imageModelFallbacks ?? []).join(", ")}`, + `Image fallbacks: ${(updated.agent?.imageModel?.fallbacks ?? []).join(", ")}`, ); } @@ -88,7 +97,7 @@ export async function modelsImageFallbacksRemoveCommand( cfg, defaultProvider: DEFAULT_PROVIDER, }); - const existing = cfg.agent?.imageModelFallbacks ?? []; + const existing = cfg.agent?.imageModel?.fallbacks ?? []; const filtered = existing.filter((entry) => { const resolvedEntry = resolveModelRefFromString({ raw: String(entry ?? ""), @@ -110,14 +119,20 @@ export async function modelsImageFallbacksRemoveCommand( ...cfg, agent: { ...cfg.agent, - imageModelFallbacks: filtered, + imageModel: { + ...((cfg.agent?.imageModel as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: filtered, + }, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); runtime.log( - `Image fallbacks: ${(updated.agent?.imageModelFallbacks ?? []).join(", ")}`, + `Image fallbacks: ${(updated.agent?.imageModel?.fallbacks ?? []).join(", ")}`, ); } @@ -126,7 +141,13 @@ export async function modelsImageFallbacksClearCommand(runtime: RuntimeEnv) { ...cfg, agent: { ...cfg.agent, - imageModelFallbacks: [], + imageModel: { + ...((cfg.agent?.imageModel as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: [], + }, }, })); diff --git a/src/commands/models/list.ts b/src/commands/models/list.ts index e061cf5d3..7a8fb7858 100644 --- a/src/commands/models/list.ts +++ b/src/commands/models/list.ts @@ -1,4 +1,4 @@ -import { type Api, getEnvApiKey, type Model } from "@mariozechner/pi-ai"; +import type { Api, Model } from "@mariozechner/pi-ai"; import { discoverAuthStorage, discoverModels, @@ -6,6 +6,15 @@ import { import chalk from "chalk"; import { resolveClawdbotAgentDir } from "../../agents/agent-paths.js"; +import { + type AuthProfileStore, + ensureAuthProfileStore, + listProfilesForProvider, +} from "../../agents/auth-profiles.js"; +import { + getCustomProviderApiKey, + resolveEnvApiKey, +} from "../../agents/model-auth.js"; import { buildModelAliasIndex, parseModelRef, @@ -81,6 +90,17 @@ const isLocalBaseUrl = (baseUrl: string) => { } }; +const hasAuthForProvider = ( + provider: string, + cfg: ClawdbotConfig, + authStore: AuthProfileStore, +): boolean => { + if (listProfilesForProvider(authStore, provider).length > 0) return true; + if (resolveEnvApiKey(provider)) return true; + if (getCustomProviderApiKey(cfg, provider)) return true; + return false; +}; + const resolveConfiguredEntries = (cfg: ClawdbotConfig) => { const resolvedDefault = resolveConfiguredModelRef({ cfg, @@ -110,7 +130,21 @@ const resolveConfiguredEntries = (cfg: ClawdbotConfig) => { addEntry(resolvedDefault, "default"); - (cfg.agent?.modelFallbacks ?? []).forEach((raw, idx) => { + const modelConfig = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; + const imageModelConfig = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; + const modelFallbacks = + typeof modelConfig === "object" ? (modelConfig?.fallbacks ?? []) : []; + const imageFallbacks = + typeof imageModelConfig === "object" + ? (imageModelConfig?.fallbacks ?? []) + : []; + const imagePrimary = imageModelConfig?.primary?.trim() ?? ""; + + modelFallbacks.forEach((raw, idx) => { const resolved = resolveModelRefFromString({ raw: String(raw ?? ""), defaultProvider: DEFAULT_PROVIDER, @@ -120,17 +154,16 @@ const resolveConfiguredEntries = (cfg: ClawdbotConfig) => { addEntry(resolved.ref, `fallback#${idx + 1}`); }); - const imageModelRaw = cfg.agent?.imageModel?.trim(); - if (imageModelRaw) { + if (imagePrimary) { const resolved = resolveModelRefFromString({ - raw: imageModelRaw, + raw: imagePrimary, defaultProvider: DEFAULT_PROVIDER, aliasIndex, }); if (resolved) addEntry(resolved.ref, "image"); } - (cfg.agent?.imageModelFallbacks ?? []).forEach((raw, idx) => { + imageFallbacks.forEach((raw, idx) => { const resolved = resolveModelRefFromString({ raw: String(raw ?? ""), defaultProvider: DEFAULT_PROVIDER, @@ -140,20 +173,10 @@ const resolveConfiguredEntries = (cfg: ClawdbotConfig) => { addEntry(resolved.ref, `img-fallback#${idx + 1}`); }); - (cfg.agent?.allowedModels ?? []).forEach((raw) => { - const parsed = parseModelRef(String(raw ?? ""), DEFAULT_PROVIDER); - if (!parsed) return; - addEntry(parsed, "allowed"); - }); - - for (const targetRaw of Object.values(cfg.agent?.modelAliases ?? {})) { - const resolved = resolveModelRefFromString({ - raw: String(targetRaw ?? ""), - defaultProvider: DEFAULT_PROVIDER, - aliasIndex, - }); - if (!resolved) continue; - addEntry(resolved.ref, "alias"); + for (const key of Object.keys(cfg.agent?.models ?? {})) { + const parsed = parseModelRef(String(key ?? ""), DEFAULT_PROVIDER); + if (!parsed) continue; + addEntry(parsed, "configured"); } const entries: ConfiguredEntry[] = order.map((key) => { @@ -190,8 +213,18 @@ function toModelRow(params: { tags: string[]; aliases?: string[]; availableKeys?: Set; + cfg?: ClawdbotConfig; + authStore?: AuthProfileStore; }): ModelRow { - const { model, key, tags, aliases = [], availableKeys } = params; + const { + model, + key, + tags, + aliases = [], + availableKeys, + cfg, + authStore, + } = params; if (!model) { return { key, @@ -207,9 +240,11 @@ function toModelRow(params: { const input = model.input.join("+") || "text"; const local = isLocalBaseUrl(model.baseUrl); - const envKey = getEnvApiKey(model.provider); const available = - availableKeys?.has(modelKey(model.provider, model.id)) || Boolean(envKey); + availableKeys?.has(modelKey(model.provider, model.id)) || + (cfg && authStore + ? hasAuthForProvider(model.provider, cfg, authStore) + : false); const aliasTags = aliases.length > 0 ? [`alias:${aliases.join(",")}`] : []; const mergedTags = new Set(tags); if (aliasTags.length > 0) { @@ -304,6 +339,7 @@ export async function modelsListCommand( ) { ensureFlagCompatibility(opts); const cfg = loadConfig(); + const authStore = ensureAuthProfileStore(); const providerFilter = opts.provider?.trim().toLowerCase(); let models: Model[] = []; @@ -346,6 +382,8 @@ export async function modelsListCommand( tags: configured ? Array.from(configured.tags) : [], aliases: configured?.aliases ?? [], availableKeys, + cfg, + authStore, }), ); } @@ -367,6 +405,8 @@ export async function modelsListCommand( tags: Array.from(entry.tags), aliases: entry.aliases, availableKeys, + cfg, + authStore, }), ); } @@ -392,13 +432,35 @@ export async function modelsStatusCommand( defaultModel: DEFAULT_MODEL, }); - const rawModel = cfg.agent?.model?.trim() ?? ""; + const modelConfig = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | string + | undefined; + const imageConfig = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | string + | undefined; + const rawModel = + typeof modelConfig === "string" + ? modelConfig.trim() + : (modelConfig?.primary?.trim() ?? ""); const defaultLabel = rawModel || `${resolved.provider}/${resolved.model}`; - const fallbacks = cfg.agent?.modelFallbacks ?? []; - const imageModel = cfg.agent?.imageModel?.trim() ?? ""; - const imageFallbacks = cfg.agent?.imageModelFallbacks ?? []; - const aliases = cfg.agent?.modelAliases ?? {}; - const allowed = cfg.agent?.allowedModels ?? []; + const fallbacks = + typeof modelConfig === "object" ? (modelConfig?.fallbacks ?? []) : []; + const imageModel = + typeof imageConfig === "string" + ? imageConfig.trim() + : (imageConfig?.primary?.trim() ?? ""); + const imageFallbacks = + typeof imageConfig === "object" ? (imageConfig?.fallbacks ?? []) : []; + const aliases = Object.entries(cfg.agent?.models ?? {}).reduce< + Record + >((acc, [key, entry]) => { + const alias = entry?.alias?.trim(); + if (alias) acc[alias] = key; + return acc; + }, {}); + const allowed = Object.keys(cfg.agent?.models ?? {}); if (opts.json) { runtime.log( @@ -446,6 +508,8 @@ export async function modelsStatusCommand( }`, ); runtime.log( - `Allowed (${allowed.length || 0}): ${allowed.length ? allowed.join(", ") : "all"}`, + `Configured models (${allowed.length || 0}): ${ + allowed.length ? allowed.join(", ") : "all" + }`, ); } diff --git a/src/commands/models/scan.ts b/src/commands/models/scan.ts index 4cb3b858f..416a220de 100644 --- a/src/commands/models/scan.ts +++ b/src/commands/models/scan.ts @@ -1,20 +1,12 @@ import { cancel, isCancel, multiselect } from "@clack/prompts"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; - -import { resolveClawdbotAgentDir } from "../../agents/agent-paths.js"; +import { resolveApiKeyForProvider } from "../../agents/model-auth.js"; import { type ModelScanResult, scanOpenRouterModels, } from "../../agents/model-scan.js"; -import { CONFIG_PATH_CLAWDBOT } from "../../config/config.js"; -import { warn } from "../../globals.js"; +import { CONFIG_PATH_CLAWDBOT, loadConfig } from "../../config/config.js"; import type { RuntimeEnv } from "../../runtime.js"; -import { - buildAllowlistSet, - formatMs, - formatTokenK, - updateConfig, -} from "./shared.js"; +import { formatMs, formatTokenK, updateConfig } from "./shared.js"; const MODEL_PAD = 42; const CTX_PAD = 8; @@ -181,8 +173,17 @@ export async function modelsScanCommand( throw new Error("--concurrency must be > 0"); } - const authStorage = discoverAuthStorage(resolveClawdbotAgentDir()); - const storedKey = await authStorage.getApiKey("openrouter"); + const cfg = loadConfig(); + let storedKey: string | undefined; + try { + const resolved = await resolveApiKeyForProvider({ + provider: "openrouter", + cfg, + }); + storedKey = resolved.apiKey; + } catch { + storedKey = undefined; + } const results = await scanOpenRouterModels({ apiKey: storedKey ?? undefined, minParamB: minParams, @@ -266,32 +267,42 @@ export async function modelsScanCommand( throw new Error("No image-capable models selected for image model."); } - const updated = await updateConfig((cfg) => { + const _updated = await updateConfig((cfg) => { + const nextModels = { ...cfg.agent?.models }; + for (const entry of selected) { + if (!nextModels[entry]) nextModels[entry] = {}; + } + for (const entry of selectedImages) { + if (!nextModels[entry]) nextModels[entry] = {}; + } + const nextImageModel = + selectedImages.length > 0 + ? { + ...((cfg.agent?.imageModel as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + fallbacks: selectedImages, + ...(opts.setImage ? { primary: selectedImages[0] } : {}), + } + : cfg.agent?.imageModel; const agent = { ...cfg.agent, - modelFallbacks: selected, - ...(opts.setDefault ? { model: selected[0] } : {}), - ...(opts.setImage && selectedImages.length > 0 - ? { imageModel: selectedImages[0] } - : {}), + model: { + ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? + {}), + fallbacks: selected, + ...(opts.setDefault ? { primary: selected[0] } : {}), + }, + ...(nextImageModel ? { imageModel: nextImageModel } : {}), + models: nextModels, } satisfies NonNullable; - if (imageSorted.length > 0) { - agent.imageModelFallbacks = selectedImages; - } return { ...cfg, agent, }; }); - const allowlist = buildAllowlistSet(updated); - const allowlistMissing = - allowlist.size > 0 ? selected.filter((entry) => !allowlist.has(entry)) : []; - const allowlistMissingImages = - allowlist.size > 0 - ? selectedImages.filter((entry) => !allowlist.has(entry)) - : []; - if (opts.json) { runtime.log( JSON.stringify( @@ -301,21 +312,7 @@ export async function modelsScanCommand( setDefault: Boolean(opts.setDefault), setImage: Boolean(opts.setImage), results, - warnings: - allowlistMissing.length > 0 || allowlistMissingImages.length > 0 - ? [ - ...(allowlistMissing.length > 0 - ? [ - `Selected models not in agent.allowedModels: ${allowlistMissing.join(", ")}`, - ] - : []), - ...(allowlistMissingImages.length > 0 - ? [ - `Selected image models not in agent.allowedModels: ${allowlistMissingImages.join(", ")}`, - ] - : []), - ] - : [], + warnings: [], }, null, 2, @@ -324,21 +321,6 @@ export async function modelsScanCommand( return; } - if (allowlistMissing.length > 0) { - runtime.log( - warn( - `Warning: ${allowlistMissing.length} selected models are not in agent.allowedModels and will be ignored by fallback: ${allowlistMissing.join(", ")}`, - ), - ); - } - if (allowlistMissingImages.length > 0) { - runtime.log( - warn( - `Warning: ${allowlistMissingImages.length} selected image models are not in agent.allowedModels and will be ignored by fallback: ${allowlistMissingImages.join(", ")}`, - ), - ); - } - runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); runtime.log(`Fallbacks: ${selected.join(", ")}`); if (selectedImages.length > 0) { diff --git a/src/commands/models/set-image.ts b/src/commands/models/set-image.ts index 6613b2e98..46214ee9a 100644 --- a/src/commands/models/set-image.ts +++ b/src/commands/models/set-image.ts @@ -1,11 +1,6 @@ import { CONFIG_PATH_CLAWDBOT } from "../../config/config.js"; import type { RuntimeEnv } from "../../runtime.js"; -import { - buildAllowlistSet, - modelKey, - resolveModelTarget, - updateConfig, -} from "./shared.js"; +import { resolveModelTarget, updateConfig } from "./shared.js"; export async function modelsSetImageCommand( modelRaw: string, @@ -13,22 +8,25 @@ export async function modelsSetImageCommand( ) { const updated = await updateConfig((cfg) => { const resolved = resolveModelTarget({ raw: modelRaw, cfg }); - const allowlist = buildAllowlistSet(cfg); - if (allowlist.size > 0) { - const key = modelKey(resolved.provider, resolved.model); - if (!allowlist.has(key)) { - throw new Error(`Model ${key} is not in agent.allowedModels.`); - } - } + const key = `${resolved.provider}/${resolved.model}`; + const nextModels = { ...cfg.agent?.models }; + if (!nextModels[key]) nextModels[key] = {}; return { ...cfg, agent: { ...cfg.agent, - imageModel: `${resolved.provider}/${resolved.model}`, + imageModel: { + ...((cfg.agent?.imageModel as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + primary: key, + }, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); - runtime.log(`Image model: ${updated.agent?.imageModel ?? modelRaw}`); + runtime.log(`Image model: ${updated.agent?.imageModel?.primary ?? modelRaw}`); } diff --git a/src/commands/models/set.ts b/src/commands/models/set.ts index 20e500519..d8546c484 100644 --- a/src/commands/models/set.ts +++ b/src/commands/models/set.ts @@ -1,31 +1,29 @@ import { CONFIG_PATH_CLAWDBOT } from "../../config/config.js"; import type { RuntimeEnv } from "../../runtime.js"; -import { - buildAllowlistSet, - modelKey, - resolveModelTarget, - updateConfig, -} from "./shared.js"; +import { resolveModelTarget, updateConfig } from "./shared.js"; export async function modelsSetCommand(modelRaw: string, runtime: RuntimeEnv) { const updated = await updateConfig((cfg) => { const resolved = resolveModelTarget({ raw: modelRaw, cfg }); - const allowlist = buildAllowlistSet(cfg); - if (allowlist.size > 0) { - const key = modelKey(resolved.provider, resolved.model); - if (!allowlist.has(key)) { - throw new Error(`Model ${key} is not in agent.allowedModels.`); - } - } + const key = `${resolved.provider}/${resolved.model}`; + const nextModels = { ...cfg.agent?.models }; + if (!nextModels[key]) nextModels[key] = {}; return { ...cfg, agent: { ...cfg.agent, - model: `${resolved.provider}/${resolved.model}`, + model: { + ...((cfg.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + primary: key, + }, + models: nextModels, }, }; }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); - runtime.log(`Default model: ${updated.agent?.model ?? modelRaw}`); + runtime.log(`Default model: ${updated.agent?.model?.primary ?? modelRaw}`); } diff --git a/src/commands/models/shared.ts b/src/commands/models/shared.ts index 347ae06d0..a8d305998 100644 --- a/src/commands/models/shared.ts +++ b/src/commands/models/shared.ts @@ -69,7 +69,8 @@ export function resolveModelTarget(params: { export function buildAllowlistSet(cfg: ClawdbotConfig): Set { const allowed = new Set(); - for (const raw of cfg.agent?.allowedModels ?? []) { + const models = cfg.agent?.models ?? {}; + for (const raw of Object.keys(models)) { const parsed = parseModelRef(String(raw ?? ""), DEFAULT_PROVIDER); if (!parsed) continue; allowed.add(modelKey(parsed.provider, parsed.model)); diff --git a/src/commands/onboard-auth.test.ts b/src/commands/onboard-auth.test.ts index 4187d1961..71526c61d 100644 --- a/src/commands/onboard-auth.test.ts +++ b/src/commands/onboard-auth.test.ts @@ -5,11 +5,12 @@ import path from "node:path"; import type { OAuthCredentials } from "@mariozechner/pi-ai"; import { afterEach, describe, expect, it } from "vitest"; -import { resolveOAuthPath } from "../config/paths.js"; import { writeOAuthCredentials } from "./onboard-auth.js"; describe("writeOAuthCredentials", () => { const previousStateDir = process.env.CLAWDBOT_STATE_DIR; + const previousAgentDir = process.env.CLAWDBOT_AGENT_DIR; + const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR; let tempStateDir: string | null = null; afterEach(async () => { @@ -22,12 +23,24 @@ describe("writeOAuthCredentials", () => { } else { process.env.CLAWDBOT_STATE_DIR = previousStateDir; } + if (previousAgentDir === undefined) { + delete process.env.CLAWDBOT_AGENT_DIR; + } else { + process.env.CLAWDBOT_AGENT_DIR = previousAgentDir; + } + if (previousPiAgentDir === undefined) { + delete process.env.PI_CODING_AGENT_DIR; + } else { + process.env.PI_CODING_AGENT_DIR = previousPiAgentDir; + } delete process.env.CLAWDBOT_OAUTH_DIR; }); - it("writes oauth.json under CLAWDBOT_STATE_DIR/credentials", async () => { + it("writes auth-profiles.json under CLAWDBOT_STATE_DIR/agent", async () => { tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-oauth-")); process.env.CLAWDBOT_STATE_DIR = tempStateDir; + process.env.CLAWDBOT_AGENT_DIR = path.join(tempStateDir, "agent"); + process.env.PI_CODING_AGENT_DIR = process.env.CLAWDBOT_AGENT_DIR; const creds = { refresh: "refresh-token", @@ -37,16 +50,19 @@ describe("writeOAuthCredentials", () => { await writeOAuthCredentials("anthropic", creds); - const oauthPath = resolveOAuthPath(); - expect(oauthPath).toBe( - path.join(tempStateDir, "credentials", "oauth.json"), + const authProfilePath = path.join( + tempStateDir, + "agent", + "auth-profiles.json", ); - - const raw = await fs.readFile(oauthPath, "utf8"); - const parsed = JSON.parse(raw) as Record; - expect(parsed.anthropic).toMatchObject({ + const raw = await fs.readFile(authProfilePath, "utf8"); + const parsed = JSON.parse(raw) as { + profiles?: Record; + }; + expect(parsed.profiles?.["anthropic:default"]).toMatchObject({ refresh: "refresh-token", access: "access-token", + type: "oauth", }); }); }); diff --git a/src/commands/onboard-auth.ts b/src/commands/onboard-auth.ts index 16b076a3d..94a272958 100644 --- a/src/commands/onboard-auth.ts +++ b/src/commands/onboard-auth.ts @@ -1,47 +1,73 @@ -import fs from "node:fs/promises"; -import path from "node:path"; - import type { OAuthCredentials, OAuthProvider } from "@mariozechner/pi-ai"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; - -import { resolveClawdbotAgentDir } from "../agents/agent-paths.js"; +import { upsertAuthProfile } from "../agents/auth-profiles.js"; import type { ClawdbotConfig } from "../config/config.js"; -import { resolveOAuthPath } from "../config/paths.js"; export async function writeOAuthCredentials( provider: OAuthProvider, creds: OAuthCredentials, ): Promise { - const filePath = resolveOAuthPath(); - const dir = path.dirname(filePath); - await fs.mkdir(dir, { recursive: true, mode: 0o700 }); - let storage: Record = {}; - try { - const raw = await fs.readFile(filePath, "utf8"); - const parsed = JSON.parse(raw) as Record; - if (parsed && typeof parsed === "object") storage = parsed; - } catch { - // ignore - } - storage[provider] = creds; - await fs.writeFile(filePath, `${JSON.stringify(storage, null, 2)}\n`, "utf8"); - await fs.chmod(filePath, 0o600); + upsertAuthProfile({ + profileId: `${provider}:default`, + credential: { + type: "oauth", + provider, + ...creds, + }, + }); } export async function setAnthropicApiKey(key: string) { - const agentDir = resolveClawdbotAgentDir(); - const authStorage = discoverAuthStorage(agentDir); - authStorage.set("anthropic", { type: "api_key", key }); + upsertAuthProfile({ + profileId: "anthropic:default", + credential: { + type: "api_key", + provider: "anthropic", + key, + }, + }); +} + +export function applyAuthProfileConfig( + cfg: ClawdbotConfig, + params: { + profileId: string; + provider: string; + mode: "api_key" | "oauth"; + email?: string; + }, +): ClawdbotConfig { + const profiles = { + ...cfg.auth?.profiles, + [params.profileId]: { + provider: params.provider, + mode: params.mode, + ...(params.email ? { email: params.email } : {}), + }, + }; + const order = { ...cfg.auth?.order }; + const list = order[params.provider] ? [...order[params.provider]] : []; + if (!list.includes(params.profileId)) list.push(params.profileId); + order[params.provider] = list; + return { + ...cfg, + auth: { + ...cfg.auth, + profiles, + order, + }, + }; } export function applyMinimaxConfig(cfg: ClawdbotConfig): ClawdbotConfig { - const allowed = new Set(cfg.agent?.allowedModels ?? []); - allowed.add("anthropic/claude-opus-4-5"); - allowed.add("lmstudio/minimax-m2.1-gs32"); - - const aliases = { ...cfg.agent?.modelAliases }; - if (!aliases.Opus) aliases.Opus = "anthropic/claude-opus-4-5"; - if (!aliases.Minimax) aliases.Minimax = "lmstudio/minimax-m2.1-gs32"; + const models = { ...cfg.agent?.models }; + models["anthropic/claude-opus-4-5"] = { + ...models["anthropic/claude-opus-4-5"], + alias: models["anthropic/claude-opus-4-5"]?.alias ?? "Opus", + }; + models["lmstudio/minimax-m2.1-gs32"] = { + ...models["lmstudio/minimax-m2.1-gs32"], + alias: models["lmstudio/minimax-m2.1-gs32"]?.alias ?? "Minimax", + }; const providers = { ...cfg.models?.providers }; if (!providers.lmstudio) { @@ -67,9 +93,12 @@ export function applyMinimaxConfig(cfg: ClawdbotConfig): ClawdbotConfig { ...cfg, agent: { ...cfg.agent, - model: "Minimax", - allowedModels: Array.from(allowed), - modelAliases: aliases, + model: { + ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? + {}), + primary: "lmstudio/minimax-m2.1-gs32", + }, + models, }, models: { mode: cfg.models?.mode ?? "merge", diff --git a/src/commands/onboard-helpers.ts b/src/commands/onboard-helpers.ts index 3e6ff3a87..0e81bf768 100644 --- a/src/commands/onboard-helpers.ts +++ b/src/commands/onboard-helpers.ts @@ -33,7 +33,13 @@ export function summarizeExistingConfig(config: ClawdbotConfig): string { const rows: string[] = []; if (config.agent?.workspace) rows.push(`workspace: ${config.agent.workspace}`); - if (config.agent?.model) rows.push(`model: ${config.agent.model}`); + if (config.agent?.model) { + const model = + typeof config.agent.model === "string" + ? config.agent.model + : config.agent.model.primary; + if (model) rows.push(`model: ${model}`); + } if (config.gateway?.mode) rows.push(`gateway.mode: ${config.gateway.mode}`); if (typeof config.gateway?.port === "number") { rows.push(`gateway.port: ${config.gateway.port}`); diff --git a/src/commands/onboard-non-interactive.ts b/src/commands/onboard-non-interactive.ts index 016c6fd3b..17d845cd7 100644 --- a/src/commands/onboard-non-interactive.ts +++ b/src/commands/onboard-non-interactive.ts @@ -14,7 +14,11 @@ import type { RuntimeEnv } from "../runtime.js"; import { defaultRuntime } from "../runtime.js"; import { resolveUserPath, sleep } from "../utils.js"; import { healthCommand } from "./health.js"; -import { applyMinimaxConfig, setAnthropicApiKey } from "./onboard-auth.js"; +import { + applyAuthProfileConfig, + applyMinimaxConfig, + setAnthropicApiKey, +} from "./onboard-auth.js"; import { applyWizardMetadata, DEFAULT_WORKSPACE, @@ -98,6 +102,11 @@ export async function runNonInteractiveOnboarding( return; } await setAnthropicApiKey(key); + nextConfig = applyAuthProfileConfig(nextConfig, { + profileId: "anthropic:default", + provider: "anthropic", + mode: "api_key", + }); } else if (authChoice === "minimax") { nextConfig = applyMinimaxConfig(nextConfig); } else if ( diff --git a/src/commands/sessions.test.ts b/src/commands/sessions.test.ts index f6ef8c626..de68266e1 100644 --- a/src/commands/sessions.test.ts +++ b/src/commands/sessions.test.ts @@ -12,7 +12,11 @@ vi.mock("../config/config.js", async (importOriginal) => { return { ...actual, loadConfig: () => ({ - agent: { model: "pi:opus", contextTokens: 32000 }, + agent: { + model: { primary: "pi:opus" }, + models: { "pi:opus": {} }, + contextTokens: 32000, + }, }), }; }); diff --git a/src/commands/setup.ts b/src/commands/setup.ts index cc36943cb..3bc176df9 100644 --- a/src/commands/setup.ts +++ b/src/commands/setup.ts @@ -8,7 +8,7 @@ import { ensureAgentWorkspace, } from "../agents/workspace.js"; import { type ClawdbotConfig, CONFIG_PATH_CLAWDBOT } from "../config/config.js"; -import { applyModelAliasDefaults } from "../config/defaults.js"; +import { applyModelDefaults } from "../config/defaults.js"; import { resolveSessionTranscriptsDir } from "../config/sessions.js"; import type { RuntimeEnv } from "../runtime.js"; import { defaultRuntime } from "../runtime.js"; @@ -31,7 +31,7 @@ async function readConfigFileRaw(): Promise<{ async function writeConfigFile(cfg: ClawdbotConfig) { await fs.mkdir(path.dirname(CONFIG_PATH_CLAWDBOT), { recursive: true }); - const json = JSON.stringify(applyModelAliasDefaults(cfg), null, 2) + const json = JSON.stringify(applyModelDefaults(cfg), null, 2) .trimEnd() .concat("\n"); await fs.writeFile(CONFIG_PATH_CLAWDBOT, json, "utf-8"); diff --git a/src/config/config.test.ts b/src/config/config.test.ts index ece86c2af..88de32c84 100644 --- a/src/config/config.test.ts +++ b/src/config/config.test.ts @@ -628,6 +628,18 @@ describe("legacy config detection", () => { } }); + it("rejects legacy agent.model string", async () => { + vi.resetModules(); + const { validateConfigObject } = await import("./config.js"); + const res = validateConfigObject({ + agent: { model: "anthropic/claude-opus-4-5" }, + }); + expect(res.ok).toBe(false); + if (!res.ok) { + expect(res.issues[0]?.path).toBe("agent.model"); + } + }); + it("migrates telegram.requireMention to telegram.groups.*.requireMention", async () => { vi.resetModules(); const { migrateLegacyConfig } = await import("./config.js"); @@ -641,6 +653,38 @@ describe("legacy config detection", () => { expect(res.config?.telegram?.requireMention).toBeUndefined(); }); + it("migrates legacy model config to agent.models + model lists", async () => { + vi.resetModules(); + const { migrateLegacyConfig } = await import("./config.js"); + const res = migrateLegacyConfig({ + agent: { + model: "anthropic/claude-opus-4-5", + modelFallbacks: ["openai/gpt-4.1-mini"], + imageModel: "openai/gpt-4.1-mini", + imageModelFallbacks: ["anthropic/claude-opus-4-5"], + allowedModels: ["anthropic/claude-opus-4-5", "openai/gpt-4.1-mini"], + modelAliases: { Opus: "anthropic/claude-opus-4-5" }, + }, + }); + + expect(res.config?.agent?.model?.primary).toBe("anthropic/claude-opus-4-5"); + expect(res.config?.agent?.model?.fallbacks).toEqual([ + "openai/gpt-4.1-mini", + ]); + expect(res.config?.agent?.imageModel?.primary).toBe("openai/gpt-4.1-mini"); + expect(res.config?.agent?.imageModel?.fallbacks).toEqual([ + "anthropic/claude-opus-4-5", + ]); + expect( + res.config?.agent?.models?.["anthropic/claude-opus-4-5"], + ).toMatchObject({ alias: "Opus" }); + expect(res.config?.agent?.models?.["openai/gpt-4.1-mini"]).toBeTruthy(); + expect(res.config?.agent?.allowedModels).toBeUndefined(); + expect(res.config?.agent?.modelAliases).toBeUndefined(); + expect(res.config?.agent?.modelFallbacks).toBeUndefined(); + expect(res.config?.agent?.imageModelFallbacks).toBeUndefined(); + }); + it("surfaces legacy issues in snapshot", async () => { await withTempHome(async (home) => { const configPath = path.join(home, ".clawdbot", "clawdbot.json"); diff --git a/src/config/defaults.ts b/src/config/defaults.ts index 2fb0eba8d..11a23699a 100644 --- a/src/config/defaults.ts +++ b/src/config/defaults.ts @@ -92,43 +92,23 @@ export function applyTalkApiKey(config: ClawdbotConfig): ClawdbotConfig { }; } -function normalizeAliasKey(value: string): string { - return value.trim().toLowerCase(); -} - -export function applyModelAliasDefaults(cfg: ClawdbotConfig): ClawdbotConfig { +export function applyModelDefaults(cfg: ClawdbotConfig): ClawdbotConfig { const existingAgent = cfg.agent; if (!existingAgent) return cfg; - const existingAliases = existingAgent?.modelAliases ?? {}; - - const byNormalized = new Map(); - for (const key of Object.keys(existingAliases)) { - const norm = normalizeAliasKey(key); - if (!norm) continue; - if (!byNormalized.has(norm)) byNormalized.set(norm, key); - } + const existingModels = existingAgent.models ?? {}; + if (Object.keys(existingModels).length === 0) return cfg; let mutated = false; - const nextAliases: Record = { ...existingAliases }; + const nextModels: Record = { + ...existingModels, + }; - for (const [canonicalKey, target] of Object.entries(DEFAULT_MODEL_ALIASES)) { - const norm = normalizeAliasKey(canonicalKey); - const existingKey = byNormalized.get(norm); - - if (!existingKey) { - nextAliases[canonicalKey] = target; - byNormalized.set(norm, canonicalKey); - mutated = true; - continue; - } - - const existingValue = String(existingAliases[existingKey] ?? ""); - if (existingKey !== canonicalKey && existingValue === target) { - delete nextAliases[existingKey]; - nextAliases[canonicalKey] = target; - byNormalized.set(norm, canonicalKey); - mutated = true; - } + for (const [alias, target] of Object.entries(DEFAULT_MODEL_ALIASES)) { + const entry = nextModels[target]; + if (!entry) continue; + if (entry.alias !== undefined) continue; + nextModels[target] = { ...entry, alias }; + mutated = true; } if (!mutated) return cfg; @@ -137,7 +117,7 @@ export function applyModelAliasDefaults(cfg: ClawdbotConfig): ClawdbotConfig { ...cfg, agent: { ...existingAgent, - modelAliases: nextAliases, + models: nextModels, }, }; } diff --git a/src/config/io.ts b/src/config/io.ts index ca04943b1..878dc0cc7 100644 --- a/src/config/io.ts +++ b/src/config/io.ts @@ -11,7 +11,7 @@ import { import { applyIdentityDefaults, applyLoggingDefaults, - applyModelAliasDefaults, + applyModelDefaults, applySessionDefaults, applyTalkApiKey, } from "./defaults.js"; @@ -114,7 +114,7 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { } return {}; } - const cfg = applyModelAliasDefaults( + const cfg = applyModelDefaults( applySessionDefaults( applyLoggingDefaults( applyIdentityDefaults(validated.data as ClawdbotConfig), @@ -148,7 +148,7 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { const exists = deps.fs.existsSync(configPath); if (!exists) { const config = applyTalkApiKey( - applyModelAliasDefaults(applySessionDefaults({})), + applyModelDefaults(applySessionDefaults({})), ); const legacyIssues: LegacyConfigIssue[] = []; return { @@ -204,7 +204,7 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { parsed: parsedRes.parsed, valid: true, config: applyTalkApiKey( - applyModelAliasDefaults( + applyModelDefaults( applySessionDefaults(applyLoggingDefaults(validated.config)), ), ), @@ -229,7 +229,7 @@ export function createConfigIO(overrides: ConfigIoDeps = {}) { await deps.fs.promises.mkdir(path.dirname(configPath), { recursive: true, }); - const json = JSON.stringify(applyModelAliasDefaults(cfg), null, 2) + const json = JSON.stringify(applyModelDefaults(cfg), null, 2) .trimEnd() .concat("\n"); await deps.fs.promises.writeFile(configPath, json, "utf-8"); diff --git a/src/config/legacy.ts b/src/config/legacy.ts index 9c633724b..10f9cfe13 100644 --- a/src/config/legacy.ts +++ b/src/config/legacy.ts @@ -3,6 +3,7 @@ import type { LegacyConfigIssue } from "./types.js"; type LegacyConfigRule = { path: string[]; message: string; + match?: (value: unknown, root: Record) => boolean; }; type LegacyConfigMigration = { @@ -27,6 +28,38 @@ const LEGACY_CONFIG_RULES: LegacyConfigRule[] = [ message: 'telegram.requireMention was removed; use telegram.groups."*".requireMention instead (run `clawdbot doctor` to migrate).', }, + { + path: ["agent", "model"], + message: + "agent.model string was replaced by agent.model.primary/fallbacks and agent.models (run `clawdbot doctor` to migrate).", + match: (value) => typeof value === "string", + }, + { + path: ["agent", "imageModel"], + message: + "agent.imageModel string was replaced by agent.imageModel.primary/fallbacks (run `clawdbot doctor` to migrate).", + match: (value) => typeof value === "string", + }, + { + path: ["agent", "allowedModels"], + message: + "agent.allowedModels was replaced by agent.models (run `clawdbot doctor` to migrate).", + }, + { + path: ["agent", "modelAliases"], + message: + "agent.modelAliases was replaced by agent.models.*.alias (run `clawdbot doctor` to migrate).", + }, + { + path: ["agent", "modelFallbacks"], + message: + "agent.modelFallbacks was replaced by agent.model.fallbacks (run `clawdbot doctor` to migrate).", + }, + { + path: ["agent", "imageModelFallbacks"], + message: + "agent.imageModelFallbacks was replaced by agent.imageModel.fallbacks (run `clawdbot doctor` to migrate).", + }, ]; const LEGACY_CONFIG_MIGRATIONS: LegacyConfigMigration[] = [ @@ -165,6 +198,158 @@ const LEGACY_CONFIG_MIGRATIONS: LegacyConfigMigration[] = [ } }, }, + { + id: "agent.model-config-v2", + describe: + "Migrate legacy agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks to agent.models + model lists", + apply: (raw, changes) => { + const agent = + raw.agent && typeof raw.agent === "object" + ? (raw.agent as Record) + : null; + if (!agent) return; + + const legacyModel = + typeof agent.model === "string" ? String(agent.model) : undefined; + const legacyImageModel = + typeof agent.imageModel === "string" + ? String(agent.imageModel) + : undefined; + const legacyAllowed = Array.isArray(agent.allowedModels) + ? (agent.allowedModels as unknown[]).map(String) + : []; + const legacyModelFallbacks = Array.isArray(agent.modelFallbacks) + ? (agent.modelFallbacks as unknown[]).map(String) + : []; + const legacyImageModelFallbacks = Array.isArray(agent.imageModelFallbacks) + ? (agent.imageModelFallbacks as unknown[]).map(String) + : []; + const legacyAliases = + agent.modelAliases && typeof agent.modelAliases === "object" + ? (agent.modelAliases as Record) + : {}; + + const hasLegacy = + legacyModel || + legacyImageModel || + legacyAllowed.length > 0 || + legacyModelFallbacks.length > 0 || + legacyImageModelFallbacks.length > 0 || + Object.keys(legacyAliases).length > 0; + if (!hasLegacy) return; + + const models = + agent.models && typeof agent.models === "object" + ? (agent.models as Record) + : {}; + + const ensureModel = (rawKey?: string) => { + const key = String(rawKey ?? "").trim(); + if (!key) return; + if (!models[key]) models[key] = {}; + }; + + ensureModel(legacyModel); + ensureModel(legacyImageModel); + for (const key of legacyAllowed) ensureModel(key); + for (const key of legacyModelFallbacks) ensureModel(key); + for (const key of legacyImageModelFallbacks) ensureModel(key); + for (const target of Object.values(legacyAliases)) { + ensureModel(String(target ?? "")); + } + + for (const [alias, targetRaw] of Object.entries(legacyAliases)) { + const target = String(targetRaw ?? "").trim(); + if (!target) continue; + const entry = + models[target] && typeof models[target] === "object" + ? (models[target] as Record) + : {}; + if (!("alias" in entry)) { + entry.alias = alias; + models[target] = entry; + } + } + + const currentModel = + agent.model && typeof agent.model === "object" + ? (agent.model as Record) + : null; + if (currentModel) { + if (!currentModel.primary && legacyModel) { + currentModel.primary = legacyModel; + } + if ( + legacyModelFallbacks.length > 0 && + (!Array.isArray(currentModel.fallbacks) || + currentModel.fallbacks.length === 0) + ) { + currentModel.fallbacks = legacyModelFallbacks; + } + agent.model = currentModel; + } else if (legacyModel || legacyModelFallbacks.length > 0) { + agent.model = { + primary: legacyModel, + fallbacks: legacyModelFallbacks.length ? legacyModelFallbacks : [], + }; + } + + const currentImageModel = + agent.imageModel && typeof agent.imageModel === "object" + ? (agent.imageModel as Record) + : null; + if (currentImageModel) { + if (!currentImageModel.primary && legacyImageModel) { + currentImageModel.primary = legacyImageModel; + } + if ( + legacyImageModelFallbacks.length > 0 && + (!Array.isArray(currentImageModel.fallbacks) || + currentImageModel.fallbacks.length === 0) + ) { + currentImageModel.fallbacks = legacyImageModelFallbacks; + } + agent.imageModel = currentImageModel; + } else if (legacyImageModel || legacyImageModelFallbacks.length > 0) { + agent.imageModel = { + primary: legacyImageModel, + fallbacks: legacyImageModelFallbacks.length + ? legacyImageModelFallbacks + : [], + }; + } + + agent.models = models; + + if (legacyModel !== undefined) { + changes.push("Migrated agent.model string → agent.model.primary."); + } + if (legacyModelFallbacks.length > 0) { + changes.push("Migrated agent.modelFallbacks → agent.model.fallbacks."); + } + if (legacyImageModel !== undefined) { + changes.push( + "Migrated agent.imageModel string → agent.imageModel.primary.", + ); + } + if (legacyImageModelFallbacks.length > 0) { + changes.push( + "Migrated agent.imageModelFallbacks → agent.imageModel.fallbacks.", + ); + } + if (legacyAllowed.length > 0) { + changes.push("Migrated agent.allowedModels → agent.models."); + } + if (Object.keys(legacyAliases).length > 0) { + changes.push("Migrated agent.modelAliases → agent.models.*.alias."); + } + + delete agent.allowedModels; + delete agent.modelAliases; + delete agent.modelFallbacks; + delete agent.imageModelFallbacks; + }, + }, ]; export function findLegacyConfigIssues(raw: unknown): LegacyConfigIssue[] { @@ -180,7 +365,7 @@ export function findLegacyConfigIssues(raw: unknown): LegacyConfigIssue[] { } cursor = (cursor as Record)[key]; } - if (cursor !== undefined) { + if (cursor !== undefined && (!rule.match || rule.match(cursor, root))) { issues.push({ path: rule.path.join("."), message: rule.message }); } } diff --git a/src/config/model-alias-defaults.test.ts b/src/config/model-alias-defaults.test.ts index 352608ec9..cf11f6c0e 100644 --- a/src/config/model-alias-defaults.test.ts +++ b/src/config/model-alias-defaults.test.ts @@ -1,90 +1,56 @@ import { describe, expect, it } from "vitest"; -import { applyLoggingDefaults, applyModelAliasDefaults } from "./defaults.js"; +import { applyModelDefaults } from "./defaults.js"; import type { ClawdbotConfig } from "./types.js"; -describe("applyModelAliasDefaults", () => { - it("adds default shorthands", () => { - const cfg = { agent: {} } satisfies ClawdbotConfig; - const next = applyModelAliasDefaults(cfg); +describe("applyModelDefaults", () => { + it("adds default aliases when models are present", () => { + const cfg = { + agent: { + models: { + "anthropic/claude-opus-4-5": {}, + "openai/gpt-5.2": {}, + }, + }, + } satisfies ClawdbotConfig; + const next = applyModelDefaults(cfg); - expect(next.agent?.modelAliases).toEqual({ - opus: "anthropic/claude-opus-4-5", - sonnet: "anthropic/claude-sonnet-4-5", - gpt: "openai/gpt-5.2", - "gpt-mini": "openai/gpt-5-mini", - gemini: "google/gemini-3-pro-preview", - "gemini-flash": "google/gemini-3-flash-preview", - }); + expect(next.agent?.models?.["anthropic/claude-opus-4-5"]?.alias).toBe( + "opus", + ); + expect(next.agent?.models?.["openai/gpt-5.2"]?.alias).toBe("gpt"); }); - it("normalizes casing when alias matches the default target", () => { + it("does not override existing aliases", () => { const cfg = { - agent: { modelAliases: { Opus: "anthropic/claude-opus-4-5" } }, + agent: { + models: { + "anthropic/claude-opus-4-5": { alias: "Opus" }, + }, + }, } satisfies ClawdbotConfig; - const next = applyModelAliasDefaults(cfg); + const next = applyModelDefaults(cfg); - expect(next.agent?.modelAliases).toMatchObject({ - opus: "anthropic/claude-opus-4-5", - }); - expect(next.agent?.modelAliases).not.toHaveProperty("Opus"); + expect(next.agent?.models?.["anthropic/claude-opus-4-5"]?.alias).toBe( + "Opus", + ); }); - it("does not override existing alias values", () => { + it("respects explicit empty alias disables", () => { const cfg = { - agent: { modelAliases: { gpt: "openai/gpt-4.1" } }, + agent: { + models: { + "google/gemini-3-pro-preview": { alias: "" }, + "google/gemini-3-flash-preview": {}, + }, + }, } satisfies ClawdbotConfig; - const next = applyModelAliasDefaults(cfg); + const next = applyModelDefaults(cfg); - expect(next.agent?.modelAliases?.gpt).toBe("openai/gpt-4.1"); - expect(next.agent?.modelAliases).toMatchObject({ - "gpt-mini": "openai/gpt-5-mini", - opus: "anthropic/claude-opus-4-5", - sonnet: "anthropic/claude-sonnet-4-5", - gemini: "google/gemini-3-pro-preview", - "gemini-flash": "google/gemini-3-flash-preview", - }); - }); - - it("does not rename when casing differs and value differs", () => { - const cfg = { - agent: { modelAliases: { GPT: "openai/gpt-4.1-mini" } }, - } satisfies ClawdbotConfig; - - const next = applyModelAliasDefaults(cfg); - - expect(next.agent?.modelAliases).toMatchObject({ - GPT: "openai/gpt-4.1-mini", - }); - expect(next.agent?.modelAliases).not.toHaveProperty("gpt"); - }); - - it("respects explicit empty-string disables", () => { - const cfg = { - agent: { modelAliases: { gemini: "" } }, - } satisfies ClawdbotConfig; - - const next = applyModelAliasDefaults(cfg); - - expect(next.agent?.modelAliases?.gemini).toBe(""); - expect(next.agent?.modelAliases).toHaveProperty( + expect(next.agent?.models?.["google/gemini-3-pro-preview"]?.alias).toBe(""); + expect(next.agent?.models?.["google/gemini-3-flash-preview"]?.alias).toBe( "gemini-flash", - "google/gemini-3-flash-preview", ); }); }); - -describe("applyLoggingDefaults", () => { - it("defaults redactSensitive to tools", () => { - const result = applyLoggingDefaults({ logging: {} }); - expect(result.logging?.redactSensitive).toBe("tools"); - }); - - it("preserves explicit redactSensitive", () => { - const result = applyLoggingDefaults({ - logging: { redactSensitive: "off" }, - }); - expect(result.logging?.redactSensitive).toBe("off"); - }); -}); diff --git a/src/config/paths.ts b/src/config/paths.ts index 1f6558625..134062561 100644 --- a/src/config/paths.ts +++ b/src/config/paths.ts @@ -1,6 +1,5 @@ import os from "node:os"; import path from "node:path"; -import { resolveUserPath } from "../utils.js"; import type { ClawdbotConfig } from "./types.js"; /** @@ -33,6 +32,15 @@ export function resolveStateDir( return path.join(homedir(), ".clawdbot"); } +function resolveUserPath(input: string): string { + const trimmed = input.trim(); + if (!trimmed) return trimmed; + if (trimmed.startsWith("~")) { + return path.resolve(trimmed.replace("~", os.homedir())); + } + return path.resolve(trimmed); +} + export const STATE_DIR_CLAWDBOT = resolveStateDir(); /** diff --git a/src/config/schema.ts b/src/config/schema.ts index b09b26a4a..ab582bab9 100644 --- a/src/config/schema.ts +++ b/src/config/schema.ts @@ -87,10 +87,13 @@ const FIELD_LABELS: Record = { "gateway.reload.mode": "Config Reload Mode", "gateway.reload.debounceMs": "Config Reload Debounce (ms)", "agent.workspace": "Workspace", - "agent.model": "Default Model", - "agent.imageModel": "Image Model", - "agent.modelFallbacks": "Model Fallbacks", - "agent.imageModelFallbacks": "Image Model Fallbacks", + "auth.profiles": "Auth Profiles", + "auth.order": "Auth Profile Order", + "agent.models": "Models", + "agent.model.primary": "Primary Model", + "agent.model.fallbacks": "Model Fallbacks", + "agent.imageModel.primary": "Image Model", + "agent.imageModel.fallbacks": "Image Model Fallbacks", "ui.seamColor": "Accent Color", "browser.controlUrl": "Browser Control URL", "session.agentToAgent.maxPingPongTurns": "Agent-to-Agent Ping-Pong Turns", @@ -114,12 +117,18 @@ const FIELD_HELP: Record = { 'Hot reload strategy for config changes ("hybrid" recommended).', "gateway.reload.debounceMs": "Debounce window (ms) before applying config changes.", - "agent.modelFallbacks": + "auth.profiles": "Named auth profiles (provider + mode + optional email).", + "auth.order": + "Ordered auth profile IDs per provider (used for automatic failover).", + "agent.models": + "Configured model catalog (keys are full provider/model IDs).", + "agent.model.primary": "Primary model (provider/model).", + "agent.model.fallbacks": "Ordered fallback models (provider/model). Used when the primary model fails.", - "agent.imageModel": - "Optional image-capable model (provider/model) used by the image tool.", - "agent.imageModelFallbacks": - "Ordered fallback image models (provider/model) used by the image tool.", + "agent.imageModel.primary": + "Optional image model (provider/model) used when the primary model lacks image input.", + "agent.imageModel.fallbacks": + "Ordered fallback image models (provider/model).", "session.agentToAgent.maxPingPongTurns": "Max reply-back turns between requester and target (0–5).", }; diff --git a/src/config/sessions.ts b/src/config/sessions.ts index e7ff6a2f5..049d4420a 100644 --- a/src/config/sessions.ts +++ b/src/config/sessions.ts @@ -34,6 +34,7 @@ export type SessionEntry = { elevatedLevel?: string; providerOverride?: string; modelOverride?: string; + authProfileOverride?: string; groupActivation?: "mention" | "always"; groupActivationNeedsSystemIntro?: boolean; sendPolicy?: "allow" | "deny"; diff --git a/src/config/types.ts b/src/config/types.ts index 29633cb6c..9e8feb291 100644 --- a/src/config/types.ts +++ b/src/config/types.ts @@ -639,7 +639,28 @@ export type ModelsConfig = { providers?: Record; }; +export type AuthProfileConfig = { + provider: string; + mode: "api_key" | "oauth"; + email?: string; +}; + +export type AuthConfig = { + profiles?: Record; + order?: Record; +}; + +export type AgentModelEntryConfig = { + alias?: string; +}; + +export type AgentModelListConfig = { + primary?: string; + fallbacks?: string[]; +}; + export type ClawdbotConfig = { + auth?: AuthConfig; env?: { /** Opt-in: import missing secrets from a login shell environment (exec `$SHELL -l -c 'env -0'`). */ shellEnv?: { @@ -669,22 +690,16 @@ export type ClawdbotConfig = { skills?: SkillsConfig; models?: ModelsConfig; agent?: { - /** Model id (provider/model), e.g. "anthropic/claude-opus-4-5". */ - model?: string; - /** Optional image-capable model (provider/model) used by the image tool. */ - imageModel?: string; + /** Primary model and fallbacks (provider/model). */ + model?: AgentModelListConfig; + /** Optional image-capable model and fallbacks (provider/model). */ + imageModel?: AgentModelListConfig; + /** Model catalog with optional aliases (full provider/model keys). */ + models?: Record; /** Agent working directory (preferred). Used as the default cwd for agent runs. */ workspace?: string; /** Optional IANA timezone for the user (used in system prompt; defaults to host timezone). */ userTimezone?: string; - /** Optional allowlist for /model (provider/model or model-only). */ - allowedModels?: string[]; - /** Optional model aliases for /model (alias -> provider/model). */ - modelAliases?: Record; - /** Ordered fallback models (provider/model). */ - modelFallbacks?: string[]; - /** Ordered fallback image models (provider/model) for the image tool. */ - imageModelFallbacks?: string[]; /** Optional display-only context window override (used for % in status UIs). */ contextTokens?: number; /** Default thinking level when no /think directive is present. */ diff --git a/src/config/validation.ts b/src/config/validation.ts index ecf57d8ab..9c6378753 100644 --- a/src/config/validation.ts +++ b/src/config/validation.ts @@ -1,6 +1,6 @@ import { applyIdentityDefaults, - applyModelAliasDefaults, + applyModelDefaults, applySessionDefaults, } from "./defaults.js"; import { findLegacyConfigIssues } from "./legacy.js"; @@ -34,7 +34,7 @@ export function validateConfigObject( } return { ok: true, - config: applyModelAliasDefaults( + config: applyModelDefaults( applySessionDefaults( applyIdentityDefaults(validated.data as ClawdbotConfig), ), diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts index bc347f8d0..51cd99726 100644 --- a/src/config/zod-schema.ts +++ b/src/config/zod-schema.ts @@ -373,17 +373,46 @@ export const ClawdbotSchema = z.object({ seamColor: HexColorSchema.optional(), }) .optional(), + auth: z + .object({ + profiles: z + .record( + z.string(), + z.object({ + provider: z.string(), + mode: z.union([z.literal("api_key"), z.literal("oauth")]), + email: z.string().optional(), + }), + ) + .optional(), + order: z.record(z.string(), z.array(z.string())).optional(), + }) + .optional(), models: ModelsConfigSchema, agent: z .object({ - model: z.string().optional(), - imageModel: z.string().optional(), + model: z + .object({ + primary: z.string().optional(), + fallbacks: z.array(z.string()).optional(), + }) + .optional(), + imageModel: z + .object({ + primary: z.string().optional(), + fallbacks: z.array(z.string()).optional(), + }) + .optional(), + models: z + .record( + z.string(), + z.object({ + alias: z.string().optional(), + }), + ) + .optional(), workspace: z.string().optional(), userTimezone: z.string().optional(), - allowedModels: z.array(z.string()).optional(), - modelAliases: z.record(z.string(), z.string()).optional(), - modelFallbacks: z.array(z.string()).optional(), - imageModelFallbacks: z.array(z.string()).optional(), contextTokens: z.number().int().positive().optional(), tools: z .object({ diff --git a/src/infra/shell-env.ts b/src/infra/shell-env.ts index 157cc1a4c..9010edcd9 100644 --- a/src/infra/shell-env.ts +++ b/src/infra/shell-env.ts @@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process"; const DEFAULT_TIMEOUT_MS = 15_000; const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024; +let lastAppliedKeys: string[] = []; function isTruthy(raw: string | undefined): boolean { if (!raw) return false; @@ -34,13 +35,16 @@ export function loadShellEnvFallback( const logger = opts.logger ?? console; const exec = opts.exec ?? execFileSync; - if (!opts.enabled) + if (!opts.enabled) { + lastAppliedKeys = []; return { ok: true, applied: [], skippedReason: "disabled" }; + } const hasAnyKey = opts.expectedKeys.some((key) => Boolean(opts.env[key]?.trim()), ); if (hasAnyKey) { + lastAppliedKeys = []; return { ok: true, applied: [], skippedReason: "already-has-keys" }; } @@ -63,6 +67,7 @@ export function loadShellEnvFallback( } catch (err) { const msg = err instanceof Error ? err.message : String(err); logger.warn(`[clawdbot] shell env fallback failed: ${msg}`); + lastAppliedKeys = []; return { ok: false, error: msg, applied: [] }; } @@ -87,6 +92,7 @@ export function loadShellEnvFallback( applied.push(key); } + lastAppliedKeys = applied; return { ok: true, applied }; } @@ -103,3 +109,7 @@ export function resolveShellEnvFallbackTimeoutMs( if (!Number.isFinite(parsed)) return DEFAULT_TIMEOUT_MS; return Math.max(0, parsed); } + +export function getShellEnvAppliedKeys(): string[] { + return [...lastAppliedKeys]; +} diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index 38e126e9b..b4f30e6a4 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -2,17 +2,17 @@ import path from "node:path"; import { loginAnthropic, + loginOpenAICodex, type OAuthCredentials, type OAuthProvider, } from "@mariozechner/pi-ai"; -import { discoverAuthStorage } from "@mariozechner/pi-coding-agent"; -import { resolveClawdbotAgentDir } from "../agents/agent-paths.js"; import { isRemoteEnvironment, loginAntigravityVpsAware, } from "../commands/antigravity-oauth.js"; import { healthCommand } from "../commands/health.js"; import { + applyAuthProfileConfig, applyMinimaxConfig, setAnthropicApiKey, writeOAuthCredentials, @@ -227,6 +227,11 @@ export async function runOnboardingWizard( spin.stop("OAuth complete"); if (oauthCreds) { await writeOAuthCredentials("anthropic", oauthCreds); + nextConfig = applyAuthProfileConfig(nextConfig, { + profileId: "anthropic:default", + provider: "anthropic", + mode: "oauth", + }); } } catch (err) { spin.stop("OAuth failed"); @@ -250,10 +255,7 @@ export async function runOnboardingWizard( ); const spin = prompter.progress("Starting OAuth flow…"); try { - const agentDir = resolveClawdbotAgentDir(); - const authStorage = discoverAuthStorage(agentDir); - const provider = "openai-codex" as unknown as OAuthProvider; - await authStorage.login(provider, { + const creds = await loginOpenAICodex({ onAuth: async ({ url }) => { if (isRemote) { spin.stop("OAuth URL ready"); @@ -275,6 +277,17 @@ export async function runOnboardingWizard( onProgress: (msg) => spin.update(msg), }); spin.stop("OpenAI OAuth complete"); + if (creds) { + await writeOAuthCredentials( + "openai-codex" as unknown as OAuthProvider, + creds, + ); + nextConfig = applyAuthProfileConfig(nextConfig, { + profileId: "openai-codex:default", + provider: "openai-codex", + mode: "oauth", + }); + } } catch (err) { spin.stop("OpenAI OAuth failed"); runtime.error(String(err)); @@ -314,11 +327,29 @@ export async function runOnboardingWizard( spin.stop("Antigravity OAuth complete"); if (oauthCreds) { await writeOAuthCredentials("google-antigravity", oauthCreds); + nextConfig = applyAuthProfileConfig(nextConfig, { + profileId: "google-antigravity:default", + provider: "google-antigravity", + mode: "oauth", + }); nextConfig = { ...nextConfig, agent: { ...nextConfig.agent, - model: "google-antigravity/claude-opus-4-5-thinking", + model: { + ...((nextConfig.agent?.model as { + primary?: string; + fallbacks?: string[]; + }) ?? {}), + primary: "google-antigravity/claude-opus-4-5-thinking", + }, + models: { + ...nextConfig.agent?.models, + "google-antigravity/claude-opus-4-5-thinking": + nextConfig.agent?.models?.[ + "google-antigravity/claude-opus-4-5-thinking" + ] ?? {}, + }, }, }; await prompter.note( @@ -336,6 +367,11 @@ export async function runOnboardingWizard( validate: (value) => (value?.trim() ? undefined : "Required"), }); await setAnthropicApiKey(String(key).trim()); + nextConfig = applyAuthProfileConfig(nextConfig, { + profileId: "anthropic:default", + provider: "anthropic", + mode: "api_key", + }); } else if (authChoice === "minimax") { nextConfig = applyMinimaxConfig(nextConfig); } From e73573eaeacabd6e6c9facb8f563df27c42cdc7a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:08:36 +0000 Subject: [PATCH 041/110] fix: clean model config typing --- src/agents/auth-profiles.ts | 64 +++++++++++++++++++------ src/agents/pi-embedded-runner.ts | 15 ++++-- src/auto-reply/reply/commands.ts | 5 +- src/commands/configure.ts | 22 +++++---- src/commands/models/fallbacks.ts | 48 ++++++++++++------- src/commands/models/image-fallbacks.ts | 50 +++++++++++-------- src/commands/models/scan.ts | 18 ++++--- src/commands/models/set-image.ts | 10 ++-- src/commands/models/set.ts | 10 ++-- src/commands/onboard-auth.ts | 9 +++- src/config/legacy.ts | 9 ++-- src/discord/monitor.tool-result.test.ts | 2 +- src/wizard/onboarding.ts | 12 +++-- 13 files changed, 184 insertions(+), 90 deletions(-) diff --git a/src/agents/auth-profiles.ts b/src/agents/auth-profiles.ts index f3019f755..df8b1b452 100644 --- a/src/agents/auth-profiles.ts +++ b/src/agents/auth-profiles.ts @@ -143,10 +143,26 @@ export function loadAuthProfileStore(): AuthProfileStore { }; for (const [provider, cred] of Object.entries(legacy)) { const profileId = `${provider}:default`; - store.profiles[profileId] = { - ...cred, - provider: cred.provider ?? (provider as OAuthProvider), - }; + if (cred.type === "api_key") { + store.profiles[profileId] = { + type: "api_key", + provider: cred.provider ?? (provider as OAuthProvider), + key: cred.key, + ...(cred.email ? { email: cred.email } : {}), + }; + } else { + store.profiles[profileId] = { + type: "oauth", + provider: cred.provider ?? (provider as OAuthProvider), + access: cred.access, + refresh: cred.refresh, + expires: cred.expires, + ...(cred.enterpriseUrl ? { enterpriseUrl: cred.enterpriseUrl } : {}), + ...(cred.projectId ? { projectId: cred.projectId } : {}), + ...(cred.accountId ? { accountId: cred.accountId } : {}), + ...(cred.email ? { email: cred.email } : {}), + }; + } } return store; } @@ -162,17 +178,35 @@ export function ensureAuthProfileStore(): AuthProfileStore { const legacyRaw = loadJsonFile(resolveLegacyAuthStorePath()); const legacy = coerceLegacyStore(legacyRaw); - const store = legacy - ? { - version: AUTH_STORE_VERSION, - profiles: Object.fromEntries( - Object.entries(legacy).map(([provider, cred]) => [ - `${provider}:default`, - { ...cred, provider: cred.provider ?? (provider as OAuthProvider) }, - ]), - ), + const store: AuthProfileStore = { + version: AUTH_STORE_VERSION, + profiles: {}, + }; + if (legacy) { + for (const [provider, cred] of Object.entries(legacy)) { + const profileId = `${provider}:default`; + if (cred.type === "api_key") { + store.profiles[profileId] = { + type: "api_key", + provider: cred.provider ?? (provider as OAuthProvider), + key: cred.key, + ...(cred.email ? { email: cred.email } : {}), + }; + } else { + store.profiles[profileId] = { + type: "oauth", + provider: cred.provider ?? (provider as OAuthProvider), + access: cred.access, + refresh: cred.refresh, + expires: cred.expires, + ...(cred.enterpriseUrl ? { enterpriseUrl: cred.enterpriseUrl } : {}), + ...(cred.projectId ? { projectId: cred.projectId } : {}), + ...(cred.accountId ? { accountId: cred.accountId } : {}), + ...(cred.email ? { email: cred.email } : {}), + }; } - : { version: AUTH_STORE_VERSION, profiles: {} }; + } + } const mergedOAuth = mergeOAuthFileIntoStore(store); const shouldWrite = legacy !== null || mergedOAuth; @@ -291,7 +325,7 @@ export function markAuthProfileGood(params: { const { store, provider, profileId } = params; const profile = store.profiles[profileId]; if (!profile || profile.provider !== provider) return; - store.lastGood = { ...(store.lastGood ?? {}), [provider]: profileId }; + store.lastGood = { ...store.lastGood, [provider]: profileId }; saveAuthProfileStore(store); } diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index 28bd4bec6..473f89175 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -82,6 +82,12 @@ export type EmbeddedPiRunMeta = { aborted?: boolean; }; +type ApiKeyInfo = { + apiKey: string; + profileId?: string; + source: string; +}; + export type EmbeddedPiRunResult = { payloads?: Array<{ text?: string; @@ -396,8 +402,8 @@ export async function runEmbeddedPiAgent(params: { const initialThinkLevel = params.thinkLevel ?? "off"; let thinkLevel = initialThinkLevel; const attemptedThinking = new Set(); - let apiKeyInfo: Awaited> | null = - null; + let apiKeyInfo: ApiKeyInfo | null = null; + let lastProfileId: string | undefined; const resolveApiKeyForCandidate = async (candidate?: string) => { return getApiKeyForModel({ @@ -411,6 +417,7 @@ export async function runEmbeddedPiAgent(params: { const applyApiKeyInfo = async (candidate?: string): Promise => { apiKeyInfo = await resolveApiKeyForCandidate(candidate); authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); + lastProfileId = apiKeyInfo.profileId; }; const advanceAuthProfile = async (): Promise => { @@ -802,11 +809,11 @@ export async function runEmbeddedPiAgent(params: { log.debug( `embedded run done: runId=${params.runId} sessionId=${params.sessionId} durationMs=${Date.now() - started} aborted=${aborted}`, ); - if (apiKeyInfo?.profileId) { + if (lastProfileId) { markAuthProfileGood({ store: authStore, provider, - profileId: apiKeyInfo.profileId, + profileId: lastProfileId, }); } return { diff --git a/src/auto-reply/reply/commands.ts b/src/auto-reply/reply/commands.ts index d8042911b..ad2778b42 100644 --- a/src/auto-reply/reply/commands.ts +++ b/src/auto-reply/reply/commands.ts @@ -337,7 +337,10 @@ export async function handleCommands(params: { const statusText = buildStatusMessage({ agent: { ...cfg.agent, - model, + model: { + ...cfg.agent?.model, + primary: model, + }, contextTokens, thinkingDefault: cfg.agent?.thinkingDefault, verboseDefault: cfg.agent?.verboseDefault, diff --git a/src/commands/configure.ts b/src/commands/configure.ts index 9d61541d4..e2b8b6451 100644 --- a/src/commands/configure.ts +++ b/src/commands/configure.ts @@ -333,10 +333,13 @@ async function promptAuthConfig( agent: { ...next.agent, model: { - ...((next.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(next.agent?.model && + "fallbacks" in (next.agent.model as Record) + ? { + fallbacks: (next.agent.model as { fallbacks?: string[] }) + .fallbacks, + } + : undefined), primary: "google-antigravity/claude-opus-4-5-thinking", }, models: { @@ -392,10 +395,13 @@ async function promptAuthConfig( agent: { ...next.agent, model: { - ...((next.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(next.agent?.model && + "fallbacks" in (next.agent.model as Record) + ? { + fallbacks: (next.agent.model as { fallbacks?: string[] }) + .fallbacks, + } + : undefined), primary: model, }, models: { diff --git a/src/commands/models/fallbacks.ts b/src/commands/models/fallbacks.ts index 3722fabfa..c5ac94f4d 100644 --- a/src/commands/models/fallbacks.ts +++ b/src/commands/models/fallbacks.ts @@ -64,15 +64,18 @@ export async function modelsFallbacksAddCommand( if (existingKeys.includes(targetKey)) return cfg; + const existingModel = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { ...cfg, agent: { ...cfg.agent, model: { - ...((cfg.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), fallbacks: [...existing, targetKey], }, models: nextModels, @@ -115,15 +118,18 @@ export async function modelsFallbacksRemoveCommand( throw new Error(`Fallback not found: ${targetKey}`); } + const existingModel = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { ...cfg, agent: { ...cfg.agent, model: { - ...((cfg.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), fallbacks: filtered, }, }, @@ -137,17 +143,23 @@ export async function modelsFallbacksRemoveCommand( } export async function modelsFallbacksClearCommand(runtime: RuntimeEnv) { - await updateConfig((cfg) => ({ - ...cfg, - agent: { - ...cfg.agent, - model: { - ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? - {}), - fallbacks: [], + await updateConfig((cfg) => { + const existingModel = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { + ...cfg, + agent: { + ...cfg.agent, + model: { + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), + fallbacks: [], + }, }, - }, - })); + }; + }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); runtime.log("Fallback list cleared."); diff --git a/src/commands/models/image-fallbacks.ts b/src/commands/models/image-fallbacks.ts index 5fcff8bd4..25ea316ec 100644 --- a/src/commands/models/image-fallbacks.ts +++ b/src/commands/models/image-fallbacks.ts @@ -64,15 +64,18 @@ export async function modelsImageFallbacksAddCommand( if (existingKeys.includes(targetKey)) return cfg; + const existingModel = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { ...cfg, agent: { ...cfg.agent, imageModel: { - ...((cfg.agent?.imageModel as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), fallbacks: [...existing, targetKey], }, models: nextModels, @@ -115,15 +118,18 @@ export async function modelsImageFallbacksRemoveCommand( throw new Error(`Image fallback not found: ${targetKey}`); } + const existingModel = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { ...cfg, agent: { ...cfg.agent, imageModel: { - ...((cfg.agent?.imageModel as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), fallbacks: filtered, }, }, @@ -137,19 +143,23 @@ export async function modelsImageFallbacksRemoveCommand( } export async function modelsImageFallbacksClearCommand(runtime: RuntimeEnv) { - await updateConfig((cfg) => ({ - ...cfg, - agent: { - ...cfg.agent, - imageModel: { - ...((cfg.agent?.imageModel as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), - fallbacks: [], + await updateConfig((cfg) => { + const existingModel = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; + return { + ...cfg, + agent: { + ...cfg.agent, + imageModel: { + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), + fallbacks: [], + }, }, - }, - })); + }; + }); runtime.log(`Updated ${CONFIG_PATH_CLAWDBOT}`); runtime.log("Image fallback list cleared."); diff --git a/src/commands/models/scan.ts b/src/commands/models/scan.ts index 416a220de..6a2a058e2 100644 --- a/src/commands/models/scan.ts +++ b/src/commands/models/scan.ts @@ -275,22 +275,28 @@ export async function modelsScanCommand( for (const entry of selectedImages) { if (!nextModels[entry]) nextModels[entry] = {}; } + const existingImageModel = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; const nextImageModel = selectedImages.length > 0 ? { - ...((cfg.agent?.imageModel as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingImageModel?.primary + ? { primary: existingImageModel.primary } + : undefined), fallbacks: selectedImages, ...(opts.setImage ? { primary: selectedImages[0] } : {}), } : cfg.agent?.imageModel; + const existingModel = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; const agent = { ...cfg.agent, model: { - ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? - {}), + ...(existingModel?.primary + ? { primary: existingModel.primary } + : undefined), fallbacks: selected, ...(opts.setDefault ? { primary: selected[0] } : {}), }, diff --git a/src/commands/models/set-image.ts b/src/commands/models/set-image.ts index 46214ee9a..ed7a3e0db 100644 --- a/src/commands/models/set-image.ts +++ b/src/commands/models/set-image.ts @@ -11,15 +11,17 @@ export async function modelsSetImageCommand( const key = `${resolved.provider}/${resolved.model}`; const nextModels = { ...cfg.agent?.models }; if (!nextModels[key]) nextModels[key] = {}; + const existingModel = cfg.agent?.imageModel as + | { primary?: string; fallbacks?: string[] } + | undefined; return { ...cfg, agent: { ...cfg.agent, imageModel: { - ...((cfg.agent?.imageModel as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.fallbacks + ? { fallbacks: existingModel.fallbacks } + : undefined), primary: key, }, models: nextModels, diff --git a/src/commands/models/set.ts b/src/commands/models/set.ts index d8546c484..0cfc9cdc3 100644 --- a/src/commands/models/set.ts +++ b/src/commands/models/set.ts @@ -8,15 +8,17 @@ export async function modelsSetCommand(modelRaw: string, runtime: RuntimeEnv) { const key = `${resolved.provider}/${resolved.model}`; const nextModels = { ...cfg.agent?.models }; if (!nextModels[key]) nextModels[key] = {}; + const existingModel = cfg.agent?.model as + | { primary?: string; fallbacks?: string[] } + | undefined; return { ...cfg, agent: { ...cfg.agent, model: { - ...((cfg.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(existingModel?.fallbacks + ? { fallbacks: existingModel.fallbacks } + : undefined), primary: key, }, models: nextModels, diff --git a/src/commands/onboard-auth.ts b/src/commands/onboard-auth.ts index 94a272958..3da496b34 100644 --- a/src/commands/onboard-auth.ts +++ b/src/commands/onboard-auth.ts @@ -94,8 +94,13 @@ export function applyMinimaxConfig(cfg: ClawdbotConfig): ClawdbotConfig { agent: { ...cfg.agent, model: { - ...((cfg.agent?.model as { primary?: string; fallbacks?: string[] }) ?? - {}), + ...(cfg.agent?.model && + "fallbacks" in (cfg.agent.model as Record) + ? { + fallbacks: (cfg.agent.model as { fallbacks?: string[] }) + .fallbacks, + } + : undefined), primary: "lmstudio/minimax-m2.1-gs32", }, models, diff --git a/src/config/legacy.ts b/src/config/legacy.ts index 10f9cfe13..1955955c3 100644 --- a/src/config/legacy.ts +++ b/src/config/legacy.ts @@ -244,7 +244,8 @@ const LEGACY_CONFIG_MIGRATIONS: LegacyConfigMigration[] = [ : {}; const ensureModel = (rawKey?: string) => { - const key = String(rawKey ?? "").trim(); + if (typeof rawKey !== "string") return; + const key = rawKey.trim(); if (!key) return; if (!models[key]) models[key] = {}; }; @@ -255,11 +256,13 @@ const LEGACY_CONFIG_MIGRATIONS: LegacyConfigMigration[] = [ for (const key of legacyModelFallbacks) ensureModel(key); for (const key of legacyImageModelFallbacks) ensureModel(key); for (const target of Object.values(legacyAliases)) { - ensureModel(String(target ?? "")); + if (typeof target !== "string") continue; + ensureModel(target); } for (const [alias, targetRaw] of Object.entries(legacyAliases)) { - const target = String(targetRaw ?? "").trim(); + if (typeof targetRaw !== "string") continue; + const target = targetRaw.trim(); if (!target) continue; const entry = models[target] && typeof models[target] === "object" diff --git a/src/discord/monitor.tool-result.test.ts b/src/discord/monitor.tool-result.test.ts index b9314b5a2..2d000c61d 100644 --- a/src/discord/monitor.tool-result.test.ts +++ b/src/discord/monitor.tool-result.test.ts @@ -49,7 +49,7 @@ vi.mock("discord.js", () => { } emit(event: string, ...args: unknown[]) { for (const handler of handlers.get(event) ?? []) { - void Promise.resolve(handler(...args)); + Promise.resolve(handler(...args)).catch(() => {}); } } login = vi.fn().mockResolvedValue(undefined); diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index b4f30e6a4..883d14614 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -337,10 +337,14 @@ export async function runOnboardingWizard( agent: { ...nextConfig.agent, model: { - ...((nextConfig.agent?.model as { - primary?: string; - fallbacks?: string[]; - }) ?? {}), + ...(nextConfig.agent?.model && + "fallbacks" in (nextConfig.agent.model as Record) + ? { + fallbacks: ( + nextConfig.agent.model as { fallbacks?: string[] } + ).fallbacks, + } + : undefined), primary: "google-antigravity/claude-opus-4-5-thinking", }, models: { From 216a23ed089690c028538b897bc5236f59fde843 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:10:32 +0000 Subject: [PATCH 042/110] fix: auto-migrate legacy config on CLI --- CHANGELOG.md | 1 + src/cli/program.ts | 27 ++++++++++++++++++++++++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b3c82b04..8a141ae8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. +- CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns). diff --git a/src/cli/program.ts b/src/cli/program.ts index 9732d7153..98bc51352 100644 --- a/src/cli/program.ts +++ b/src/cli/program.ts @@ -10,7 +10,12 @@ import { sessionsCommand } from "../commands/sessions.js"; import { setupCommand } from "../commands/setup.js"; import { statusCommand } from "../commands/status.js"; import { updateCommand } from "../commands/update.js"; -import { readConfigFileSnapshot } from "../config/config.js"; +import { + isNixMode, + migrateLegacyConfig, + readConfigFileSnapshot, + writeConfigFile, +} from "../config/config.js"; import { danger, setVerbose } from "../globals.js"; import { loginWeb, logoutWeb } from "../provider-web.js"; import { defaultRuntime } from "../runtime.js"; @@ -87,6 +92,26 @@ export function buildProgram() { if (actionCommand.name() === "doctor") return; const snapshot = await readConfigFileSnapshot(); if (snapshot.legacyIssues.length === 0) return; + if (isNixMode) { + defaultRuntime.error( + danger( + "Legacy config entries detected while running in Nix mode. Update your Nix config to the latest schema and retry.", + ), + ); + process.exit(1); + } + const migrated = migrateLegacyConfig(snapshot.parsed); + if (migrated.config) { + await writeConfigFile(migrated.config); + if (migrated.changes.length > 0) { + defaultRuntime.log( + `Migrated legacy config entries:\n${migrated.changes + .map((entry) => `- ${entry}`) + .join("\n")}`, + ); + } + return; + } const issues = snapshot.legacyIssues .map((issue) => `- ${issue.path}: ${issue.message}`) .join("\n"); From 085c70a87bd54186330bdb1e1755b4e1808dc1f2 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:21:45 +0000 Subject: [PATCH 043/110] fix: prefer env keys unless profiles configured --- src/agents/auth-profiles.test.ts | 41 ++++++++++++++++++++++++++++++++ src/agents/auth-profiles.ts | 13 ++++++---- src/agents/model-auth.test.ts | 14 ++++++++++- 3 files changed, 63 insertions(+), 5 deletions(-) diff --git a/src/agents/auth-profiles.test.ts b/src/agents/auth-profiles.test.ts index c9bb4ec25..286b52093 100644 --- a/src/agents/auth-profiles.test.ts +++ b/src/agents/auth-profiles.test.ts @@ -21,9 +21,26 @@ describe("resolveAuthProfileOrder", () => { }, }, }; + const cfg = { + auth: { + profiles: { + "anthropic:default": { provider: "anthropic", mode: "api_key" }, + "anthropic:work": { provider: "anthropic", mode: "api_key" }, + }, + }, + }; + + it("returns empty order without explicit config", () => { + const order = resolveAuthProfileOrder({ + store, + provider: "anthropic", + }); + expect(order).toEqual([]); + }); it("prioritizes preferred profiles", () => { const order = resolveAuthProfileOrder({ + cfg, store, provider: "anthropic", preferredProfile: "anthropic:work", @@ -34,9 +51,33 @@ describe("resolveAuthProfileOrder", () => { it("prioritizes last-good profile when no preferred override", () => { const order = resolveAuthProfileOrder({ + cfg, store: { ...store, lastGood: { anthropic: "anthropic:work" } }, provider: "anthropic", }); expect(order[0]).toBe("anthropic:work"); }); + + it("uses explicit profiles when order is missing", () => { + const order = resolveAuthProfileOrder({ + cfg, + store, + provider: "anthropic", + }); + expect(order).toEqual(["anthropic:default", "anthropic:work"]); + }); + + it("uses configured order when provided", () => { + const order = resolveAuthProfileOrder({ + cfg: { + auth: { + order: { anthropic: ["anthropic:work", "anthropic:default"] }, + profiles: cfg.auth.profiles, + }, + }, + store, + provider: "anthropic", + }); + expect(order).toEqual(["anthropic:work", "anthropic:default"]); + }); }); diff --git a/src/agents/auth-profiles.ts b/src/agents/auth-profiles.ts index df8b1b452..61346566d 100644 --- a/src/agents/auth-profiles.ts +++ b/src/agents/auth-profiles.ts @@ -251,12 +251,17 @@ export function resolveAuthProfileOrder(params: { preferredProfile?: string; }): string[] { const { cfg, store, provider, preferredProfile } = params; - const configuredOrder = cfg?.auth?.order?.[provider] ?? []; + const configuredOrder = cfg?.auth?.order?.[provider]; + const explicitProfiles = cfg?.auth?.profiles + ? Object.entries(cfg.auth.profiles) + .filter(([, profile]) => profile.provider === provider) + .map(([profileId]) => profileId) + : []; const lastGood = store.lastGood?.[provider]; const order = - configuredOrder.length > 0 - ? configuredOrder - : listProfilesForProvider(store, provider); + configuredOrder ?? + (explicitProfiles.length > 0 ? explicitProfiles : undefined); + if (!order) return []; const filtered = order.filter((profileId) => { const cred = store.profiles[profileId]; diff --git a/src/agents/model-auth.test.ts b/src/agents/model-auth.test.ts index b8a41e3f4..578eeec20 100644 --- a/src/agents/model-auth.test.ts +++ b/src/agents/model-auth.test.ts @@ -40,7 +40,19 @@ describe("getApiKeyForModel", () => { api: "openai-codex-responses", } as Model; - const apiKey = await getApiKeyForModel({ model }); + const apiKey = await getApiKeyForModel({ + model, + cfg: { + auth: { + profiles: { + "openai-codex:default": { + provider: "openai-codex", + mode: "oauth", + }, + }, + }, + }, + }); expect(apiKey.apiKey).toBe(oauthFixture.access); const authProfiles = await fs.readFile( From b56338171b0e3a8baa55c089eac94ddaf89a8096 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:06:06 +0100 Subject: [PATCH 044/110] feat: gate slash commands and add compact --- CHANGELOG.md | 5 +- README.md | 1 + docs/clawd.md | 1 + docs/faq.md | 5 +- docs/group-messages.md | 2 +- docs/session.md | 1 + docs/tui.md | 1 + src/agents/pi-embedded-runner.ts | 218 ++++++++++++++++++++++++++ src/agents/pi-embedded.ts | 2 + src/auto-reply/command-auth.ts | 65 ++++++++ src/auto-reply/command-detection.ts | 4 +- src/auto-reply/reply.triggers.test.ts | 100 +++++++++++- src/auto-reply/reply.ts | 28 +++- src/auto-reply/reply/commands.ts | 173 ++++++++++++++------ src/auto-reply/reply/session.ts | 10 +- src/auto-reply/status.ts | 9 +- 16 files changed, 566 insertions(+), 59 deletions(-) create mode 100644 src/auto-reply/command-auth.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a141ae8d..bf4bbaf24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ ### Breaking - Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only). - Model config schema changes (auth profiles + model lists); doctor auto-migrates and the gateway rewrites legacy configs on startup. +- Commands: gate all slash commands to authorized senders; add `/compact` to manually compact session context. ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. @@ -18,10 +19,10 @@ - macOS: local gateway now connects via tailnet IP when bind mode is `tailnet`/`auto`. - macOS: Connections settings now use a custom sidebar to avoid toolbar toggle issues, with rounded styling and full-width row hit targets. - macOS: drop deprecated `afterMs` from agent wait params to match gateway schema. -- Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth-profiles.json. +- Auth: add OpenAI Codex OAuth support and migrate legacy oauth.json into auth.json. - Model: `/model` list shows auth source (masked key or OAuth email) per provider. - Model: `/model list` is an alias for `/model`. -- Model: `/model` output now includes auth source location (env/auth-profiles.json/models.json). +- Model: `/model` output now includes auth source location (env/auth.json/models.json). - Model: avoid duplicate `missing (missing)` auth labels in `/model` list output. - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding. - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments. diff --git a/README.md b/README.md index e68a5be0f..d91c7d47b 100644 --- a/README.md +++ b/README.md @@ -209,6 +209,7 @@ Send these in WhatsApp/Telegram/Slack/WebChat (group commands are owner-only): - `/status` — health + session info (group shows activation mode) - `/new` or `/reset` — reset the session +- `/compact` — compact session context (summary) - `/think ` — off|minimal|low|medium|high - `/verbose on|off` - `/restart` — restart the gateway (owner-only in groups) diff --git a/docs/clawd.md b/docs/clawd.md index 21eb2c2af..044c89536 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -147,6 +147,7 @@ Example: - Session files: `~/.clawdbot/sessions/{{SessionId}}.jsonl` - Session metadata (token usage, last route, etc): `~/.clawdbot/sessions/sessions.json` (legacy: `~/.clawdbot/sessions.json`) - `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset. +- `/compact [instructions]` compacts the session context and reports the remaining context budget. ## Heartbeats (proactive mode) diff --git a/docs/faq.md b/docs/faq.md index d969916bc..ea12dcf30 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -302,7 +302,7 @@ Claude Opus has a 200k token context window, and Clawdbot uses **autocompaction* Practical tips: - Keep `AGENTS.md` focused, not bloated. -- Use `/new` to reset the session when context gets stale. +- Use `/compact` to shrink older context or `/new` to reset when it gets stale. - For large memory/notes collections, use search tools like `qmd` rather than loading everything. ### Where are my memory files? @@ -551,6 +551,9 @@ Quick reference (send these in chat): |---------|--------| | `/status` | Health + session info | | `/new` or `/reset` | Reset the session | +| `/compact` | Compact session context | + +Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces). | `/think ` | Set thinking level (off\|minimal\|low\|medium\|high) | | `/verbose on\|off` | Toggle verbose mode | | `/elevated on\|off` | Toggle elevated bash mode (approved senders only) | diff --git a/docs/group-messages.md b/docs/group-messages.md index 0c6701cd1..07be1e4f6 100644 --- a/docs/group-messages.md +++ b/docs/group-messages.md @@ -58,7 +58,7 @@ Only the owner number (from `whatsapp.allowFrom`, defaulting to the bot’s own 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. +4) Session-level directives (`/verbose on`, `/think:high`, `/new` or `/reset`, `/compact`) 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). diff --git a/docs/session.md b/docs/session.md index d038aab37..6cc7a3396 100644 --- a/docs/session.md +++ b/docs/session.md @@ -77,6 +77,7 @@ Runtime override (owner only): - `pnpm clawdbot sessions --json` — dumps every entry (filter with `--active `). - `pnpm clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access). - Send `/status` in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs). +- Send `/compact` (optional instructions) to summarize older context and free up window space. - JSONL transcripts can be opened directly to review full turns. ## Tips diff --git a/docs/tui.md b/docs/tui.md index 1585b75ec..de0479788 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -55,6 +55,7 @@ Use SSH tunneling or Tailscale to reach the Gateway WS. - `/activation ` - `/deliver ` - `/new` or `/reset` +- `/compact [instructions]` - `/abort` - `/settings` - `/exit` diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index 473f89175..d04314e71 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -98,6 +98,18 @@ export type EmbeddedPiRunResult = { meta: EmbeddedPiRunMeta; }; +export type EmbeddedPiCompactResult = { + ok: boolean; + compacted: boolean; + reason?: string; + result?: { + summary: string; + firstKeptEntryId: string; + tokensBefore: number; + details?: unknown; + }; +}; + type EmbeddedPiQueueHandle = { queueMessage: (text: string) => Promise; isStreaming: () => boolean; @@ -314,6 +326,212 @@ function resolvePromptSkills( .filter((skill): skill is Skill => Boolean(skill)); } +export async function compactEmbeddedPiSession(params: { + sessionId: string; + sessionKey?: string; + surface?: string; + sessionFile: string; + workspaceDir: string; + config?: ClawdbotConfig; + skillsSnapshot?: SkillSnapshot; + provider?: string; + model?: string; + thinkLevel?: ThinkLevel; + bashElevated?: BashElevatedDefaults; + customInstructions?: string; + lane?: string; + enqueue?: typeof enqueueCommand; + extraSystemPrompt?: string; + ownerNumbers?: string[]; +}): Promise { + const sessionLane = resolveSessionLane( + params.sessionKey?.trim() || params.sessionId, + ); + const globalLane = resolveGlobalLane(params.lane); + const enqueueGlobal = + params.enqueue ?? + ((task, opts) => enqueueCommandInLane(globalLane, task, opts)); + return enqueueCommandInLane(sessionLane, () => + enqueueGlobal(async () => { + const resolvedWorkspace = resolveUserPath(params.workspaceDir); + const prevCwd = process.cwd(); + + const provider = + (params.provider ?? DEFAULT_PROVIDER).trim() || DEFAULT_PROVIDER; + const modelId = (params.model ?? DEFAULT_MODEL).trim() || DEFAULT_MODEL; + await ensureClawdbotModelsJson(params.config); + const agentDir = resolveClawdbotAgentDir(); + const { model, error, authStorage, modelRegistry } = resolveModel( + provider, + modelId, + agentDir, + ); + if (!model) { + return { + ok: false, + compacted: false, + reason: error ?? `Unknown model: ${provider}/${modelId}`, + }; + } + try { + const apiKey = await getApiKeyForModel(model, authStorage); + authStorage.setRuntimeApiKey(model.provider, apiKey); + } catch (err) { + return { + ok: false, + compacted: false, + reason: describeUnknownError(err), + }; + } + + await fs.mkdir(resolvedWorkspace, { recursive: true }); + await ensureSessionHeader({ + sessionFile: params.sessionFile, + sessionId: params.sessionId, + cwd: resolvedWorkspace, + }); + + let restoreSkillEnv: (() => void) | undefined; + process.chdir(resolvedWorkspace); + try { + const shouldLoadSkillEntries = + !params.skillsSnapshot || !params.skillsSnapshot.resolvedSkills; + const skillEntries = shouldLoadSkillEntries + ? loadWorkspaceSkillEntries(resolvedWorkspace) + : []; + const skillsSnapshot = + params.skillsSnapshot ?? + buildWorkspaceSkillSnapshot(resolvedWorkspace, { + config: params.config, + entries: skillEntries, + }); + const sandboxSessionKey = params.sessionKey?.trim() || params.sessionId; + const sandbox = await resolveSandboxContext({ + config: params.config, + sessionKey: sandboxSessionKey, + workspaceDir: resolvedWorkspace, + }); + restoreSkillEnv = params.skillsSnapshot + ? applySkillEnvOverridesFromSnapshot({ + snapshot: params.skillsSnapshot, + config: params.config, + }) + : applySkillEnvOverrides({ + skills: skillEntries ?? [], + config: params.config, + }); + + const bootstrapFiles = + await loadWorkspaceBootstrapFiles(resolvedWorkspace); + const contextFiles = buildBootstrapContextFiles(bootstrapFiles); + const promptSkills = resolvePromptSkills(skillsSnapshot, skillEntries); + const tools = createClawdbotCodingTools({ + bash: { + ...params.config?.agent?.bash, + elevated: params.bashElevated, + }, + sandbox, + surface: params.surface, + sessionKey: params.sessionKey ?? params.sessionId, + config: params.config, + }); + const machineName = await getMachineDisplayName(); + const runtimeInfo = { + host: machineName, + os: `${os.type()} ${os.release()}`, + arch: os.arch(), + node: process.version, + model: `${provider}/${modelId}`, + }; + const sandboxInfo = buildEmbeddedSandboxInfo(sandbox); + const reasoningTagHint = provider === "ollama"; + const userTimezone = resolveUserTimezone( + params.config?.agent?.userTimezone, + ); + const userTime = formatUserTime(new Date(), userTimezone); + const systemPrompt = buildSystemPrompt({ + appendPrompt: buildAgentSystemPromptAppend({ + workspaceDir: resolvedWorkspace, + defaultThinkLevel: params.thinkLevel, + extraSystemPrompt: params.extraSystemPrompt, + ownerNumbers: params.ownerNumbers, + reasoningTagHint, + runtimeInfo, + sandboxInfo, + toolNames: tools.map((tool) => tool.name), + userTimezone, + userTime, + }), + contextFiles, + skills: promptSkills, + cwd: resolvedWorkspace, + tools, + }); + + const sessionManager = SessionManager.open(params.sessionFile); + const settingsManager = SettingsManager.create( + resolvedWorkspace, + agentDir, + ); + + const builtInToolNames = new Set(["read", "bash", "edit", "write"]); + const builtInTools = tools.filter((t) => builtInToolNames.has(t.name)); + const customTools = toToolDefinitions( + tools.filter((t) => !builtInToolNames.has(t.name)), + ); + + const { session } = await createAgentSession({ + cwd: resolvedWorkspace, + agentDir, + authStorage, + modelRegistry, + model, + thinkingLevel: mapThinkingLevel(params.thinkLevel), + systemPrompt, + tools: builtInTools, + customTools, + sessionManager, + settingsManager, + skills: promptSkills, + contextFiles, + }); + + try { + const prior = await sanitizeSessionMessagesImages( + session.messages, + "session:history", + ); + if (prior.length > 0) { + session.agent.replaceMessages(prior); + } + const result = await session.compact(params.customInstructions); + return { + ok: true, + compacted: true, + result: { + summary: result.summary, + firstKeptEntryId: result.firstKeptEntryId, + tokensBefore: result.tokensBefore, + details: result.details, + }, + }; + } finally { + session.dispose(); + } + } catch (err) { + return { + ok: false, + compacted: false, + reason: describeUnknownError(err), + }; + } finally { + restoreSkillEnv?.(); + process.chdir(prevCwd); + } + }), + ); +} + export async function runEmbeddedPiAgent(params: { sessionId: string; sessionKey?: string; diff --git a/src/agents/pi-embedded.ts b/src/agents/pi-embedded.ts index 022a4898f..81e99feec 100644 --- a/src/agents/pi-embedded.ts +++ b/src/agents/pi-embedded.ts @@ -1,10 +1,12 @@ export type { EmbeddedPiAgentMeta, + EmbeddedPiCompactResult, EmbeddedPiRunMeta, EmbeddedPiRunResult, } from "./pi-embedded-runner.js"; export { abortEmbeddedPiRun, + compactEmbeddedPiSession, isEmbeddedPiRunActive, isEmbeddedPiRunStreaming, queueEmbeddedPiMessage, diff --git a/src/auto-reply/command-auth.ts b/src/auto-reply/command-auth.ts new file mode 100644 index 000000000..d48141802 --- /dev/null +++ b/src/auto-reply/command-auth.ts @@ -0,0 +1,65 @@ +import type { ClawdbotConfig } from "../config/config.js"; +import { normalizeE164 } from "../utils.js"; +import type { MsgContext } from "./templating.js"; + +export type CommandAuthorization = { + isWhatsAppSurface: boolean; + ownerList: string[]; + senderE164?: string; + isAuthorizedSender: boolean; + from?: string; + to?: string; +}; + +export function resolveCommandAuthorization(params: { + ctx: MsgContext; + cfg: ClawdbotConfig; + commandAuthorized: boolean; +}): CommandAuthorization { + const { ctx, cfg, commandAuthorized } = params; + const surface = (ctx.Surface ?? "").trim().toLowerCase(); + const isWhatsAppSurface = + surface === "whatsapp" || + (ctx.From ?? "").startsWith("whatsapp:") || + (ctx.To ?? "").startsWith("whatsapp:"); + + const configuredAllowFrom = isWhatsAppSurface + ? cfg.whatsapp?.allowFrom + : undefined; + const from = (ctx.From ?? "").replace(/^whatsapp:/, ""); + const to = (ctx.To ?? "").replace(/^whatsapp:/, ""); + const allowFromList = + configuredAllowFrom?.filter((entry) => entry?.trim()) ?? []; + const allowAll = + !isWhatsAppSurface || + allowFromList.length === 0 || + allowFromList.some((entry) => entry.trim() === "*"); + + const senderE164 = normalizeE164(ctx.SenderE164 ?? ""); + const ownerCandidates = + isWhatsAppSurface && !allowAll + ? allowFromList.filter((entry) => entry !== "*") + : []; + if (isWhatsAppSurface && !allowAll && ownerCandidates.length === 0 && to) { + ownerCandidates.push(to); + } + const ownerList = ownerCandidates + .map((entry) => normalizeE164(entry)) + .filter((entry): entry is string => Boolean(entry)); + + const isOwner = + !isWhatsAppSurface || + allowAll || + ownerList.length === 0 || + (senderE164 ? ownerList.includes(senderE164) : false); + const isAuthorizedSender = commandAuthorized && isOwner; + + return { + isWhatsAppSurface, + ownerList, + senderE164: senderE164 || undefined, + isAuthorizedSender, + from: from || undefined, + to: to || undefined, + }; +} diff --git a/src/auto-reply/command-detection.ts b/src/auto-reply/command-detection.ts index 1148732af..1782f66f9 100644 --- a/src/auto-reply/command-detection.ts +++ b/src/auto-reply/command-detection.ts @@ -1,5 +1,5 @@ const CONTROL_COMMAND_RE = - /(?:^|\s)\/(?:status|help|thinking|think|t|verbose|v|elevated|elev|model|queue|activation|send|restart|reset|new)(?=$|\s|:)\b/i; + /(?:^|\s)\/(?:status|help|thinking|think|t|verbose|v|elevated|elev|model|queue|activation|send|restart|reset|new|compact)(?=$|\s|:)\b/i; const CONTROL_COMMAND_EXACT = new Set([ "help", @@ -16,6 +16,8 @@ const CONTROL_COMMAND_EXACT = new Set([ "/reset", "new", "/new", + "compact", + "/compact", ]); export function hasControlCommand(text?: string): boolean { diff --git a/src/auto-reply/reply.triggers.test.ts b/src/auto-reply/reply.triggers.test.ts index 19d6f0ff7..24c53f662 100644 --- a/src/auto-reply/reply.triggers.test.ts +++ b/src/auto-reply/reply.triggers.test.ts @@ -5,6 +5,7 @@ import { afterEach, describe, expect, it, vi } from "vitest"; vi.mock("../agents/pi-embedded.js", () => ({ abortEmbeddedPiRun: vi.fn().mockReturnValue(false), + compactEmbeddedPiSession: vi.fn(), runEmbeddedPiAgent: vi.fn(), queueEmbeddedPiMessage: vi.fn().mockReturnValue(false), resolveEmbeddedSessionLane: (key: string) => @@ -13,7 +14,10 @@ vi.mock("../agents/pi-embedded.js", () => ({ isEmbeddedPiRunStreaming: vi.fn().mockReturnValue(false), })); -import { runEmbeddedPiAgent } from "../agents/pi-embedded.js"; +import { + compactEmbeddedPiSession, + runEmbeddedPiAgent, +} from "../agents/pi-embedded.js"; import { ensureSandboxWorkspaceForSession } from "../agents/sandbox.js"; import { resolveSessionKey } from "../config/sessions.js"; import { getReplyFromConfig } from "./reply.js"; @@ -670,6 +674,100 @@ describe("trigger handling", () => { }); }); + it("does not reset for unauthorized /reset", async () => { + await withTempHome(async (home) => { + const res = await getReplyFromConfig( + { + Body: "/reset", + From: "+1003", + To: "+2000", + CommandAuthorized: false, + }, + {}, + { + agent: { + model: "anthropic/claude-opus-4-5", + workspace: join(home, "clawd"), + }, + whatsapp: { + allowFrom: ["+1999"], + }, + session: { + store: join(tmpdir(), `clawdbot-session-test-${Date.now()}.json`), + }, + }, + ); + expect(res).toBeUndefined(); + expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + }); + }); + + it("blocks /reset for non-owner senders", async () => { + await withTempHome(async (home) => { + const res = await getReplyFromConfig( + { + Body: "/reset", + From: "+1003", + To: "+2000", + }, + {}, + { + agent: { + model: "anthropic/claude-opus-4-5", + workspace: join(home, "clawd"), + }, + whatsapp: { + allowFrom: ["+1999"], + }, + session: { + store: join(tmpdir(), `clawdbot-session-test-${Date.now()}.json`), + }, + }, + ); + expect(res).toBeUndefined(); + expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + }); + }); + + it("runs /compact as a gated command", async () => { + await withTempHome(async (home) => { + vi.mocked(compactEmbeddedPiSession).mockResolvedValue({ + ok: true, + compacted: true, + result: { + summary: "summary", + firstKeptEntryId: "x", + tokensBefore: 12000, + }, + }); + + const res = await getReplyFromConfig( + { + Body: "/compact focus on decisions", + From: "+1003", + To: "+2000", + }, + {}, + { + agent: { + model: "anthropic/claude-opus-4-5", + workspace: join(home, "clawd"), + }, + whatsapp: { + allowFrom: ["*"], + }, + session: { + store: join(tmpdir(), `clawdbot-session-test-${Date.now()}.json`), + }, + }, + ); + const text = Array.isArray(res) ? res[0]?.text : res?.text; + expect(text?.startsWith("⚙️ Compacted")).toBe(true); + expect(compactEmbeddedPiSession).toHaveBeenCalledOnce(); + expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + }); + }); + it("ignores think directives that only appear in the context wrapper", async () => { await withTempHome(async (home) => { vi.mocked(runEmbeddedPiAgent).mockResolvedValue({ diff --git a/src/auto-reply/reply.ts b/src/auto-reply/reply.ts index 26144ef64..085563d6c 100644 --- a/src/auto-reply/reply.ts +++ b/src/auto-reply/reply.ts @@ -24,6 +24,7 @@ import { resolveSessionTranscriptPath } from "../config/sessions.js"; import { logVerbose } from "../globals.js"; import { clearCommandLane, getQueueSize } from "../process/command-queue.js"; import { defaultRuntime } from "../runtime.js"; +import { resolveCommandAuthorization } from "./command-auth.js"; import { hasControlCommand } from "./command-detection.js"; import { getAbortMemory } from "./reply/abort.js"; import { runReplyAgent } from "./reply/agent-runner.js"; @@ -42,6 +43,7 @@ import { defaultGroupActivation, resolveGroupRequireMention, } from "./reply/groups.js"; +import { stripMentions } from "./reply/mentions.js"; import { createModelSelectionState, resolveContextTokens, @@ -76,6 +78,9 @@ export type { GetReplyOptions, ReplyPayload } from "./types.js"; const BARE_SESSION_RESET_PROMPT = "A new session was started via /new or /reset. Say hi briefly (1-2 sentences) and ask what the user wants to do next. Do not mention internal steps, files, tools, or reasoning."; +const CONTROL_COMMAND_PREFIX_RE = + /^\/(?:status|help|thinking|think|t|verbose|v|elevated|elev|model|queue|activation|send|restart|reset|new|compact)\b/i; + function normalizeAllowToken(value?: string) { if (!value) return ""; return value.trim().toLowerCase(); @@ -240,7 +245,17 @@ export async function getReplyFromConfig( } } - const sessionState = await initSessionState({ ctx, cfg }); + const commandAuthorized = ctx.CommandAuthorized ?? true; + const commandAuth = resolveCommandAuthorization({ + ctx, + cfg, + commandAuthorized, + }); + const sessionState = await initSessionState({ + ctx, + cfg, + commandAuthorized, + }); let { sessionCtx, sessionEntry, @@ -258,7 +273,6 @@ export async function getReplyFromConfig( } = sessionState; const rawBody = sessionCtx.BodyStripped ?? sessionCtx.Body ?? ""; - const commandAuthorized = ctx.CommandAuthorized ?? true; const parsedDirectives = parseInlineDirectives(rawBody); const directives = commandAuthorized ? parsedDirectives @@ -516,6 +530,16 @@ export async function getReplyFromConfig( const baseBody = sessionCtx.BodyStripped ?? sessionCtx.Body ?? ""; const rawBodyTrimmed = (ctx.Body ?? "").trim(); const baseBodyTrimmedRaw = baseBody.trim(); + const strippedCommandBody = isGroup + ? stripMentions(triggerBodyNormalized, ctx, cfg) + : triggerBodyNormalized; + if ( + !commandAuth.isAuthorizedSender && + CONTROL_COMMAND_PREFIX_RE.test(strippedCommandBody.trim()) + ) { + typing.cleanup(); + return undefined; + } if (!commandAuthorized && !baseBodyTrimmedRaw && hasControlCommand(rawBody)) { typing.cleanup(); return undefined; diff --git a/src/auto-reply/reply/commands.ts b/src/auto-reply/reply/commands.ts index ad2778b42..dcfe6d769 100644 --- a/src/auto-reply/reply/commands.ts +++ b/src/auto-reply/reply/commands.ts @@ -6,30 +6,44 @@ import { getCustomProviderApiKey, resolveEnvApiKey, } from "../../agents/model-auth.js"; +import { + abortEmbeddedPiRun, + compactEmbeddedPiSession, + isEmbeddedPiRunActive, + waitForEmbeddedPiRunEnd, +} from "../../agents/pi-embedded.js"; import type { ClawdbotConfig } from "../../config/config.js"; import { + resolveSessionTranscriptPath, type SessionEntry, type SessionScope, saveSessionStore, } from "../../config/sessions.js"; import { logVerbose } from "../../globals.js"; import { triggerClawdbotRestart } from "../../infra/restart.js"; +import { enqueueSystemEvent } from "../../infra/system-events.js"; import { resolveSendPolicy } from "../../sessions/send-policy.js"; import { normalizeE164 } from "../../utils.js"; import { resolveHeartbeatSeconds } from "../../web/reconnect.js"; import { getWebAuthAgeMs, webAuthExists } from "../../web/session.js"; +import { resolveCommandAuthorization } from "../command-auth.js"; import { normalizeGroupActivation, parseActivationCommand, } from "../group-activation.js"; import { parseSendPolicyCommand } from "../send-policy.js"; -import { buildHelpMessage, buildStatusMessage } from "../status.js"; +import { + buildHelpMessage, + buildStatusMessage, + formatContextUsageShort, + formatTokenCount, +} from "../status.js"; import type { MsgContext } from "../templating.js"; import type { ElevatedLevel, ThinkLevel, VerboseLevel } from "../thinking.js"; import type { ReplyPayload } from "../types.js"; import { isAbortTrigger, setAbortMemory } from "./abort.js"; import type { InlineDirectives } from "./directive-handling.js"; -import { stripMentions } from "./mentions.js"; +import { stripMentions, stripStructuralPrefixes } from "./mentions.js"; export type CommandContext = { surface: string; @@ -74,6 +88,30 @@ function resolveModelAuthLabel( return "unknown"; } +function extractCompactInstructions(params: { + rawBody?: string; + ctx: MsgContext; + cfg: ClawdbotConfig; + isGroup: boolean; +}): string | undefined { + const raw = stripStructuralPrefixes(params.rawBody ?? ""); + const stripped = params.isGroup + ? stripMentions(raw, params.ctx, params.cfg) + : raw; + const trimmed = stripped.trim(); + if (!trimmed) return undefined; + const lowered = trimmed.toLowerCase(); + const prefix = lowered.startsWith("/compact") + ? "/compact" + : lowered.startsWith("compact") + ? "compact" + : null; + if (!prefix) return undefined; + let rest = trimmed.slice(prefix.length).trimStart(); + if (rest.startsWith(":")) rest = rest.slice(1).trimStart(); + return rest.length ? rest : undefined; +} + export function buildCommandContext(params: { ctx: MsgContext; cfg: ClawdbotConfig; @@ -82,66 +120,31 @@ export function buildCommandContext(params: { triggerBodyNormalized: string; commandAuthorized: boolean; }): CommandContext { - const { + const { ctx, cfg, sessionKey, isGroup, triggerBodyNormalized } = params; + const auth = resolveCommandAuthorization({ ctx, cfg, - sessionKey, - isGroup, - triggerBodyNormalized, - commandAuthorized, - } = params; + commandAuthorized: params.commandAuthorized, + }); const surface = (ctx.Surface ?? "").trim().toLowerCase(); - const isWhatsAppSurface = - surface === "whatsapp" || - (ctx.From ?? "").startsWith("whatsapp:") || - (ctx.To ?? "").startsWith("whatsapp:"); - - const configuredAllowFrom = isWhatsAppSurface - ? cfg.whatsapp?.allowFrom - : undefined; - const from = (ctx.From ?? "").replace(/^whatsapp:/, ""); - const to = (ctx.To ?? "").replace(/^whatsapp:/, ""); - const allowFromList = - configuredAllowFrom?.filter((entry) => entry?.trim()) ?? []; - const allowAll = - !isWhatsAppSurface || - allowFromList.length === 0 || - allowFromList.some((entry) => entry.trim() === "*"); - - const abortKey = sessionKey ?? (from || undefined) ?? (to || undefined); + const abortKey = + sessionKey ?? (auth.from || undefined) ?? (auth.to || undefined); const rawBodyNormalized = triggerBodyNormalized; const commandBodyNormalized = isGroup ? stripMentions(rawBodyNormalized, ctx, cfg) : rawBodyNormalized; - const senderE164 = normalizeE164(ctx.SenderE164 ?? ""); - const ownerCandidates = - isWhatsAppSurface && !allowAll - ? allowFromList.filter((entry) => entry !== "*") - : []; - if (isWhatsAppSurface && !allowAll && ownerCandidates.length === 0 && to) { - ownerCandidates.push(to); - } - const ownerList = ownerCandidates - .map((entry) => normalizeE164(entry)) - .filter((entry): entry is string => Boolean(entry)); - const isOwner = - !isWhatsAppSurface || - allowAll || - ownerList.length === 0 || - (senderE164 ? ownerList.includes(senderE164) : false); - const isAuthorizedSender = commandAuthorized && isOwner; return { surface, - isWhatsAppSurface, - ownerList, - isAuthorizedSender, - senderE164: senderE164 || undefined, + isWhatsAppSurface: auth.isWhatsAppSurface, + ownerList: auth.ownerList, + isAuthorizedSender: auth.isAuthorizedSender, + senderE164: auth.senderE164, abortKey, rawBodyNormalized, commandBodyNormalized, - from: from || undefined, - to: to || undefined, + from: auth.from, + to: auth.to, }; } @@ -364,6 +367,78 @@ export async function handleCommands(params: { return { shouldContinue: false, reply: { text: statusText } }; } + const compactRequested = + command.commandBodyNormalized === "/compact" || + command.commandBodyNormalized === "compact" || + command.commandBodyNormalized.startsWith("/compact ") || + command.commandBodyNormalized.startsWith("compact "); + if (compactRequested) { + if (!command.isAuthorizedSender) { + logVerbose( + `Ignoring /compact from unauthorized sender: ${command.senderE164 || ""}`, + ); + return { shouldContinue: false }; + } + if (!sessionEntry?.sessionId) { + return { + shouldContinue: false, + reply: { text: "⚙️ Compaction unavailable (missing session id)." }, + }; + } + const sessionId = sessionEntry.sessionId; + if (isEmbeddedPiRunActive(sessionId)) { + abortEmbeddedPiRun(sessionId); + await waitForEmbeddedPiRunEnd(sessionId, 15_000); + } + const customInstructions = extractCompactInstructions({ + rawBody: ctx.Body, + ctx, + cfg, + isGroup, + }); + const result = await compactEmbeddedPiSession({ + sessionId, + sessionKey, + surface: command.surface, + sessionFile: resolveSessionTranscriptPath(sessionId), + workspaceDir, + config: cfg, + skillsSnapshot: sessionEntry.skillsSnapshot, + provider, + model, + thinkLevel: resolvedThinkLevel ?? (await resolveDefaultThinkingLevel()), + bashElevated: { + enabled: false, + allowed: false, + defaultLevel: "off", + }, + customInstructions, + ownerNumbers: + command.ownerList.length > 0 ? command.ownerList : undefined, + }); + + const totalTokens = + sessionEntry.totalTokens ?? + (sessionEntry.inputTokens ?? 0) + (sessionEntry.outputTokens ?? 0); + const contextSummary = formatContextUsageShort( + totalTokens > 0 ? totalTokens : null, + contextTokens ?? sessionEntry.contextTokens ?? null, + ); + const compactLabel = result.ok + ? result.compacted + ? result.result?.tokensBefore + ? `Compacted (${formatTokenCount(result.result.tokensBefore)} before)` + : "Compacted" + : "Compaction skipped" + : "Compaction failed"; + const reason = result.reason?.trim(); + const line = reason + ? `${compactLabel}: ${reason} • ${contextSummary}` + : `${compactLabel} • ${contextSummary}`; + enqueueSystemEvent(line); + return { shouldContinue: false, reply: { text: `⚙️ ${line}` } }; + } + const abortRequested = isAbortTrigger(command.rawBodyNormalized); if (abortRequested) { if (sessionEntry && sessionStore && sessionKey) { diff --git a/src/auto-reply/reply/session.ts b/src/auto-reply/reply/session.ts index eeb2edc2f..a6d4f0357 100644 --- a/src/auto-reply/reply/session.ts +++ b/src/auto-reply/reply/session.ts @@ -14,6 +14,7 @@ import { type SessionScope, saveSessionStore, } from "../../config/sessions.js"; +import { resolveCommandAuthorization } from "../command-auth.js"; import type { MsgContext, TemplateContext } from "../templating.js"; import { stripMentions, stripStructuralPrefixes } from "./mentions.js"; @@ -37,8 +38,9 @@ export type SessionInitResult = { export async function initSessionState(params: { ctx: MsgContext; cfg: ClawdbotConfig; + commandAuthorized: boolean; }): Promise { - const { ctx, cfg } = params; + const { ctx, cfg, commandAuthorized } = params; const sessionCfg = cfg.session; const mainKey = sessionCfg?.mainKey ?? "main"; const resetTriggers = sessionCfg?.resetTriggers?.length @@ -76,6 +78,11 @@ export async function initSessionState(params: { const rawBody = ctx.Body ?? ""; const trimmedBody = rawBody.trim(); + const resetAuthorized = resolveCommandAuthorization({ + ctx, + cfg, + commandAuthorized, + }).isAuthorizedSender; // Timestamp/message prefixes (e.g. "[Dec 4 17:35] ") are added by the // web inbox before we get here. They prevented reset triggers like "/new" // from matching, so strip structural wrappers when checking for resets. @@ -84,6 +91,7 @@ export async function initSessionState(params: { : triggerBodyNormalized; for (const trigger of resetTriggers) { if (!trigger) continue; + if (!resetAuthorized) break; if (trimmedBody === trigger || strippedForReset === trigger) { isNewSession = true; bodyStripped = ""; diff --git a/src/auto-reply/status.ts b/src/auto-reply/status.ts index 281f25824..9c4e2ca01 100644 --- a/src/auto-reply/status.ts +++ b/src/auto-reply/status.ts @@ -56,6 +56,8 @@ const formatAge = (ms?: number | null) => { const formatKTokens = (value: number) => `${(value / 1000).toFixed(value >= 10_000 ? 0 : 1)}k`; +export const formatTokenCount = (value: number) => formatKTokens(value); + const formatTokens = ( total: number | null | undefined, contextTokens: number | null, @@ -71,6 +73,11 @@ const formatTokens = ( return `${totalLabel}/${ctxLabel}${pct !== null ? ` (${pct}%)` : ""}`; }; +export const formatContextUsageShort = ( + total: number | null | undefined, + contextTokens: number | null | undefined, +) => `Context ${formatTokens(total, contextTokens ?? null)}`; + const readUsageFromSessionLog = ( sessionId?: string, ): @@ -262,7 +269,7 @@ export function buildStatusMessage(args: StatusArgs): string { export function buildHelpMessage(): string { return [ "ℹ️ Help", - "Shortcuts: /new reset | /restart relink", + "Shortcuts: /new reset | /compact [instructions] | /restart relink", "Options: /think | /verbose on|off | /elevated on|off | /model ", ].join("\n"); } From b85248bd072721b5d3ed77a8eb1b51106044e8b5 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:22:20 +0100 Subject: [PATCH 045/110] fix: patch qrcode-terminal import for Node 22 --- docs/docker.md | 6 ++++++ docs/test.md | 8 ++++++++ package.json | 4 +++- patches/qrcode-terminal.patch | 12 ++++++++++++ pnpm-lock.yaml | 7 +++++-- scripts/e2e/Dockerfile.qr-import | 9 +++++++++ scripts/e2e/qr-import-docker.sh | 11 +++++++++++ 7 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 patches/qrcode-terminal.patch create mode 100644 scripts/e2e/Dockerfile.qr-import create mode 100755 scripts/e2e/qr-import-docker.sh diff --git a/docs/docker.md b/docs/docker.md index 4d553536e..c587233c6 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -59,6 +59,12 @@ docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBO scripts/e2e/onboard-docker.sh ``` +### QR import smoke test (Docker) + +```bash +pnpm test:docker:qr +``` + ### Notes - Gateway bind defaults to `lan` for container use. diff --git a/docs/test.md b/docs/test.md index cb0bcbe19..b31a57fbb 100644 --- a/docs/test.md +++ b/docs/test.md @@ -33,3 +33,11 @@ scripts/e2e/onboard-docker.sh ``` This script drives the interactive wizard via a pseudo-tty, verifies config/workspace/session files, then starts the gateway and runs `clawdbot health`. + +## QR import smoke (Docker) + +Ensures `qrcode-terminal` loads under Node 22+ in Docker: + +```bash +pnpm test:docker:qr +``` diff --git a/package.json b/package.json index 23e044de8..5ddc0c3a7 100644 --- a/package.json +++ b/package.json @@ -67,6 +67,7 @@ "test:force": "tsx scripts/test-force.ts", "test:coverage": "vitest run --coverage", "test:e2e": "vitest run --config vitest.e2e.config.ts", + "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh", "protocol:gen": "tsx scripts/protocol-gen.ts", "protocol:gen:swift": "tsx scripts/protocol-gen-swift.ts", "protocol:check": "pnpm protocol:gen && pnpm protocol:gen:swift && git diff --exit-code -- dist/protocol.schema.json apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift", @@ -148,7 +149,8 @@ "@sinclair/typebox": "0.34.46" }, "patchedDependencies": { - "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch" + "@mariozechner/pi-ai": "patches/@mariozechner__pi-ai.patch", + "qrcode-terminal": "patches/qrcode-terminal.patch" } }, "vitest": { diff --git a/patches/qrcode-terminal.patch b/patches/qrcode-terminal.patch new file mode 100644 index 000000000..96929c20b --- /dev/null +++ b/patches/qrcode-terminal.patch @@ -0,0 +1,12 @@ +diff --git a/lib/main.js b/lib/main.js +index 488cc1aea9802b3d6ae13aee27556403bec55d1c..3de1f934868d81e8204f00e6a4bf2696a05f7340 100644 +--- a/lib/main.js ++++ b/lib/main.js +@@ -1,5 +1,5 @@ +-var QRCode = require('./../vendor/QRCode'), +- QRErrorCorrectLevel = require('./../vendor/QRCode/QRErrorCorrectLevel'), ++var QRCode = require('./../vendor/QRCode/index.js'), ++ QRErrorCorrectLevel = require('./../vendor/QRCode/QRErrorCorrectLevel.js'), + black = "\033[40m \033[0m", + white = "\033[47m \033[0m", + toCell = function (isBlack) { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 11815c700..ce9e10913 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,9 @@ patchedDependencies: '@mariozechner/pi-ai': hash: 628fb051b6f4886984a846a5ee7aa0a571c3360d35b8d114e4684e5edcd100c5 path: patches/@mariozechner__pi-ai.patch + qrcode-terminal: + hash: ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12 + path: patches/qrcode-terminal.patch importers: @@ -102,7 +105,7 @@ importers: version: 1.57.0 qrcode-terminal: specifier: ^0.12.0 - version: 0.12.0 + version: 0.12.0(patch_hash=ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12) sharp: specifier: ^0.34.5 version: 0.34.5 @@ -5460,7 +5463,7 @@ snapshots: '@thi.ng/bitstream': 2.4.37 optional: true - qrcode-terminal@0.12.0: {} + qrcode-terminal@0.12.0(patch_hash=ed82029850dbdf551f5df1de320945af52b8ea8500cc7bd4f39258e7a3d92e12): {} qs@6.14.1: dependencies: diff --git a/scripts/e2e/Dockerfile.qr-import b/scripts/e2e/Dockerfile.qr-import new file mode 100644 index 000000000..c2370044d --- /dev/null +++ b/scripts/e2e/Dockerfile.qr-import @@ -0,0 +1,9 @@ +FROM node:22-bookworm + +RUN corepack enable + +WORKDIR /app + +COPY . . + +RUN pnpm install --frozen-lockfile diff --git a/scripts/e2e/qr-import-docker.sh b/scripts/e2e/qr-import-docker.sh new file mode 100755 index 000000000..036a996a1 --- /dev/null +++ b/scripts/e2e/qr-import-docker.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +IMAGE_NAME="${CLAWDBOT_QR_SMOKE_IMAGE:-clawdbot-qr-smoke}" + +echo "Building Docker image..." +docker build -t "$IMAGE_NAME" -f "$ROOT_DIR/scripts/e2e/Dockerfile.qr-import" "$ROOT_DIR" + +echo "Running qrcode-terminal import smoke..." +docker run --rm -t "$IMAGE_NAME" node -e "import('qrcode-terminal').then((m)=>m.default.generate('qr-smoke',{small:true}))" From b6ae3760762a26db704a9f1e73ba05b585d51a88 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:23:50 +0100 Subject: [PATCH 046/110] fix: gate reset auth and infer whatsapp sender --- CHANGELOG.md | 1 + src/auto-reply/command-auth.ts | 19 ++++++++++++++----- src/auto-reply/reply/commands.ts | 13 +++++++++++++ 3 files changed, 28 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf4bbaf24..e0b04b119 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,7 @@ - Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235. - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242. +- Auto-reply: block unauthorized `/reset` and infer WhatsApp senders from E.164 inputs. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/src/auto-reply/command-auth.ts b/src/auto-reply/command-auth.ts index d48141802..7599c7390 100644 --- a/src/auto-reply/command-auth.ts +++ b/src/auto-reply/command-auth.ts @@ -18,16 +18,23 @@ export function resolveCommandAuthorization(params: { }): CommandAuthorization { const { ctx, cfg, commandAuthorized } = params; const surface = (ctx.Surface ?? "").trim().toLowerCase(); - const isWhatsAppSurface = - surface === "whatsapp" || + const from = (ctx.From ?? "").replace(/^whatsapp:/, ""); + const to = (ctx.To ?? "").replace(/^whatsapp:/, ""); + const hasWhatsappPrefix = (ctx.From ?? "").startsWith("whatsapp:") || (ctx.To ?? "").startsWith("whatsapp:"); + const looksLikeE164 = (value: string) => + Boolean(value && /^\+?\d{3,}$/.test(value.replace(/[^\d+]/g, ""))); + const inferWhatsApp = + !surface && + Boolean(cfg.whatsapp?.allowFrom?.length) && + (looksLikeE164(from) || looksLikeE164(to)); + const isWhatsAppSurface = + surface === "whatsapp" || hasWhatsappPrefix || inferWhatsApp; const configuredAllowFrom = isWhatsAppSurface ? cfg.whatsapp?.allowFrom : undefined; - const from = (ctx.From ?? "").replace(/^whatsapp:/, ""); - const to = (ctx.To ?? "").replace(/^whatsapp:/, ""); const allowFromList = configuredAllowFrom?.filter((entry) => entry?.trim()) ?? []; const allowAll = @@ -35,7 +42,9 @@ export function resolveCommandAuthorization(params: { allowFromList.length === 0 || allowFromList.some((entry) => entry.trim() === "*"); - const senderE164 = normalizeE164(ctx.SenderE164 ?? ""); + const senderE164 = normalizeE164( + ctx.SenderE164 ?? (isWhatsAppSurface ? from : ""), + ); const ownerCandidates = isWhatsAppSurface && !allowAll ? allowFromList.filter((entry) => entry !== "*") diff --git a/src/auto-reply/reply/commands.ts b/src/auto-reply/reply/commands.ts index dcfe6d769..21b65a91c 100644 --- a/src/auto-reply/reply/commands.ts +++ b/src/auto-reply/reply/commands.ts @@ -173,6 +173,7 @@ export async function handleCommands(params: { shouldContinue: boolean; }> { const { + ctx, cfg, command, directives, @@ -193,6 +194,18 @@ export async function handleCommands(params: { isGroup, } = params; + const resetRequested = + command.commandBodyNormalized === "/reset" || + command.commandBodyNormalized === "reset" || + command.commandBodyNormalized === "/new" || + command.commandBodyNormalized === "new"; + if (resetRequested && !command.isAuthorizedSender) { + logVerbose( + `Ignoring /reset from unauthorized sender: ${command.senderE164 || ""}`, + ); + return { shouldContinue: false }; + } + const activationCommand = parseActivationCommand( command.commandBodyNormalized, ); From 162f8e9bb79cde6cb829f4555d8e78ab4004fb74 Mon Sep 17 00:00:00 2001 From: Echo Date: Mon, 5 Jan 2026 19:37:05 -0600 Subject: [PATCH 047/110] fix(discord): convert readMessages timestamps to local time (#240) Co-authored-by: Cash Williams --- src/agents/tools/discord-actions-messaging.ts | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/src/agents/tools/discord-actions-messaging.ts b/src/agents/tools/discord-actions-messaging.ts index 63759cb35..63fbe491a 100644 --- a/src/agents/tools/discord-actions-messaging.ts +++ b/src/agents/tools/discord-actions-messaging.ts @@ -24,6 +24,32 @@ type ActionGate = ( defaultValue?: boolean, ) => boolean; +function formatDiscordTimestamp(ts?: string | null): string | undefined { + if (!ts) return undefined; + const date = new Date(ts); + if (Number.isNaN(date.getTime())) return undefined; + + const yyyy = String(date.getFullYear()).padStart(4, "0"); + const mm = String(date.getMonth() + 1).padStart(2, "0"); + const dd = String(date.getDate()).padStart(2, "0"); + const hh = String(date.getHours()).padStart(2, "0"); + const min = String(date.getMinutes()).padStart(2, "0"); + + // getTimezoneOffset() is minutes *behind* UTC. Flip sign to get ISO offset. + const offsetMinutes = -date.getTimezoneOffset(); + const sign = offsetMinutes >= 0 ? "+" : "-"; + const absOffsetMinutes = Math.abs(offsetMinutes); + const offsetH = String(Math.floor(absOffsetMinutes / 60)).padStart(2, "0"); + const offsetM = String(absOffsetMinutes % 60).padStart(2, "0"); + + const tz = Intl.DateTimeFormat().resolvedOptions().timeZone; + const tzSuffix = tz ? `{${tz}}` : ""; + + // Compact ISO-like *local* timestamp with minutes precision. + // Example: 2025-01-02T03:04-08:00{America/Los_Angeles} + return `${yyyy}-${mm}-${dd}T${hh}:${min}${sign}${offsetH}:${offsetM}${tzSuffix}`; +} + export async function handleDiscordMessagingAction( action: string, params: Record, @@ -133,7 +159,12 @@ export async function handleDiscordMessagingAction( after: readStringParam(params, "after"), around: readStringParam(params, "around"), }); - return jsonResult({ ok: true, messages }); + const formattedMessages = messages.map((message) => ({ + ...message, + timestamp: + formatDiscordTimestamp(message.timestamp) ?? message.timestamp, + })); + return jsonResult({ ok: true, messages: formattedMessages }); } case "sendMessage": { if (!isActionEnabled("messages")) { From 6f541d6304ead7964b3a4504e8fe29c5e05b42b7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:26:24 +0000 Subject: [PATCH 048/110] fix: improve discord permission errors --- CHANGELOG.md | 1 + src/discord/send.test.ts | 32 ++++++++++ src/discord/send.ts | 126 +++++++++++++++++++++++++++++++++++---- 3 files changed, 148 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e0b04b119..40b2c295e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,7 @@ - Heartbeat: make HEARTBEAT_OK ack padding configurable across heartbeat and cron delivery. (#238) — thanks @jalehman - WhatsApp: set sender E.164 for direct chats so owner commands work in DMs. - Slack: keep auto-replies in the original thread when responding to thread messages. Thanks @scald for PR #251. +- Discord: surface missing-permission hints (muted/role overrides) when replies fail. - Docs: clarify Slack manifest scopes (current vs optional) with references. Thanks @jarvis-medmatic for PR #235. - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242. diff --git a/src/discord/send.test.ts b/src/discord/send.test.ts index dac4426ed..f406e710a 100644 --- a/src/discord/send.test.ts +++ b/src/discord/send.test.ts @@ -106,6 +106,38 @@ describe("sendMessageDiscord", () => { expect(res.channelId).toBe("chan1"); }); + it("adds missing permission hints on 50013", async () => { + const { rest, postMock, getMock } = makeRest(); + const perms = new PermissionsBitField([PermissionsBitField.Flags.ViewChannel]); + const apiError = Object.assign(new Error("Missing Permissions"), { + code: 50013, + status: 403, + }); + postMock.mockRejectedValueOnce(apiError); + getMock + .mockResolvedValueOnce({ + id: "789", + guild_id: "guild1", + type: 0, + permission_overwrites: [], + }) + .mockResolvedValueOnce({ id: "bot1" }) + .mockResolvedValueOnce({ + id: "guild1", + roles: [{ id: "guild1", permissions: perms.bitfield.toString() }], + }) + .mockResolvedValueOnce({ roles: [] }); + + let error: unknown; + try { + await sendMessageDiscord("channel:789", "hello", { rest, token: "t" }); + } catch (err) { + error = err; + } + expect(String(error)).toMatch(/missing permissions/i); + expect(String(error)).toMatch(/SendMessages/); + }); + it("uploads media attachments", async () => { const { rest, postMock } = makeRest(); postMock.mockResolvedValue({ id: "msg", channel_id: "789" }); diff --git a/src/discord/send.ts b/src/discord/send.ts index 9aebd7f2b..821cd1b80 100644 --- a/src/discord/send.ts +++ b/src/discord/send.ts @@ -1,4 +1,4 @@ -import { PermissionsBitField, REST, Routes } from "discord.js"; +import { ChannelType, PermissionsBitField, REST, Routes } from "discord.js"; import { PollLayoutType } from "discord-api-types/payloads/v10"; import type { RESTAPIPoll } from "discord-api-types/rest/v10"; import type { @@ -24,6 +24,24 @@ const DISCORD_MAX_STICKER_BYTES = 512 * 1024; const DISCORD_POLL_MIN_ANSWERS = 2; const DISCORD_POLL_MAX_ANSWERS = 10; const DISCORD_POLL_MAX_DURATION_HOURS = 32 * 24; +const DISCORD_MISSING_PERMISSIONS = 50013; +const DISCORD_CANNOT_DM = 50007; + +export class DiscordSendError extends Error { + kind?: "missing-permissions" | "dm-blocked"; + channelId?: string; + missingPermissions?: string[]; + + constructor(message: string, opts?: Partial) { + super(message); + this.name = "DiscordSendError"; + if (opts) Object.assign(this, opts); + } + + override toString() { + return this.message; + } +} type DiscordRecipient = | { @@ -78,6 +96,7 @@ export type DiscordPermissionsSummary = { permissions: string[]; raw: string; isDm: boolean; + channelType?: number; }; export type DiscordMessageQuery = { @@ -251,6 +270,80 @@ function normalizePollInput(input: DiscordPollInput): RESTAPIPoll { }; } +function getDiscordErrorCode(err: unknown) { + if (!err || typeof err !== "object") return undefined; + const candidate = + "code" in err && err.code !== undefined + ? err.code + : "rawError" in err && err.rawError && typeof err.rawError === "object" + ? (err.rawError as { code?: unknown }).code + : undefined; + if (typeof candidate === "number") return candidate; + if (typeof candidate === "string" && /^\d+$/.test(candidate)) { + return Number(candidate); + } + return undefined; +} + +function isThreadChannelType(channelType?: number) { + return ( + channelType === ChannelType.GuildNewsThread || + channelType === ChannelType.GuildPublicThread || + channelType === ChannelType.GuildPrivateThread + ); +} + +async function buildDiscordSendError( + err: unknown, + ctx: { + channelId: string; + rest: REST; + token: string; + hasMedia: boolean; + }, +) { + if (err instanceof DiscordSendError) return err; + const code = getDiscordErrorCode(err); + if (code === DISCORD_CANNOT_DM) { + return new DiscordSendError( + "discord dm failed: user blocks dms or privacy settings disallow it", + { kind: "dm-blocked" }, + ); + } + if (code !== DISCORD_MISSING_PERMISSIONS) return err; + + let missing: string[] = []; + try { + const permissions = await fetchChannelPermissionsDiscord(ctx.channelId, { + rest: ctx.rest, + token: ctx.token, + }); + const current = new Set(permissions.permissions); + const required = ["ViewChannel", "SendMessages"]; + if (isThreadChannelType(permissions.channelType)) { + required.push("SendMessagesInThreads"); + } + if (ctx.hasMedia) { + required.push("AttachFiles"); + } + missing = required.filter((permission) => !current.has(permission)); + } catch { + /* ignore permission probe errors */ + } + + const missingLabel = missing.length + ? `missing permissions in channel ${ctx.channelId}: ${missing.join(", ")}` + : `missing permissions in channel ${ctx.channelId}`; + return new DiscordSendError( + `${missingLabel}. bot might be muted or blocked by role/channel overrides`, + { + kind: "missing-permissions", + channelId: ctx.channelId, + missingPermissions: missing, + }, + ); +} + async function resolveChannelId( rest: REST, recipient: DiscordRecipient, @@ -374,17 +467,25 @@ export async function sendMessageDiscord( let result: | { id: string; channel_id: string } | { id: string | null; channel_id: string }; - - if (opts.mediaUrl) { - result = await sendDiscordMedia( - rest, + try { + if (opts.mediaUrl) { + result = await sendDiscordMedia( + rest, + channelId, + text, + opts.mediaUrl, + opts.replyTo, + ); + } else { + result = await sendDiscordText(rest, channelId, text, opts.replyTo); + } + } catch (err) { + throw await buildDiscordSendError(err, { channelId, - text, - opts.mediaUrl, - opts.replyTo, - ); - } else { - result = await sendDiscordText(rest, channelId, text, opts.replyTo); + rest, + token, + hasMedia: Boolean(opts.mediaUrl), + }); } return { @@ -512,6 +613,7 @@ export async function fetchChannelPermissionsDiscord( const token = resolveToken(opts.token); const rest = opts.rest ?? new REST({ version: "10" }).setToken(token); const channel = (await rest.get(Routes.channel(channelId))) as APIChannel; + const channelType = "type" in channel ? channel.type : undefined; const guildId = "guild_id" in channel ? channel.guild_id : undefined; if (!guildId) { return { @@ -519,6 +621,7 @@ export async function fetchChannelPermissionsDiscord( permissions: [], raw: "0", isDm: true, + channelType, }; } @@ -573,6 +676,7 @@ export async function fetchChannelPermissionsDiscord( permissions: permissions.toArray(), raw: permissions.bitfield.toString(), isDm: false, + channelType, }; } From 87f4efda8d11918321154065151a2748d0bfc0da Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:38:09 +0000 Subject: [PATCH 049/110] fix: restore auth fallback ordering --- CHANGELOG.md | 1 + src/agents/auth-profiles.test.ts | 29 +++++++++++++++++++++++++++-- src/agents/auth-profiles.ts | 26 +++++++++++++++++++++++--- src/agents/pi-embedded-runner.ts | 7 +++++-- src/discord/send.test.ts | 4 +++- 5 files changed, 59 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40b2c295e..4660aeccc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. - CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). +- Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order. - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns). diff --git a/src/agents/auth-profiles.test.ts b/src/agents/auth-profiles.test.ts index 286b52093..493f2c09d 100644 --- a/src/agents/auth-profiles.test.ts +++ b/src/agents/auth-profiles.test.ts @@ -30,12 +30,12 @@ describe("resolveAuthProfileOrder", () => { }, }; - it("returns empty order without explicit config", () => { + it("uses stored profiles when no config exists", () => { const order = resolveAuthProfileOrder({ store, provider: "anthropic", }); - expect(order).toEqual([]); + expect(order).toEqual(["anthropic:default", "anthropic:work"]); }); it("prioritizes preferred profiles", () => { @@ -80,4 +80,29 @@ describe("resolveAuthProfileOrder", () => { }); expect(order).toEqual(["anthropic:work", "anthropic:default"]); }); + + it("prioritizes oauth profiles when order missing", () => { + const mixedStore: AuthProfileStore = { + version: 1, + profiles: { + "anthropic:default": { + type: "api_key", + provider: "anthropic", + key: "sk-default", + }, + "anthropic:oauth": { + type: "oauth", + provider: "anthropic", + access: "access-token", + refresh: "refresh-token", + expires: Date.now() + 60_000, + }, + }, + }; + const order = resolveAuthProfileOrder({ + store: mixedStore, + provider: "anthropic", + }); + expect(order).toEqual(["anthropic:oauth", "anthropic:default"]); + }); }); diff --git a/src/agents/auth-profiles.ts b/src/agents/auth-profiles.ts index 61346566d..f9999f17e 100644 --- a/src/agents/auth-profiles.ts +++ b/src/agents/auth-profiles.ts @@ -258,10 +258,16 @@ export function resolveAuthProfileOrder(params: { .map(([profileId]) => profileId) : []; const lastGood = store.lastGood?.[provider]; - const order = + const baseOrder = configuredOrder ?? - (explicitProfiles.length > 0 ? explicitProfiles : undefined); - if (!order) return []; + (explicitProfiles.length > 0 + ? explicitProfiles + : listProfilesForProvider(store, provider)); + if (baseOrder.length === 0) return []; + const order = + configuredOrder && configuredOrder.length > 0 + ? baseOrder + : orderProfilesByMode(baseOrder, store); const filtered = order.filter((profileId) => { const cred = store.profiles[profileId]; @@ -288,6 +294,20 @@ export function resolveAuthProfileOrder(params: { return deduped; } +function orderProfilesByMode( + order: string[], + store: AuthProfileStore, +): string[] { + const scored = order.map((profileId) => { + const type = store.profiles[profileId]?.type; + const score = type === "oauth" ? 0 : type === "api_key" ? 1 : 2; + return { profileId, score }; + }); + return scored + .sort((a, b) => a.score - b.score) + .map((entry) => entry.profileId); +} + export async function resolveApiKeyForProfile(params: { cfg?: ClawdbotConfig; store: AuthProfileStore; diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index d04314e71..c3ccbe107 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -374,8 +374,11 @@ export async function compactEmbeddedPiSession(params: { }; } try { - const apiKey = await getApiKeyForModel(model, authStorage); - authStorage.setRuntimeApiKey(model.provider, apiKey); + const apiKey = await getApiKeyForModel({ + model, + cfg: params.config, + }); + authStorage.setRuntimeApiKey(model.provider, apiKey.apiKey); } catch (err) { return { ok: false, diff --git a/src/discord/send.test.ts b/src/discord/send.test.ts index f406e710a..675cb464a 100644 --- a/src/discord/send.test.ts +++ b/src/discord/send.test.ts @@ -108,7 +108,9 @@ describe("sendMessageDiscord", () => { it("adds missing permission hints on 50013", async () => { const { rest, postMock, getMock } = makeRest(); - const perms = new PermissionsBitField([PermissionsBitField.Flags.ViewChannel]); + const perms = new PermissionsBitField([ + PermissionsBitField.Flags.ViewChannel, + ]); const apiError = Object.assign(new Error("Missing Permissions"), { code: 50013, status: 403, From 11a54959190fa8052c7302491ba255401167ea05 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:40:02 +0000 Subject: [PATCH 050/110] docs: add group chat guidance --- CHANGELOG.md | 1 + docs/templates/AGENTS.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4660aeccc..8c3c42610 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. - CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). - Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order. +- Docs: add group chat participation guidance to the AGENTS template. - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns). diff --git a/docs/templates/AGENTS.md b/docs/templates/AGENTS.md index 121756b8f..be4345fd7 100644 --- a/docs/templates/AGENTS.md +++ b/docs/templates/AGENTS.md @@ -69,6 +69,29 @@ Vectors + BM25 + reranking finds things even with different wording. You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak. +### 💬 Know When to Speak! +In group chats where you receive every message, be **smart about when to contribute**: + +**Respond when:** +- Directly mentioned or asked a question +- You can add genuine value (info, insight, help) +- Something witty/funny fits naturally +- Correcting important misinformation +- Summarizing when asked + +**Stay silent (HEARTBEAT_OK) when:** +- It's just casual banter between humans +- Someone already answered the question +- Your response would just be "yeah" or "nice" +- The conversation is flowing fine without you +- Adding a message would interrupt the vibe + +**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it. + +**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments. + +Participate, don't dominate. + ## Tools Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`. From 55b33b4e6969b771643becd1f2cfd6420b10986a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:40:15 +0000 Subject: [PATCH 051/110] fix: stop gmail watcher restart on bind error --- CHANGELOG.md | 1 + src/hooks/gmail-watcher.test.ts | 14 ++++++++++++++ src/hooks/gmail-watcher.ts | 21 ++++++++++++++++++++- 3 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 src/hooks/gmail-watcher.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c3c42610..7b29b4a0c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ - CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). - Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order. - Docs: add group chat participation guidance to the AGENTS template. +- Gmail: stop restart loop when `gog gmail watch serve` fails to bind (address already in use). - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. - TUI: migrate key handling to the updated pi-tui Key matcher API. - Logging: redact sensitive tokens in verbose tool summaries by default (configurable patterns). diff --git a/src/hooks/gmail-watcher.test.ts b/src/hooks/gmail-watcher.test.ts new file mode 100644 index 000000000..aa16e4ad2 --- /dev/null +++ b/src/hooks/gmail-watcher.test.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from "vitest"; +import { isAddressInUseError } from "./gmail-watcher.js"; + +describe("gmail watcher", () => { + it("detects address already in use errors", () => { + expect( + isAddressInUseError( + "listen tcp 127.0.0.1:8788: bind: address already in use", + ), + ).toBe(true); + expect(isAddressInUseError("EADDRINUSE: address already in use")).toBe(true); + expect(isAddressInUseError("some other error")).toBe(false); + }); +}); diff --git a/src/hooks/gmail-watcher.ts b/src/hooks/gmail-watcher.ts index bd4e07969..0b3133066 100644 --- a/src/hooks/gmail-watcher.ts +++ b/src/hooks/gmail-watcher.ts @@ -20,6 +20,12 @@ import { ensureTailscaleEndpoint } from "./gmail-setup-utils.js"; const log = createSubsystemLogger("gmail-watcher"); +const ADDRESS_IN_USE_RE = /address already in use|EADDRINUSE/i; + +export function isAddressInUseError(line: string): boolean { + return ADDRESS_IN_USE_RE.test(line); +} + let watcherProcess: ChildProcess | null = null; let renewInterval: ReturnType | null = null; let shuttingDown = false; @@ -61,6 +67,7 @@ async function startGmailWatch( function spawnGogServe(cfg: GmailHookRuntimeConfig): ChildProcess { const args = buildGogWatchServeArgs(cfg); log.info(`starting gog ${args.join(" ")}`); + let addressInUse = false; const child = spawn("gog", args, { stdio: ["ignore", "pipe", "pipe"], @@ -74,7 +81,11 @@ function spawnGogServe(cfg: GmailHookRuntimeConfig): ChildProcess { child.stderr?.on("data", (data: Buffer) => { const line = data.toString().trim(); - if (line) log.warn(`[gog] ${line}`); + if (!line) return; + if (isAddressInUseError(line)) { + addressInUse = true; + } + log.warn(`[gog] ${line}`); }); child.on("error", (err) => { @@ -83,6 +94,14 @@ function spawnGogServe(cfg: GmailHookRuntimeConfig): ChildProcess { child.on("exit", (code, signal) => { if (shuttingDown) return; + if (addressInUse) { + log.warn( + "gog serve failed to bind (address already in use); stopping restarts. " + + "Another watcher is likely running. Set CLAWDBOT_SKIP_GMAIL_WATCHER=1 or stop the other process.", + ); + watcherProcess = null; + return; + } log.warn(`gog exited (code=${code}, signal=${signal}); restarting in 5s`); watcherProcess = null; setTimeout(() => { From 3c6dea3ef337a1cd90883c88f8020982182cb67b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 01:46:59 +0000 Subject: [PATCH 052/110] style: format gmail watcher test --- src/hooks/gmail-watcher.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/hooks/gmail-watcher.test.ts b/src/hooks/gmail-watcher.test.ts index aa16e4ad2..039a5977e 100644 --- a/src/hooks/gmail-watcher.test.ts +++ b/src/hooks/gmail-watcher.test.ts @@ -8,7 +8,9 @@ describe("gmail watcher", () => { "listen tcp 127.0.0.1:8788: bind: address already in use", ), ).toBe(true); - expect(isAddressInUseError("EADDRINUSE: address already in use")).toBe(true); + expect(isAddressInUseError("EADDRINUSE: address already in use")).toBe( + true, + ); expect(isAddressInUseError("some other error")).toBe(false); }); }); From b30bae89edd8afc527a394a2c8475deba12d8f5b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:41:48 +0100 Subject: [PATCH 053/110] feat: track compaction count + verbose notice --- CHANGELOG.md | 1 + src/agents/pi-embedded-subscribe.ts | 8 ++ src/auto-reply/reply.triggers.test.ts | 15 ++- .../agent-runner.heartbeat-typing.test.ts | 62 ++++++++- src/auto-reply/reply/agent-runner.ts | 25 ++++ src/auto-reply/reply/commands.ts | 9 ++ .../reply/followup-runner.compaction.test.ts | 119 ++++++++++++++++++ src/auto-reply/reply/followup-runner.ts | 25 ++++ src/auto-reply/reply/session-updates.ts | 29 +++++ src/auto-reply/status.test.ts | 2 + src/auto-reply/status.ts | 3 + src/config/sessions.ts | 1 + 12 files changed, 293 insertions(+), 6 deletions(-) create mode 100644 src/auto-reply/reply/followup-runner.compaction.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b29b4a0c..63e954950 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,7 @@ - Control UI: avoid Slack config ReferenceError by reading slack config snapshots. Thanks @sreekaransrinath for PR #249. - Telegram: honor routing.groupChat.mentionPatterns for group mention gating. Thanks @regenrek for PR #242. - Auto-reply: block unauthorized `/reset` and infer WhatsApp senders from E.164 inputs. +- Auto-reply: track compaction count in session status; verbose mode announces auto-compactions. ### Maintenance - Deps: bump pi-* stack, Slack SDK, discord-api-types, file-type, zod, and Biome. diff --git a/src/agents/pi-embedded-subscribe.ts b/src/agents/pi-embedded-subscribe.ts index 69bbecf65..330422efd 100644 --- a/src/agents/pi-embedded-subscribe.ts +++ b/src/agents/pi-embedded-subscribe.ts @@ -555,6 +555,10 @@ export function subscribeEmbeddedPiSession(params: { compactionInFlight = true; ensureCompactionPromise(); log.debug(`embedded run compaction start: runId=${params.runId}`); + params.onAgentEvent?.({ + stream: "compaction", + data: { phase: "start" }, + }); } if (evt.type === "auto_compaction_end") { @@ -567,6 +571,10 @@ export function subscribeEmbeddedPiSession(params: { } else { maybeResolveCompactionWait(); } + params.onAgentEvent?.({ + stream: "compaction", + data: { phase: "end", willRetry }, + }); } if (evt.type === "agent_end") { diff --git a/src/auto-reply/reply.triggers.test.ts b/src/auto-reply/reply.triggers.test.ts index 24c53f662..006bfdaca 100644 --- a/src/auto-reply/reply.triggers.test.ts +++ b/src/auto-reply/reply.triggers.test.ts @@ -19,7 +19,7 @@ import { runEmbeddedPiAgent, } from "../agents/pi-embedded.js"; import { ensureSandboxWorkspaceForSession } from "../agents/sandbox.js"; -import { resolveSessionKey } from "../config/sessions.js"; +import { loadSessionStore, resolveSessionKey } from "../config/sessions.js"; import { getReplyFromConfig } from "./reply.js"; import { HEARTBEAT_TOKEN } from "./tokens.js"; @@ -731,6 +731,10 @@ describe("trigger handling", () => { it("runs /compact as a gated command", async () => { await withTempHome(async (home) => { + const storePath = join( + tmpdir(), + `clawdbot-session-test-${Date.now()}.json`, + ); vi.mocked(compactEmbeddedPiSession).mockResolvedValue({ ok: true, compacted: true, @@ -757,7 +761,7 @@ describe("trigger handling", () => { allowFrom: ["*"], }, session: { - store: join(tmpdir(), `clawdbot-session-test-${Date.now()}.json`), + store: storePath, }, }, ); @@ -765,6 +769,13 @@ describe("trigger handling", () => { expect(text?.startsWith("⚙️ Compacted")).toBe(true); expect(compactEmbeddedPiSession).toHaveBeenCalledOnce(); expect(runEmbeddedPiAgent).not.toHaveBeenCalled(); + const store = loadSessionStore(storePath); + const sessionKey = resolveSessionKey("per-sender", { + Body: "/compact focus on decisions", + From: "+1003", + To: "+2000", + }); + expect(store[sessionKey]?.compactionCount).toBe(1); }); }); diff --git a/src/auto-reply/reply/agent-runner.heartbeat-typing.test.ts b/src/auto-reply/reply/agent-runner.heartbeat-typing.test.ts index e5cec45c8..2b437a57f 100644 --- a/src/auto-reply/reply/agent-runner.heartbeat-typing.test.ts +++ b/src/auto-reply/reply/agent-runner.heartbeat-typing.test.ts @@ -1,5 +1,9 @@ +import fs from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; import { describe, expect, it, vi } from "vitest"; +import type { SessionEntry } from "../../config/sessions.js"; import type { TemplateContext } from "../templating.js"; import type { GetReplyOptions } from "../types.js"; import type { FollowupRun, QueueSettings } from "./queue.js"; @@ -54,7 +58,14 @@ type EmbeddedPiAgentParams = { onPartialReply?: (payload: { text?: string }) => Promise | void; }; -function createMinimalRun(params?: { opts?: GetReplyOptions }) { +function createMinimalRun(params?: { + opts?: GetReplyOptions; + resolvedVerboseLevel?: "off" | "on"; + sessionStore?: Record; + sessionEntry?: SessionEntry; + sessionKey?: string; + storePath?: string; +}) { const typing = createTyping(); const opts = params?.opts; const sessionCtx = { @@ -62,13 +73,14 @@ function createMinimalRun(params?: { opts?: GetReplyOptions }) { MessageSid: "msg", } as unknown as TemplateContext; const resolvedQueue = { mode: "interrupt" } as unknown as QueueSettings; + const sessionKey = params?.sessionKey ?? "main"; const followupRun = { prompt: "hello", summaryLine: "hello", enqueuedAt: Date.now(), run: { sessionId: "session", - sessionKey: "main", + sessionKey, surface: "whatsapp", sessionFile: "/tmp/session.jsonl", workspaceDir: "/tmp", @@ -77,7 +89,7 @@ function createMinimalRun(params?: { opts?: GetReplyOptions }) { provider: "anthropic", model: "claude", thinkLevel: "low", - verboseLevel: "off", + verboseLevel: params?.resolvedVerboseLevel ?? "off", elevatedLevel: "off", bashElevated: { enabled: false, @@ -104,9 +116,13 @@ function createMinimalRun(params?: { opts?: GetReplyOptions }) { isStreaming: false, opts, typing, + sessionEntry: params?.sessionEntry, + sessionStore: params?.sessionStore, + sessionKey, + storePath: params?.storePath, sessionCtx, defaultModel: "anthropic/claude-opus-4-5", - resolvedVerboseLevel: "off", + resolvedVerboseLevel: params?.resolvedVerboseLevel ?? "off", isNewSession: false, blockStreamingEnabled: false, resolvedBlockStreamingBreak: "message_end", @@ -153,4 +169,42 @@ describe("runReplyAgent typing (heartbeat)", () => { expect(typing.startTypingOnText).not.toHaveBeenCalled(); expect(typing.startTypingLoop).not.toHaveBeenCalled(); }); + + it("announces auto-compaction in verbose mode and tracks count", async () => { + const storePath = path.join( + await fs.mkdtemp(path.join(tmpdir(), "clawdbot-compaction-")), + "sessions.json", + ); + const sessionEntry = { sessionId: "session", updatedAt: Date.now() }; + const sessionStore = { main: sessionEntry }; + + runEmbeddedPiAgentMock.mockImplementationOnce( + async (params: { + onAgentEvent?: (evt: { + stream: string; + data: Record; + }) => void; + }) => { + params.onAgentEvent?.({ + stream: "compaction", + data: { phase: "end", willRetry: false }, + }); + return { payloads: [{ text: "final" }], meta: {} }; + }, + ); + + const { run } = createMinimalRun({ + resolvedVerboseLevel: "on", + sessionEntry, + sessionStore, + sessionKey: "main", + storePath, + }); + const res = await run(); + expect(Array.isArray(res)).toBe(true); + const payloads = res as { text?: string }[]; + expect(payloads[0]?.text).toContain("Auto-compaction complete"); + expect(payloads[0]?.text).toContain("count 1"); + expect(sessionStore.main.compactionCount).toBe(1); + }); }); diff --git a/src/auto-reply/reply/agent-runner.ts b/src/auto-reply/reply/agent-runner.ts index fd2a8eef1..9f994bdd6 100644 --- a/src/auto-reply/reply/agent-runner.ts +++ b/src/auto-reply/reply/agent-runner.ts @@ -27,6 +27,7 @@ import { scheduleFollowupDrain, } from "./queue.js"; import { extractReplyToTag } from "./reply-tags.js"; +import { incrementCompactionCount } from "./session-updates.js"; import type { TypingController } from "./typing.js"; export async function runReplyAgent(params: { @@ -167,6 +168,7 @@ export async function runReplyAgent(params: { }; let didLogHeartbeatStrip = false; + let autoCompactionCompleted = false; try { const runId = crypto.randomUUID(); if (sessionKey) { @@ -233,6 +235,14 @@ export async function runReplyAgent(params: { }); } : undefined, + onAgentEvent: (evt) => { + if (evt.stream !== "compaction") return; + const phase = String(evt.data.phase ?? ""); + const willRetry = Boolean(evt.data.willRetry); + if (phase === "end" && !willRetry) { + autoCompactionCompleted = true; + } + }, onBlockReply: blockStreamingEnabled && opts?.onBlockReply ? async (payload) => { @@ -478,6 +488,21 @@ export async function runReplyAgent(params: { // If verbose is enabled and this is a new session, prepend a session hint. let finalPayloads = filteredPayloads; + if (autoCompactionCompleted) { + const count = await incrementCompactionCount({ + sessionEntry, + sessionStore, + sessionKey, + storePath, + }); + if (resolvedVerboseLevel === "on") { + const suffix = typeof count === "number" ? ` (count ${count})` : ""; + finalPayloads = [ + { text: `🧹 Auto-compaction complete${suffix}.` }, + ...finalPayloads, + ]; + } + } if (resolvedVerboseLevel === "on" && isNewSession) { finalPayloads = [ { text: `🧭 New session: ${followupRun.run.sessionId}` }, diff --git a/src/auto-reply/reply/commands.ts b/src/auto-reply/reply/commands.ts index 21b65a91c..22cc7f7c8 100644 --- a/src/auto-reply/reply/commands.ts +++ b/src/auto-reply/reply/commands.ts @@ -44,6 +44,7 @@ import type { ReplyPayload } from "../types.js"; import { isAbortTrigger, setAbortMemory } from "./abort.js"; import type { InlineDirectives } from "./directive-handling.js"; import { stripMentions, stripStructuralPrefixes } from "./mentions.js"; +import { incrementCompactionCount } from "./session-updates.js"; export type CommandContext = { surface: string; @@ -444,6 +445,14 @@ export async function handleCommands(params: { : "Compacted" : "Compaction skipped" : "Compaction failed"; + if (result.ok && result.compacted) { + await incrementCompactionCount({ + sessionEntry, + sessionStore, + sessionKey, + storePath, + }); + } const reason = result.reason?.trim(); const line = reason ? `${compactLabel}: ${reason} • ${contextSummary}` diff --git a/src/auto-reply/reply/followup-runner.compaction.test.ts b/src/auto-reply/reply/followup-runner.compaction.test.ts new file mode 100644 index 000000000..b4ac4c856 --- /dev/null +++ b/src/auto-reply/reply/followup-runner.compaction.test.ts @@ -0,0 +1,119 @@ +import fs from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { describe, expect, it, vi } from "vitest"; + +import type { SessionEntry } from "../../config/sessions.js"; +import type { FollowupRun } from "./queue.js"; +import type { TypingController } from "./typing.js"; + +const runEmbeddedPiAgentMock = vi.fn(); + +vi.mock("../../agents/model-fallback.js", () => ({ + runWithModelFallback: async ({ + provider, + model, + run, + }: { + provider: string; + model: string; + run: (provider: string, model: string) => Promise; + }) => ({ + result: await run(provider, model), + provider, + model, + }), +})); + +vi.mock("../../agents/pi-embedded.js", () => ({ + runEmbeddedPiAgent: (params: unknown) => runEmbeddedPiAgentMock(params), +})); + +import { createFollowupRunner } from "./followup-runner.js"; + +function createTyping(): TypingController { + return { + onReplyStart: vi.fn(async () => {}), + startTypingLoop: vi.fn(async () => {}), + startTypingOnText: vi.fn(async () => {}), + refreshTypingTtl: vi.fn(), + cleanup: vi.fn(), + }; +} + +describe("createFollowupRunner compaction", () => { + it("adds verbose auto-compaction notice and tracks count", async () => { + const storePath = path.join( + await fs.mkdtemp(path.join(tmpdir(), "clawdbot-compaction-")), + "sessions.json", + ); + const sessionEntry: SessionEntry = { + sessionId: "session", + updatedAt: Date.now(), + }; + const sessionStore: Record = { + main: sessionEntry, + }; + const onBlockReply = vi.fn(async () => {}); + + runEmbeddedPiAgentMock.mockImplementationOnce( + async (params: { + onAgentEvent?: (evt: { + stream: string; + data: Record; + }) => void; + }) => { + params.onAgentEvent?.({ + stream: "compaction", + data: { phase: "end", willRetry: false }, + }); + return { payloads: [{ text: "final" }], meta: {} }; + }, + ); + + const runner = createFollowupRunner({ + opts: { onBlockReply }, + typing: createTyping(), + sessionEntry, + sessionStore, + sessionKey: "main", + storePath, + defaultModel: "anthropic/claude-opus-4-5", + }); + + const queued = { + prompt: "hello", + summaryLine: "hello", + enqueuedAt: Date.now(), + run: { + sessionId: "session", + sessionKey: "main", + surface: "whatsapp", + sessionFile: "/tmp/session.jsonl", + workspaceDir: "/tmp", + config: {}, + skillsSnapshot: {}, + provider: "anthropic", + model: "claude", + thinkLevel: "low", + verboseLevel: "on", + elevatedLevel: "off", + bashElevated: { + enabled: false, + allowed: false, + defaultLevel: "off", + }, + timeoutMs: 1_000, + blockReplyBreak: "message_end", + }, + } as FollowupRun; + + await runner(queued); + + expect(onBlockReply).toHaveBeenCalled(); + expect(onBlockReply.mock.calls[0][0].text).toContain( + "Auto-compaction complete", + ); + expect(sessionStore.main.compactionCount).toBe(1); + }); +}); diff --git a/src/auto-reply/reply/followup-runner.ts b/src/auto-reply/reply/followup-runner.ts index ebb6d5cfa..528bca679 100644 --- a/src/auto-reply/reply/followup-runner.ts +++ b/src/auto-reply/reply/followup-runner.ts @@ -12,6 +12,7 @@ import { SILENT_REPLY_TOKEN } from "../tokens.js"; import type { GetReplyOptions, ReplyPayload } from "../types.js"; import type { FollowupRun } from "./queue.js"; import { extractReplyToTag } from "./reply-tags.js"; +import { incrementCompactionCount } from "./session-updates.js"; import type { TypingController } from "./typing.js"; export function createFollowupRunner(params: { @@ -61,6 +62,7 @@ export function createFollowupRunner(params: { if (queued.run.sessionKey) { registerAgentRunContext(runId, { sessionKey: queued.run.sessionKey }); } + let autoCompactionCompleted = false; let runResult: Awaited>; let fallbackProvider = queued.run.provider; let fallbackModel = queued.run.model; @@ -91,6 +93,14 @@ export function createFollowupRunner(params: { timeoutMs: queued.run.timeoutMs, runId, blockReplyBreak: queued.run.blockReplyBreak, + onAgentEvent: (evt) => { + if (evt.stream !== "compaction") return; + const phase = String(evt.data.phase ?? ""); + const willRetry = Boolean(evt.data.willRetry); + if (phase === "end" && !willRetry) { + autoCompactionCompleted = true; + } + }, }), }); runResult = fallbackResult.result; @@ -132,6 +142,21 @@ export function createFollowupRunner(params: { if (replyTaggedPayloads.length === 0) return; + if (autoCompactionCompleted) { + const count = await incrementCompactionCount({ + sessionEntry, + sessionStore, + sessionKey, + storePath, + }); + if (queued.run.verboseLevel === "on") { + const suffix = typeof count === "number" ? ` (count ${count})` : ""; + replyTaggedPayloads.unshift({ + text: `🧹 Auto-compaction complete${suffix}.`, + }); + } + } + if (sessionStore && sessionKey) { const usage = runResult.meta.agentMeta?.usage; const modelUsed = diff --git a/src/auto-reply/reply/session-updates.ts b/src/auto-reply/reply/session-updates.ts index 23e1a8777..f780455e0 100644 --- a/src/auto-reply/reply/session-updates.ts +++ b/src/auto-reply/reply/session-updates.ts @@ -122,3 +122,32 @@ export async function ensureSkillSnapshot(params: { return { sessionEntry: nextEntry, skillsSnapshot, systemSent }; } + +export async function incrementCompactionCount(params: { + sessionEntry?: SessionEntry; + sessionStore?: Record; + sessionKey?: string; + storePath?: string; + now?: number; +}): Promise { + const { + sessionEntry, + sessionStore, + sessionKey, + storePath, + now = Date.now(), + } = params; + if (!sessionStore || !sessionKey) return undefined; + const entry = sessionStore[sessionKey] ?? sessionEntry; + if (!entry) return undefined; + const nextCount = (entry.compactionCount ?? 0) + 1; + sessionStore[sessionKey] = { + ...entry, + compactionCount: nextCount, + updatedAt: now, + }; + if (storePath) { + await saveSessionStore(storePath, sessionStore); + } + return nextCount; +} diff --git a/src/auto-reply/status.test.ts b/src/auto-reply/status.test.ts index 187f0ac97..3d4bc9587 100644 --- a/src/auto-reply/status.test.ts +++ b/src/auto-reply/status.test.ts @@ -22,6 +22,7 @@ describe("buildStatusMessage", () => { contextTokens: 32_000, thinkingLevel: "low", verboseLevel: "on", + compactionCount: 2, }, sessionKey: "main", sessionScope: "per-sender", @@ -39,6 +40,7 @@ describe("buildStatusMessage", () => { expect(text).toContain("Runtime: direct"); expect(text).toContain("Context: 16k/32k (50%)"); expect(text).toContain("Session: main"); + expect(text).toContain("compactions 2"); expect(text).toContain("Web: linked"); expect(text).toContain("heartbeat 45s"); expect(text).toContain("thinking=medium"); diff --git a/src/auto-reply/status.ts b/src/auto-reply/status.ts index 9c4e2ca01..bec2aa262 100644 --- a/src/auto-reply/status.ts +++ b/src/auto-reply/status.ts @@ -217,6 +217,9 @@ export function buildStatusMessage(args: StatusArgs): string { entry?.updatedAt ? `updated ${formatAge(now - entry.updatedAt)}` : "no activity", + typeof entry?.compactionCount === "number" + ? `compactions ${entry.compactionCount}` + : undefined, args.storePath ? `store ${shortenHomePath(args.storePath)}` : undefined, ] .filter(Boolean) diff --git a/src/config/sessions.ts b/src/config/sessions.ts index 049d4420a..ff440eab8 100644 --- a/src/config/sessions.ts +++ b/src/config/sessions.ts @@ -55,6 +55,7 @@ export type SessionEntry = { modelProvider?: string; model?: string; contextTokens?: number; + compactionCount?: number; displayName?: string; surface?: string; subject?: string; From b6ac2d860d6b1d122726250ca292501fdf3871e2 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:43:35 +0100 Subject: [PATCH 054/110] fix: resolve embedded api key lookup --- src/agents/pi-embedded-runner.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/agents/pi-embedded-runner.ts b/src/agents/pi-embedded-runner.ts index c3ccbe107..cc27f95ef 100644 --- a/src/agents/pi-embedded-runner.ts +++ b/src/agents/pi-embedded-runner.ts @@ -374,11 +374,11 @@ export async function compactEmbeddedPiSession(params: { }; } try { - const apiKey = await getApiKeyForModel({ + const apiKeyInfo = await getApiKeyForModel({ model, cfg: params.config, }); - authStorage.setRuntimeApiKey(model.provider, apiKey.apiKey); + authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); } catch (err) { return { ok: false, From 28fad05e960a98ebf9580abdf6df77637da703f5 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:43:40 +0100 Subject: [PATCH 055/110] test: stabilize docker onboarding e2e --- scripts/e2e/onboard-docker.sh | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/scripts/e2e/onboard-docker.sh b/scripts/e2e/onboard-docker.sh index 42f9c3f7e..411cf12ad 100755 --- a/scripts/e2e/onboard-docker.sh +++ b/scripts/e2e/onboard-docker.sh @@ -37,7 +37,7 @@ TRASH local delay="${2:-0.4}" # Let prompts render before sending keystrokes. sleep "$delay" - printf "%b" "$payload" >&3 + printf "%b" "$payload" >&3 2>/dev/null || true } start_gateway() { @@ -134,6 +134,8 @@ TRASH send $'"'"'\e[B'"'"' 0.6 send $'"'"'\e[B'"'"' 0.6 send $'"'"'\e[B'"'"' 0.6 + send $'"'"'\e[B'"'"' 0.6 + send $'"'"'\e[B'"'"' 0.6 send $'"'"'\r'"'"' 0.6 send $'"'"'\r'"'"' 0.5 send $'"'"'\r'"'"' 0.5 @@ -170,7 +172,7 @@ TRASH # Configure providers now? (default Yes) send $'"'"'\r'"'"' 0.8 send "" 0.8 - # Select Telegram, Discord, Signal. + # Select Telegram, Discord, Slack. send $'"'"'\e[B'"'"' 0.4 send $'"'"' '"'"' 0.4 send $'"'"'\e[B'"'"' 0.4 @@ -178,11 +180,14 @@ TRASH send $'"'"'\e[B'"'"' 0.4 send $'"'"' '"'"' 0.4 send $'"'"'\r'"'"' 0.6 - send $'"'"'tg_token\r'"'"' 0.6 - send $'"'"'discord_token\r'"'"' 0.6 - send $'"'"'n\r'"'"' 0.6 - send $'"'"'+15551234567\r'"'"' 0.6 - send $'"'"'n\r'"'"' 0.6 + send $'"'"'tg_token\r'"'"' 0.8 + send $'"'"'discord_token\r'"'"' 0.8 + send "" 0.6 + send $'"'"'\r'"'"' 0.6 + send "" 0.6 + send $'"'"'slack_bot\r'"'"' 0.8 + send "" 0.6 + send $'"'"'slack_app\r'"'"' 0.8 } send_skills_flow() { @@ -393,11 +398,11 @@ if (cfg?.telegram?.botToken !== "tg_token") { if (cfg?.discord?.token !== "discord_token") { errors.push(`discord.token mismatch (got ${cfg?.discord?.token ?? "unset"})`); } -if (cfg?.signal?.account !== "+15551234567") { - errors.push(`signal.account mismatch (got ${cfg?.signal?.account ?? "unset"})`); +if (cfg?.slack?.botToken !== "slack_bot") { + errors.push(`slack.botToken mismatch (got ${cfg?.slack?.botToken ?? "unset"})`); } -if (cfg?.signal?.cliPath !== "signal-cli") { - errors.push(`signal.cliPath mismatch (got ${cfg?.signal?.cliPath ?? "unset"})`); +if (cfg?.slack?.appToken !== "slack_app") { + errors.push(`slack.appToken mismatch (got ${cfg?.slack?.appToken ?? "unset"})`); } if (cfg?.wizard?.lastRunMode !== "local") { errors.push(`wizard.lastRunMode mismatch (got ${cfg?.wizard?.lastRunMode ?? "unset"})`); From 17db03ad553520e8e43cbad5b5ab8c2f7ae5f158 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:44:54 +0100 Subject: [PATCH 056/110] test: ignore SIGPIPE in docker e2e --- scripts/e2e/onboard-docker.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/e2e/onboard-docker.sh b/scripts/e2e/onboard-docker.sh index 411cf12ad..f132b82f7 100755 --- a/scripts/e2e/onboard-docker.sh +++ b/scripts/e2e/onboard-docker.sh @@ -10,6 +10,7 @@ docker build -t "$IMAGE_NAME" -f "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR" echo "Running onboarding E2E..." docker run --rm -t "$IMAGE_NAME" bash -lc ' set -euo pipefail + trap "" PIPE export TERM=xterm-256color # Provide a minimal trash shim to avoid noisy "missing trash" logs in containers. From 20705d1b3787e56be70fcd7e1de5038c20556646 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 02:48:53 +0100 Subject: [PATCH 057/110] fix: set codex oauth model default --- CHANGELOG.md | 2 + docs/onboarding.md | 1 + docs/wizard.md | 4 +- src/agents/model-auth.test.ts | 72 +++++++++++++++++++++++++++ src/agents/model-auth.ts | 10 ++++ src/wizard/onboarding.ts | 91 +++++++++++++++++++++++++++++++++++ 6 files changed, 179 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 63e954950..6ed9ccd79 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ ### Fixes - Onboarding: resolve CLI entrypoint when running via `npx` so gateway daemon install works without a build step. +- Onboarding: when OpenAI Codex OAuth is used, default to `openai-codex/gpt-5.2` and warn if the selected model lacks auth. - CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). - Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order. - Docs: add group chat participation guidance to the AGENTS template. @@ -27,6 +28,7 @@ - Model: `/model list` is an alias for `/model`. - Model: `/model` output now includes auth source location (env/auth.json/models.json). - Model: avoid duplicate `missing (missing)` auth labels in `/model` list output. +- Auth: when `openai` has no API key but Codex OAuth exists, suggest `openai-codex/gpt-5.2` vs `OPENAI_API_KEY`. - Docs: clarify auth storage, migration, and OpenAI Codex OAuth onboarding. - Sandbox: copy inbound media into sandbox workspaces so agent tools can read attachments. - Control UI: show a reading indicator bubble while the assistant is responding. diff --git a/docs/onboarding.md b/docs/onboarding.md index d1b1c1dd1..bc897e5e3 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -50,6 +50,7 @@ The macOS app should: - Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible. - If the callback fails, prompt the user to paste the redirect URL or code. - Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic). +- Set `agent.model` to `openai-codex/gpt-5.2` when the model is unset or `openai/*`. ### Alternative: API key (instructions only) diff --git a/docs/wizard.md b/docs/wizard.md index ccb885f7d..883f4e003 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -49,10 +49,12 @@ It does **not** install or change anything on the remote host. 2) **Model/Auth** - **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`. - **OpenAI Codex OAuth**: browser flow; paste the `code#state`. + - Sets `agent.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. - **API key**: stores the key for you. - **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint. - **Skip**: no auth configured yet. - - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agent/auth-profiles.json` (API keys + OAuth). + - Wizard runs a model check and warns if the configured model is unknown or missing auth. + - OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agent/auth-profiles.json` (API keys + OAuth). 3) **Workspace** - Default `~/clawd` (configurable). diff --git a/src/agents/model-auth.test.ts b/src/agents/model-auth.test.ts index 578eeec20..ac37fad6a 100644 --- a/src/agents/model-auth.test.ts +++ b/src/agents/model-auth.test.ts @@ -87,4 +87,76 @@ describe("getApiKeyForModel", () => { await fs.rm(tempDir, { recursive: true, force: true }); } }); + + it("suggests openai-codex when only Codex OAuth is configured", async () => { + const previousStateDir = process.env.CLAWDBOT_STATE_DIR; + const previousAgentDir = process.env.CLAWDBOT_AGENT_DIR; + const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR; + const previousOpenAiKey = process.env.OPENAI_API_KEY; + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-auth-")); + + try { + delete process.env.OPENAI_API_KEY; + process.env.CLAWDBOT_STATE_DIR = tempDir; + process.env.CLAWDBOT_AGENT_DIR = path.join(tempDir, "agent"); + process.env.PI_CODING_AGENT_DIR = process.env.CLAWDBOT_AGENT_DIR; + + const authProfilesPath = path.join( + tempDir, + "agent", + "auth-profiles.json", + ); + await fs.mkdir(path.dirname(authProfilesPath), { + recursive: true, + mode: 0o700, + }); + await fs.writeFile( + authProfilesPath, + `${JSON.stringify( + { + version: 1, + profiles: { + "openai-codex:default": { + type: "oauth", + provider: "openai-codex", + ...oauthFixture, + }, + }, + }, + null, + 2, + )}\n`, + "utf8", + ); + + vi.resetModules(); + const { resolveApiKeyForProvider } = await import("./model-auth.js"); + + await expect( + resolveApiKeyForProvider({ provider: "openai" }), + ).rejects.toThrow(/openai-codex\/gpt-5\\.2/); + } finally { + if (previousOpenAiKey === undefined) { + delete process.env.OPENAI_API_KEY; + } else { + process.env.OPENAI_API_KEY = previousOpenAiKey; + } + if (previousStateDir === undefined) { + delete process.env.CLAWDBOT_STATE_DIR; + } else { + process.env.CLAWDBOT_STATE_DIR = previousStateDir; + } + if (previousAgentDir === undefined) { + delete process.env.CLAWDBOT_AGENT_DIR; + } else { + process.env.CLAWDBOT_AGENT_DIR = previousAgentDir; + } + if (previousPiAgentDir === undefined) { + delete process.env.PI_CODING_AGENT_DIR; + } else { + process.env.PI_CODING_AGENT_DIR = previousPiAgentDir; + } + await fs.rm(tempDir, { recursive: true, force: true }); + } + }); }); diff --git a/src/agents/model-auth.ts b/src/agents/model-auth.ts index bf29e165b..0564381e4 100644 --- a/src/agents/model-auth.ts +++ b/src/agents/model-auth.ts @@ -5,6 +5,7 @@ import { getShellEnvAppliedKeys } from "../infra/shell-env.js"; import { type AuthProfileStore, ensureAuthProfileStore, + listProfilesForProvider, resolveApiKeyForProfile, resolveAuthProfileOrder, } from "./auth-profiles.js"; @@ -83,6 +84,15 @@ export async function resolveApiKeyForProvider(params: { return { apiKey: customKey, source: "models.json" }; } + if (provider === "openai") { + const hasCodex = listProfilesForProvider(store, "openai-codex").length > 0; + if (hasCodex) { + throw new Error( + 'No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth. Use openai-codex/gpt-5.2 (ChatGPT OAuth) or set OPENAI_API_KEY for openai/gpt-5.2.', + ); + } + } + throw new Error(`No API key found for provider "${provider}".`); } diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index 883d14614..1578db290 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -6,6 +6,11 @@ import { type OAuthCredentials, type OAuthProvider, } from "@mariozechner/pi-ai"; +import { ensureAuthProfileStore, listProfilesForProvider } from "../agents/auth-profiles.js"; +import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js"; +import { getCustomProviderApiKey, resolveEnvApiKey } from "../agents/model-auth.js"; +import { loadModelCatalog } from "../agents/model-catalog.js"; +import { resolveConfiguredModelRef } from "../agents/model-selection.js"; import { isRemoteEnvironment, loginAntigravityVpsAware, @@ -58,6 +63,82 @@ import { defaultRuntime } from "../runtime.js"; import { resolveUserPath, sleep } from "../utils.js"; import type { WizardPrompter } from "./prompts.js"; +const OPENAI_CODEX_DEFAULT_MODEL = "openai-codex/gpt-5.2"; + +function shouldSetOpenAICodexModel(model?: string): boolean { + const trimmed = model?.trim(); + if (!trimmed) return true; + const normalized = trimmed.toLowerCase(); + if (normalized.startsWith("openai-codex/")) return false; + if (normalized.startsWith("openai/")) return true; + return normalized === "gpt" || normalized === "gpt-mini"; +} + +function applyOpenAICodexModelDefault( + cfg: ClawdbotConfig, +): { next: ClawdbotConfig; changed: boolean } { + if (!shouldSetOpenAICodexModel(cfg.agent?.model)) { + return { next: cfg, changed: false }; + } + return { + next: { + ...cfg, + agent: { + ...cfg.agent, + model: OPENAI_CODEX_DEFAULT_MODEL, + }, + }, + changed: true, + }; +} + +async function warnIfModelConfigLooksOff( + config: ClawdbotConfig, + prompter: WizardPrompter, +) { + const ref = resolveConfiguredModelRef({ + cfg: config, + defaultProvider: DEFAULT_PROVIDER, + defaultModel: DEFAULT_MODEL, + }); + const warnings: string[] = []; + const catalog = await loadModelCatalog({ config, useCache: false }); + if (catalog.length > 0) { + const known = catalog.some( + (entry) => entry.provider === ref.provider && entry.id === ref.model, + ); + if (!known) { + warnings.push( + `Model not found: ${ref.provider}/${ref.model}. Update agent.model or run /models list.`, + ); + } + } + + const store = ensureAuthProfileStore(); + const hasProfile = listProfilesForProvider(store, ref.provider).length > 0; + const envKey = resolveEnvApiKey(ref.provider); + const customKey = getCustomProviderApiKey(config, ref.provider); + if (!hasProfile && !envKey && !customKey) { + warnings.push( + `No auth configured for provider "${ref.provider}". The agent may fail until credentials are added.`, + ); + } + + if (ref.provider === "openai") { + const hasCodex = + listProfilesForProvider(store, "openai-codex").length > 0; + if (hasCodex) { + warnings.push( + `Detected OpenAI Codex OAuth. Consider setting agent.model to ${OPENAI_CODEX_DEFAULT_MODEL}.`, + ); + } + } + + if (warnings.length > 0) { + await prompter.note(warnings.join("\n"), "Model check"); + } +} + export async function runOnboardingWizard( opts: OnboardOptions, runtime: RuntimeEnv = defaultRuntime, @@ -287,6 +368,14 @@ export async function runOnboardingWizard( provider: "openai-codex", mode: "oauth", }); + const applied = applyOpenAICodexModelDefault(nextConfig); + nextConfig = applied.next; + if (applied.changed) { + await prompter.note( + `Default model set to ${OPENAI_CODEX_DEFAULT_MODEL}`, + "Model configured", + ); + } } } catch (err) { spin.stop("OpenAI OAuth failed"); @@ -380,6 +469,8 @@ export async function runOnboardingWizard( nextConfig = applyMinimaxConfig(nextConfig); } + await warnIfModelConfigLooksOff(nextConfig, prompter); + const portRaw = await prompter.text({ message: "Gateway port", initialValue: String(localPort), From 00061b2fd3d6147f11988b5df75693c56a076de7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 03:05:56 +0100 Subject: [PATCH 058/110] fix: harden config form --- CHANGELOG.md | 1 + src/agents/model-auth.test.ts | 10 +- src/wizard/onboarding.ts | 39 ++- ui/src/ui/config-form.browser.test.ts | 116 ++++++++- ui/src/ui/controllers/config.test.ts | 26 +- ui/src/ui/controllers/config.ts | 8 +- ui/src/ui/views/config-form.ts | 347 +++++++++++++++++++++++-- ui/src/ui/views/config.browser.test.ts | 44 ++++ ui/src/ui/views/config.ts | 24 +- 9 files changed, 577 insertions(+), 38 deletions(-) create mode 100644 ui/src/ui/views/config.browser.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ed9ccd79..8aad296b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ - Onboarding: when OpenAI Codex OAuth is used, default to `openai-codex/gpt-5.2` and warn if the selected model lacks auth. - CLI: auto-migrate legacy config entries on command start (same behavior as gateway startup). - Auth: prioritize OAuth profiles but fall back to API keys when refresh fails; stored profiles now load without explicit auth order. +- Control UI: harden config Form view with schema normalization, map editing, and guardrails to prevent data loss on save. - Docs: add group chat participation guidance to the AGENTS template. - Gmail: stop restart loop when `gog gmail watch serve` fails to bind (address already in use). - Linux: auto-attempt lingering during onboarding (try without sudo, fallback to sudo) and prompt on install/restart to keep the gateway alive after logout/idle. Thanks @tobiasbischoff for PR #237. diff --git a/src/agents/model-auth.test.ts b/src/agents/model-auth.test.ts index ac37fad6a..49900389f 100644 --- a/src/agents/model-auth.test.ts +++ b/src/agents/model-auth.test.ts @@ -132,9 +132,13 @@ describe("getApiKeyForModel", () => { vi.resetModules(); const { resolveApiKeyForProvider } = await import("./model-auth.js"); - await expect( - resolveApiKeyForProvider({ provider: "openai" }), - ).rejects.toThrow(/openai-codex\/gpt-5\\.2/); + let error: unknown = null; + try { + await resolveApiKeyForProvider({ provider: "openai" }); + } catch (err) { + error = err; + } + expect(String(error)).toContain("openai-codex/gpt-5.2"); } finally { if (previousOpenAiKey === undefined) { delete process.env.OPENAI_API_KEY; diff --git a/src/wizard/onboarding.ts b/src/wizard/onboarding.ts index 1578db290..4077ac579 100644 --- a/src/wizard/onboarding.ts +++ b/src/wizard/onboarding.ts @@ -6,9 +6,15 @@ import { type OAuthCredentials, type OAuthProvider, } from "@mariozechner/pi-ai"; -import { ensureAuthProfileStore, listProfilesForProvider } from "../agents/auth-profiles.js"; +import { + ensureAuthProfileStore, + listProfilesForProvider, +} from "../agents/auth-profiles.js"; import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../agents/defaults.js"; -import { getCustomProviderApiKey, resolveEnvApiKey } from "../agents/model-auth.js"; +import { + getCustomProviderApiKey, + resolveEnvApiKey, +} from "../agents/model-auth.js"; import { loadModelCatalog } from "../agents/model-catalog.js"; import { resolveConfiguredModelRef } from "../agents/model-selection.js"; import { @@ -62,6 +68,7 @@ import type { RuntimeEnv } from "../runtime.js"; import { defaultRuntime } from "../runtime.js"; import { resolveUserPath, sleep } from "../utils.js"; import type { WizardPrompter } from "./prompts.js"; +import type { AgentModelListConfig } from "../config/types.js"; const OPENAI_CODEX_DEFAULT_MODEL = "openai-codex/gpt-5.2"; @@ -74,10 +81,22 @@ function shouldSetOpenAICodexModel(model?: string): boolean { return normalized === "gpt" || normalized === "gpt-mini"; } -function applyOpenAICodexModelDefault( - cfg: ClawdbotConfig, -): { next: ClawdbotConfig; changed: boolean } { - if (!shouldSetOpenAICodexModel(cfg.agent?.model)) { +function resolvePrimaryModel( + model?: AgentModelListConfig | string, +): string | undefined { + if (typeof model === "string") return model; + if (model && typeof model === "object" && typeof model.primary === "string") { + return model.primary; + } + return undefined; +} + +function applyOpenAICodexModelDefault(cfg: ClawdbotConfig): { + next: ClawdbotConfig; + changed: boolean; +} { + const current = resolvePrimaryModel(cfg.agent?.model); + if (!shouldSetOpenAICodexModel(current)) { return { next: cfg, changed: false }; } return { @@ -85,7 +104,10 @@ function applyOpenAICodexModelDefault( ...cfg, agent: { ...cfg.agent, - model: OPENAI_CODEX_DEFAULT_MODEL, + model: + cfg.agent?.model && typeof cfg.agent.model === "object" + ? { ...cfg.agent.model, primary: OPENAI_CODEX_DEFAULT_MODEL } + : { primary: OPENAI_CODEX_DEFAULT_MODEL }, }, }, changed: true, @@ -125,8 +147,7 @@ async function warnIfModelConfigLooksOff( } if (ref.provider === "openai") { - const hasCodex = - listProfilesForProvider(store, "openai-codex").length > 0; + const hasCodex = listProfilesForProvider(store, "openai-codex").length > 0; if (hasCodex) { warnings.push( `Detected OpenAI Codex OAuth. Consider setting agent.model to ${OPENAI_CODEX_DEFAULT_MODEL}.`, diff --git a/ui/src/ui/config-form.browser.test.ts b/ui/src/ui/config-form.browser.test.ts index 9ade22641..8de0b25ab 100644 --- a/ui/src/ui/config-form.browser.test.ts +++ b/ui/src/ui/config-form.browser.test.ts @@ -1,7 +1,7 @@ import { render } from "lit"; import { describe, expect, it, vi } from "vitest"; -import { renderConfigForm } from "./views/config-form"; +import { analyzeConfigSchema, renderConfigForm } from "./views/config-form"; const rootSchema = { type: "object", @@ -28,6 +28,14 @@ const rootSchema = { enabled: { type: "boolean", }, + bind: { + anyOf: [ + { const: "auto" }, + { const: "lan" }, + { const: "tailnet" }, + { const: "loopback" }, + ], + }, }, }; @@ -35,12 +43,14 @@ describe("config form renderer", () => { it("renders inputs and patches values", () => { const onPatch = vi.fn(); const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); render( renderConfigForm({ - schema: rootSchema, + schema: analysis.schema, uiHints: { "gateway.auth.token": { label: "Gateway Token", sensitive: true }, }, + unsupportedPaths: analysis.unsupportedPaths, value: {}, onPatch, }), @@ -79,10 +89,12 @@ describe("config form renderer", () => { it("adds and removes array entries", () => { const onPatch = vi.fn(); const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); render( renderConfigForm({ - schema: rootSchema, + schema: analysis.schema, uiHints: {}, + unsupportedPaths: analysis.unsupportedPaths, value: { allowFrom: ["+1"] }, onPatch, }), @@ -103,4 +115,102 @@ describe("config form renderer", () => { removeButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); expect(onPatch).toHaveBeenCalledWith(["allowFrom"], []); }); + + it("renders union literals as select options", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const analysis = analyzeConfigSchema(rootSchema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: {}, + unsupportedPaths: analysis.unsupportedPaths, + value: { bind: "auto" }, + onPatch, + }), + container, + ); + + const selects = Array.from(container.querySelectorAll("select")); + const bindSelect = selects.find((el) => + Array.from(el.options).some((opt) => opt.value === "tailnet"), + ) as HTMLSelectElement | undefined; + expect(bindSelect).not.toBeUndefined(); + if (!bindSelect) return; + bindSelect.value = "tailnet"; + bindSelect.dispatchEvent(new Event("change", { bubbles: true })); + expect(onPatch).toHaveBeenCalledWith(["bind"], "tailnet"); + }); + + it("renders map fields from additionalProperties", () => { + const onPatch = vi.fn(); + const container = document.createElement("div"); + const schema = { + type: "object", + properties: { + slack: { + type: "object", + additionalProperties: { + type: "string", + }, + }, + }, + }; + const analysis = analyzeConfigSchema(schema); + render( + renderConfigForm({ + schema: analysis.schema, + uiHints: {}, + unsupportedPaths: analysis.unsupportedPaths, + value: { slack: { channelA: "ok" } }, + onPatch, + }), + container, + ); + + const removeButton = Array.from(container.querySelectorAll("button")).find( + (btn) => btn.textContent?.trim() === "Remove", + ); + expect(removeButton).not.toBeUndefined(); + removeButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + expect(onPatch).toHaveBeenCalledWith(["slack"], {}); + }); + + it("flags unsupported unions", () => { + const schema = { + type: "object", + properties: { + mixed: { + anyOf: [{ type: "string" }, { type: "number" }], + }, + }, + }; + const analysis = analyzeConfigSchema(schema); + expect(analysis.unsupportedPaths).toContain("mixed"); + }); + + it("supports nullable types", () => { + const schema = { + type: "object", + properties: { + note: { type: ["string", "null"] }, + }, + }; + const analysis = analyzeConfigSchema(schema); + expect(analysis.unsupportedPaths).not.toContain("note"); + }); + + it("flags additionalProperties true", () => { + const schema = { + type: "object", + properties: { + extra: { + type: "object", + additionalProperties: true, + }, + }, + }; + const analysis = analyzeConfigSchema(schema); + expect(analysis.unsupportedPaths).toContain("extra"); + }); }); diff --git a/ui/src/ui/controllers/config.test.ts b/ui/src/ui/controllers/config.test.ts index f8ee03dc0..87fda4ce1 100644 --- a/ui/src/ui/controllers/config.test.ts +++ b/ui/src/ui/controllers/config.test.ts @@ -1,6 +1,10 @@ import { describe, expect, it } from "vitest"; -import { applyConfigSnapshot, type ConfigState } from "./config"; +import { + applyConfigSnapshot, + updateConfigFormValue, + type ConfigState, +} from "./config"; import { defaultDiscordActions, defaultSlackActions, @@ -137,3 +141,23 @@ describe("applyConfigSnapshot", () => { expect(state.slackForm.actions).toEqual(defaultSlackActions); }); }); + +describe("updateConfigFormValue", () => { + it("seeds from snapshot when form is null", () => { + const state = createState(); + state.configSnapshot = { + config: { telegram: { botToken: "t" }, gateway: { mode: "local" } }, + valid: true, + issues: [], + raw: "{}", + }; + + updateConfigFormValue(state, ["gateway", "port"], 18789); + + expect(state.configFormDirty).toBe(true); + expect(state.configForm).toEqual({ + telegram: { botToken: "t" }, + gateway: { mode: "local", port: 18789 }, + }); + }); +}); diff --git a/ui/src/ui/controllers/config.ts b/ui/src/ui/controllers/config.ts index 760b1d452..5844baad5 100644 --- a/ui/src/ui/controllers/config.ts +++ b/ui/src/ui/controllers/config.ts @@ -402,7 +402,9 @@ export function updateConfigFormValue( path: Array, value: unknown, ) { - const base = cloneConfigObject(state.configForm ?? {}); + const base = cloneConfigObject( + state.configForm ?? state.configSnapshot?.config ?? {}, + ); setPathValue(base, path, value); state.configForm = base; state.configFormDirty = true; @@ -412,7 +414,9 @@ export function removeConfigFormValue( state: ConfigState, path: Array, ) { - const base = cloneConfigObject(state.configForm ?? {}); + const base = cloneConfigObject( + state.configForm ?? state.configSnapshot?.config ?? {}, + ); removePathValue(base, path); state.configForm = base; state.configFormDirty = true; diff --git a/ui/src/ui/views/config-form.ts b/ui/src/ui/views/config-form.ts index 29bb0af99..dcf5d01f3 100644 --- a/ui/src/ui/views/config-form.ts +++ b/ui/src/ui/views/config-form.ts @@ -2,9 +2,11 @@ import { html, nothing } from "lit"; import type { ConfigUiHint, ConfigUiHints } from "../types"; export type ConfigFormProps = { - schema: unknown | null; + schema: JsonSchema | null; uiHints: ConfigUiHints; value: Record | null; + disabled?: boolean; + unsupportedPaths?: string[]; onPatch: (path: Array, value: unknown) => void; }; @@ -14,22 +16,26 @@ type JsonSchema = { description?: string; properties?: Record; items?: JsonSchema | JsonSchema[]; + additionalProperties?: JsonSchema | boolean; enum?: unknown[]; + const?: unknown; default?: unknown; anyOf?: JsonSchema[]; oneOf?: JsonSchema[]; allOf?: JsonSchema[]; + nullable?: boolean; }; export function renderConfigForm(props: ConfigFormProps) { if (!props.schema) { return html`

Schema unavailable.
`; } - const schema = props.schema as JsonSchema; + const schema = props.schema; const value = props.value ?? {}; if (schemaType(schema) !== "object" || !schema.properties) { return html`
Unsupported schema. Use Raw.
`; } + const unsupported = new Set(props.unsupportedPaths ?? []); const entries = Object.entries(schema.properties); const sorted = entries.sort((a, b) => { const orderA = hintForPath([a[0]], props.uiHints)?.order ?? 0; @@ -46,6 +52,8 @@ export function renderConfigForm(props: ConfigFormProps) { value: (value as Record)[key], path: [key], hints: props.uiHints, + unsupported, + disabled: props.disabled ?? false, onPatch: props.onPatch, }), )} @@ -58,13 +66,24 @@ function renderNode(params: { value: unknown; path: Array; hints: ConfigUiHints; + unsupported: Set; + disabled: boolean; + showLabel?: boolean; onPatch: (path: Array, value: unknown) => void; }) { - const { schema, value, path, hints, onPatch } = params; + const { schema, value, path, hints, unsupported, disabled, onPatch } = params; + const showLabel = params.showLabel ?? true; const type = schemaType(schema); const hint = hintForPath(path, hints); const label = hint?.label ?? schema.title ?? humanize(String(path.at(-1))); const help = hint?.help ?? schema.description; + const key = pathKey(path); + + if (unsupported.has(key)) { + return html`
+ ${label}: unsupported schema node. Use Raw. +
`; + } if (schema.anyOf || schema.oneOf || schema.allOf) { return html`
@@ -75,7 +94,11 @@ function renderNode(params: { if (type === "object") { const props = schema.properties ?? {}; const entries = Object.entries(props); - if (entries.length === 0) return nothing; + const hasMap = + schema.additionalProperties && + typeof schema.additionalProperties === "object"; + if (entries.length === 0 && !hasMap) return nothing; + const reservedKeys = new Set(entries.map(([key]) => key)); return html`
${label} @@ -86,9 +109,23 @@ function renderNode(params: { value: value && typeof value === "object" ? (value as any)[key] : undefined, path: [...path, key], hints, + unsupported, onPatch, + disabled, }), )} + ${hasMap + ? renderMapField({ + schema: schema.additionalProperties as JsonSchema, + value: value && typeof value === "object" ? (value as any) : {}, + path, + hints, + unsupported, + disabled, + reservedKeys, + onPatch, + }) + : nothing}
`; } @@ -101,14 +138,15 @@ function renderNode(params: { return html`
- ${label} -
@@ -121,11 +159,14 @@ function renderNode(params: { value: entry, path: [...path, index], hints, + unsupported, + disabled, onPatch, }) : nothing} +
+ ${entries.length === 0 + ? html`
No entries yet.
` + : entries.map(([key, entryValue]) => { + const valuePath = [...path, key]; + return html`
+ { + const nextKey = (e.target as HTMLInputElement).value.trim(); + if (!nextKey || nextKey === key) return; + const next = { ...(value ?? {}) }; + if (nextKey in next) return; + next[nextKey] = next[key]; + delete next[key]; + onPatch(path, next); + }} + /> +
+ ${renderNode({ + schema, + value: entryValue, + path: valuePath, + hints, + unsupported, + disabled, + showLabel: false, + onPatch, + })} +
+ +
`; + })} +
+ `; +} + +export type ConfigSchemaAnalysis = { + schema: JsonSchema | null; + unsupportedPaths: string[]; +}; + +export function analyzeConfigSchema(raw: unknown): ConfigSchemaAnalysis { + if (!raw || typeof raw !== "object") { + return { schema: null, unsupportedPaths: [""] }; + } + const result = normalizeSchemaNode(raw as JsonSchema, []); + return result; +} + +function normalizeSchemaNode( + schema: JsonSchema, + path: Array, +): ConfigSchemaAnalysis { + const unsupportedPaths: string[] = []; + const normalized = { ...schema }; + const pathLabel = pathKey(path) || ""; + + if (schema.anyOf || schema.oneOf || schema.allOf) { + const union = normalizeUnion(schema, path); + if (union) return union; + unsupportedPaths.push(pathLabel); + return { schema, unsupportedPaths }; + } + + const nullable = + Array.isArray(schema.type) && schema.type.includes("null"); + const type = + schemaType(schema) ?? + (schema.properties || schema.additionalProperties ? "object" : undefined); + normalized.type = type ?? schema.type; + normalized.nullable = nullable || schema.nullable; + + if (normalized.enum) { + const { enumValues, nullable: enumNullable } = normalizeEnumValues( + normalized.enum, + ); + normalized.enum = enumValues; + if (enumNullable) normalized.nullable = true; + if (enumValues.length === 0) { + unsupportedPaths.push(pathLabel); + } + } + + if (type === "object") { + const props = schema.properties ?? {}; + const normalizedProps: Record = {}; + for (const [key, child] of Object.entries(props)) { + const result = normalizeSchemaNode(child, [...path, key]); + if (result.schema) normalizedProps[key] = result.schema; + unsupportedPaths.push(...result.unsupportedPaths); + } + normalized.properties = normalizedProps; + + if (schema.additionalProperties === true) { + unsupportedPaths.push(pathLabel); + } else if (schema.additionalProperties === false) { + normalized.additionalProperties = false; + } else if (schema.additionalProperties) { + const result = normalizeSchemaNode( + schema.additionalProperties, + [...path, "*"], + ); + normalized.additionalProperties = result.schema ?? schema.additionalProperties; + if (result.unsupportedPaths.length > 0) { + unsupportedPaths.push(pathLabel); + } + } + } else if (type === "array") { + const itemSchema = Array.isArray(schema.items) + ? schema.items[0] + : schema.items; + if (!itemSchema) { + unsupportedPaths.push(pathLabel); + } else { + const result = normalizeSchemaNode(itemSchema, [...path, "*"]); + normalized.items = result.schema ?? itemSchema; + if (result.unsupportedPaths.length > 0) { + unsupportedPaths.push(pathLabel); + } + } + } else if ( + type === "string" || + type === "number" || + type === "integer" || + type === "boolean" + ) { + // ok + } else if (!normalized.enum) { + unsupportedPaths.push(pathLabel); + } + + return { + schema: normalized, + unsupportedPaths: Array.from(new Set(unsupportedPaths)), + }; +} + +function normalizeUnion( + schema: JsonSchema, + path: Array, +): ConfigSchemaAnalysis | null { + const variants = schema.anyOf ?? schema.oneOf ?? schema.allOf; + if (!variants) return null; + const values: unknown[] = []; + const nonLiteral: JsonSchema[] = []; + let nullable = false; + for (const variant of variants) { + if (!variant || typeof variant !== "object") return null; + if (Array.isArray(variant.enum)) { + const { enumValues, nullable: enumNullable } = normalizeEnumValues( + variant.enum, + ); + values.push(...enumValues); + if (enumNullable) nullable = true; + continue; + } + if ("const" in variant) { + if (variant.const === null || variant.const === undefined) { + nullable = true; + continue; + } + values.push(variant.const); + continue; + } + if (schemaType(variant) === "null") { + nullable = true; + continue; + } + nonLiteral.push(variant); + } + + if (values.length > 0 && nonLiteral.length === 0) { + const unique: unknown[] = []; + for (const value of values) { + if (!unique.some((entry) => Object.is(entry, value))) unique.push(value); + } + return { + schema: { + ...schema, + enum: unique, + nullable, + anyOf: undefined, + oneOf: undefined, + allOf: undefined, + }, + unsupportedPaths: [], + }; + } + + if (nonLiteral.length === 1) { + const result = normalizeSchemaNode(nonLiteral[0], path); + if (result.schema) { + result.schema.nullable = true; + } + return result; + } + + return null; +} + +function normalizeEnumValues(values: unknown[]) { + const filtered = values.filter((value) => value !== null && value !== undefined); + const nullable = filtered.length !== values.length; + const unique: unknown[] = []; + for (const value of filtered) { + if (!unique.some((entry) => Object.is(entry, value))) unique.push(value); + } + return { enumValues: unique, nullable }; +} diff --git a/ui/src/ui/views/config.browser.test.ts b/ui/src/ui/views/config.browser.test.ts new file mode 100644 index 000000000..c975c4631 --- /dev/null +++ b/ui/src/ui/views/config.browser.test.ts @@ -0,0 +1,44 @@ +import { render } from "lit"; +import { describe, expect, it, vi } from "vitest"; + +import { renderConfig } from "./config"; + +describe("config view", () => { + it("disables save when form is unsafe", () => { + const container = document.createElement("div"); + render( + renderConfig({ + raw: "{\n}\n", + valid: true, + issues: [], + loading: false, + saving: false, + connected: true, + schema: { + type: "object", + properties: { + mixed: { anyOf: [{ type: "string" }, { type: "number" }] }, + }, + }, + schemaLoading: false, + uiHints: {}, + formMode: "form", + formValue: { mixed: "x" }, + onRawChange: vi.fn(), + onFormModeChange: vi.fn(), + onFormPatch: vi.fn(), + onReload: vi.fn(), + onSave: vi.fn(), + }), + container, + ); + + const saveButton = Array.from( + container.querySelectorAll("button"), + ).find((btn) => btn.textContent?.trim() === "Save") as + | HTMLButtonElement + | undefined; + expect(saveButton).not.toBeUndefined(); + expect(saveButton?.disabled).toBe(true); + }); +}); diff --git a/ui/src/ui/views/config.ts b/ui/src/ui/views/config.ts index c11ee4204..27571d1ab 100644 --- a/ui/src/ui/views/config.ts +++ b/ui/src/ui/views/config.ts @@ -1,6 +1,6 @@ import { html, nothing } from "lit"; import type { ConfigUiHints } from "../types"; -import { renderConfigForm } from "./config-form"; +import { analyzeConfigSchema, renderConfigForm } from "./config-form"; export type ConfigProps = { raw: string; @@ -24,6 +24,16 @@ export type ConfigProps = { export function renderConfig(props: ConfigProps) { const validity = props.valid == null ? "unknown" : props.valid ? "valid" : "invalid"; + const analysis = analyzeConfigSchema(props.schema); + const formUnsafe = analysis.schema + ? analysis.unsupportedPaths.length > 0 + : false; + const canSaveForm = + Boolean(props.formValue) && !props.loading && !formUnsafe; + const canSave = + props.connected && + !props.saving && + (props.formMode === "raw" ? true : canSaveForm); return html`
@@ -52,7 +62,7 @@ export function renderConfig(props: ConfigProps) {
` : html`