Add bundled pi default and session token reporting

docs/agents.md

@@ -1,6 +1,7 @@
 # Agent Integration 🤖
 
 CLAWDIS now ships with a single coding agent: Pi (the Tau CLI). Legacy Claude/Codex/Gemini/Opencode paths have been removed.
+Pi is bundled as a dependency of `clawdis`, so a fresh `pnpm install` gives you the `pi`/`tau` binaries automatically.
 
 ## Pi / Tau
 
@@ -10,10 +11,11 @@ The recommended (and only) agent for CLAWDIS. Built by Mario Zechner, forked wit
 {
   "reply": {
     "mode": "command",
-    "agent": {
-      "kind": "pi",
-      "format": "json"
-    },
+  "agent": {
+    "kind": "pi",
+    "format": "json",
+    "model": "claude-opus-4-5" // default if omitted
+  },
     "command": [
       "node",
       "/path/to/pi-mono/packages/coding-agent/dist/cli.js",
@@ -44,6 +46,8 @@ RPC mode is enforced by CLAWDIS (we rewrite `--mode` to `rpc` for Pi invocations
 - 📊 Token usage tracking
 - 🔄 Streaming responses
 
+If the agent does not report a model, CLAWDIS assumes `claude-opus-4-5` with ~200k context tokens (pi-ai defaults) for usage summaries.
+
 ## Session Management
 
 ### Per-Sender Sessions

docs/configuration.md

@@ -43,7 +43,9 @@ CLAWDIS uses a JSON configuration file at `~/.clawdis/clawdis.json`.
       "mode": "command",
       "agent": {
         "kind": "pi",
-        "format": "json"
+        "format": "json",
+        "model": "claude-opus-4-5",
+        "contextTokens": 200000
       },
       "cwd": "/Users/you/clawd",
       "command": [
@@ -99,6 +101,11 @@ Array of E.164 phone numbers allowed to trigger the AI. Use `["*"]` to allow eve
 | `timeoutSeconds` | number | Max time for agent to respond |
 | `heartbeatMinutes` | number | Interval for heartbeat pings |
 | `heartbeatBody` | string | Message sent on heartbeat |
+| `agent.kind` | string | Only `"pi"` is supported |
+| `agent.model` | string | Optional model name to annotate sessions (defaults to `claude-opus-4-5`) |
+| `agent.contextTokens` | number | Optional context window size; used for session token % reporting (defaults to ~200,000 for Opus 4.5) |
+
+> Quick start: If you omit `inbound.reply`, CLAWDIS falls back to the bundled `@mariozechner/pi-coding-agent` with `--mode rpc`, per-sender sessions, and a 200k-token window. No extra install or config needed to get a reply.
 
 ### Template Variables
 

docs/index.md

@@ -62,6 +62,7 @@ clawdis status
 - [Direct Agent CLI](./agent-send.md) — Use `warelay agent` without sending WhatsApp messages
 - [Group Chats](./groups.md) — Mention patterns and filtering
 - [Media Handling](./media.md) — Images, voice, documents
+- [Session Management](./session.md) — How conversations are keyed and reset
 - [Security](./security.md) — Keeping your lobster safe
 - [Troubleshooting](./troubleshooting.md) — When the CLAWDIS misbehaves
 

docs/session.md

@@ -0,0 +1,55 @@
+# Session Management
+
+CLAWDIS keeps lightweight session state so your agent can remember context between messages. Sessions are stored in a small JSON file and expire automatically after idle time or when you reset them.
+
+## Where sessions live
+
+- Default path: `~/.clawdis/sessions.json` (legacy: `~/.warelay/sessions.json`).
+- Override with `inbound.reply.session.store` in your config if you want a custom location.
+- The file is a plain map of `sessionKey -> { sessionId, updatedAt, ... }`; it is safe to delete if you want a full reset.
+
+## How session keys are chosen
+
+- Direct chats: normalized E.164 sender number (e.g., `+15551234567`).
+- Group chats: `group:<whatsapp-jid>` so group history stays isolated from DMs.
+- Global mode: set `inbound.reply.session.scope = "global"` to force a single shared session for all chats.
+- Unknown senders fall back to `unknown`.
+
+## When sessions reset
+
+- Idle timeout: `inbound.reply.session.idleMinutes` (default 60). If no messages arrive within this window, a new `sessionId` is created on the next message.
+- Reset triggers: `inbound.reply.session.resetTriggers` (default `['/new']`). Sending exactly `/new` or `/new <text>` starts a fresh session and passes the remaining text to the agent.
+- Manual nuke: delete the store file or remove specific keys with `jq`/your editor; a new file is created on the next message.
+
+## Configuration recap
+
+```json5
+// ~/.clawdis/clawdis.json
+{
+  inbound: {
+    reply: {
+      session: {
+        scope: "per-sender",      // or "global"
+        resetTriggers: ["/new"],   // additional triggers allowed
+        idleMinutes: 120,           // extend or shrink timeout (min 1)
+        store: "~/state/clawdis-sessions.json" // optional custom path
+      }
+    }
+  }
+}
+```
+
+Other session-related behaviors:
+- `thinkingLevel` and `verboseLevel` persist per session so inline directives stick until the session resets.
+- Heartbeats reuse the existing session for a recipient when available (good for keeping context warm).
+
+## Inspecting sessions
+
+- `clawdis status` shows the session store path, total count, and the five most recent keys with ages.
+- `clawdis sessions` lists every session (filter with `--active <minutes>` or use `--json` for scripts). It also reports token usage per session; set `inbound.reply.agent.contextTokens` to see the budget percentage (defaults to ~200k tokens for Opus 4.5 via pi-ai defaults).
+- For a deeper look, open the JSON store directly; the keys match the rules above.
+
+## Tips
+
+- Keep groups isolated: mention-based triggers plus the `group:<jid>` session key prevent group traffic from contaminating your DM history.
+- If you automate cleanup, prefer deleting specific keys instead of the whole file to keep other conversations intact.