docs: update group chat commands

2025-12-22 20:36:34 +01:00
parent f10c8f2b4c
commit 8cadb5cf18
7 changed files with 29 additions and 18 deletions
--- 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 <level>` — 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)
--- 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)

--- 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"
    }
--- 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:<jid>` so commands such as `/verbose on` or `/think:high` are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
 - Context injection: last N (default 50) group messages are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`.
@@ -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).
--- 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
--- 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
    }
--- 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