From 0f06e9926b6a765883f835e7f771adafd88c9778 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 24 Dec 2025 00:22:57 +0000 Subject: [PATCH] docs: update routing/messages/session config --- CHANGELOG.md | 17 ++++++------ README.md | 4 +-- docs/agent-send.md | 2 +- docs/agent.md | 2 +- docs/audio.md | 9 ++----- docs/clawd.md | 44 +++++++++++++++--------------- docs/configuration.md | 60 ++++++++++++++++++++++++----------------- docs/group-messages.md | 6 ++--- docs/health.md | 2 +- docs/heartbeat.md | 6 ++--- docs/index.md | 4 +-- docs/mac/webchat.md | 2 +- docs/onboarding.md | 2 +- docs/security.md | 10 ++++--- docs/session.md | 18 ++++++------- docs/telegram.md | 2 +- docs/troubleshooting.md | 6 ++--- docs/whatsapp.md | 18 ++++++------- 18 files changed, 109 insertions(+), 105 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dc119aa4b..3cb7809dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ - WhatsApp send now preserves existing JIDs (including group `@g.us`) instead of coercing to `@s.whatsapp.net`. (Thanks @arun-8687.) - Telegram/WhatsApp: native replies now target the original inbound message; reply context is appended to `Body` and captured in `ReplyTo*` fields. (Thanks @joshp123 for the PR and follow-up question.) - WhatsApp web creds persistence hardened; credentials are restored before auth checks and QR login auto-restarts if it stalls. -- Group chats now honor `inbound.groupChat.requireMention=false` as the default activation when no per-group override exists. +- Group chats now honor `routing.groupChat.requireMention=false` as the default activation when no per-group override exists. - Gateway auth no longer supports PAM/system mode; use token or shared password. - Tailscale Funnel now requires password auth (no token-only public exposure). - Group `/new` resets now work with @mentions so activation guidance appears on fresh sessions. @@ -21,6 +21,7 @@ - WhatsApp group typing now starts immediately only when the bot is mentioned; otherwise it waits until real output exists. - Streamed `` segments are stripped before partial replies are emitted. - System prompt now tags allowlisted owner numbers as the user identity to avoid mistaken “friend” assumptions. +- LM Studio/Ollama replies now require tags; streaming ignores content until begins. - Canvas defaults/A2UI auto-nav aligned; debug status overlay centered; redundant await removed in `CanvasManager`. - Gateway launchd loop fixed by removing redundant `kickstart -k`. - CLI now hints when Peekaboo is unauthorized. @@ -90,7 +91,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le ### Breaking - Renamed to **Clawdis**: defaults now live under `~/.clawdis` (sessions in `~/.clawdis/sessions/`, IPC at `~/.clawdis/clawdis.sock`, logs in `/tmp/clawdis`). Launchd labels and config filenames follow the new name; legacy stores are copied forward on first run. -- Pi only: `inbound.reply.agent.kind` accepts only `"pi"`, and the agent CLI/CLI flags for Claude/Codex/Gemini were removed. The Pi CLI runs in RPC mode with a persistent worker. +- Pi only: only the embedded Pi runtime remains, and the agent CLI/CLI flags for Claude/Codex/Gemini were removed. The Pi CLI runs in RPC mode with a persistent worker. - WhatsApp Web is the only transport; Twilio support and related CLI flags/tests were removed. - Direct chats now collapse into a single `main` session by default (no config needed); groups stay isolated as `group:`. - Gateway is now a loopback-only WebSocket daemon (`ws://127.0.0.1:18789`) that owns all providers/state; clients (CLI, WebChat, macOS app, nodes) connect to it. Start it explicitly (`clawdis gateway …`) or via Clawdis.app; helper subcommands no longer auto-spawn a gateway. @@ -138,7 +139,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le ## 1.5.0 — 2025-12-05 ### Breaking -- Dropped all non-Pi agents (Claude, Codex, Gemini, Opencode); `inbound.reply.agent.kind` now only accepts `"pi"` and related CLI helpers have been removed. +- Dropped all non-Pi agents (Claude, Codex, Gemini, Opencode); only the embedded Pi runtime remains and related CLI helpers have been removed. - Removed Twilio support and all related commands/options (webhook/up/provider flags/wait-poll); CLAWDIS is Baileys Web-only. ### Changes @@ -165,7 +166,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le ## 1.4.0 — 2025-12-03 ### Highlights -- **Thinking directives & state:** `/t|/think|/thinking ` (aliases off|minimal|low|medium|high|max/highest). Inline applies to that message; directive-only message pins the level for the session; `/think:off` clears. Resolution: inline > session override > `inbound.reply.thinkingDefault` > off. Pi gets `--thinking ` (except off); other agents append cue words (`think` → `think hard` → `think harder` → `ultrathink`). Heartbeat probe uses `HEARTBEAT /think:high`. +- **Thinking directives & state:** `/t|/think|/thinking ` (aliases off|minimal|low|medium|high|max/highest). Inline applies to that message; directive-only message pins the level for the session; `/think:off` clears. Resolution: inline > session override > `agent.thinkingDefault` > off. Pi gets `--thinking ` (except off); other agents append cue words (`think` → `think hard` → `think harder` → `ultrathink`). Heartbeat probe uses `HEARTBEAT /think:high`. - **Group chats (web provider):** Clawdis now fully supports WhatsApp groups: mention-gated triggers (including image-only @ mentions), recent group history injection, per-group sessions, sender attribution, and a first-turn primer with group subject/member roster; heartbeats are skipped for groups. - **Group session primer:** The first turn of a group session now tells the agent it is in a WhatsApp group and lists known members/subject so it can address the right speaker. - **Media failures are surfaced:** When a web auto-reply media fetch/send fails (e.g., HTTP 404), we now append a warning to the fallback text so you know the attachment was skipped. @@ -207,7 +208,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le ## 1.3.0 — 2025-12-02 ### Highlights -- **Pluggable agents (Claude, Pi, Codex, Opencode):** `inbound.reply.agent` selects CLI/parser; per-agent argv builders and NDJSON parsers enable swapping without template changes. +- **Pluggable agents (Claude, Pi, Codex, Opencode):** agent selection via config/CLI plus per-agent argv builders and NDJSON parsers enable swapping without template changes. - **Safety stop words:** `stop|esc|abort|wait|exit` immediately reply “Agent was aborted.” and mark the session so the next prompt is prefixed with an abort reminder. - **Agent session reliability:** Only Claude returns a stable `session_id`; others may reset between runs. @@ -224,7 +225,7 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le - Batched inbound messages with timestamps; typing indicator after sends. - Watchdog restarts WhatsApp after long inactivity; heartbeat logging includes minutes since last message. - Early `allowFrom` filtering before decryption. -- Same-phone mode with echo detection and optional `inbound.samePhoneMarker`. +- Same-phone mode with echo detection and optional message prefix marker. ## 1.2.2 — 2025-11-28 @@ -254,10 +255,10 @@ First Clawdis release post rebrand. This is a semver-major because we dropped le ## 1.1.0 — 2025-11-26 ### Changes -- Web auto-replies resize/recompress media and honor `inbound.reply.mediaMaxMb`. +- Web auto-replies resize/recompress media and honor `agent.mediaMaxMb`. - Detect media kind, enforce provider caps (images ≤6MB, audio/video ≤16MB, docs ≤100MB). - `session.sendSystemOnce` and optional `sessionIntro`. -- Typing indicator refresh during commands; configurable via `inbound.reply.typingIntervalSeconds`. +- Typing indicator refresh during commands; configurable via `agent.typingIntervalSeconds`. - Optional audio transcription via external CLI. - Command replies return structured payload/meta; respect `mediaMaxMb`; log Claude metadata; include `cwd` in timeout messages. - Web provider refactor; logout command; web-only gateway start helper. diff --git a/README.md b/README.md index 1cf9a9ea0..23561e4c5 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ Minimal `~/.clawdis/clawdis.json`: ```json5 { - inbound: { + routing: { allowFrom: ["+1234567890"] } } @@ -152,7 +152,7 @@ Minimal `~/.clawdis/clawdis.json`: ### WhatsApp - Link the device: `pnpm clawdis login` (stores creds in `~/.clawdis/credentials`). -- Allowlist who can talk to the assistant via `inbound.allowFrom`. +- Allowlist who can talk to the assistant via `routing.allowFrom`. ### Telegram diff --git a/docs/agent-send.md b/docs/agent-send.md index fd98c7543..097f72d18 100644 --- a/docs/agent-send.md +++ b/docs/agent-send.md @@ -11,7 +11,7 @@ read_when: - Required: `--message ` - Session selection: - If `--session-id` is given, reuse it. - - Else if `--to ` is given, derive the session key from `inbound.session.scope` (direct chats collapse to `inbound.session.mainKey`). + - Else if `--to ` is given, derive the session key from `session.scope` (direct chats collapse to `session.mainKey`). - Runs the embedded Pi agent (configured via `agent`). - Thinking/verbose: - Flags `--thinking ` and `--verbose ` persist into the session store. diff --git a/docs/agent.md b/docs/agent.md index c707511fa..ede88e0c9 100644 --- a/docs/agent.md +++ b/docs/agent.md @@ -76,7 +76,7 @@ Incoming user messages are queued while the agent is streaming. The queue is che At minimum, set: - `agent.workspace` -- `inbound.allowFrom` (strongly recommended) +- `routing.allowFrom` (strongly recommended) --- diff --git a/docs/audio.md b/docs/audio.md index c97e47cde..d45e6e647 100644 --- a/docs/audio.md +++ b/docs/audio.md @@ -7,7 +7,7 @@ read_when: # Audio / Voice Notes — 2025-12-05 ## What works -- **Optional transcription**: If `inbound.transcribeAudio.command` is set in `~/.clawdis/clawdis.json`, CLAWDIS will: +- **Optional transcription**: If `routing.transcribeAudio.command` is set in `~/.clawdis/clawdis.json`, CLAWDIS will: 1) Download inbound audio to a temp path when WhatsApp only provides a URL. 2) Run the configured CLI (templated with `{{MediaPath}}`), expecting transcript on stdout. 3) Replace `Body` with the transcript, set `{{Transcript}}`, and prepend the original media path plus a `Transcript:` section in the command prompt so models see both. @@ -18,7 +18,7 @@ read_when: Requires `OPENAI_API_KEY` in env and `openai` CLI installed: ```json5 { - inbound: { + routing: { transcribeAudio: { command: [ "openai", @@ -32,11 +32,6 @@ Requires `OPENAI_API_KEY` in env and `openai` CLI installed: "text" ], timeoutSeconds: 45 - }, - reply: { - mode: "command", - command: ["pi", "{{Body}}"], - agent: { kind: "pi" } } } } diff --git a/docs/clawd.md b/docs/clawd.md index cf296c713..9b2e699cd 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -17,7 +17,7 @@ You’re putting an agent in a position to: - send messages back out via WhatsApp/Telegram Start conservative: -- Always set `inbound.allowFrom` (never run open-to-the-world on your personal Mac). +- Always set `routing.allowFrom` (never run open-to-the-world on your personal Mac). - Use a dedicated WhatsApp number for the assistant. - Keep heartbeats disabled until you trust the setup (`heartbeatMinutes: 0`). @@ -74,7 +74,7 @@ clawdis gateway --port 18789 ```json5 { - inbound: { + routing: { allowFrom: ["+15555550123"] } } @@ -98,7 +98,7 @@ Optional: choose a different workspace with `agent.workspace` (supports `~`). ```json5 { - inbound: { + agent: { workspace: "~/clawd" } } @@ -116,27 +116,27 @@ Example: ```json5 { logging: { level: "info" }, - inbound: { - allowFrom: ["+15555550123"], + agent: { + provider: "anthropic", + model: "claude-opus-4-5", workspace: "~/clawd", + thinkingDefault: "high", + timeoutSeconds: 1800, + // Start with 0; enable later. + heartbeatMinutes: 0 + }, + routing: { + allowFrom: ["+15555550123"], groupChat: { requireMention: true, mentionPatterns: ["@clawd", "clawd"] - }, - agent: { - provider: "anthropic", - model: "claude-opus-4-5", - thinkingDefault: "high", - timeoutSeconds: 1800, - // Start with 0; enable later. - heartbeatMinutes: 0 - }, - session: { - scope: "per-sender", - resetTriggers: ["/new", "/reset"], - idleMinutes: 10080, - mainKey: "main" } + }, + session: { + scope: "per-sender", + resetTriggers: ["/new", "/reset"], + idleMinutes: 10080, + mainKey: "main" } } ``` @@ -155,10 +155,8 @@ When `agent.heartbeatMinutes > 0`, CLAWDIS periodically runs a heartbeat prompt ```json5 { - inbound: { - agent: { - heartbeatMinutes: 30 - } + agent: { + heartbeatMinutes: 30 } } ``` diff --git a/docs/configuration.md b/docs/configuration.md index dc25dd626..089587902 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -9,10 +9,11 @@ read_when: CLAWDIS reads an optional **JSON5** config from `~/.clawdis/clawdis.json` (comments + trailing commas allowed). If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to: -- restrict who can trigger the bot (`inbound.allowFrom`) -- tune group mention behavior (`inbound.groupChat`) +- restrict who can trigger the bot (`routing.allowFrom`) +- tune group mention behavior (`routing.groupChat`) +- customize message prefixes (`messages`) - set the agent’s workspace (`agent.workspace`) -- tune the embedded agent (`agent`) and session behavior (`inbound.session`) +- tune the embedded agent (`agent`) and session behavior (`session`) - set the agent’s identity (`identity`) ## Minimal config (recommended starting point) @@ -20,7 +21,7 @@ If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per- ```json5 { agent: { workspace: "~/clawd" }, - inbound: { allowFrom: ["+15555550123"] } + routing: { allowFrom: ["+15555550123"] } } ``` @@ -31,8 +32,8 @@ If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per- Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant. If set, CLAWDIS derives defaults (only when you haven’t set them explicitly): -- `inbound.responsePrefix` from `identity.emoji` -- `inbound.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups) +- `messages.responsePrefix` from `identity.emoji` +- `routing.groupChat.mentionPatterns` from `identity.name` (so “@Samantha” works in groups) ```json5 { @@ -59,23 +60,23 @@ If set, CLAWDIS derives defaults (only when you haven’t set them explicitly): } ``` -### `inbound.allowFrom` +### `routing.allowFrom` Allowlist of E.164 phone numbers that may trigger auto-replies. ```json5 { - inbound: { allowFrom: ["+15555550123", "+447700900123"] } + routing: { allowFrom: ["+15555550123", "+447700900123"] } } ``` -### `inbound.groupChat` +### `routing.groupChat` Group messages default to **require mention** (either metadata mention or regex patterns). ```json5 { - inbound: { + routing: { groupChat: { mentionPatterns: ["@clawd", "clawdbot", "clawd"], historyLimit: 50 @@ -96,6 +97,20 @@ Default: `~/clawd`. } ``` +### `messages` + +Controls inbound/outbound prefixes and timestamps. + +```json5 +{ + messages: { + messagePrefix: "[clawdis]", + responsePrefix: "🦞", + timestampPrefix: "Europe/London" + } +} +``` + ### `agent` Controls the embedded agent runtime (provider/model/thinking/verbose/timeouts). @@ -117,8 +132,7 @@ Controls the embedded agent runtime (provider/model/thinking/verbose/timeouts). mediaMaxMb: 5, heartbeatMinutes: 30, contextTokens: 200000 - }, - inbound: { workspace: "~/clawd" } + } } ``` @@ -138,9 +152,7 @@ Select the model via `agent.provider` + `agent.model`. ```json5 { - inbound: { - agent: { provider: "custom-proxy", model: "llama-3.1-8b" } - }, + agent: { provider: "custom-proxy", model: "llama-3.1-8b" }, models: { mode: "merge", providers: { @@ -172,20 +184,18 @@ Notes: - Override the agent config root with `CLAWDIS_AGENT_DIR` (or `PI_CODING_AGENT_DIR`) if you want `models.json` stored elsewhere. -### `inbound.session` +### `session` Controls session scoping, idle expiry, reset triggers, and where the session store is written. ```json5 { - inbound: { - session: { - scope: "per-sender", - idleMinutes: 60, - resetTriggers: ["/new", "/reset"], - store: "~/.clawdis/sessions/sessions.json", - mainKey: "main" - } + session: { + scope: "per-sender", + idleMinutes: 60, + resetTriggers: ["/new", "/reset"], + store: "~/.clawdis/sessions/sessions.json", + mainKey: "main" } } ``` @@ -377,7 +387,7 @@ clawdis dns setup --apply ## Template variables -Template placeholders are expanded in `inbound.transcribeAudio.command` (and any future templated command fields). +Template placeholders are expanded in `routing.transcribeAudio.command` (and any future templated command fields). | Variable | Description | |----------|-------------| diff --git a/docs/group-messages.md b/docs/group-messages.md index 191827d4b..c50a5a5d0 100644 --- a/docs/group-messages.md +++ b/docs/group-messages.md @@ -9,7 +9,7 @@ Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that ## 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`. Activation is controlled per group (command or UI), not via config. -- Group allowlist bypass: we still enforce `allowFrom` on the participant at inbox ingest, but group JIDs themselves no longer block replies. +- Group allowlist bypass: we still enforce `routing.allowFrom` on the participant at inbox ingest, but group JIDs themselves no longer block replies. - Per-group sessions: session keys look like `group:` so commands such as `/verbose on` or `/think:high` are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads. - Context injection: last N (default 50) group messages are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. - Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking. @@ -21,7 +21,7 @@ Add a `groupChat` block to `~/.clawdis/clawdis.json` so display-name pings work ```json5 { - "inbound": { + "routing": { "groupChat": { "historyLimit": 50, "mentionPatterns": [ @@ -45,7 +45,7 @@ Use the group chat command: - `/activation mention` - `/activation always` -Only the owner number (from `allowFrom`, defaulting to the bot’s own E.164 when unset) can change this. `/status` in the group shows the current activation mode. +Only the owner number (from `routing.allowFrom`, defaulting to the bot’s own E.164 when unset) can change this. `/status` in the group shows the current activation mode. ## How to use 1) Add Clawd UK (`+447700900123`) to the group. diff --git a/docs/health.md b/docs/health.md index 86e7ed82a..0581dcf18 100644 --- a/docs/health.md +++ b/docs/health.md @@ -22,7 +22,7 @@ Short guide to verify the WhatsApp Web / Baileys stack without guessing. ## When something fails - `logged out` or status 409–515 → relink with `clawdis logout` then `clawdis login`. - Gateway unreachable → start it: `clawdis gateway --port 18789` (use `--force` if the port is busy). -- No inbound messages → confirm linked phone is online and the sender is allowed (`inbound.allowFrom`); for group chats, ensure mention rules match (`inbound.groupChat`). +- No inbound messages → confirm linked phone is online and the sender is allowed (`routing.allowFrom`); for group chats, ensure mention rules match (`routing.groupChat`). ## Dedicated "health" command `clawdis health --json` asks the running Gateway for its health snapshot (no direct Baileys socket from the CLI). It reports linked creds, auth age, Baileys connect result/status code, session-store summary, and a probe duration. It exits non-zero if the Gateway is unreachable or the probe fails/timeouts. Use `--timeout ` to override the 10s default. diff --git a/docs/heartbeat.md b/docs/heartbeat.md index 9ddc4fe70..22bcb9051 100644 --- a/docs/heartbeat.md +++ b/docs/heartbeat.md @@ -14,7 +14,7 @@ Goal: add a simple heartbeat poll for the embedded agent that only notifies user ## Config & defaults - New config key: `agent.heartbeatMinutes` (number of minutes; `0` disables). - Default: 30 minutes. -- New optional idle override for heartbeats: `inbound.session.heartbeatIdleMinutes` (defaults to `idleMinutes`). Heartbeat skips do **not** update the session `updatedAt` so idle expiry still works. +- New optional idle override for heartbeats: `session.heartbeatIdleMinutes` (defaults to `idleMinutes`). Heartbeat skips do **not** update the session `updatedAt` so idle expiry still works. ## Poller behavior - When gateway runs with command-mode auto-reply, start a timer with the resolved heartbeat interval. @@ -42,8 +42,8 @@ Goal: add a simple heartbeat poll for the embedded agent that only notifies user ## Documentation - Add a short README snippet under configuration showing `heartbeatMinutes` and the sentinel rule. - Expose CLI triggers: - - `clawdis heartbeat` (web provider, defaults to first `allowFrom`; optional `--to` override) + - `clawdis heartbeat` (web provider, defaults to first `routing.allowFrom`; optional `--to` override) - `--session-id ` forces resuming a specific session for that heartbeat - `clawdis gateway --heartbeat-now` to run the gateway loop with an immediate heartbeat - Gateway supports `--heartbeat-now` to fire once at startup. - - When multiple sessions are active or `allowFrom` is only `"*"`, require `--to ` or `--all` for manual heartbeats to avoid ambiguous targets. + - When multiple sessions are active or `routing.allowFrom` is only `"*"`, require `--to ` or `--all` for manual heartbeats to avoid ambiguous targets. diff --git a/docs/index.md b/docs/index.md index bff206253..841179915 100644 --- a/docs/index.md +++ b/docs/index.md @@ -98,13 +98,13 @@ clawdis send --to +15555550123 --message "Hello from CLAWDIS" Config lives at `~/.clawdis/clawdis.json`. - If you **do nothing**, CLAWDIS uses the bundled Pi binary in RPC mode with per-sender sessions. -- If you want to lock it down, start with `inbound.allowFrom` and (for groups) mention rules. +- If you want to lock it down, start with `routing.allowFrom` and (for groups) mention rules. Example: ```json5 { - inbound: { + routing: { allowFrom: ["+15555550123"], groupChat: { requireMention: true, mentionPatterns: ["@clawd"] } } diff --git a/docs/mac/webchat.md b/docs/mac/webchat.md index 0c47e3155..3c2b5b332 100644 --- a/docs/mac/webchat.md +++ b/docs/mac/webchat.md @@ -5,7 +5,7 @@ read_when: --- # Web Chat (macOS app) -The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses the **primary Clawd session** (`main` by default, configurable via `inbound.session.mainKey`). +The macOS menu bar app shows the WebChat UI as a native SwiftUI view and reuses the **primary Clawd session** (`main` by default, configurable via `session.mainKey`). - **Local mode**: connects directly to the local Gateway WebSocket. - **Remote mode**: forwards the Gateway WebSocket control port over SSH and uses that as the data plane. diff --git a/docs/onboarding.md b/docs/onboarding.md index f60768a49..9b536e0eb 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -95,7 +95,7 @@ We no longer collect identity in the onboarding wizard. Instead, the **first age Identity data still feeds the same defaults as before: -- outbound prefix emoji (`inbound.responsePrefix`) +- outbound prefix emoji (`messages.responsePrefix`) - group mention patterns / wake words - default session intro (“You are Samantha…”) - macOS UI labels diff --git a/docs/security.md b/docs/security.md index 9789ca6d2..c5c261bbb 100644 --- a/docs/security.md +++ b/docs/security.md @@ -42,7 +42,7 @@ This is social engineering 101. Create distrust, encourage snooping. ```json { - "inbound": { + "routing": { "allowFrom": ["+15555550123"] } } @@ -54,9 +54,11 @@ Only allow specific phone numbers to trigger your AI. Never use `["*"]` in produ ```json { - "groupChat": { - "requireMention": true, - "mentionPatterns": ["@clawd", "@mybot"] + "routing": { + "groupChat": { + "requireMention": true, + "mentionPatterns": ["@clawd", "@mybot"] + } } } ``` diff --git a/docs/session.md b/docs/session.md index 72585ef5a..f9f6264a2 100644 --- a/docs/session.md +++ b/docs/session.md @@ -5,7 +5,7 @@ read_when: --- # Session Management -Clawdis treats **one session as primary**. By default the canonical key is `main` for every direct chat; no configuration is required. You can rename it via `inbound.session.mainKey` if you really want, but there is still only a single primary session. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls. +Clawdis treats **one session as primary**. By default the canonical key is `main` for every direct chat; no configuration is required. You can rename it via `session.mainKey` if you really want, but there is still only a single primary session. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls. ## Gateway is the source of truth All session state is **owned by the gateway** (the “master” Clawdis). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files. @@ -26,7 +26,7 @@ All session state is **owned by the gateway** (the “master” Clawdis). UI cli - Group chats still isolate state with `group:` keys; do not reuse the primary key for groups. ## Lifecyle -- Idle expiry: `inbound.session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message. +- Idle expiry: `session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message. - Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdis runs a short “hello” greeting turn to confirm the reset. - Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them. @@ -34,14 +34,12 @@ All session state is **owned by the gateway** (the “master” Clawdis). UI cli ```json5 // ~/.clawdis/clawdis.json { - inbound: { - session: { - scope: "per-sender", // keep group keys separate - idleMinutes: 120, - resetTriggers: ["/new", "/reset"], - store: "~/.clawdis/sessions/sessions.json", - mainKey: "main" // optional rename; still a single primary - } + session: { + scope: "per-sender", // keep group keys separate + idleMinutes: 120, + resetTriggers: ["/new", "/reset"], + store: "~/.clawdis/sessions/sessions.json", + mainKey: "main" // optional rename; still a single primary } } ``` diff --git a/docs/telegram.md b/docs/telegram.md index 3f05b3d28..e65cdc50c 100644 --- a/docs/telegram.md +++ b/docs/telegram.md @@ -24,7 +24,7 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup - If you need a different public port/host, set `telegram.webhookUrl` to the externally reachable URL and use a reverse proxy to forward to `:8787`. 4) Direct chats: user sends the first message; all subsequent turns land in the shared `main` session (default, no extra config). 5) Groups: add the bot, disable privacy mode (or make it admin) so it can read messages; group threads stay on `group:` and require mention/command to trigger replies. -6) Optional allowlist: reuse `inbound.allowFrom` for direct chats by chat id (`123456789` or `telegram:123456789`). +6) Optional allowlist: reuse `routing.allowFrom` for direct chats by chat id (`123456789` or `telegram:123456789`). ## Capabilities & limits (Bot API) - Sees only messages sent after it’s added to a chat; no pre-history access. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3105e9e22..e4e1b0df5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -22,15 +22,15 @@ The agent was interrupted mid-response. ### Messages Not Triggering -**Check 1:** Is the sender in `allowFrom`? +**Check 1:** Is the sender in `routing.allowFrom`? ```bash -cat ~/.clawdis/clawdis.json | jq '.inbound.allowFrom' +cat ~/.clawdis/clawdis.json | jq '.routing.allowFrom' ``` **Check 2:** For group chats, is mention required? ```bash # The message must contain a pattern from mentionPatterns -cat ~/.clawdis/clawdis.json | jq '.inbound.groupChat' +cat ~/.clawdis/clawdis.json | jq '.routing.groupChat' ``` **Check 3:** Check the logs diff --git a/docs/whatsapp.md b/docs/whatsapp.md index c7260387e..b2f6a743c 100644 --- a/docs/whatsapp.md +++ b/docs/whatsapp.md @@ -30,8 +30,8 @@ Status: WhatsApp Web via Baileys only. Gateway owns the single session. - WhatsApp events come from `messages.upsert` (Baileys). - Status/broadcast chats are ignored. - Direct chats use E.164; groups use group JID. -- **Allowlist**: `inbound.allowFrom` enforced for direct chats only. - - If allowFrom is empty, default allowlist = self number (self-chat mode). +- **Allowlist**: `routing.allowFrom` enforced for direct chats only. + - If `routing.allowFrom` is empty, default allowlist = self number (self-chat mode). - **Self-chat mode**: avoids auto read receipts and ignores mention JIDs. - Read receipts sent for non-self-chat DMs. @@ -56,7 +56,7 @@ Status: WhatsApp Web via Baileys only. Gateway owns the single session. - `mention` (default): requires @mention or regex match. - `always`: always triggers. - `/activation mention|always` is owner-only. -- Owner = `inbound.allowFrom` (or self E.164 if unset). +- Owner = `routing.allowFrom` (or self E.164 if unset). - **History injection**: - Recent messages (default 50) inserted under: `[Chat messages since your last reply - for context]` @@ -98,14 +98,14 @@ Status: WhatsApp Web via Baileys only. Gateway owns the single session. - Logged-out => stop and require re-link. ## Config quick map -- `inbound.allowFrom` (DM allowlist). -- `inbound.groupChat.mentionPatterns` -- `inbound.groupChat.historyLimit` -- `inbound.messagePrefix` (inbound prefix) -- `inbound.responsePrefix` (outbound prefix) +- `routing.allowFrom` (DM allowlist). +- `routing.groupChat.mentionPatterns` +- `routing.groupChat.historyLimit` +- `messages.messagePrefix` (inbound prefix) +- `messages.responsePrefix` (outbound prefix) - `agent.mediaMaxMb` - `agent.heartbeatMinutes` -- `inbound.session.*` (scope, idle, store, mainKey) +- `session.*` (scope, idle, store, mainKey) - `web.heartbeatSeconds` - `web.reconnect.*`