alvin-bot 4.13.2 → 4.14.1

package/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.14.1] — 2026-04-16
+
+### 🐛 Patch: `/subagents list` now shows v4.13+ dispatch agents too
+
+**Bug Ali caught:** typing `/subagents list` in Telegram while a `alvin_dispatch_agent` sub-agent was actively running returned "no agents running" — even though the user could see the agent finish and deliver a result shortly after. Cross-platform effect too: `/alvin` slash command on Slack had the same display gap.
+
+**Root cause:** two separate registries for sub-agents:
+- `src/services/subagents.ts` `activeAgents` Map — used since v4.0.0 for bot-level sub-agents (cron spawns, implicit Task tool children, `/sub-agents spawn` CLI)
+- `src/services/async-agent-watcher.ts` `pending` Map — used since v4.13 for detached `alvin_dispatch_agent` subprocesses
+
+`/subagents list` only read from the first map. The entire v4.13+ dispatch path was invisible in the listing.
+
+**Fix:** new `listActiveSubAgents()` helper in subagents.ts that merges both registries. Pending async-agent-watcher entries get synthesized into `SubAgentInfo` shape (status="running", source="cron", depth=0, platform preserved). The `/subagents list` handler and the default-render path both switch to the merged helper. The old `listSubAgents()` function stays pure (unchanged behavior) — cancel/result paths still use it because detached subprocess PIDs aren't tracked.
+
+### Technical details
+
+- `listActiveSubAgents()` is async (lazy dynamic import of the watcher module to keep subagents.ts load order clean) — existing `listSubAgents()` remains sync for the v4.0.0 consumers
+- Synthesis mapping: `PendingAsyncAgent.agentId → SubAgentInfo.id`, `description → name`, `startedAt → startedAt`, always `status="running"` (pending by definition), `source="cron"` (matches watcher's delivery banner), `depth=0`
+- Platform field preserved so the renderer can show cross-platform context if desired later
+
+### Testing
+
+- **Baseline**: 492 tests (v4.14.0)
+- **New**: `test/list-subagents-merged.test.ts` — 6 tests (empty state, single slack agent, multi-platform merge, timestamp preservation, source tag, listSubAgents purity guard)
+- **Total**: 498 tests, all green, TSC clean
+
+### Files changed
+
+- **Modified**: `src/services/subagents.ts` (new listActiveSubAgents helper), `src/handlers/commands.ts` (both /subagents list paths switch to merged view)
+- **NEW tests**: `test/list-subagents-merged.test.ts`
+- **Version**: `package.json` 4.14.0 → 4.14.1
+
+---
+
+## [4.14.0] — 2026-04-16
+
+### ✨ Sub-agent dispatch on Slack, Discord, WhatsApp (Telegram unchanged)
+
+v4.13.0 shipped truly-detached sub-agents via the `mcp__alvin__dispatch_agent` MCP tool, but only Telegram passed the required `alvinDispatchContext` to the provider. Slack/Discord/WhatsApp users couldn't trigger background sub-agents — the tool was visible to Claude but effectively unreachable.
+
+v4.14 wires the same dispatch path through the non-Telegram handler (`src/handlers/platform-message.ts`) and adds a platform-aware delivery router so results come back on the same platform they were dispatched from.
+
+**Telegram is untouched.** The v4.13.0 Telegram pipeline (message.ts → Claude SDK → alvin_dispatch_agent → watcher → grammy-api delivery) is bit-for-bit identical. Only the types widened (`chatId: number | string`, `platform?: ...`), and the new code paths activate only when `platform !== "telegram"`.
+
+### Technical details
+
+**Type widening** (`src/services/async-agent-watcher.ts`, `src/services/alvin-dispatch.ts`, `src/services/alvin-mcp-tools.ts`, `src/providers/types.ts`, `src/services/subagents.ts`):
+- `PendingAsyncAgent.chatId` / `userId`: `number` → `number | string`
+- `PendingAsyncAgent.platform?: "telegram" | "slack" | "discord" | "whatsapp"` (optional, undefined = telegram)
+- `SubAgentInfo.parentChatId`: same widening
+- `SubAgentInfo.platform?: ...` new field
+- `DispatchInput`, `AlvinDispatchContext`, `QueryOptions.alvinDispatchContext`: same widening + `platform` field
+
+Pre-v4.14 persisted `async-agents.json` entries keep working — missing `platform` field defaults to `telegram`, numeric `chatId` still routes through grammy.
+
+**New module** `src/services/delivery-registry.ts`:
+- `registerDeliveryAdapter({ platform, sendText, sendDocument? })` — called by each platform module at startup
+- `getDeliveryAdapter(platform)` — watcher lookup
+- Tiny surface: sendText + optional sendDocument, string | number chatId, no Markdown or live-stream
+
+**Delivery router** `src/services/subagent-delivery.ts` `deliverSubAgentResult()`:
+- Branches on `info.platform ?? "telegram"`:
+  - `telegram` → existing grammy path (unchanged Markdown parsing, file uploads, 3800-char chunking)
+  - `slack`/`discord`/`whatsapp` → new `deliverViaRegistry()` path — plain text (no Markdown), 3800-char chunks, optional file upload via adapter.sendDocument
+
+**Adapter registration** in `src/platforms/slack.ts`, `src/platforms/discord.ts`, `src/platforms/whatsapp.ts`:
+- Each platform's `start()` now calls `registerDeliveryAdapter` at the end
+- The adapter's `sendText` wraps the existing platform `sendText` (no duplicate code)
+
+**Handler wiring** `src/handlers/platform-message.ts`:
+- When the active provider is SDK, `alvinDispatchContext: { chatId, userId, sessionKey, platform }` is passed in queryOpts — mirrors the Telegram handler's v4.13.0 behavior
+- Claude sees the same `mcp__alvin__dispatch_agent` tool and uses it the same way
+
+### Testing
+
+- **Baseline**: 483 tests (v4.13.2)
+- **New**:
+  - `test/delivery-registry.test.ts` — 4 tests (register/get roundtrip, unregistered returns null, re-register replaces, per-platform isolation)
+  - `test/subagent-delivery-platform-routing.test.ts` — 5 tests (slack routes via registry not grammy, telegram defaults still use grammy, discord routes correctly, orphan platform skips gracefully, long output chunks on non-telegram adapters)
+- **Total**: 492 tests, all green, TSC clean
+- **Telegram regression guard**: the routing test explicitly verifies `info.platform=undefined` still hits grammy, and `info.platform='slack'` never touches grammy. That's the load-bearing invariant.
+
+### Files changed
+
+- **NEW**: `src/services/delivery-registry.ts`, `test/delivery-registry.test.ts`, `test/subagent-delivery-platform-routing.test.ts`
+- **Modified**: `src/services/async-agent-watcher.ts` (chatId widening + platform field), `src/services/subagent-delivery.ts` (platform router + plain-text banner variant), `src/services/alvin-dispatch.ts` (type widening), `src/services/alvin-mcp-tools.ts` (context pass-through), `src/services/subagents.ts` (SubAgentInfo.platform + widened parentChatId), `src/providers/types.ts` (QueryOptions.alvinDispatchContext extended), `src/handlers/platform-message.ts` (dispatch context), `src/platforms/slack.ts` / `discord.ts` / `whatsapp.ts` (adapter registration)
+- **Version**: `package.json` 4.13.2 → 4.14.0 (minor bump — new public surface: delivery-registry, platform field)
+
+### Known limitations
+
+- **Slack slash command context**: when a user invokes `/alvin <prompt>` in Slack, dispatch works (same codepath), but the sub-agent result delivery lands as a persistent channel message, not an ephemeral slash-command response. If you want ephemeral replies, use DM.
+- **Discord/WhatsApp not smoke-tested**: the code paths match Slack, and the adapter registration is symmetric, but I only end-to-end tested Slack. YMMV until you run a real test.
+
+---
+
 ## [4.13.2] — 2026-04-16
 
 ### ✨ Slack: `/alvin` slash commands + rewritten setup guide

package/dist/handlers/commands.js

@@ -1910,7 +1910,7 @@ export function registerCommands(bot) {
     // type both "/sub-agents" and "/subagents" — Telegram routes both to this.
     bot.command(["sub_agents", "subagents"], async (ctx) => {
         const lang = getSession(ctx.from.id).language;
-        const { listSubAgents, cancelSubAgent, getSubAgentResult, getMaxParallelAgents, getConfiguredMaxParallel, setMaxParallelAgents, findSubAgentByName, getVisibility, setVisibility, getQueueCap, setQueueCap, getDefaultTimeoutMs, setDefaultTimeoutMs, } = await import("../services/subagents.js");
+        const { listSubAgents, listActiveSubAgents, cancelSubAgent, getSubAgentResult, getMaxParallelAgents, getConfiguredMaxParallel, setMaxParallelAgents, findSubAgentByName, getVisibility, setVisibility, getQueueCap, setQueueCap, getDefaultTimeoutMs, setDefaultTimeoutMs, } = await import("../services/subagents.js");
         const arg = (ctx.match || "").trim();
         const tokens = arg.split(/\s+/).filter(Boolean);
         const sub = tokens[0]?.toLowerCase() || "";
@@ -2040,8 +2040,10 @@ export function registerCommands(bot) {
             return;
         }
         // /sub-agents list  — same rendering as the default, but forced
+        // v4.14.1 — uses listActiveSubAgents (merged view) so v4.13+
+        // alvin_dispatch_agent detached subprocesses also show up here.
         if (sub === "list") {
-            const agents = listSubAgents();
+            const agents = await listActiveSubAgents();
             if (agents.length === 0) {
                 await ctx.reply(t("bot.subagents.noneRunning", lang));
                 return;
@@ -2142,7 +2144,8 @@ export function registerCommands(bot) {
         const timeoutLabel = currentTimeout <= 0
             ? `⏱ Timeout: *∞ (unlimited)*`
             : `⏱ Timeout: *${Math.round(currentTimeout / 1000)}s*`;
-        const agents = listSubAgents();
+        // v4.14.1 — merged view incl. v4.13+ alvin_dispatch_agent agents.
+        const agents = await listActiveSubAgents();
         let body = "";
         if (agents.length === 0) {
             body = `\n${t("bot.subagents.noneRunning", lang)}`;

package/dist/handlers/platform-message.js

@@ -171,6 +171,18 @@ export async function handlePlatformMessage(msg, adapter) {
             effort: session.effort,
             sessionId: isSDK ? session.sessionId : null,
             history: !isSDK ? session.history : undefined,
+            // v4.14 — Expose alvin_dispatch_agent MCP tool on non-Telegram
+            // platforms too (Slack/Discord/WhatsApp). The watcher routes the
+            // eventual delivery via the platform's registered DeliveryAdapter.
+            // Only for SDK provider (where MCP tools are supported).
+            alvinDispatchContext: isSDK
+                ? {
+                    chatId: msg.chatId,
+                    userId: msg.userId,
+                    sessionKey,
+                    platform: msg.platform,
+                }
+                : undefined,
         };
         if (!isSDK) {
             addToHistory(sessionKey, { role: "user", content: fullText });

package/dist/platforms/discord.js

@@ -83,6 +83,20 @@ export class DiscordAdapter {
             });
             await this.client.login(this.token);
             console.log(`🎮 Discord adapter started (${this.client.user?.tag})`);
+            // v4.14 — Register with the delivery registry so the async-agent
+            // watcher can deliver background sub-agent results back to Discord.
+            try {
+                const { registerDeliveryAdapter } = await import("../services/delivery-registry.js");
+                registerDeliveryAdapter({
+                    platform: "discord",
+                    sendText: async (chatId, text) => {
+                        await this.sendText(String(chatId), text);
+                    },
+                });
+            }
+            catch (err) {
+                console.warn("[discord] failed to register delivery adapter:", err);
+            }
         }
         catch (err) {
             _discordState.status = "error";

package/dist/platforms/slack.js

@@ -110,6 +110,21 @@ export class SlackAdapter {
             _slackState.status = "connected";
             _slackState.connectedAt = Date.now();
             console.log(`\uD83D\uDCAC Slack connected (${_slackState.botName} @ ${_slackState.teamName})`);
+            // v4.14 — Register this adapter with the delivery registry so the
+            // async-agent watcher can deliver background sub-agent results
+            // back to Slack. The registry accepts string channel IDs directly.
+            try {
+                const { registerDeliveryAdapter } = await import("../services/delivery-registry.js");
+                registerDeliveryAdapter({
+                    platform: "slack",
+                    sendText: async (chatId, text) => {
+                        await this.sendText(String(chatId), text);
+                    },
+                });
+            }
+            catch (err) {
+                console.warn("[slack] failed to register delivery adapter:", err);
+            }
         }
         catch (err) {
             _slackState.status = "error";

package/dist/platforms/whatsapp.js

@@ -217,6 +217,20 @@ export class WhatsAppAdapter {
             connectedAt: null, error: null, info: null,
         };
         await this.connect();
+        // v4.14 — Register with the delivery registry so the async-agent
+        // watcher can deliver background sub-agent results back to WhatsApp.
+        try {
+            const { registerDeliveryAdapter } = await import("../services/delivery-registry.js");
+            registerDeliveryAdapter({
+                platform: "whatsapp",
+                sendText: async (chatId, text) => {
+                    await this.sendText(String(chatId), text);
+                },
+            });
+        }
+        catch (err) {
+            console.warn("[whatsapp] failed to register delivery adapter:", err);
+        }
     }
     async connect() {
         let baileys;

package/dist/services/alvin-dispatch.js

@@ -108,6 +108,7 @@ export function dispatchDetachedAgent(input) {
         userId: input.userId,
         toolUseId: null,
         sessionKey: input.sessionKey,
+        platform: input.platform,
     });
     // Increment the session's pendingBackgroundCount so the main handler
     // knows a background task is in flight (same signal path as SDK's

package/dist/services/alvin-mcp-tools.js

@@ -70,6 +70,7 @@ export function buildAlvinMcpServer(ctx) {
                         chatId: ctx.chatId,
                         userId: ctx.userId,
                         sessionKey: ctx.sessionKey,
+                        platform: ctx.platform,
                         cwd: ctx.cwd,
                     });
                     return {

package/dist/services/async-agent-watcher.js

@@ -83,6 +83,7 @@ export function registerPendingAgent(input) {
         giveUpAt: input.giveUpAt ?? now + MAX_AGENT_AGE_MS,
         toolUseId: input.toolUseId,
         sessionKey: input.sessionKey,
+        platform: input.platform,
     };
     pending.set(input.agentId, entry);
     saveToDisk();
@@ -175,6 +176,7 @@ async function deliverAsCompleted(entry, output, tokensUsed) {
         source: "cron", // Reuse cron banner format — fits async background agents.
         depth: 0,
         parentChatId: entry.chatId,
+        platform: entry.platform,
     };
     const result = {
         id: entry.agentId,
@@ -202,6 +204,7 @@ async function deliverAsFailure(entry, status, error) {
         source: "cron",
         depth: 0,
         parentChatId: entry.chatId,
+        platform: entry.platform,
     };
     const result = {
         id: entry.agentId,

package/dist/services/delivery-registry.js

@@ -0,0 +1,21 @@
+const adapters = new Map();
+/**
+ * Register (or replace) an adapter for a platform. Idempotent —
+ * registering the same platform twice replaces the previous entry
+ * (handles platform-module reload during dev).
+ */
+export function registerDeliveryAdapter(adapter) {
+    adapters.set(adapter.platform, adapter);
+}
+/** Look up the adapter for a platform. Returns null if not registered. */
+export function getDeliveryAdapter(platform) {
+    return adapters.get(platform) ?? null;
+}
+/** List all registered adapters — used for /status and diagnostics. */
+export function listDeliveryAdapters() {
+    return [...adapters.values()];
+}
+/** Test-only — reset the registry between tests. */
+export function __resetForTest() {
+    adapters.clear();
+}

package/dist/services/subagent-delivery.js

@@ -244,7 +244,11 @@ export function createLiveStream(chatId, agentName) {
  * config default), then dispatches to the source-specific renderer.
  *
  * Errors are logged but never thrown — delivery must not break the sub-agent
- * lifecycle. A failed Telegram send falls through silently.
+ * lifecycle. A failed send falls through silently.
+ *
+ * v4.14 — routes by `info.platform`:
+ *   - "telegram" (default) → existing grammy pipeline (unchanged)
+ *   - "slack" / "discord" / "whatsapp" → delivery-registry lookup
  */
 export async function deliverSubAgentResult(info, result, opts = {}) {
     // Implicit spawns: the Task-tool bridge in the main stream has already
@@ -254,17 +258,28 @@ export async function deliverSubAgentResult(info, result, opts = {}) {
     const effective = opts.visibility ?? getVisibility();
     if (effective === "silent")
         return;
-    // "live" mode is handled inline by runSubAgent via LiveStream. If we
-    // get here with "live" visibility it means the live-stream path wasn't
-    // applicable (wrong source, missing editMessageText, etc.) — fall
-    // through to the normal banner+final behavior below.
+    if (!info.parentChatId) {
+        console.warn(`[subagent-delivery] missing parentChatId for ${info.name} (source=${info.source})`);
+        return;
+    }
+    // v4.14 — Platform routing. Telegram is the default path (unchanged).
+    const platform = info.platform ?? "telegram";
+    if (platform !== "telegram") {
+        await deliverViaRegistry(platform, info, result);
+        return;
+    }
+    // ── Telegram path (v4.12.x behavior, unchanged) ──────────────────
     const api = getBotApi();
     if (!api) {
         console.warn(`[subagent-delivery] no bot api available for ${info.name}`);
         return;
     }
-    if (!info.parentChatId) {
-        console.warn(`[subagent-delivery] missing parentChatId for ${info.name} (source=${info.source})`);
+    // Telegram's chatId is always a number at runtime; defensive cast.
+    const tgChatId = typeof info.parentChatId === "number"
+        ? info.parentChatId
+        : Number(info.parentChatId);
+    if (!Number.isFinite(tgChatId)) {
+        console.warn(`[subagent-delivery] invalid telegram chatId for ${info.name}`);
         return;
     }
     const banner = buildBanner(info, result);
@@ -272,32 +287,103 @@ export async function deliverSubAgentResult(info, result, opts = {}) {
     try {
         // Case 1: very long output → file upload with a short banner
         if (body.length > FILE_UPLOAD_THRESHOLD) {
-            await sendWithMarkdownFallback(api, info.parentChatId, banner);
+            await sendWithMarkdownFallback(api, tgChatId, banner);
             try {
                 const { InputFile } = await import("grammy");
                 const buf = Buffer.from(body, "utf-8");
-                await api.sendDocument(info.parentChatId, new InputFile(buf, `${info.name}.md`));
+                await api.sendDocument(tgChatId, new InputFile(buf, `${info.name}.md`));
             }
             catch (err) {
                 console.error(`[subagent-delivery] file upload failed:`, err);
-                await api.sendMessage(info.parentChatId, body.slice(0, MAX_TG_CHUNK));
+                await api.sendMessage(tgChatId, body.slice(0, MAX_TG_CHUNK));
             }
             return;
         }
         // Case 2: fits in a single message → banner + body joined
         if (body.length + banner.length + 2 <= MAX_TG_CHUNK) {
-            await sendWithMarkdownFallback(api, info.parentChatId, `${banner}\n\n${body}`);
+            await sendWithMarkdownFallback(api, tgChatId, `${banner}\n\n${body}`);
             return;
         }
         // Case 3: medium output → banner as its own message, body chunked
-        await sendWithMarkdownFallback(api, info.parentChatId, banner);
+        await sendWithMarkdownFallback(api, tgChatId, banner);
         for (let i = 0; i < body.length; i += MAX_TG_CHUNK) {
             // Body chunks are always sent as plain text — markdown across
             // arbitrary chunk boundaries would be inconsistent anyway.
-            await api.sendMessage(info.parentChatId, body.slice(i, i + MAX_TG_CHUNK));
+            await api.sendMessage(tgChatId, body.slice(i, i + MAX_TG_CHUNK));
         }
     }
     catch (err) {
         console.error(`[subagent-delivery] send failed for ${info.name}:`, err);
     }
 }
+/**
+ * v4.14 — Delivery path for non-Telegram platforms. Uses the adapter
+ * registered in delivery-registry (populated by each platform module
+ * at startup). Simpler than the Telegram path: no Markdown parsing,
+ * no live-stream mode, plain text only, chunked to a conservative
+ * 3800-char cap that all three platforms handle.
+ */
+async function deliverViaRegistry(platform, info, result) {
+    const { getDeliveryAdapter } = await import("./delivery-registry.js");
+    const adapter = getDeliveryAdapter(platform);
+    if (!adapter) {
+        console.warn(`[subagent-delivery] no ${platform} adapter registered for ${info.name} — skipping delivery`);
+        return;
+    }
+    if (info.parentChatId === undefined)
+        return;
+    // Registry adapters accept string | number chatId directly.
+    const chatId = info.parentChatId;
+    const banner = buildBannerPlain(info, result);
+    const body = result.output?.trim() || `(empty output)`;
+    const NON_TG_CHUNK = 3800;
+    const FILE_THRESHOLD = 20_000;
+    try {
+        // Very long output → file upload if supported, else truncated text
+        if (body.length > FILE_THRESHOLD) {
+            await adapter.sendText(chatId, banner);
+            if (adapter.sendDocument) {
+                try {
+                    await adapter.sendDocument(chatId, Buffer.from(body, "utf-8"), `${info.name}.md`);
+                    return;
+                }
+                catch (err) {
+                    console.error(`[subagent-delivery] ${platform} file upload failed:`, err);
+                }
+            }
+            // Fallback: chunked text if no file upload or upload failed
+            for (let i = 0; i < body.length; i += NON_TG_CHUNK) {
+                await adapter.sendText(chatId, body.slice(i, i + NON_TG_CHUNK));
+            }
+            return;
+        }
+        // Fits in one message → combined
+        if (body.length + banner.length + 2 <= NON_TG_CHUNK) {
+            await adapter.sendText(chatId, `${banner}\n\n${body}`);
+            return;
+        }
+        // Medium — banner first, then chunked body
+        await adapter.sendText(chatId, banner);
+        for (let i = 0; i < body.length; i += NON_TG_CHUNK) {
+            await adapter.sendText(chatId, body.slice(i, i + NON_TG_CHUNK));
+        }
+    }
+    catch (err) {
+        console.error(`[subagent-delivery] ${platform} send failed for ${info.name}:`, err);
+    }
+}
+/**
+ * v4.14 — Plain-text banner variant for non-Telegram platforms.
+ * No Markdown (some platforms render it inconsistently), just emoji +
+ * clean labels. Matches the info layout of buildBanner.
+ */
+function buildBannerPlain(info, result) {
+    const truncated = result.status === "completed" &&
+        (!result.output || result.output.trim().length === 0);
+    const icon = truncated ? "⚠️" : statusIcon(result.status);
+    const statusLabel = truncated ? "completed · empty output" : result.status;
+    const dur = formatDuration(result.duration);
+    const ti = formatTokens(result.tokensUsed.input);
+    const to = formatTokens(result.tokensUsed.output);
+    return `${icon} ${info.name} — ${statusLabel} · ${dur} · ${ti} in / ${to} out`;
+}

package/dist/services/subagents.js

@@ -576,10 +576,69 @@ export function spawnSubAgent(agentConfig) {
 }
 /**
  * List all agents (active + recent completed).
+ *
+ * This is the v4.0.0 API — shows only agents from the bot-level
+ * registry (activeAgents Map). Does NOT include v4.13+ detached
+ * `alvin_dispatch_agent` subprocesses which live in async-agent-
+ * watcher. For the merged view used by `/subagents list`, use
+ * `listActiveSubAgents()` instead.
  */
 export function listSubAgents() {
     return [...activeAgents.values()].map((a) => ({ ...a.info }));
 }
+/**
+ * v4.14.1 — Merged view of BOTH sub-agent registries:
+ *   1. Bot-level agents (subagents.ts activeAgents Map) — v4.0.0+
+ *      the /sub-agents spawn CLI, cron-spawned sub-agents, implicit
+ *      Task-tool children.
+ *   2. Detached `alvin_dispatch_agent` subprocesses (async-agent-
+ *      watcher pending Map) — v4.13+ the MCP-tool-dispatched
+ *      agents that survive parent aborts.
+ *
+ * The user doesn't care which registry an agent lives in — "is there
+ * anything running right now?" is the question `/subagents list`
+ * answers. This function unifies the view.
+ *
+ * Pending async agents are synthesized into SubAgentInfo shape:
+ *   - id: PendingAsyncAgent.agentId (alvin-prefixed hex)
+ *   - name: PendingAsyncAgent.description
+ *   - status: "running" (we wouldn't be pending otherwise)
+ *   - startedAt: PendingAsyncAgent.startedAt
+ *   - source: "cron" — matches the delivery banner's source tag
+ *   - depth: 0 — dispatch agents are always top-level (no nesting)
+ *   - platform: preserved from the pending entry
+ *   - parentChatId: from the pending entry
+ *
+ * Lazy import of the watcher keeps this function cheap for callers
+ * who only need the v4.0.0 view (importing the watcher pulls in its
+ * whole startup cost otherwise).
+ */
+export async function listActiveSubAgents() {
+    const botLevel = listSubAgents();
+    let pending = [];
+    try {
+        // Lazy dynamic import so this module doesn't depend on the watcher
+        // at load time (preserves test isolation + avoids a circular boot).
+        const watcher = await import("./async-agent-watcher.js");
+        if (typeof watcher.listPendingAgents === "function") {
+            const raw = watcher.listPendingAgents();
+            pending = raw.map((p) => ({
+                id: p.agentId,
+                name: p.description,
+                status: "running",
+                startedAt: p.startedAt,
+                source: "cron",
+                depth: 0,
+                platform: p.platform,
+                parentChatId: p.chatId,
+            }));
+        }
+    }
+    catch {
+        /* never break listing because of merge errors */
+    }
+    return [...botLevel, ...pending];
+}
 /**
  * Cancel a running sub-agent by ID.
  * Returns true if the agent was found and aborted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.13.2",
+  "version": "4.14.1",
   "description": "Alvin Bot \u2014 Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/delivery-registry.test.ts

@@ -0,0 +1,71 @@
+/**
+ * v4.14 — delivery-registry module tests.
+ *
+ * Registers platform adapters (slack/discord/whatsapp) so the sub-agent
+ * watcher can route delivery to the right one based on
+ * PendingAsyncAgent.platform. Telegram does NOT go through this registry
+ * — it continues to use the existing grammy-bot path via attachBotApi.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+beforeEach(() => vi.resetModules());
+
+describe("delivery-registry (v4.14)", () => {
+  it("register + get roundtrip", async () => {
+    const { registerDeliveryAdapter, getDeliveryAdapter, __resetForTest } =
+      await import("../src/services/delivery-registry.js");
+    __resetForTest();
+
+    const fake = {
+      platform: "slack" as const,
+      sendText: vi.fn(async () => {}),
+    };
+    registerDeliveryAdapter(fake);
+    expect(getDeliveryAdapter("slack")).toBe(fake);
+  });
+
+  it("returns null for unregistered platform", async () => {
+    const { getDeliveryAdapter, __resetForTest } = await import(
+      "../src/services/delivery-registry.js"
+    );
+    __resetForTest();
+    expect(getDeliveryAdapter("slack")).toBeNull();
+    expect(getDeliveryAdapter("discord")).toBeNull();
+    expect(getDeliveryAdapter("telegram")).toBeNull();
+  });
+
+  it("re-register replaces the existing adapter (handles platform reload)", async () => {
+    const {
+      registerDeliveryAdapter,
+      getDeliveryAdapter,
+      __resetForTest,
+    } = await import("../src/services/delivery-registry.js");
+    __resetForTest();
+
+    const first = { platform: "slack" as const, sendText: vi.fn(async () => {}) };
+    const second = { platform: "slack" as const, sendText: vi.fn(async () => {}) };
+    registerDeliveryAdapter(first);
+    registerDeliveryAdapter(second);
+    expect(getDeliveryAdapter("slack")).toBe(second);
+  });
+
+  it("adapters are isolated per platform", async () => {
+    const {
+      registerDeliveryAdapter,
+      getDeliveryAdapter,
+      __resetForTest,
+    } = await import("../src/services/delivery-registry.js");
+    __resetForTest();
+
+    const slack = { platform: "slack" as const, sendText: vi.fn(async () => {}) };
+    const discord = {
+      platform: "discord" as const,
+      sendText: vi.fn(async () => {}),
+    };
+    registerDeliveryAdapter(slack);
+    registerDeliveryAdapter(discord);
+    expect(getDeliveryAdapter("slack")).toBe(slack);
+    expect(getDeliveryAdapter("discord")).toBe(discord);
+    expect(getDeliveryAdapter("whatsapp")).toBeNull();
+  });
+});

package/test/list-subagents-merged.test.ts

@@ -0,0 +1,172 @@
+/**
+ * v4.14.1 — `/subagents list` must show v4.13+ dispatch agents too.
+ *
+ * Root cause: `listSubAgents()` in subagents.ts only iterates the
+ * `activeAgents` Map (B1+B2 from v4.0.0). v4.13's `alvin_dispatch_agent`
+ * MCP tool writes into `async-agent-watcher.ts`'s `pending` Map instead.
+ * User-facing impact: "no subagents running" while the bot is visibly
+ * dispatching sub-agents.
+ *
+ * Fix strategy: a new `listActiveSubAgents()` helper that merges both
+ * registries into a unified SubAgentInfo-shaped list. The `/subagents
+ * list` handler uses this instead of the bare `listSubAgents()`.
+ * Cancel/result operations keep using the old registry — we can't
+ * cancel a detached `claude -p` subprocess anyway without knowing its
+ * PID, which isn't tracked.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(
+  os.tmpdir(),
+  `alvin-list-merged-${process.pid}-${Date.now()}`,
+);
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  vi.resetModules();
+
+  vi.doMock("../src/services/subagent-delivery.js", () => ({
+    deliverSubAgentResult: async () => {},
+    attachBotApi: () => {},
+    __setBotApiForTest: () => {},
+  }));
+});
+
+afterEach(async () => {
+  try {
+    const mod = await import("../src/services/async-agent-watcher.js");
+    mod.stopWatcher();
+    mod.__resetForTest();
+  } catch {}
+});
+
+describe("listActiveSubAgents merged view (v4.14.1)", () => {
+  it("returns empty list when neither registry has agents", async () => {
+    const mod = await import("../src/services/subagents.js");
+    expect(await mod.listActiveSubAgents()).toEqual([]);
+  });
+
+  it("includes async-agent-watcher pending agents in the merged list", async () => {
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    watcher.registerPendingAgent({
+      agentId: "alvin-abc123",
+      outputFile: `${TEST_DATA_DIR}/out.jsonl`,
+      description: "Research Higgsfield",
+      prompt: "...",
+      chatId: "C012SLACK",
+      userId: "U123",
+      toolUseId: null,
+      sessionKey: "slack:C012SLACK",
+      platform: "slack",
+    });
+
+    const mod = await import("../src/services/subagents.js");
+    const agents = await mod.listActiveSubAgents();
+    expect(agents).toHaveLength(1);
+    expect(agents[0].id).toBe("alvin-abc123");
+    expect(agents[0].name).toBe("Research Higgsfield");
+    expect(agents[0].status).toBe("running");
+    expect(agents[0].depth).toBe(0);
+    expect(agents[0].platform).toBe("slack");
+  });
+
+  it("merges multiple agents from both registries without dupes", async () => {
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    watcher.registerPendingAgent({
+      agentId: "alvin-one",
+      outputFile: `${TEST_DATA_DIR}/a.jsonl`,
+      description: "Agent One",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey: "s",
+      platform: "telegram",
+    });
+    watcher.registerPendingAgent({
+      agentId: "alvin-two",
+      outputFile: `${TEST_DATA_DIR}/b.jsonl`,
+      description: "Agent Two",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey: "s",
+      platform: "telegram",
+    });
+
+    const mod = await import("../src/services/subagents.js");
+    const agents = await mod.listActiveSubAgents();
+    const ids = agents.map((a) => a.id).sort();
+    expect(ids).toEqual(["alvin-one", "alvin-two"]);
+  });
+
+  it("preserves startedAt timestamp for age rendering", async () => {
+    const fixedTs = Date.now() - 45_000; // 45 seconds ago
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    watcher.registerPendingAgent({
+      agentId: "alvin-aged",
+      outputFile: `${TEST_DATA_DIR}/aged.jsonl`,
+      description: "Old agent",
+      prompt: "p",
+      chatId: 1,
+      userId: 1,
+      toolUseId: null,
+      sessionKey: "s",
+      platform: "slack",
+    });
+
+    const mod = await import("../src/services/subagents.js");
+    const agents = await mod.listActiveSubAgents();
+    expect(agents[0].startedAt).toBeGreaterThan(fixedTs - 1000);
+    expect(agents[0].startedAt).toBeLessThan(Date.now() + 1000);
+  });
+
+  it("tags async dispatch agents with source='cron' (matches v4.12 banner format)", async () => {
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    watcher.registerPendingAgent({
+      agentId: "alvin-sourced",
+      outputFile: `${TEST_DATA_DIR}/s.jsonl`,
+      description: "sourced",
+      prompt: "p",
+      chatId: 1,
+      userId: 1,
+      toolUseId: null,
+      sessionKey: "s",
+      platform: "telegram",
+    });
+    const mod = await import("../src/services/subagents.js");
+    const agents = await mod.listActiveSubAgents();
+    // source='cron' = the ⏰ badge in /subagents list rendering. Matches
+    // the existing v4.12.x watcher delivery's SubAgentInfo.source value.
+    expect(agents[0].source).toBe("cron");
+  });
+
+  it("listSubAgents() (v4.0.0 API) is unchanged and doesn't include pending dispatches", async () => {
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    watcher.registerPendingAgent({
+      agentId: "alvin-isolated",
+      outputFile: `${TEST_DATA_DIR}/iso.jsonl`,
+      description: "isolated",
+      prompt: "p",
+      chatId: 1,
+      userId: 1,
+      toolUseId: null,
+      sessionKey: "s",
+      platform: "telegram",
+    });
+    const mod = await import("../src/services/subagents.js");
+    // The original listSubAgents is kept pure — only the merged helper
+    // returns combined results. Cancel/result paths still use the
+    // bot-level registry.
+    expect(mod.listSubAgents()).toHaveLength(0);
+    expect(await mod.listActiveSubAgents()).toHaveLength(1);
+  });
+});

package/test/subagent-delivery-platform-routing.test.ts

@@ -0,0 +1,232 @@
+/**
+ * v4.14 — subagent-delivery platform routing tests.
+ *
+ * Covers the new v4.14 behavior: deliveries with `info.platform` other
+ * than "telegram" go through the delivery-registry adapter instead of
+ * the grammy bot API. Telegram path is unchanged and still uses the
+ * injected grammy-compatible API.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+interface CapturedMsg {
+  chatId: string | number;
+  text: string;
+}
+
+beforeEach(() => vi.resetModules());
+
+async function loadModules() {
+  const delivery = await import("../src/services/subagent-delivery.js");
+  const registry = await import("../src/services/delivery-registry.js");
+  registry.__resetForTest();
+  return { delivery, registry };
+}
+
+describe("subagent-delivery platform routing (v4.14)", () => {
+  afterEach(async () => {
+    const { delivery, registry } = await loadModules();
+    delivery.__setBotApiForTest(null);
+    registry.__resetForTest();
+  });
+
+  it("info.platform='slack' routes via delivery-registry (NOT grammy api)", async () => {
+    const { delivery, registry } = await loadModules();
+
+    // Register fake Slack adapter
+    const sent: CapturedMsg[] = [];
+    registry.registerDeliveryAdapter({
+      platform: "slack",
+      sendText: async (chatId, text) => {
+        sent.push({ chatId, text });
+      },
+    });
+
+    // Set a grammy api that SHOULD NOT be called
+    const grammyCalls: CapturedMsg[] = [];
+    delivery.__setBotApiForTest({
+      sendMessage: async (chatId: number, text: string) => {
+        grammyCalls.push({ chatId, text });
+        return { message_id: 1 };
+      },
+      sendDocument: async () => ({ message_id: 1 }),
+    });
+
+    await delivery.deliverSubAgentResult(
+      {
+        id: "a1",
+        name: "Research task",
+        status: "completed",
+        startedAt: Date.now() - 5000,
+        source: "cron",
+        depth: 0,
+        parentChatId: "C012SLACKCH",
+        platform: "slack",
+      },
+      {
+        id: "a1",
+        name: "Research task",
+        status: "completed",
+        output: "Result body",
+        tokensUsed: { input: 100, output: 50 },
+        duration: 5000,
+      },
+    );
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0].chatId).toBe("C012SLACKCH");
+    expect(sent[0].text).toContain("Research task");
+    expect(sent[0].text).toContain("Result body");
+    // grammy must NOT have been touched
+    expect(grammyCalls).toHaveLength(0);
+  });
+
+  it("info.platform='telegram' (default) still uses grammy api — behavior unchanged", async () => {
+    const { delivery, registry } = await loadModules();
+
+    // Register Slack adapter that SHOULD NOT be called
+    const slackCalls: CapturedMsg[] = [];
+    registry.registerDeliveryAdapter({
+      platform: "slack",
+      sendText: async (chatId, text) => slackCalls.push({ chatId, text }),
+    });
+
+    const grammyCalls: CapturedMsg[] = [];
+    delivery.__setBotApiForTest({
+      sendMessage: async (chatId: number, text: string) => {
+        grammyCalls.push({ chatId, text });
+        return { message_id: 1 };
+      },
+      sendDocument: async () => ({ message_id: 1 }),
+    });
+
+    await delivery.deliverSubAgentResult(
+      {
+        id: "a2",
+        name: "Telegram task",
+        status: "completed",
+        startedAt: Date.now() - 3000,
+        source: "cron",
+        depth: 0,
+        parentChatId: 8425689727,
+        // platform undefined → defaults to telegram
+      },
+      {
+        id: "a2",
+        name: "Telegram task",
+        status: "completed",
+        output: "Telegram body",
+        tokensUsed: { input: 10, output: 5 },
+        duration: 3000,
+      },
+    );
+
+    expect(grammyCalls).toHaveLength(1);
+    expect(grammyCalls[0].chatId).toBe(8425689727);
+    expect(grammyCalls[0].text).toContain("Telegram body");
+    // Slack adapter must NOT have been touched
+    expect(slackCalls).toHaveLength(0);
+  });
+
+  it("info.platform='discord' routes to discord adapter", async () => {
+    const { delivery, registry } = await loadModules();
+
+    const discordCalls: CapturedMsg[] = [];
+    registry.registerDeliveryAdapter({
+      platform: "discord",
+      sendText: async (chatId, text) =>
+        discordCalls.push({ chatId, text }),
+    });
+
+    await delivery.deliverSubAgentResult(
+      {
+        id: "a3",
+        name: "Discord task",
+        status: "completed",
+        startedAt: Date.now() - 1000,
+        source: "cron",
+        depth: 0,
+        parentChatId: "1234567890123456",
+        platform: "discord",
+      },
+      {
+        id: "a3",
+        name: "Discord task",
+        status: "completed",
+        output: "Discord body",
+        tokensUsed: { input: 1, output: 1 },
+        duration: 1000,
+      },
+    );
+
+    expect(discordCalls).toHaveLength(1);
+    expect(discordCalls[0].chatId).toBe("1234567890123456");
+  });
+
+  it("non-telegram platform with NO registered adapter skips delivery (no crash)", async () => {
+    const { delivery } = await loadModules();
+
+    await expect(
+      delivery.deliverSubAgentResult(
+        {
+          id: "a4",
+          name: "Orphan",
+          status: "completed",
+          startedAt: Date.now(),
+          source: "cron",
+          depth: 0,
+          parentChatId: "C999",
+          platform: "slack",
+        },
+        {
+          id: "a4",
+          name: "Orphan",
+          status: "completed",
+          output: "x",
+          tokensUsed: { input: 1, output: 1 },
+          duration: 100,
+        },
+      ),
+    ).resolves.not.toThrow();
+  });
+
+  it("long output triggers chunking on non-Telegram adapter", async () => {
+    const { delivery, registry } = await loadModules();
+
+    const sent: string[] = [];
+    registry.registerDeliveryAdapter({
+      platform: "slack",
+      sendText: async (_chatId, text) => {
+        sent.push(text);
+      },
+    });
+
+    // Build ~8000 chars of output (forces chunking at 3800)
+    const longBody = "x".repeat(8000);
+
+    await delivery.deliverSubAgentResult(
+      {
+        id: "a5",
+        name: "Long task",
+        status: "completed",
+        startedAt: Date.now(),
+        source: "cron",
+        depth: 0,
+        parentChatId: "C1",
+        platform: "slack",
+      },
+      {
+        id: "a5",
+        name: "Long task",
+        status: "completed",
+        output: longBody,
+        tokensUsed: { input: 1, output: 1 },
+        duration: 100,
+      },
+    );
+
+    // Expect: 1 banner + multiple body chunks
+    expect(sent.length).toBeGreaterThan(1);
+    const bodyBytes = sent.slice(1).join("").length;
+    expect(bodyBytes).toBe(longBody.length);
+  });
+});