@rozek/nanoclaw 1.2.17

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

@@ -0,0 +1,207 @@
+---
+name: add-slack
+description: Add Slack as a channel. Can replace WhatsApp entirely or run alongside it. Uses Socket Mode (no public URL needed).
+---
+
+# Add Slack Channel
+
+This skill adds Slack support to NanoClaw, then walks through interactive setup.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/channels/slack.ts` exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
+
+### Ask the user
+
+**Do they already have a Slack app configured?** If yes, collect the Bot Token and App Token now. If no, we'll create one in Phase 3.
+
+## Phase 2: Apply Code Changes
+
+### Ensure channel remote
+
+```bash
+git remote -v
+```
+
+If `slack` is missing, add it:
+
+```bash
+git remote add slack https://github.com/qwibitai/nanoclaw-slack.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch slack main
+git merge slack/main || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/slack.ts` (SlackChannel class with self-registration via `registerChannel`)
+- `src/channels/slack.test.ts` (46 unit tests)
+- `import './slack.js'` appended to the channel barrel file `src/channels/index.ts`
+- `@slack/bolt` npm dependency in `package.json`
+- `SLACK_BOT_TOKEN` and `SLACK_APP_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/slack.test.ts
+```
+
+All tests must pass (including the new Slack tests) and build must be clean before proceeding.
+
+## Phase 3: Setup
+
+### Create Slack App (if needed)
+
+If the user doesn't have a Slack app, share [SLACK_SETUP.md](SLACK_SETUP.md) which has step-by-step instructions with screenshots guidance, troubleshooting, and a token reference table.
+
+Quick summary of what's needed:
+1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
+2. Enable Socket Mode and generate an App-Level Token (`xapp-...`)
+3. Subscribe to bot events: `message.channels`, `message.groups`, `message.im`
+4. Add OAuth scopes: `chat:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`
+5. Install to workspace and copy the Bot Token (`xoxb-...`)
+
+Wait for the user to provide both tokens.
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_APP_TOKEN=xapp-your-app-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:
+
+> 1. Add the bot to a Slack channel (right-click channel → **View channel details** → **Integrations** → **Add apps**)
+> 2. In that channel, the channel ID is in the URL when you open it in a browser: `https://app.slack.com/client/T.../C0123456789` — the `C...` part is the channel ID
+> 3. Alternatively, right-click the channel name → **Copy link** — the channel ID is the last path segment
+>
+> The JID format for NanoClaw is: `slack:C0123456789`
+
+Wait for the user to provide the channel ID.
+
+### 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 "slack:<channel-id>" --name "<channel-name>" --folder "slack_main" --trigger "@${ASSISTANT_NAME}" --channel slack --no-trigger-required --is-main
+```
+
+For additional channels (trigger-only):
+
+```bash
+npx tsx setup/index.ts --step register -- --jid "slack:<channel-id>" --name "<channel-name>" --folder "slack_<channel-name>" --trigger "@${ASSISTANT_NAME}" --channel slack
+```
+
+## Phase 5: Verify
+
+### Test the connection
+
+Tell the user:
+
+> Send a message in your registered Slack channel:
+> - For main channel: Any message works
+> - For non-main: `@<assistant-name> hello` (using the configured trigger word)
+>
+> The bot should respond within a few seconds.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+## Troubleshooting
+
+### Bot not responding
+
+1. Check `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` are 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 'slack:%'"`
+3. For non-main channels: message must include trigger pattern
+4. Service is running: `launchctl list | grep nanoclaw`
+
+### Bot connected but not receiving messages
+
+1. Verify Socket Mode is enabled in the Slack app settings
+2. Verify the bot is subscribed to the correct events (`message.channels`, `message.groups`, `message.im`)
+3. Verify the bot has been added to the channel
+4. Check that the bot has the required OAuth scopes
+
+### Bot not seeing messages in channels
+
+By default, bots only see messages in channels they've been explicitly added to. Make sure to:
+1. Add the bot to each channel you want it to monitor
+2. Check the bot has `channels:history` and/or `groups:history` scopes
+
+### "missing_scope" errors
+
+If the bot logs `missing_scope` errors:
+1. Go to **OAuth & Permissions** in your Slack app settings
+2. Add the missing scope listed in the error message
+3. **Reinstall the app** to your workspace — scope changes require reinstallation
+4. Copy the new Bot Token (it changes on reinstall) and update `.env`
+5. Sync: `mkdir -p data/env && cp .env data/env/env`
+6. Restart: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
+
+### Getting channel ID
+
+If the channel ID is hard to find:
+- In Slack desktop: right-click channel → **Copy link** → extract the `C...` ID from the URL
+- In Slack web: the URL shows `https://app.slack.com/client/TXXXXXXX/C0123456789`
+- Via API: `curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'`
+
+## After Setup
+
+The Slack channel supports:
+- **Public channels** — Bot must be added to the channel
+- **Private channels** — Bot must be invited to the channel
+- **Direct messages** — Users can DM the bot directly
+- **Multi-channel** — Can run alongside WhatsApp or other channels (auto-enabled by credentials)
+
+## Known Limitations
+
+- **Threads are flattened** — Threaded replies are delivered to the agent as regular channel messages. The agent sees them but has no awareness they originated in a thread. Responses always go to the channel, not back into the thread. Users in a thread will need to check the main channel for the bot's reply. Full thread-aware routing (respond in-thread) requires pipeline-wide changes: database schema, `NewMessage` type, `Channel.sendMessage` interface, and routing logic.
+- **No typing indicator** — Slack's Bot API does not expose a typing indicator endpoint. The `setTyping()` method is a no-op. Users won't see "bot is typing..." while the agent works.
+- **Message splitting is naive** — Long messages are split at a fixed 4000-character boundary, which may break mid-word or mid-sentence. A smarter split (on paragraph or sentence boundaries) would improve readability.
+- **No file/image handling** — The bot only processes text content. File uploads, images, and rich message blocks are not forwarded to the agent.
+- **Channel metadata sync is unbounded** — `syncChannelMetadata()` paginates through all channels the bot is a member of, but has no upper bound or timeout. Workspaces with thousands of channels may experience slow startup.
+- **Workspace admin policies not detected** — If the Slack workspace restricts bot app installation, the setup will fail at the "Install to Workspace" step with no programmatic detection or guidance. See SLACK_SETUP.md troubleshooting section.

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

@@ -0,0 +1,222 @@
+---
+name: add-telegram
+description: Add Telegram as a channel. Can replace WhatsApp entirely or run alongside it. Also configurable as a control-only channel (triggers actions) or passive channel (receives notifications only).
+---
+
+# Add Telegram Channel
+
+This skill adds Telegram support to NanoClaw, then walks through interactive setup.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/channels/telegram.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 Telegram 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 `telegram` is missing, add it:
+
+```bash
+git remote add telegram https://github.com/qwibitai/nanoclaw-telegram.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch telegram main
+git merge telegram/main || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/channels/telegram.ts` (TelegramChannel class with self-registration via `registerChannel`)
+- `src/channels/telegram.test.ts` (unit tests with grammy mock)
+- `import './telegram.js'` appended to the channel barrel file `src/channels/index.ts`
+- `grammy` npm dependency in `package.json`
+- `TELEGRAM_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/telegram.test.ts
+```
+
+All tests must pass (including the new Telegram tests) and build must be clean before proceeding.
+
+## Phase 3: Setup
+
+### Create Telegram Bot (if needed)
+
+If the user doesn't have a bot token, tell them:
+
+> I need you to create a Telegram bot:
+>
+> 1. Open Telegram and search for `@BotFather`
+> 2. Send `/newbot` and follow prompts:
+>    - Bot name: Something friendly (e.g., "Andy Assistant")
+>    - Bot username: Must end with "bot" (e.g., "andy_ai_bot")
+> 3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
+
+Wait for the user to provide the token.
+
+### Configure environment
+
+Add to `.env`:
+
+```bash
+TELEGRAM_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.
+
+### Disable Group Privacy (for group chats)
+
+Tell the user:
+
+> **Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
+>
+> 1. Open Telegram and search for `@BotFather`
+> 2. Send `/mybots` and select your bot
+> 3. Go to **Bot Settings** > **Group Privacy** > **Turn off**
+>
+> This is optional if you only want trigger-based responses via @mentioning the bot.
+
+### Build and restart
+
+```bash
+npm run build
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Registration
+
+### Get Chat ID
+
+Tell the user:
+
+> 1. Open your bot in Telegram (search for its username)
+> 2. Send `/chatid` — it will reply with the chat ID
+> 3. For groups: add the bot to the group first, then send `/chatid` in the group
+
+Wait for the user to provide the chat ID (format: `tg:123456789` or `tg:-1001234567890`).
+
+### Register the chat
+
+The chat ID, name, and folder name are needed. Use `npx tsx setup/index.ts --step register` with the appropriate flags.
+
+For a main chat (responds to all messages):
+
+```bash
+npx tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_main" --trigger "@${ASSISTANT_NAME}" --channel telegram --no-trigger-required --is-main
+```
+
+For additional chats (trigger-only):
+
+```bash
+npx tsx setup/index.ts --step register -- --jid "tg:<chat-id>" --name "<chat-name>" --folder "telegram_<group-name>" --trigger "@${ASSISTANT_NAME}" --channel telegram
+```
+
+## Phase 5: Verify
+
+### Test the connection
+
+Tell the user:
+
+> Send a message to your registered Telegram chat:
+> - For main chat: Any message works
+> - For non-main: `@Andy hello` or @mention the bot
+>
+> The bot should respond within a few seconds.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log
+```
+
+## Troubleshooting
+
+### Bot not responding
+
+Check:
+1. `TELEGRAM_BOT_TOKEN` is set in `.env` AND synced to `data/env/env`
+2. Chat is registered in SQLite (check with: `sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'tg:%'"`)
+3. For non-main chats: message includes trigger pattern
+4. Service is running: `launchctl list | grep nanoclaw` (macOS) or `systemctl --user status nanoclaw` (Linux)
+
+### Bot only responds to @mentions in groups
+
+Group Privacy is enabled (default). Fix:
+1. `@BotFather` > `/mybots` > select bot > **Bot Settings** > **Group Privacy** > **Turn off**
+2. Remove and re-add the bot to the group (required for the change to take effect)
+
+### Getting chat ID
+
+If `/chatid` doesn't work:
+- Verify token: `curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe"`
+- Check bot is started: `tail -f logs/nanoclaw.log`
+
+## After Setup
+
+If running `npm run dev` while the service is active:
+```bash
+# macOS:
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+npm run dev
+# When done testing:
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+# Linux:
+# systemctl --user stop nanoclaw
+# npm run dev
+# systemctl --user start nanoclaw
+```
+
+## Agent Swarms (Teams)
+
+After completing the Telegram setup, use `AskUserQuestion`:
+
+AskUserQuestion: Would you like to add Agent Swarm support? Without it, Agent Teams still work — they just operate behind the scenes. With Swarm support, each subagent appears as a different bot in the Telegram group so you can see who's saying what and have interactive team sessions.
+
+If they say yes, invoke the `/add-telegram-swarm` skill.
+
+## Removal
+
+To remove Telegram integration:
+
+1. Delete `src/channels/telegram.ts` and `src/channels/telegram.test.ts`
+2. Remove `import './telegram.js'` from `src/channels/index.ts`
+3. Remove `TELEGRAM_BOT_TOKEN` from `.env`
+4. Remove Telegram registrations from SQLite: `sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE 'tg:%'"`
+5. Uninstall: `npm uninstall grammy`
+6. Rebuild: `npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw` (macOS) or `npm run build && systemctl --user restart nanoclaw` (Linux)