tomo-ai 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.1 (2026-04-08)
+
+### Features
+
+- Add context window breakdown by category to session metadata
+- Auto-nudge agent to compact when context hits 80%
+
+### Bug fixes
+
+- Surface API errors to Telegram instead of silently swallowing
+- Split cost log into per-turn and cumulative session total
+- Fix totalCostUsd double-counting in session stats
+
 ## 0.2.0 (2026-04-08)
 
 ### Features

package/README.md

@@ -14,7 +14,7 @@
   Personality system ·
   Persistent memory ·
   Scheduled tasks ·
-  Telegram (more channels coming)
+  Telegram · iMessage
 </p>
 
 ---
@@ -33,12 +33,15 @@ That's it. Open Telegram and message your bot.
 
 - Node.js 22+
 - [Claude Code](https://claude.com/claude-code) installed and authenticated (subscription plan — API keys are not currently supported)
-- Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- At least one channel:
+  - **Telegram** — bot token from [@BotFather](https://t.me/BotFather)
+  - **iMessage** — [BlueBubbles](https://bluebubbles.app) server running on a Mac with iMessage signed in
 
 ## CLI
 
 ```bash
 tomo init              # First-time setup
+tomo config            # Interactive settings (model, channels, identities, groups)
 tomo start             # Start in background (daemon)
 tomo start -f          # Start in foreground (for dev)
 tomo stop              # Stop the daemon
@@ -48,16 +51,14 @@ tomo logs              # View logs (pretty-printed)
 tomo logs -f           # Follow logs live
 tomo sessions list     # Show active sessions
 tomo sessions clear    # Reset all sessions
-tomo cron add          # Create a scheduled task
-tomo cron list         # List all jobs
-tomo cron remove <id>  # Delete a job
 ```
 
-## Telegram Commands
+## Chat Commands
 
 | Command | Description |
 |---------|-------------|
 | `/new` | Start a new conversation (resets session) |
+| `/model` | Switch model (sonnet/opus/haiku) |
 
 ## Features
 
@@ -84,7 +85,20 @@ File-based persistent memory at `~/.tomo/workspace/memory/`. The `MEMORY.md` ind
   - Image/photo support (sends to Claude as vision input)
   - Group chat: only responds when @mentioned or replied to, tracks participants
   - Markdown rendering with plain-text fallback
-- More channels coming (iMessage, Discord, etc.)
+- **iMessage** — via [BlueBubbles](https://bluebubbles.app)
+  - DM and group chat support
+  - Image attachment support
+  - Contact name resolution from Mac contacts
+  - Group chat: observes all messages, only responds when relevant (replies `NO_REPLY` to stay silent)
+
+### Multi-Channel Sessions
+
+Talk to Tomo from multiple channels using the same session. Configure identities in `tomo config` to bind your Telegram and iMessage accounts — Tomo replies on whichever channel you last used (or a fixed default).
+
+- DM sessions are unified across channels per identity
+- Group chats always get their own isolated session
+- Per-channel allowlists control who can message Tomo
+- Group chats require a secret passphrase to activate (configured in `tomo config`)
 
 ### Tools
 
@@ -101,24 +115,7 @@ Tomo has access to Claude's built-in tools:
 
 ### Scheduled Tasks
 
-```bash
-# One-shot reminder
-tomo cron add --name "standup" --schedule "in 20m" --message "Time for standup!"
-
-# Recurring task
-tomo cron add --name "morning" --schedule "0 9 * * *" --message "Check calendar and weather"
-
-# Interval
-tomo cron add --name "check" --schedule "every 2h" --message "Check email inbox"
-```
-
-Tomo can also create jobs itself — just ask "remind me in 30 minutes to stretch."
-
-| Format | Type | Example |
-|--------|------|---------|
-| `in Xm/h/d` | One-shot | `in 30m`, `in 2h` |
-| `every Xm/h` | Recurring interval | `every 30m` |
-| Cron expression | Recurring (5-field) | `0 9 * * *` |
+Tomo can create scheduled tasks on its own — just ask "remind me in 30 minutes to stretch" or "check the weather every morning at 9am." Supports one-shot reminders, recurring intervals, and cron expressions.
 
 ### Sessions
 
@@ -138,7 +135,7 @@ Structured logs via [pino](https://github.com/pinojs/pino):
 
 ```
 ~/.tomo/
-  config.json                 # Telegram token, model
+  config.json                 # Channels, identities, model, settings
   tomo.pid                    # PID file (when running)
   workspace/
     SOUL.md                   # Your personality config
@@ -155,14 +152,23 @@ Structured logs via [pino](https://github.com/pinojs/pino):
 
 ## Configuration
 
-Config lives at `~/.tomo/config.json`:
+Run `tomo config` for interactive setup, or edit `~/.tomo/config.json` directly:
 
 ```json
 {
   "channels": {
-    "telegram": { "token": "your-bot-token" }
+    "telegram": { "token": "your-bot-token", "allowlist": ["123456789"] },
+    "imessage": { "url": "http://localhost:1234", "password": "...", "allowlist": ["+15551234567"] }
   },
-  "model": "claude-sonnet-4-6"
+  "identities": [
+    {
+      "name": "yourname",
+      "channels": { "telegram": "123456789", "imessage": "+15551234567" },
+      "replyPolicy": "last-active"
+    }
+  ],
+  "model": "claude-sonnet-4-6",
+  "groupSecret": "tomo-xxxxxxxx"
 }
 ```
 
@@ -171,6 +177,7 @@ Environment variables override config file values:
 | Variable | Description |
 |----------|-------------|
 | `TELEGRAM_BOT_TOKEN` | Override Telegram token |
+| `IMESSAGE_URL` | Override BlueBubbles URL |
 | `CLAUDE_MODEL` | Override model |
 | `TOMO_WORKSPACE` | Override workspace directory |
 | `LOG_LEVEL` | Log level (default: `debug`) |

package/defaults/skills/lcm/SKILL.md

@@ -39,32 +39,67 @@ Replace a heavy section with a summary. Use timestamps to specify the range:
 tomo lcm compact --session-id SESSION_ID \
   --from-time "2026-03-28T16:29" \
   --to-time "2026-03-28T19:09" \
-  --summary "Refactored auth module: extracted middleware, added JWT validation, updated 12 routes. Tests passing."
+  --summary "2026-03-28: Refactored auth module: extracted middleware, added JWT validation, updated 12 routes. Tests passing."
 ```
 
-- `--from-time` / `--to-time`: ISO timestamps (you already know these from the conversation)
+- `--from-time` / `--to-time`: ISO timestamps — you already know these from the conversation, no need to run stats first
 - `--summary`: Write a concise summary of what happened in that range — you know best since you just did the work
 
 **Workflow:**
 1. After completing a big task, decide what can be compacted
-2. You already know the time range from the timestamps in the conversation
+2. Read the time range directly from conversation timestamps — no need to run `stats` first
 3. Write a summary capturing key decisions, outcomes, and anything worth remembering
 4. Run `tomo lcm compact` with the time range and your summary
-5. Optionally run `tomo lcm stats` first if you want to see the full breakdown
+5. Optionally run `tomo lcm stats` to verify the result
 
 The original messages are archived to the transcript file and can be searched later.
 
+**Daily memory notes:**
+
+When compacting a section, also write a brief note to `memory/YYYY-MM-DD.md` for each date covered. This creates a fast, human-readable index you can read directly — without needing to invoke any tools.
+
+```bash
+# Example: after compacting 2026-03-29
+# Append to memory/2026-03-29.md (create if it doesn't exist)
+```
+
+```markdown
+## 2026-03-29 — from LCM compact
+
+- Completed auth refactor: JWT middleware extracted, 12 routes updated
+- Discussed deployment strategy with team — decided on blue/green
+- Set up backup cron job
+```
+
+Two-layer recall:
+1. **`memory/YYYY-MM-DD.md`** — read directly, fast, no tools needed
+2. **`tomo lcm search`** — when you need the raw original messages
+
+**Writing good summaries:**
+- Use your own natural voice — more like a note to your future self than a changelog
+- Always include explicit dates in **YYYY-MM-DD format** for anything date-specific — e.g. "2026-03-29: published first blog post". This makes `tomo lcm search` much more useful later.
+- Record *outcomes* and *key decisions*, not every step taken
+- For tool-heavy sections (browser loops, exec retries): one sentence on what was attempted and whether it worked
+- For conversations: preserve texture — a key quote or specific detail is worth more than a paragraph of abstraction
+
 ## Search past conversations
 
 Search the transcript archive for past messages:
 
 ```bash
-tomo lcm search --channel-key CHANNEL_KEY --query "momo"
+# Search both current transcript AND archive (requires --session-id)
+tomo lcm search --channel-key CHANNEL_KEY --session-id SESSION_ID --query "momo"
+
+# Search by sequence range
 tomo lcm search --channel-key CHANNEL_KEY --from-seq 100 --to-seq 200
-tomo lcm search --channel-key CHANNEL_KEY --query "blog" --limit 10
+
+# Limit results
+tomo lcm search --channel-key CHANNEL_KEY --session-id SESSION_ID --query "blog" --limit 10
 ```
 
-Your channel key is in your system prompt under `# SESSION`.
+Your channel key and session ID are in your system prompt under `# SESSION`.
+
+**Note:** Always include `--session-id` to search the archive — without it, only the current transcript is searched.
 
 Add `--json` for machine-readable output.
 
@@ -73,4 +108,4 @@ Add `--json` for machine-readable output.
 - After completing a big task with many tool calls (file operations, debugging, etc.)
 - When you notice context is above 70% capacity
 - When the harness warns you about context usage
-- Compact `tool_ops` sections first — they're usually the largest and least important to keep verbatim
+- Prioritize sections with many tool calls (browser, exec, Read/Edit loops) — these are usually the largest and least important to keep verbatim

package/dist/agent.d.ts

@@ -2,15 +2,22 @@ import type { Channel } from "./channels/types.js";
 export declare class Agent {
     private channels;
     private sessions;
+    private router;
     private liveSessions;
+    private messageQueues;
     private groupParticipants;
     private modelOverrides;
     private lastPromptHash;
     constructor();
+    /** Look up a channel by name */
+    private getChannel;
+    /** Activate a group chat by adding it to the channel's allowlist */
+    private activateGroup;
     addChannel(channel: Channel): void;
+    /** Queue messages per session key so they process sequentially */
+    private enqueueMessage;
     private static readonly AVAILABLE_MODELS;
     private handleCommand;
-    private sessionKey;
     private getOrCreateLiveSession;
     private closeLiveSession;
     private hashString;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AAiTpE,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,cAAc,CAAc;;IAMpC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAMlC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAItC;YAEY,aAAa;IAkC3B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,sBAAsB;IA4B9B,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,UAAU;YAQJ,aAAa;YAsFb,YAAY;YA8CZ,kBAAkB;IA0BhC,OAAO,CAAC,eAAe;IAWvB,sCAAsC;IAChC,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgD9F,0EAA0E;IACpE,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBrD,OAAO,CAAC,cAAc;IAShB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AA8TpE,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,cAAc,CAAc;;IAYpC,gCAAgC;IAChC,OAAO,CAAC,UAAU;IAIlB,oEAAoE;YACtD,aAAa;IAsB3B,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAMlC,kEAAkE;YACpD,cAAc;IAS5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAItC;YAEY,aAAa;IAkC3B,OAAO,CAAC,sBAAsB;IA4B9B,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,UAAU;YAQJ,aAAa;YA6Hb,YAAY;YA8CZ,kBAAkB;IA+BhC,OAAO,CAAC,eAAe;IAWvB,sCAAsC;IAChC,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqE9F,0EAA0E;IACpE,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrD,OAAO,CAAC,cAAc;IAShB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAM5B"}

package/dist/agent.js

@@ -1,8 +1,9 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
-import { config } from "./config.js";
+import { config, CONFIG_PATH } from "./config.js";
 import { buildSystemPrompt } from "./workspace/index.js";
 import { SessionStore } from "./sessions/index.js";
 import { checkAndClearCompactTrigger } from "./lcm/index.js";
+import { IdentityRouter } from "./router.js";
 import { log } from "./logger.js";
 function isSilentReply(text) {
     return /^\s*NO_REPLY\s*$/i.test(text);
@@ -54,6 +55,7 @@ class LiveSession {
     sessionId = null;
     alive = true;
     lastResult = null;
+    prevTotalCost = 0;
     eventLoopDone;
     constructor(options) {
         this.q = query({ prompt: this.messageGenerator(), options });
@@ -121,9 +123,13 @@ class LiveSession {
             const output = u?.output_tokens ?? 0;
             const cacheRead = u?.cache_read_input_tokens ?? 0;
             const cacheCreated = u?.cache_creation_input_tokens ?? 0;
+            // Compute per-turn cost as delta from cumulative total
+            const totalCost = result.total_cost_usd ?? 0;
+            const turnCost = totalCost - this.prevTotalCost;
+            this.prevTotalCost = totalCost;
             // Store result stats, get context usage, then resolve
             this.lastResult = {
-                costUsd: result.total_cost_usd ?? 0,
+                costUsd: totalCost,
                 inputTokens: input,
                 outputTokens: output,
                 cacheReadTokens: cacheRead,
@@ -132,7 +138,7 @@ class LiveSession {
                 contextMax: 0,
             };
             // Await context usage before resolving so stats are complete
-            await this.logContextUsage(result, input, output, cacheRead, cacheCreated);
+            await this.logContextUsage(result, turnCost, totalCost, input, output, cacheRead, cacheCreated);
             const response = this.parts.join("\n").trim() || "I'm not sure how to respond to that.";
             this.parts = [];
             this.streamingText = "";
@@ -140,7 +146,7 @@ class LiveSession {
             this.currentRequest = null;
         }
     }
-    async logContextUsage(result, input, output, cacheRead, cacheCreated) {
+    async logContextUsage(result, turnCost, totalCost, input, output, cacheRead, cacheCreated) {
         const contextInfo = await (async () => {
             try {
                 const ctx = await this.q.getContextUsage();
@@ -148,6 +154,9 @@ class LiveSession {
                 if (this.lastResult) {
                     this.lastResult.contextUsed = ctx.totalTokens;
                     this.lastResult.contextMax = ctx.maxTokens;
+                    this.lastResult.contextBreakdown = ctx.categories
+                        .filter((c) => c.tokens > 0)
+                        .map((c) => ({ name: c.name, tokens: c.tokens }));
                 }
                 if (pct >= 80) {
                     log.warn({ used: ctx.totalTokens, max: ctx.maxTokens, pct: `${pct}%` }, "Context nearing compaction");
@@ -166,7 +175,8 @@ class LiveSession {
         log.info({
             turns: result.num_turns,
             duration: `${result.duration_ms}ms`,
-            cost: `$${result.total_cost_usd?.toFixed(4)}`,
+            cost: `$${turnCost.toFixed(4)}`,
+            totalCost: `$${totalCost.toFixed(4)}`,
             tokens: `in:${input} out:${output}`,
             cache: `read:${cacheRead} created:${cacheCreated}`,
             context: contextInfo,
@@ -239,25 +249,68 @@ function summarizeToolInput(name, input) {
 export class Agent {
     channels = [];
     sessions;
+    router;
     liveSessions = new Map();
+    messageQueues = new Map();
     groupParticipants = new Map();
     modelOverrides = new Map();
     lastPromptHash = "";
     constructor() {
         this.sessions = new SessionStore(config.sessionsDir, config.historyLimit);
+        this.router = new IdentityRouter(config.identities, this.sessions, config.channelAllowlists);
+        // Load persistent per-session model overrides
+        for (const [key, model] of Object.entries(config.sessionModelOverrides)) {
+            this.modelOverrides.set(key, model);
+        }
+    }
+    /** Look up a channel by name */
+    getChannel(name) {
+        return this.channels.find((ch) => ch.name === name);
+    }
+    /** Activate a group chat by adding it to the channel's allowlist */
+    async activateGroup(channel, chatId) {
+        try {
+            const { readFileSync, writeFileSync } = await import("node:fs");
+            const cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+            const channels = (cfg.channels ?? {});
+            if (!channels[channel.name])
+                channels[channel.name] = {};
+            const allowlist = (channels[channel.name].allowlist ?? []);
+            if (!allowlist.includes(chatId)) {
+                allowlist.push(chatId);
+                channels[channel.name].allowlist = allowlist;
+                cfg.channels = channels;
+                writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+                // Update the router's in-memory allowlist
+                this.router.addToAllowlist(channel.name, chatId);
+            }
+            log.info({ channel: channel.name, chatId }, "Group chat activated via secret");
+            await channel.send({ chatId, text: "Tomo activated in this group." });
+        }
+        catch (err) {
+            log.error({ err }, "Failed to activate group");
+        }
     }
     addChannel(channel) {
-        channel.onMessage((msg) => this.handleMessage(channel, msg));
+        channel.onMessage((msg) => this.enqueueMessage(channel, msg));
         channel.onCommand((cmd, chatId, senderName, args) => this.handleCommand(channel, cmd, chatId, senderName, args));
         this.channels.push(channel);
     }
+    /** Queue messages per session key so they process sequentially */
+    async enqueueMessage(channel, message) {
+        const isGroup = message.isGroup ?? false;
+        const { sessionKey } = this.router.resolve(channel.name, message.chatId, isGroup);
+        const prev = this.messageQueues.get(sessionKey) ?? Promise.resolve();
+        const next = prev.then(() => this.handleMessage(channel, message)).catch(() => { });
+        this.messageQueues.set(sessionKey, next);
+    }
     static AVAILABLE_MODELS = {
         "sonnet": "claude-sonnet-4-6[1m]",
         "opus": "claude-opus-4-6[1m]",
         "haiku": "claude-haiku-4-5",
     };
     async handleCommand(channel, command, chatId, senderName, args) {
-        const key = this.sessionKey(channel, chatId);
+        const { sessionKey: key } = this.router.resolve(channel.name, chatId, false);
         if (command === "new") {
             this.closeLiveSession(key);
             this.sessions.clearSdkSessionId(key);
@@ -286,9 +339,6 @@ export class Agent {
             return;
         }
     }
-    sessionKey(channel, chatId) {
-        return `${channel.name}:${chatId}`;
-    }
     getOrCreateLiveSession(key) {
         let session = this.liveSessions.get(key);
         if (session?.isAlive())
@@ -333,10 +383,23 @@ export class Agent {
         const isGroup = message.isGroup ?? false;
         const isMentioned = message.isMentioned ?? false;
         log.info({ channel: channel.name, sender: message.senderName, group: isGroup || undefined, mentioned: isMentioned || undefined, images: hasImages ? message.images.length : undefined }, message.text);
-        const key = this.sessionKey(channel, message.chatId);
+        // Group secret activation: if message matches the secret, add group to allowlist
+        if (isGroup && config.groupSecret && message.text.trim() === config.groupSecret) {
+            await this.activateGroup(channel, message.chatId);
+            return;
+        }
+        // Allowlist check: reject messages from unknown senders
+        if (!this.router.isAllowed(channel.name, message.chatId)) {
+            log.debug({ channel: channel.name, chatId: message.chatId }, "Message blocked (not in allowlist)");
+            return;
+        }
+        const resolution = this.router.resolve(channel.name, message.chatId, isGroup);
+        const key = resolution.sessionKey;
+        const replyChannel = this.getChannel(resolution.replyTarget.channelName) ?? channel;
+        const replyChatId = resolution.replyTarget.chatId;
         const textForAgent = isGroup ? `${message.senderName}: ${message.text}` : message.text;
         if (isGroup) {
-            await this.updateGroupContext(key, message.senderName, message.chatTitle);
+            await this.updateGroupContext(key, message.senderName, channel.name, message.chatTitle);
         }
         this.sessions.append(key, {
             role: "user",
@@ -349,33 +412,50 @@ export class Agent {
             log.debug("Group message ignored (not mentioned)");
             return;
         }
-        const stopTyping = channel.startTyping(message.chatId);
+        // iMessage groups: skip typing indicator (most messages will be NO_REPLY)
+        const isImessageGroup = isGroup && channel.name === "imessage";
+        const stopTyping = isImessageGroup ? () => { } : replyChannel.startTyping(replyChatId);
         try {
             const stampedText = this.injectTimestamp(textForAgent);
-            const stream = channel.createStreamingMessage(message.chatId, message.id);
+            const stream = replyChannel.createStreamingMessage(replyChatId, isGroup ? message.id : undefined);
             const response = await this.runWithRetry(key, stampedText, (text) => {
                 stream.update(text.replace(MEDIA_RE, "").trim());
             }, message.images);
             stopTyping();
+            // If context is high, send a system nudge so the agent can compact
+            const liveSession = this.liveSessions.get(key);
+            const ctx = liveSession?.lastResult;
+            if (ctx && ctx.contextMax > 0) {
+                const pct = Math.round((ctx.contextUsed / ctx.contextMax) * 100);
+                if (pct >= 80) {
+                    this.runWithRetry(key, `System: Context usage is at ${pct}% (${ctx.contextUsed}/${ctx.contextMax} tokens). Use the lcm compact skill to free up space before the next user message.`).catch(() => { });
+                }
+            }
             this.sessions.append(key, {
                 role: "assistant",
                 content: response,
-                channel: channel.name,
+                channel: replyChannel.name,
                 timestamp: Date.now(),
             });
-            log.info({ channel: channel.name }, "Tomo: %s", response);
+            log.info({ channel: replyChannel.name }, "Tomo: %s", response);
             if (isSilentReply(response)) {
                 log.info("Silent reply (no message sent)");
                 return;
             }
+            // Surface API errors that the SDK returns as response text
+            if (/^API Error: \d+/i.test(response) || /^\{"type":"error"/.test(response)) {
+                await stream.finish();
+                await replyChannel.send({ chatId: replyChatId, text: `[error] ${response}` });
+                return;
+            }
             const { cleanText, mediaPaths } = extractMedia(response);
             if (mediaPaths.length > 0) {
                 const { existsSync: fileExists } = await import("node:fs");
                 const validPaths = mediaPaths.filter((p) => fileExists(p));
                 if (validPaths.length > 0) {
                     for (let i = 0; i < validPaths.length; i++) {
-                        await channel.send({
-                            chatId: message.chatId,
+                        await replyChannel.send({
+                            chatId: replyChatId,
                             photo: validPaths[i],
                             text: i === 0 ? cleanText : "",
                         });
@@ -393,10 +473,13 @@ export class Agent {
         catch (err) {
             stopTyping();
             log.error({ err }, "Error handling message");
-            await channel.send({
-                chatId: message.chatId,
-                text: "Sorry, something went wrong. Please try again.",
-                replyTo: message.id,
+            // iMessage groups: suppress error messages to avoid polluting the chat
+            if (isImessageGroup)
+                return;
+            const detail = err instanceof Error ? err.message : String(err);
+            await replyChannel.send({
+                chatId: replyChatId,
+                text: `[error] ${detail}`,
             });
         }
     }
@@ -438,7 +521,7 @@ export class Agent {
             throw err;
         }
     }
-    async updateGroupContext(key, senderName, chatTitle) {
+    async updateGroupContext(key, senderName, channelName, chatTitle) {
         let participants = this.groupParticipants.get(key);
         const isNew = !participants;
         if (!participants) {
@@ -450,7 +533,11 @@ export class Agent {
         if (isNew || !wasKnown) {
             const names = [...participants].join(", ");
             const title = chatTitle ? `"${chatTitle}"` : "a group chat";
-            const contextMsg = `System: You are in ${title}. Participants so far: ${names}. Messages are prefixed with sender names.`;
+            let contextMsg = `System: You are in ${title}. Participants so far: ${names}. Messages are prefixed with sender names.`;
+            // iMessage groups: inject guidance to stay silent unless needed
+            if (isNew && channelName === "imessage") {
+                contextMsg += " This is an iMessage group chat. You see every message but should only reply when you have something genuinely useful to add. Reply NO_REPLY to stay silent. Do not respond to casual chatter, greetings, or messages not directed at you.";
+            }
             try {
                 await this.runWithRetry(key, contextMsg);
                 log.info({ group: chatTitle, participants: names }, "Group context updated");
@@ -472,26 +559,56 @@ export class Agent {
     }
     /** Handle a cron-triggered message */
     async handleCronMessage(message, channelName, chatId) {
-        const channel = channelName
-            ? this.channels.find((ch) => ch.name === channelName)
-            : this.channels[0];
-        if (!channel) {
-            log.warn({ channelName }, "Cron: no channel found for delivery");
-            return;
-        }
-        const targetChatId = chatId ?? this.findLastChatId(channel.name);
-        if (!targetChatId) {
-            log.warn({ channel: channel.name }, "Cron: no chatId available for delivery");
-            return;
+        // Resolve delivery target
+        let key;
+        let deliveryChannel;
+        let deliveryChatId;
+        if (channelName && chatId) {
+            // Explicit channel+chatId from cron job — resolve through router for identity support
+            const resolution = this.router.resolve(channelName, chatId, false);
+            key = resolution.sessionKey;
+            deliveryChannel = this.getChannel(resolution.replyTarget.channelName) ?? this.channels[0];
+            deliveryChatId = resolution.replyTarget.chatId;
+        }
+        else {
+            // No explicit target — try unified dm session first, then fall back to channel scan
+            const dmKey = this.router.findFirstDmSession();
+            if (dmKey) {
+                key = dmKey;
+                const target = this.router.getReplyTarget(dmKey);
+                if (target) {
+                    deliveryChannel = this.getChannel(target.channelName) ?? this.channels[0];
+                    deliveryChatId = target.chatId;
+                }
+                else {
+                    log.warn("Cron: dm session has no reply target");
+                    return;
+                }
+            }
+            else {
+                // Legacy fallback: find last active chatId on first channel
+                const channel = this.channels[0];
+                if (!channel) {
+                    log.warn("Cron: no channel available");
+                    return;
+                }
+                const fallbackChatId = this.findLastChatId(channel.name);
+                if (!fallbackChatId) {
+                    log.warn({ channel: channel.name }, "Cron: no chatId available");
+                    return;
+                }
+                key = `${channel.name}:${fallbackChatId}`;
+                deliveryChannel = channel;
+                deliveryChatId = fallbackChatId;
+            }
         }
-        const key = this.sessionKey(channel, targetChatId);
         const stampedMessage = this.injectTimestamp(message);
-        log.info({ channel: channel.name, sender: "cron" }, message);
-        const stopTyping = channel.startTyping(targetChatId);
+        log.info({ channel: deliveryChannel.name, sender: "cron" }, message);
+        const stopTyping = deliveryChannel.startTyping(deliveryChatId);
         try {
             const response = await this.runWithRetry(key, stampedMessage);
             stopTyping();
-            log.info({ channel: channel.name }, "Tomo: %s", response);
+            log.info({ channel: deliveryChannel.name }, "Tomo: %s", response);
             if (isSilentReply(response)) {
                 log.info("Cron completed silently (no reply sent)");
                 return;
@@ -499,34 +616,42 @@ export class Agent {
             this.sessions.append(key, {
                 role: "assistant",
                 content: response,
-                channel: channel.name,
+                channel: deliveryChannel.name,
                 timestamp: Date.now(),
             });
-            await channel.send({ chatId: targetChatId, text: response });
+            await deliveryChannel.send({ chatId: deliveryChatId, text: response });
         }
         catch (err) {
             stopTyping();
             log.error({ err }, "Cron message handling failed");
+            const detail = err instanceof Error ? err.message : String(err);
+            await deliveryChannel.send({ chatId: deliveryChatId, text: `[error] cron failed: ${detail}` });
         }
     }
     /** Handle a continuity heartbeat — runs on the first active DM session */
     async handleContinuity(prompt) {
-        // Find the first active DM session
-        const channel = this.channels[0];
-        if (!channel) {
-            log.warn("Continuity: no channel available");
-            return;
-        }
-        const targetChatId = this.findLastChatId(channel.name);
-        if (!targetChatId) {
-            log.debug("Continuity: no active session, skipping");
-            return;
+        // Prefer unified dm session, then fall back to channel-scoped session
+        const dmKey = this.router.findFirstDmSession();
+        let key;
+        if (dmKey) {
+            key = dmKey;
+        }
+        else {
+            const channel = this.channels[0];
+            if (!channel) {
+                log.warn("Continuity: no channel available");
+                return;
+            }
+            const chatId = this.findLastChatId(channel.name);
+            if (!chatId) {
+                log.debug("Continuity: no active session, skipping");
+                return;
+            }
+            key = `${channel.name}:${chatId}`;
         }
-        const key = this.sessionKey(channel, targetChatId);
         try {
             const response = await this.runWithRetry(key, prompt);
             log.info("Continuity response: %s", response.slice(0, 100));
-            // Continuity responses are always silent — agent should reply NO_REPLY
         }
         catch (err) {
             log.error({ err }, "Continuity heartbeat failed");