diff --git a/README.md b/README.md index 5715d0366..f5e96e0d9 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ Your surfaces - **Canvas** — a live visual workspace you can drive from the agent. - **Automation-ready** — browser control, media handling, and tool streaming. - **Local-first control plane** — the Gateway owns state, everything else connects. +- **Group chats** — mention-based by default, `/activation always|mention` per group (owner-only). ## How it works (short) @@ -75,6 +76,17 @@ pnpm clawdis agent --message "Ship checklist" --thinking high If you run from source, prefer `pnpm clawdis …` (not global `clawdis`). +## Chat commands + +Send these in WhatsApp/Telegram/WebChat (group commands are owner-only): + +- `/status` — health + session info (group shows activation mode) +- `/new` or `/reset` — reset the session +- `/think ` — off|minimal|low|medium|high +- `/verbose on|off` +- `/restart` — restart the gateway (owner-only in groups) +- `/activation mention|always` — group activation toggle (groups only) + ## Architecture ### TypeScript Gateway (src/gateway/server.ts) @@ -171,6 +183,7 @@ Browser control (optional): - [`docs/index.md`](docs/index.md) (overview) - [`docs/configuration.md`](docs/configuration.md) +- [`docs/group-messages.md`](docs/group-messages.md) - [`docs/gateway.md`](docs/gateway.md) - [`docs/web.md`](docs/web.md) - [`docs/discovery.md`](docs/discovery.md) diff --git a/docs/clawd.md b/docs/clawd.md index 9b3b0df5f..f5881e1b0 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -133,7 +133,7 @@ Example: }, session: { scope: "per-sender", - resetTriggers: ["/new"], + resetTriggers: ["/new", "/reset"], idleMinutes: 10080, mainKey: "main" } @@ -145,7 +145,7 @@ Example: - Session files: `~/.clawdis/sessions/{{SessionId}}.jsonl` - Session metadata (token usage, last route, etc): `~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`) -- `/new` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset. +- `/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. ## Heartbeats (proactive mode) diff --git a/docs/configuration.md b/docs/configuration.md index 81834a68a..41152a1c0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -73,13 +73,12 @@ Allowlist of E.164 phone numbers that may trigger auto-replies. ### `inbound.groupChat` -Group messages default to **require mention** (either metadata mention or regex patterns). You can switch to always-on activation. +Group messages default to **require mention** (either metadata mention or regex patterns). ```json5 { inbound: { groupChat: { - activation: "mention", // mention | always mentionPatterns: ["@clawd", "clawdbot", "clawd"], historyLimit: 50 } @@ -87,10 +86,6 @@ Group messages default to **require mention** (either metadata mention or regex } ``` -Notes: -- `activation` defaults to `mention`. -- `requireMention` is still supported for backwards compatibility (`false` ≈ `activation: "always"`). - ### `inbound.workspace` Sets the **single global workspace directory** used by the agent for file operations. @@ -135,7 +130,7 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto session: { scope: "per-sender", idleMinutes: 60, - resetTriggers: ["/new"], + resetTriggers: ["/new", "/reset"], store: "~/.clawdis/sessions/sessions.json", mainKey: "main" } diff --git a/docs/group-messages.md b/docs/group-messages.md index 2d6de89c5..bb6498eef 100644 --- a/docs/group-messages.md +++ b/docs/group-messages.md @@ -8,7 +8,7 @@ read_when: Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session. ## What’s implemented (2025-12-03) -- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token (see below). +- 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. - 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]`. @@ -23,7 +23,6 @@ Add a `groupChat` block to `~/.clawdis/clawdis.json` so display-name pings work { "inbound": { "groupChat": { - "activation": "mention", "historyLimit": 50, "mentionPatterns": [ "@?clawd", @@ -40,15 +39,19 @@ Notes: - The regexes are case-insensitive; they cover `@clawd`, `@clawd uk`, `clawdbot`, and the raw number with or without `+`/spaces. - WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is rarely needed but is a good safety net. -### Always-on mode +### Activation command (owner-only) -Set `"activation": "always"` to wake on every group message. In this mode the agent is instructed to return `NO_REPLY` (exact token) when it decides no reply is necessary, and Clawdis will suppress the outbound message. +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. ## How to use 1) Add Clawd UK (`+447700900123`) to the group. 2) Say `@clawd …` (or `@clawd uk`, `@clawdbot`, or include the number). Anyone in the group can trigger it. 3) The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person. -4) Session-level directives (`/verbose on`, `/think:high`, `/new`) apply only to that group’s session; your personal DM session remains independent. +4) Session-level directives (`/verbose on`, `/think:high`, `/new` or `/reset`) apply only to that group’s session; your personal DM session remains independent. ## Testing / verification - Automated: `pnpm test -- src/web/auto-reply.test.ts --runInBand` (covers mention gating, history injection, sender suffix). diff --git a/docs/index.md b/docs/index.md index b5b4d09a2..bff206253 100644 --- a/docs/index.md +++ b/docs/index.md @@ -62,7 +62,7 @@ Most operations flow through the **Gateway** (`clawdis gateway`), a single long- - ✈️ **Telegram Bot** — DMs + groups via grammY - 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming - 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated -- 👥 **Group Chat Support** — Mention-based triggering in group chats +- 👥 **Group Chat Support** — Mention-based by default; owner can toggle `/activation always|mention` - 📎 **Media Support** — Send and receive images, audio, documents - 🎤 **Voice notes** — Optional transcription hook - 🖥️ **WebChat + macOS app** — Local UI + menu bar companion for ops and voice wake diff --git a/docs/session.md b/docs/session.md index cbf228d14..480a7f798 100644 --- a/docs/session.md +++ b/docs/session.md @@ -26,7 +26,7 @@ All session state is **owned by the gateway** (the “master” Clawdis). UI cli ## Lifecyle - Idle expiry: `inbound.session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message. -- Reset triggers: exact `/new` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` is sent alone, Clawdis runs a short “hello” greeting turn to confirm the reset. +- 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. ## Configuration (optional rename example) @@ -37,7 +37,7 @@ All session state is **owned by the gateway** (the “master” Clawdis). UI cli session: { scope: "per-sender", // keep group keys separate idleMinutes: 120, - resetTriggers: ["/new"], + resetTriggers: ["/new", "/reset"], store: "~/.clawdis/sessions/sessions.json", mainKey: "main" // optional rename; still a single primary } diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ee7da42c8..3105e9e22 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -62,7 +62,7 @@ ls -la ~/.clawdis/sessions/ } ``` -**Check 3:** Did someone send `/new` or a reset trigger? +**Check 3:** Did someone send `/new`, `/reset`, or a reset trigger? ### Agent Timing Out