@rozek/nanoclaw 1.2.17

package/.claude/settings.json

@@ -0,0 +1 @@
+{}

package/.claude/skills/add-compact/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: add-compact
+description: Add /compact command for manual context compaction. Solves context rot in long sessions by forwarding the SDK's built-in /compact slash command. Main-group or trusted sender only.
+---
+
+# Add /compact Command
+
+Adds a `/compact` session command that compacts conversation history to fight context rot in long-running sessions. Uses the Claude Agent SDK's built-in `/compact` slash command — no synthetic system prompts.
+
+**Session contract:** `/compact` keeps the same logical session alive. The SDK returns a new session ID after compaction (via the `init` system message), which the agent-runner forwards to the orchestrator as `newSessionId`. No destructive reset occurs — the agent retains summarized context.
+
+## Phase 1: Pre-flight
+
+Check if `src/session-commands.ts` exists:
+
+```bash
+test -f src/session-commands.ts && echo "Already applied" || echo "Not applied"
+```
+
+If already applied, skip to Phase 3 (Verify).
+
+## Phase 2: Apply Code Changes
+
+Merge the skill branch:
+
+```bash
+git fetch upstream skill/compact
+git merge upstream/skill/compact
+```
+
+> **Note:** `upstream` is the remote pointing to `qwibitai/nanoclaw`. If using a different remote name, substitute accordingly.
+
+This adds:
+- `src/session-commands.ts` (extract and authorize session commands)
+- `src/session-commands.test.ts` (unit tests for command parsing and auth)
+- Session command interception in `src/index.ts` (both `processGroupMessages` and `startMessageLoop`)
+- Slash command handling in `container/agent-runner/src/index.ts`
+
+### Validate
+
+```bash
+npm test
+npm run build
+```
+
+### Rebuild container
+
+```bash
+./container/build.sh
+```
+
+### Restart service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 3: Verify
+
+### Integration Test
+
+1. Start NanoClaw in dev mode: `npm run dev`
+2. From the **main group** (self-chat), send exactly: `/compact`
+3. Verify:
+   - The agent acknowledges compaction (e.g., "Conversation compacted.")
+   - The session continues — send a follow-up message and verify the agent responds coherently
+   - A conversation archive is written to `groups/{folder}/conversations/` (by the PreCompact hook)
+   - Container logs show `Compact boundary observed` (confirms SDK actually compacted)
+   - If `compact_boundary` was NOT observed, the response says "compact_boundary was not observed"
+4. From a **non-main group** as a non-admin user, send: `@<assistant> /compact`
+5. Verify:
+   - The bot responds with "Session commands require admin access."
+   - No compaction occurs, no container is spawned for the command
+6. From a **non-main group** as the admin (device owner / `is_from_me`), send: `@<assistant> /compact`
+7. Verify:
+   - Compaction proceeds normally (same behavior as main group)
+8. While an **active container** is running for the main group, send `/compact`
+9. Verify:
+   - The active container is signaled to close (authorized senders only — untrusted senders cannot kill in-flight work)
+   - Compaction proceeds via a new container once the active one exits
+   - The command is not dropped (no cursor race)
+10. Send a normal message, then `/compact`, then another normal message in quick succession (same polling batch):
+11. Verify:
+    - Pre-compact messages are sent to the agent first (check container logs for two `runAgent` calls)
+    - Compaction proceeds after pre-compact messages are processed
+    - Messages **after** `/compact` in the batch are preserved (cursor advances to `/compact`'s timestamp only) and processed on the next poll cycle
+12. From a **non-main group** as a non-admin user, send `@<assistant> /compact`:
+13. Verify:
+    - Denial message is sent ("Session commands require admin access.")
+    - The `/compact` is consumed (cursor advanced) — it does NOT replay on future polls
+    - Other messages in the same batch are also consumed (cursor is a high-water mark — this is an accepted tradeoff for the narrow edge case of denied `/compact` + other messages in the same polling interval)
+    - No container is killed or interrupted
+14. From a **non-main group** (with `requiresTrigger` enabled) as a non-admin user, send bare `/compact` (no trigger prefix):
+15. Verify:
+    - No denial message is sent (trigger policy prevents untrusted bot responses)
+    - The `/compact` is consumed silently
+    - Note: in groups where `requiresTrigger` is `false`, a denial message IS sent because the sender is considered reachable
+16. After compaction, verify **no auto-compaction** behavior — only manual `/compact` triggers it
+
+### Validation on Fresh Clone
+
+```bash
+git clone <your-fork> /tmp/nanoclaw-test
+cd /tmp/nanoclaw-test
+claude  # then run /add-compact
+npm run build
+npm test
+./container/build.sh
+# Manual: send /compact from main group, verify compaction + continuation
+# Manual: send @<assistant> /compact from non-main as non-admin, verify denial
+# Manual: send @<assistant> /compact from non-main as admin, verify allowed
+# Manual: verify no auto-compaction behavior
+```
+
+## Security Constraints
+
+- **Main-group or trusted/admin sender only.** The main group is the user's private self-chat and is trusted (see `docs/SECURITY.md`). Non-main groups are untrusted — a careless or malicious user could wipe the agent's short-term memory. However, the device owner (`is_from_me`) is always trusted and can compact from any group.
+- **No auto-compaction.** This skill implements manual compaction only. Automatic threshold-based compaction is a separate concern and should be a separate skill.
+- **No config file.** NanoClaw's philosophy is customization through code changes, not configuration sprawl.
+- **Transcript archived before compaction.** The existing `PreCompact` hook in the agent-runner archives the full transcript to `conversations/` before the SDK compacts it.
+- **Session continues after compaction.** This is not a destructive reset. The conversation continues with summarized context.
+
+## What This Does NOT Do
+
+- No automatic compaction threshold (add separately if desired)
+- No `/clear` command (separate skill, separate semantics — `/clear` is a destructive reset)
+- No cross-group compaction (each group's session is isolated)
+- No changes to the container image, Dockerfile, or build script
+
+## Troubleshooting
+
+- **"Session commands require admin access"**: Only the device owner (`is_from_me`) or main-group senders can use `/compact`. Other users are denied.
+- **No compact_boundary in logs**: The SDK may not emit this event in all versions. Check the agent-runner logs for the warning message. Compaction may still have succeeded.
+- **Pre-compact failure**: If messages before `/compact` fail to process, the error message says "Failed to process messages before /compact." The cursor advances past sent output to prevent duplicates; `/compact` remains pending for the next attempt.

package/.claude/skills/add-discord/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: add-discord
+description: Add Discord bot channel integration to NanoClaw.
+---
+
+# Add Discord Channel
+
+This skill adds Discord support to NanoClaw, then walks through interactive setup.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/channels/discord.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
+
+### Ask the user
+
+Use `AskUserQuestion` to collect configuration:
+
+AskUserQuestion: Do you have a Discord bot token, or do you need to create one?
+
+If they have one, collect it now. If not, we'll create one in Phase 3.
+
+## Phase 2: Apply Code Changes
+
+### Ensure channel remote
+
+```bash
+git remote -v
+```
+
+If `discord` is missing, add it:
+
+```bash
+git remote add discord https://github.com/qwibitai/nanoclaw-discord.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch discord main
+git merge discord/main || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/discord.ts` (DiscordChannel class with self-registration via `registerChannel`)
+- `src/channels/discord.test.ts` (unit tests with discord.js mock)
+- `import './discord.js'` appended to the channel barrel file `src/channels/index.ts`
+- `discord.js` npm dependency in `package.json`
+- `DISCORD_BOT_TOKEN` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+npm install
+npm run build
+npx vitest run src/channels/discord.test.ts
+```
+
+All tests must pass (including the new Discord tests) and build must be clean before proceeding.
+
+## Phase 3: Setup
+
+### Create Discord Bot (if needed)
+
+If the user doesn't have a bot token, tell them:
+
+> I need you to create a Discord bot:
+>
+> 1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
+> 2. Click **New Application** and give it a name (e.g., "Andy Assistant")
+> 3. Go to the **Bot** tab on the left sidebar
+> 4. Click **Reset Token** to generate a new bot token — copy it immediately (you can only see it once)
+> 5. Under **Privileged Gateway Intents**, enable:
+>    - **Message Content Intent** (required to read message text)
+>    - **Server Members Intent** (optional, for member display names)
+> 6. Go to **OAuth2** > **URL Generator**:
+>    - Scopes: select `bot`
+>    - Bot Permissions: select `Send Messages`, `Read Message History`, `View Channels`
+>    - Copy the generated URL and open it in your browser to invite the bot to your server
+
+Wait for the user to provide the token.
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+DISCORD_BOT_TOKEN=<their-token>
+```
+
+Channels auto-enable when their credentials are present — no extra configuration needed.
+
+Sync to container environment:
+
+```bash
+mkdir -p data/env && cp .env data/env/env
+```
+
+The container reads environment from `data/env/env`, not `.env` directly.
+
+### Build and restart
+
+```bash
+npm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+```
+
+## Phase 4: Registration
+
+### Get Channel ID
+
+Tell the user:
+
+> To get the channel ID for registration:
+>
+> 1. In Discord, go to **User Settings** > **Advanced** > Enable **Developer Mode**
+> 2. Right-click the text channel you want the bot to respond in
+> 3. Click **Copy Channel ID**
+>
+> The channel ID will be a long number like `1234567890123456`.
+
+Wait for the user to provide the channel ID (format: `dc:1234567890123456`).
+
+### Register the channel
+
+The channel ID, name, and folder name are needed. Use `npx tsx setup/index.ts --step register` with the appropriate flags.
+
+For a main channel (responds to all messages):
+
+```bash
+npx tsx setup/index.ts --step register -- --jid "dc:<channel-id>" --name "<server-name> #<channel-name>" --folder "discord_main" --trigger "@${ASSISTANT_NAME}" --channel discord --no-trigger-required --is-main
+```
+
+For additional channels (trigger-only):
+
+```bash
+npx tsx setup/index.ts --step register -- --jid "dc:<channel-id>" --name "<server-name> #<channel-name>" --folder "discord_<channel-name>" --trigger "@${ASSISTANT_NAME}" --channel discord
+```
+
+## Phase 5: Verify
+
+### Test the connection
+
+Tell the user:
+
+> Send a message in your registered Discord channel:
+> - For main channel: Any message works
+> - For non-main: @mention the bot in Discord
+>
+> The bot should respond within a few seconds.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+## Troubleshooting
+
+### Bot not responding
+
+1. Check `DISCORD_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
+2. Check channel is registered: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'dc:%'"`
+3. For non-main channels: message must include trigger pattern (@mention the bot)
+4. Service is running: `launchctl list | grep nanoclaw`
+5. Verify the bot has been invited to the server (check OAuth2 URL was used)
+
+### Bot only responds to @mentions
+
+This is the default behavior for non-main channels (`requiresTrigger: true`). To change:
+- Update the registered group's `requiresTrigger` to `false`
+- Or register the channel as the main channel
+
+### Message Content Intent not enabled
+
+If the bot connects but can't read messages, ensure:
+1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
+2. Select your application > **Bot** tab
+3. Under **Privileged Gateway Intents**, enable **Message Content Intent**
+4. Restart NanoClaw
+
+### Getting Channel ID
+
+If you can't copy the channel ID:
+- Ensure **Developer Mode** is enabled: User Settings > Advanced > Developer Mode
+- Right-click the channel name in the server sidebar > Copy Channel ID
+
+## After Setup
+
+The Discord bot supports:
+- Text messages in registered channels
+- Attachment descriptions (images, videos, files shown as placeholders)
+- Reply context (shows who the user is replying to)
+- @mention translation (Discord `<@botId>` → NanoClaw trigger format)
+- Message splitting for responses over 2000 characters
+- Typing indicators while the agent processes

package/.claude/skills/add-gmail/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: add-gmail
+description: Add Gmail integration to NanoClaw. Can be configured as a tool (agent reads/sends emails when triggered from WhatsApp) or as a full channel (emails can trigger the agent, schedule tasks, and receive replies). Guides through GCP OAuth setup and implements the integration.
+---
+
+# Add Gmail Integration
+
+This skill adds Gmail support to NanoClaw — either as a tool (read, send, search, draft) or as a full channel that polls the inbox.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/channels/gmail.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
+
+### Ask the user
+
+Use `AskUserQuestion`:
+
+AskUserQuestion: Should incoming emails be able to trigger the agent?
+
+- **Yes** — Full channel mode: the agent listens on Gmail and responds to incoming emails automatically
+- **No** — Tool-only: the agent gets full Gmail tools (read, send, search, draft) but won't monitor the inbox. No channel code is added.
+
+## Phase 2: Apply Code Changes
+
+### Ensure channel remote
+
+```bash
+git remote -v
+```
+
+If `gmail` is missing, add it:
+
+```bash
+git remote add gmail https://github.com/qwibitai/nanoclaw-gmail.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch gmail main
+git merge gmail/main || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/gmail.ts` (GmailChannel class with self-registration via `registerChannel`)
+- `src/channels/gmail.test.ts` (unit tests)
+- `import './gmail.js'` appended to the channel barrel file `src/channels/index.ts`
+- Gmail credentials mount (`~/.gmail-mcp`) in `src/container-runner.ts`
+- Gmail MCP server (`@gongrzhe/server-gmail-autoauth-mcp`) and `mcp__gmail__*` allowed tool in `container/agent-runner/src/index.ts`
+- `googleapis` npm dependency in `package.json`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Add email handling instructions (Channel mode only)
+
+If the user chose channel mode, append the following to `groups/main/CLAUDE.md` (before the formatting section):
+
+```markdown
+## Email Notifications
+
+When you receive an email notification (messages starting with `[Email from ...`), inform the user about it but do NOT reply to the email unless specifically asked. You have Gmail tools available — use them only when the user explicitly asks you to reply, forward, or take action on an email.
+```
+
+### Validate code changes
+
+```bash
+npm install
+npm run build
+npx vitest run src/channels/gmail.test.ts
+```
+
+All tests must pass (including the new Gmail tests) and build must be clean before proceeding.
+
+## Phase 3: Setup
+
+### Check existing Gmail credentials
+
+```bash
+ls -la ~/.gmail-mcp/ 2>/dev/null || echo "No Gmail config found"
+```
+
+If `credentials.json` already exists, skip to "Build and restart" below.
+
+### GCP Project Setup
+
+Tell the user:
+
+> I need you to set up Google Cloud OAuth credentials:
+>
+> 1. Open https://console.cloud.google.com — create a new project or select existing
+> 2. Go to **APIs & Services > Library**, search "Gmail API", click **Enable**
+> 3. Go to **APIs & Services > Credentials**, click **+ CREATE CREDENTIALS > OAuth client ID**
+>    - If prompted for consent screen: choose "External", fill in app name and email, save
+>    - Application type: **Desktop app**, name: anything (e.g., "NanoClaw Gmail")
+> 4. Click **DOWNLOAD JSON** and save as `gcp-oauth.keys.json`
+>
+> Where did you save the file? (Give me the full path, or paste the file contents here)
+
+If user provides a path, copy it:
+
+```bash
+mkdir -p ~/.gmail-mcp
+cp "/path/user/provided/gcp-oauth.keys.json" ~/.gmail-mcp/gcp-oauth.keys.json
+```
+
+If user pastes JSON content, write it to `~/.gmail-mcp/gcp-oauth.keys.json`.
+
+### OAuth Authorization
+
+Tell the user:
+
+> I'm going to run Gmail authorization. A browser window will open — sign in and grant access. If you see an "app isn't verified" warning, click "Advanced" then "Go to [app name] (unsafe)" — this is normal for personal OAuth apps.
+
+Run the authorization:
+
+```bash
+npx -y @gongrzhe/server-gmail-autoauth-mcp auth
+```
+
+If that fails (some versions don't have an auth subcommand), try `timeout 60 npx -y @gongrzhe/server-gmail-autoauth-mcp || true`. Verify with `ls ~/.gmail-mcp/credentials.json`.
+
+### Build and restart
+
+Clear stale per-group agent-runner copies (they only get re-created if missing, so existing copies won't pick up the new Gmail server):
+
+```bash
+rm -r data/sessions/*/agent-runner-src 2>/dev/null || true
+```
+
+Rebuild the container (agent-runner changed):
+
+```bash
+cd container && ./build.sh
+```
+
+Then compile and restart:
+
+```bash
+npm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test tool access (both modes)
+
+Tell the user:
+
+> Gmail is connected! Send this in your main channel:
+>
+> `@Andy check my recent emails` or `@Andy list my Gmail labels`
+
+### Test channel mode (Channel mode only)
+
+Tell the user to send themselves a test email. The agent should pick it up within a minute. Monitor: `tail -f logs/nanoclaw.log | grep -iE "(gmail|email)"`.
+
+Once verified, offer filter customization via `AskUserQuestion` — by default, only emails in the Primary inbox trigger the agent (Promotions, Social, Updates, and Forums are excluded). The user can keep this default or narrow further by sender, label, or keywords. No code changes needed for filters.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+## Troubleshooting
+
+### Gmail connection not responding
+
+Test directly:
+
+```bash
+npx -y @gongrzhe/server-gmail-autoauth-mcp
+```
+
+### OAuth token expired
+
+Re-authorize:
+
+```bash
+rm ~/.gmail-mcp/credentials.json
+npx -y @gongrzhe/server-gmail-autoauth-mcp
+```
+
+### Container can't access Gmail
+
+- Verify `~/.gmail-mcp` is mounted: check `src/container-runner.ts` for the `.gmail-mcp` mount
+- Check container logs: `cat groups/main/logs/container-*.log | tail -50`
+
+### Emails not being detected (Channel mode only)
+
+- By default, the channel polls unread Primary inbox emails (`is:unread category:primary`)
+- Check logs for Gmail polling errors
+
+## Removal
+
+### Tool-only mode
+
+1. Remove `~/.gmail-mcp` mount from `src/container-runner.ts`
+2. Remove `gmail` MCP server and `mcp__gmail__*` from `container/agent-runner/src/index.ts`
+3. Rebuild and restart
+4. Clear stale agent-runner copies: `rm -r data/sessions/*/agent-runner-src 2>/dev/null || true`
+5. Rebuild: `cd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)
+
+### Channel mode
+
+1. Delete `src/channels/gmail.ts` and `src/channels/gmail.test.ts`
+2. Remove `import './gmail.js'` from `src/channels/index.ts`
+3. Remove `~/.gmail-mcp` mount from `src/container-runner.ts`
+4. Remove `gmail` MCP server and `mcp__gmail__*` from `container/agent-runner/src/index.ts`
+5. Uninstall: `npm uninstall googleapis`
+6. Rebuild and restart
+7. Clear stale agent-runner copies: `rm -r data/sessions/*/agent-runner-src 2>/dev/null || true`
+8. Rebuild: `cd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `systemctl --user restart nanoclaw` (Linux)

package/.claude/skills/add-image-vision/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: add-image-vision
+description: Add image vision to NanoClaw agents. Resizes and processes WhatsApp image attachments, then sends them to Claude as multimodal content blocks.
+---
+
+# Image Vision Skill
+
+Adds the ability for NanoClaw agents to see and understand images sent via WhatsApp. Images are downloaded, resized with sharp, saved to the group workspace, and passed to the agent as base64-encoded multimodal content blocks.
+
+## Phase 1: Pre-flight
+
+1. Check if `src/image.ts` exists — skip to Phase 3 if already applied
+2. Confirm `sharp` is installable (native bindings require build tools)
+
+**Prerequisite:** WhatsApp must be installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
+
+## Phase 2: Apply Code Changes
+
+### Ensure WhatsApp fork remote
+
+```bash
+git remote -v
+```
+
+If `whatsapp` is missing, add it:
+
+```bash
+git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch whatsapp skill/image-vision
+git merge whatsapp/skill/image-vision || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/image.ts` (image download, resize via sharp, base64 encoding)
+- `src/image.test.ts` (8 unit tests)
+- Image attachment handling in `src/channels/whatsapp.ts`
+- Image passing to agent in `src/index.ts` and `src/container-runner.ts`
+- Image content block support in `container/agent-runner/src/index.ts`
+- `sharp` npm dependency in `package.json`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Validate code changes
+
+```bash
+npm install
+npm run build
+npx vitest run src/image.test.ts
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Configure
+
+1. Rebuild the container (agent-runner changes need a rebuild):
+   ```bash
+   ./container/build.sh
+   ```
+
+2. Sync agent-runner source to group caches:
+   ```bash
+   for dir in data/sessions/*/agent-runner-src/; do
+     cp container/agent-runner/src/*.ts "$dir"
+   done
+   ```
+
+3. Restart the service:
+   ```bash
+   launchctl kickstart -k gui/$(id -u)/com.nanoclaw
+   ```
+
+## Phase 4: Verify
+
+1. Send an image in a registered WhatsApp group
+2. Check the agent responds with understanding of the image content
+3. Check logs for "Processed image attachment":
+   ```bash
+   tail -50 groups/*/logs/container-*.log
+   ```
+
+## Troubleshooting
+
+- **"Image - download failed"**: Check WhatsApp connection stability. The download may timeout on slow connections.
+- **"Image - processing failed"**: Sharp may not be installed correctly. Run `npm ls sharp` to verify.
+- **Agent doesn't mention image content**: Check container logs for "Loaded image" messages. If missing, ensure agent-runner source was synced to group caches.