@rozek/nanoclaw 1.2.17

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

@@ -0,0 +1,384 @@
+---
+name: add-telegram-swarm
+description: Add Agent Swarm (Teams) support to Telegram. Each subagent gets its own bot identity in the group. Requires Telegram channel to be set up first (use /add-telegram). Triggers on "agent swarm", "agent teams telegram", "telegram swarm", "bot pool".
+---
+
+# Add Agent Swarm to Telegram
+
+This skill adds Agent Teams (Swarm) support to an existing Telegram channel. Each subagent in a team gets its own bot identity in the Telegram group, so users can visually distinguish which agent is speaking.
+
+**Prerequisite**: Telegram must already be set up via the `/add-telegram` skill. If `src/telegram.ts` does not exist or `TELEGRAM_BOT_TOKEN` is not configured, tell the user to run `/add-telegram` first.
+
+## How It Works
+
+- The **main bot** receives messages and sends lead agent responses (already set up by `/add-telegram`)
+- **Pool bots** are send-only — each gets a Grammy `Api` instance (no polling)
+- When a subagent calls `send_message` with a `sender` parameter, the host assigns a pool bot and renames it to match the sender's role
+- Messages appear in Telegram from different bot identities
+
+```
+Subagent calls send_message(text: "Found 3 results", sender: "Researcher")
+  → MCP writes IPC file with sender field
+  → Host IPC watcher picks it up
+  → Assigns pool bot #2 to "Researcher" (round-robin, stable per-group)
+  → Renames pool bot #2 to "Researcher" via setMyName
+  → Sends message via pool bot #2's Api instance
+  → Appears in Telegram from "Researcher" bot
+```
+
+## Prerequisites
+
+### 1. Create Pool Bots
+
+Tell the user:
+
+> I need you to create 3-5 Telegram bots to use as the agent pool. These will be renamed dynamically to match agent roles.
+>
+> 1. Open Telegram and search for `@BotFather`
+> 2. Send `/newbot` for each bot:
+>    - Give them any placeholder name (e.g., "Bot 1", "Bot 2")
+>    - Usernames like `myproject_swarm_1_bot`, `myproject_swarm_2_bot`, etc.
+> 3. Copy all the tokens
+> 4. Add all bots to your Telegram group(s) where you want agent teams
+
+Wait for user to provide the tokens.
+
+### 2. Disable Group Privacy for Pool Bots
+
+Tell the user:
+
+> **Important**: Each pool bot needs Group Privacy disabled so it can send messages in groups.
+>
+> For each pool bot in `@BotFather`:
+> 1. Send `/mybots` and select the bot
+> 2. Go to **Bot Settings** > **Group Privacy** > **Turn off**
+>
+> Then add all pool bots to your Telegram group(s).
+
+## Implementation
+
+### Step 1: Update Configuration
+
+Read `src/config.ts` and add the bot pool config near the other Telegram exports:
+
+```typescript
+export const TELEGRAM_BOT_POOL = (process.env.TELEGRAM_BOT_POOL || '')
+  .split(',')
+  .map((t) => t.trim())
+  .filter(Boolean);
+```
+
+### Step 2: Add Bot Pool to Telegram Module
+
+Read `src/telegram.ts` and add the following:
+
+1. **Update imports** — add `Api` to the Grammy import:
+
+```typescript
+import { Api, Bot } from 'grammy';
+```
+
+2. **Add pool state** after the existing `let bot` declaration:
+
+```typescript
+// Bot pool for agent teams: send-only Api instances (no polling)
+const poolApis: Api[] = [];
+// Maps "{groupFolder}:{senderName}" → pool Api index for stable assignment
+const senderBotMap = new Map<string, number>();
+let nextPoolIndex = 0;
+```
+
+3. **Add pool functions** — place these before the `isTelegramConnected` function:
+
+```typescript
+/**
+ * Initialize send-only Api instances for the bot pool.
+ * Each pool bot can send messages but doesn't poll for updates.
+ */
+export async function initBotPool(tokens: string[]): Promise<void> {
+  for (const token of tokens) {
+    try {
+      const api = new Api(token);
+      const me = await api.getMe();
+      poolApis.push(api);
+      logger.info(
+        { username: me.username, id: me.id, poolSize: poolApis.length },
+        'Pool bot initialized',
+      );
+    } catch (err) {
+      logger.error({ err }, 'Failed to initialize pool bot');
+    }
+  }
+  if (poolApis.length > 0) {
+    logger.info({ count: poolApis.length }, 'Telegram bot pool ready');
+  }
+}
+
+/**
+ * Send a message via a pool bot assigned to the given sender name.
+ * Assigns bots round-robin on first use; subsequent messages from the
+ * same sender in the same group always use the same bot.
+ * On first assignment, renames the bot to match the sender's role.
+ */
+export async function sendPoolMessage(
+  chatId: string,
+  text: string,
+  sender: string,
+  groupFolder: string,
+): Promise<void> {
+  if (poolApis.length === 0) {
+    // No pool bots — fall back to main bot
+    await sendTelegramMessage(chatId, text);
+    return;
+  }
+
+  const key = `${groupFolder}:${sender}`;
+  let idx = senderBotMap.get(key);
+  if (idx === undefined) {
+    idx = nextPoolIndex % poolApis.length;
+    nextPoolIndex++;
+    senderBotMap.set(key, idx);
+    // Rename the bot to match the sender's role, then wait for Telegram to propagate
+    try {
+      await poolApis[idx].setMyName(sender);
+      await new Promise((r) => setTimeout(r, 2000));
+      logger.info({ sender, groupFolder, poolIndex: idx }, 'Assigned and renamed pool bot');
+    } catch (err) {
+      logger.warn({ sender, err }, 'Failed to rename pool bot (sending anyway)');
+    }
+  }
+
+  const api = poolApis[idx];
+  try {
+    const numericId = chatId.replace(/^tg:/, '');
+    const MAX_LENGTH = 4096;
+    if (text.length <= MAX_LENGTH) {
+      await api.sendMessage(numericId, text);
+    } else {
+      for (let i = 0; i < text.length; i += MAX_LENGTH) {
+        await api.sendMessage(numericId, text.slice(i, i + MAX_LENGTH));
+      }
+    }
+    logger.info({ chatId, sender, poolIndex: idx, length: text.length }, 'Pool message sent');
+  } catch (err) {
+    logger.error({ chatId, sender, err }, 'Failed to send pool message');
+  }
+}
+```
+
+### Step 3: Add sender Parameter to MCP Tool
+
+Read `container/agent-runner/src/ipc-mcp-stdio.ts` and update the `send_message` tool to accept an optional `sender` parameter:
+
+Change the tool's schema from:
+```typescript
+{ text: z.string().describe('The message text to send') },
+```
+
+To:
+```typescript
+{
+  text: z.string().describe('The message text to send'),
+  sender: z.string().optional().describe('Your role/identity name (e.g. "Researcher"). When set, messages appear from a dedicated bot in Telegram.'),
+},
+```
+
+And update the handler to include `sender` in the IPC data:
+
+```typescript
+async (args) => {
+    const data: Record<string, string | undefined> = {
+      type: 'message',
+      chatJid,
+      text: args.text,
+      sender: args.sender || undefined,
+      groupFolder,
+      timestamp: new Date().toISOString(),
+    };
+
+    writeIpcFile(MESSAGES_DIR, data);
+
+    return { content: [{ type: 'text' as const, text: 'Message sent.' }] };
+  },
+```
+
+### Step 4: Update Host IPC Routing
+
+Read `src/ipc.ts` and make these changes:
+
+1. **Add imports** — add `sendPoolMessage` and `initBotPool` from the Telegram swarm module, and `TELEGRAM_BOT_POOL` from config.
+
+2. **Update IPC message routing** — in `src/ipc.ts`, find where the `sendMessage` dependency is called to deliver IPC messages (inside `processIpcFiles`). The `sendMessage` is passed in via the `IpcDeps` parameter. Wrap it to route Telegram swarm messages through the bot pool:
+
+```typescript
+if (data.sender && data.chatJid.startsWith('tg:')) {
+  await sendPoolMessage(
+    data.chatJid,
+    data.text,
+    data.sender,
+    sourceGroup,
+  );
+} else {
+  await deps.sendMessage(data.chatJid, data.text);
+}
+```
+
+Note: The assistant name prefix is handled by `formatOutbound()` in the router — Telegram channels have `prefixAssistantName = false` so no prefix is added for `tg:` JIDs.
+
+3. **Initialize pool in `main()` in `src/index.ts`** — after creating the Telegram channel, add:
+
+```typescript
+if (TELEGRAM_BOT_POOL.length > 0) {
+  await initBotPool(TELEGRAM_BOT_POOL);
+}
+```
+
+### Step 5: Update CLAUDE.md Files
+
+#### 5a. Add global message formatting rules
+
+Read `groups/global/CLAUDE.md` and add a Message Formatting section:
+
+```markdown
+## Message Formatting
+
+NEVER use markdown. Only use WhatsApp/Telegram formatting:
+- *single asterisks* for bold (NEVER **double asterisks**)
+- _underscores_ for italic
+- • bullet points
+- ```triple backticks``` for code
+
+No ## headings. No [links](url). No **double stars**.
+```
+
+#### 5b. Update existing group CLAUDE.md headings
+
+In any group CLAUDE.md that has a "WhatsApp Formatting" section (e.g. `groups/main/CLAUDE.md`), rename the heading to reflect multi-channel support:
+
+```
+## WhatsApp Formatting (and other messaging apps)
+```
+
+#### 5c. Add Agent Teams instructions to Telegram groups
+
+For each Telegram group that will use agent teams, create or update its `groups/{folder}/CLAUDE.md` with these instructions. Read the existing CLAUDE.md first (or `groups/global/CLAUDE.md` as a base) and add the Agent Teams section:
+
+```markdown
+## Agent Teams
+
+When creating a team to tackle a complex task, follow these rules:
+
+### CRITICAL: Follow the user's prompt exactly
+
+Create *exactly* the team the user asked for — same number of agents, same roles, same names. Do NOT add extra agents, rename roles, or use generic names like "Researcher 1". If the user says "a marine biologist, a physicist, and Alexander Hamilton", create exactly those three agents with those exact names.
+
+### Team member instructions
+
+Each team member MUST be instructed to:
+
+1. *Share progress in the group* via `mcp__nanoclaw__send_message` with a `sender` parameter matching their exact role/character name (e.g., `sender: "Marine Biologist"` or `sender: "Alexander Hamilton"`). This makes their messages appear from a dedicated bot in the Telegram group.
+2. *Also communicate with teammates* via `SendMessage` as normal for coordination.
+3. Keep group messages *short* — 2-4 sentences max per message. Break longer content into multiple `send_message` calls. No walls of text.
+4. Use the `sender` parameter consistently — always the same name so the bot identity stays stable.
+5. NEVER use markdown formatting. Use ONLY WhatsApp/Telegram formatting: single *asterisks* for bold (NOT **double**), _underscores_ for italic, • for bullets, ```backticks``` for code. No ## headings, no [links](url), no **double asterisks**.
+
+### Example team creation prompt
+
+When creating a teammate, include instructions like:
+
+\```
+You are the Marine Biologist. When you have findings or updates for the user, send them to the group using mcp__nanoclaw__send_message with sender set to "Marine Biologist". Keep each message short (2-4 sentences max). Use emojis for strong reactions. ONLY use single *asterisks* for bold (never **double**), _underscores_ for italic, • for bullets. No markdown. Also communicate with teammates via SendMessage.
+\```
+
+### Lead agent behavior
+
+As the lead agent who created the team:
+
+- You do NOT need to react to or relay every teammate message. The user sees those directly from the teammate bots.
+- Send your own messages only to comment, share thoughts, synthesize, or direct the team.
+- When processing an internal update from a teammate that doesn't need a user-facing response, wrap your *entire* output in `<internal>` tags.
+- Focus on high-level coordination and the final synthesis.
+```
+
+### Step 6: Update Environment
+
+Add pool tokens to `.env`:
+
+```bash
+TELEGRAM_BOT_POOL=TOKEN1,TOKEN2,TOKEN3,...
+```
+
+**Important**: Sync to all required locations:
+
+```bash
+cp .env data/env/env
+```
+
+Also add `TELEGRAM_BOT_POOL` to the launchd plist (`~/Library/LaunchAgents/com.nanoclaw.plist`) in the `EnvironmentVariables` dict if using launchd.
+
+### Step 7: Rebuild and Restart
+
+```bash
+npm run build
+./container/build.sh  # Required — MCP tool changed
+# macOS:
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+# Linux:
+# systemctl --user restart nanoclaw
+```
+
+Must use `unload/load` (macOS) or `restart` (Linux) because the service env vars changed.
+
+### Step 8: Test
+
+Tell the user:
+
+> Send a message in your Telegram group asking for a multi-agent task, e.g.:
+> "Assemble a team of a researcher and a coder to build me a hello world app"
+>
+> You should see:
+> - The lead agent (main bot) acknowledging and creating the team
+> - Each subagent messaging from a different bot, renamed to their role
+> - Short, scannable messages from each agent
+>
+> Check logs: `tail -f logs/nanoclaw.log | grep -i pool`
+
+## Architecture Notes
+
+- Pool bots use Grammy's `Api` class — lightweight, no polling, just send
+- Bot names are set via `setMyName` — changes are global to the bot, not per-chat
+- A 2-second delay after `setMyName` allows Telegram to propagate the name change before the first message
+- Sender→bot mapping is stable within a group (keyed as `{groupFolder}:{senderName}`)
+- Mapping resets on service restart — pool bots get reassigned fresh
+- If pool runs out, bots are reused (round-robin wraps)
+
+## Troubleshooting
+
+### Pool bots not sending messages
+
+1. Verify tokens: `curl -s "https://api.telegram.org/botTOKEN/getMe"`
+2. Check pool initialized: `grep "Pool bot" logs/nanoclaw.log`
+3. Ensure all pool bots are members of the Telegram group
+4. Check Group Privacy is disabled for each pool bot
+
+### Bot names not updating
+
+Telegram caches bot names client-side. The 2-second delay after `setMyName` helps, but users may need to restart their Telegram client to see updated names immediately.
+
+### Subagents not using send_message
+
+Check the group's `CLAUDE.md` has the Agent Teams instructions. The lead agent reads this when creating teammates and must include the `send_message` + `sender` instructions in each teammate's prompt.
+
+## Removal
+
+To remove Agent Swarm support while keeping basic Telegram:
+
+1. Remove `TELEGRAM_BOT_POOL` from `src/config.ts`
+2. Remove pool code from `src/telegram.ts` (`poolApis`, `senderBotMap`, `initBotPool`, `sendPoolMessage`)
+3. Remove pool routing from IPC handler in `src/index.ts` (revert to plain `sendMessage`)
+4. Remove `initBotPool` call from `main()`
+5. Remove `sender` param from MCP tool in `container/agent-runner/src/ipc-mcp-stdio.ts`
+6. Remove Agent Teams section from group CLAUDE.md files
+7. Remove `TELEGRAM_BOT_POOL` from `.env`, `data/env/env`, and launchd plist/systemd unit
+8. Rebuild: `npm run build && ./container/build.sh && launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist && launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist` (macOS) or `npm run build && ./container/build.sh && systemctl --user restart nanoclaw` (Linux)

package/.claude/skills/add-voice-transcription/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: add-voice-transcription
+description: Add voice message transcription to NanoClaw using OpenAI's Whisper API. Automatically transcribes WhatsApp voice notes so the agent can read and respond to them.
+---
+
+# Add Voice Transcription
+
+This skill adds automatic voice message transcription to NanoClaw's WhatsApp channel using OpenAI's Whisper API. When a voice note arrives, it is downloaded, transcribed, and delivered to the agent as `[Voice: <transcript>]`.
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `src/transcription.ts` exists. If it does, skip to Phase 3 (Configure). The code changes are already in place.
+
+### Ask the user
+
+Use `AskUserQuestion` to collect information:
+
+AskUserQuestion: Do you have an OpenAI API key for Whisper transcription?
+
+If yes, collect it now. If no, direct them to create one at https://platform.openai.com/api-keys.
+
+## Phase 2: Apply Code Changes
+
+**Prerequisite:** WhatsApp must be installed first (`skill/whatsapp` merged). This skill modifies WhatsApp channel files.
+
+### 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/voice-transcription
+git merge whatsapp/skill/voice-transcription || {
+  git checkout --theirs package-lock.json
+  git add package-lock.json
+  git merge --continue
+}
+```
+
+This merges in:
+- `src/transcription.ts` (voice transcription module using OpenAI Whisper)
+- Voice handling in `src/channels/whatsapp.ts` (isVoiceMessage check, transcribeAudioMessage call)
+- Transcription tests in `src/channels/whatsapp.test.ts`
+- `openai` npm dependency in `package.json`
+- `OPENAI_API_KEY` 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 --legacy-peer-deps
+npm run build
+npx vitest run src/channels/whatsapp.test.ts
+```
+
+All tests must pass and build must be clean before proceeding.
+
+## Phase 3: Configure
+
+### Get OpenAI API key (if needed)
+
+If the user doesn't have an API key:
+
+> I need you to create an OpenAI API key:
+>
+> 1. Go to https://platform.openai.com/api-keys
+> 2. Click "Create new secret key"
+> 3. Give it a name (e.g., "NanoClaw Transcription")
+> 4. Copy the key (starts with `sk-`)
+>
+> Cost: ~$0.006 per minute of audio (~$0.003 per typical 30-second voice note)
+
+Wait for the user to provide the key.
+
+### Add to environment
+
+Add to `.env`:
+
+```bash
+OPENAI_API_KEY=<their-key>
+```
+
+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  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test with a voice note
+
+Tell the user:
+
+> Send a voice note in any registered WhatsApp chat. The agent should receive it as `[Voice: <transcript>]` and respond to its content.
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i voice
+```
+
+Look for:
+- `Transcribed voice message` — successful transcription with character count
+- `OPENAI_API_KEY not set` — key missing from `.env`
+- `OpenAI transcription failed` — API error (check key validity, billing)
+- `Failed to download audio message` — media download issue
+
+## Troubleshooting
+
+### Voice notes show "[Voice Message - transcription unavailable]"
+
+1. Check `OPENAI_API_KEY` is set in `.env` AND synced to `data/env/env`
+2. Verify key works: `curl -s https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200`
+3. Check OpenAI billing — Whisper requires a funded account
+
+### Voice notes show "[Voice Message - transcription failed]"
+
+Check logs for the specific error. Common causes:
+- Network timeout — transient, will work on next message
+- Invalid API key — regenerate at https://platform.openai.com/api-keys
+- Rate limiting — wait and retry
+
+### Agent doesn't respond to voice notes
+
+Verify the chat is registered and the agent is running. Voice transcription only runs for registered groups.