alvin-bot 4.6.0 → 4.8.0

package/dist/services/subagents.js

@@ -15,9 +15,11 @@ const DATA_DIR = process.env.ALVIN_DATA_DIR || resolve(os.homedir(), ".alvin-bot
 const CONFIG_FILE = resolve(DATA_DIR, "sub-agents.json");
 const ABSOLUTE_MAX_AGENTS = 16; // Hard cap no matter what
 const MAX_SUBAGENT_DEPTH = 2; // F2: hard cap on nested spawning
+const DEFAULT_QUEUE_CAP = 20; // D3: default bounded-queue size
+const ABSOLUTE_MAX_QUEUE = 200; // D3: absolute ceiling on queue length
 let configCache = null;
 function isValidVisibility(v) {
-    return v === "auto" || v === "banner" || v === "silent";
+    return v === "auto" || v === "banner" || v === "silent" || v === "live";
 }
 function loadSubAgentsConfig() {
     if (configCache)
@@ -28,6 +30,9 @@ function loadSubAgentsConfig() {
         configCache = {
             maxParallel: typeof parsed.maxParallel === "number" ? parsed.maxParallel : 0,
             visibility: isValidVisibility(parsed.visibility) ? parsed.visibility : "auto",
+            queueCap: typeof parsed.queueCap === "number"
+                ? Math.max(0, Math.min(Math.floor(parsed.queueCap), ABSOLUTE_MAX_QUEUE))
+                : DEFAULT_QUEUE_CAP,
         };
     }
     catch {
@@ -35,6 +40,7 @@ function loadSubAgentsConfig() {
         configCache = {
             maxParallel: Number(process.env.MAX_SUBAGENTS) || 0,
             visibility: "auto",
+            queueCap: DEFAULT_QUEUE_CAP,
         };
     }
     return configCache;
@@ -79,11 +85,23 @@ export function getVisibility() {
  */
 export function setVisibility(mode) {
     if (!isValidVisibility(mode)) {
-        throw new Error(`Invalid visibility mode "${mode}". Expected: auto | banner | silent.`);
+        throw new Error(`Invalid visibility mode "${mode}". Expected: auto | banner | silent | live.`);
     }
     const cfg = loadSubAgentsConfig();
     saveSubAgentsConfig({ ...cfg, visibility: mode });
 }
+/** D3: Current bounded-queue cap. 0 = queue disabled (reject on full pool). */
+export function getQueueCap() {
+    return loadSubAgentsConfig().queueCap;
+}
+/** D3: Set the queue cap. Clamped to [0, ABSOLUTE_MAX_QUEUE].
+ *  Returns the effective value after clamping. */
+export function setQueueCap(n) {
+    const clamped = Math.max(0, Math.min(Math.floor(n), ABSOLUTE_MAX_QUEUE));
+    const cfg = loadSubAgentsConfig();
+    saveSubAgentsConfig({ ...cfg, queueCap: clamped });
+    return clamped;
+}
 // ── State ───────────────────────────────────────────────
 const activeAgents = new Map();
 // ── Name resolver (B2) ──────────────────────────────────
@@ -167,6 +185,28 @@ export function findSubAgentByName(name, opts = {}) {
 async function runSubAgent(id, agentConfig, abort, resolvedName) {
     const startTime = Date.now();
     const entry = activeAgents.get(id);
+    // A4 live-stream state — set up if the effective visibility is "live"
+    // AND this is a user spawn with a parent chat. Cron and implicit spawns
+    // don't get live-streaming (cron because there's no interactive watcher,
+    // implicit because the parent Claude stream already shows everything).
+    let liveStream = null;
+    const effectiveVisibility = agentConfig.visibility ?? loadSubAgentsConfig().visibility;
+    if (effectiveVisibility === "live" &&
+        agentConfig.source === "user" &&
+        typeof agentConfig.parentChatId === "number") {
+        try {
+            const { createLiveStream } = await import("./subagent-delivery.js");
+            const stream = createLiveStream(agentConfig.parentChatId, resolvedName);
+            if (stream) {
+                await stream.start();
+                if (!stream.failed)
+                    liveStream = stream;
+            }
+        }
+        catch (err) {
+            console.error(`[subagent ${id}] live-stream init failed:`, err);
+        }
+    }
     try {
         const { getRegistry } = await import("../engine.js");
         const registry = getRegistry();
@@ -189,8 +229,13 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             effort: "high",
             abortSignal: abort.signal,
         })) {
-            if (chunk.type === "text")
+            if (chunk.type === "text") {
                 finalText = chunk.text || "";
+                // A4: push text updates into the throttled live-stream
+                if (liveStream && !liveStream.failed) {
+                    liveStream.update(finalText);
+                }
+            }
             if (chunk.type === "done") {
                 inputTokens = chunk.inputTokens || 0;
                 outputTokens = chunk.outputTokens || 0;
@@ -227,6 +272,20 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
             };
             entry.info.status = "completed";
         }
+        // A4: finalize the live-stream if we had one. On success, mark the
+        // entry as delivered so spawnSubAgent.finally() skips the normal
+        // deliverSubAgentResult path — the live stream already posted the
+        // body, and finalize() already posted the banner.
+        if (liveStream && !liveStream.failed && entry.result) {
+            try {
+                await liveStream.finalize(entry.info, entry.result);
+                entry.delivered = true;
+            }
+            catch (err) {
+                console.error(`[subagent ${id}] live-stream finalize failed:`, err);
+                // Let the normal delivery path fire as a fallback.
+            }
+        }
     }
     catch (err) {
         const isAbort = err instanceof Error && err.message.includes("abort");
@@ -248,109 +307,179 @@ async function runSubAgent(id, agentConfig, abort, resolvedName) {
         entry.info.status = status;
     }
 }
-// ── Public API ──────────────────────────────────────────
+const pendingQueue = [];
+/** Priority order used when draining the queue — higher index = lower priority. */
+const SOURCE_PRIORITY = ["user", "cron", "implicit"];
+function sourceOf(cfg) {
+    return cfg.source ?? "implicit";
+}
+/** Count how many agents are currently running. */
+function runningCount() {
+    return [...activeAgents.values()].filter((a) => a.info.status === "running").length;
+}
+/**
+ * Pop the next queued spawn according to priority (user > cron > implicit)
+ * and within each priority in FIFO order. Returns null if the queue is empty.
+ */
+function popHighestPriorityQueued() {
+    for (const priority of SOURCE_PRIORITY) {
+        const idx = pendingQueue.findIndex((q) => sourceOf(q.agentConfig) === priority);
+        if (idx >= 0) {
+            const [entry] = pendingQueue.splice(idx, 1);
+            return entry;
+        }
+    }
+    return null;
+}
 /**
- * Spawn an isolated sub-agent that runs in the background.
- * Returns the agent ID immediately (does NOT await completion).
+ * Recalculate queuePosition for every entry still in the queue. Called
+ * after a pop or a cancel so /subagents list reflects the current state.
  */
+function reindexQueue() {
+    for (let i = 0; i < pendingQueue.length; i++) {
+        const q = pendingQueue[i];
+        const entry = activeAgents.get(q.id);
+        if (entry)
+            entry.info.queuePosition = i + 1;
+    }
+}
+/** Drain as many queued spawns as fit into the current free slots. */
+function drainQueue() {
+    const maxParallel = getMaxParallelAgents();
+    while (pendingQueue.length > 0 && runningCount() < maxParallel) {
+        const next = popHighestPriorityQueued();
+        if (!next)
+            break;
+        const entry = activeAgents.get(next.id);
+        if (!entry)
+            continue; // was cancelled while queued
+        reindexQueue();
+        // Transition to running
+        entry.info.status = "running";
+        entry.info.startedAt = Date.now();
+        entry.info.queuePosition = undefined;
+        startRun(next);
+    }
+}
+// ── Spawn pipeline ──────────────────────────────────────────
+function startRun(q) {
+    const { id, resolvedName, agentConfig, timeoutId } = q;
+    const entry = activeAgents.get(id);
+    if (!entry)
+        return;
+    // Run in background — don't await
+    runSubAgent(id, agentConfig, entry.abort, resolvedName)
+        .finally(() => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        const currentEntry = activeAgents.get(id);
+        if (agentConfig.onComplete && currentEntry?.result) {
+            try {
+                agentConfig.onComplete(currentEntry.result);
+            }
+            catch (err) {
+                console.error(`[subagent ${id}] onComplete callback threw:`, err);
+            }
+        }
+        // I3: fire delivery router (non-blocking, errors logged). Guarded
+        // by the `delivered` flag.
+        if (currentEntry?.result && !currentEntry.delivered) {
+            currentEntry.delivered = true;
+            const resultSnapshot = currentEntry.result;
+            const infoSnapshot = currentEntry.info;
+            import("./subagent-delivery.js")
+                .then(({ deliverSubAgentResult }) => deliverSubAgentResult(infoSnapshot, resultSnapshot, {
+                visibility: agentConfig.visibility,
+            }))
+                .catch((err) => console.error(`[subagent ${id}] delivery failed:`, err));
+        }
+        // H3: record this run in the rolling 24h stats (non-blocking).
+        if (currentEntry?.result) {
+            const resultSnapshot = currentEntry.result;
+            const infoSnapshot = currentEntry.info;
+            import("./subagent-stats.js")
+                .then(({ recordSubAgentRun }) => recordSubAgentRun(infoSnapshot, resultSnapshot))
+                .catch((err) => console.error(`[subagent ${id}] stats recording failed:`, err));
+        }
+        // D3: drain the queue now that a slot has freed up
+        drainQueue();
+        // Auto-cleanup: remove completed agents after 30 minutes
+        setTimeout(() => {
+            const e = activeAgents.get(id);
+            if (e && e.info.status !== "running" && e.info.status !== "queued") {
+                activeAgents.delete(id);
+            }
+        }, 30 * 60 * 1000);
+    });
+}
 export function spawnSubAgent(agentConfig) {
     // F2: enforce depth cap before touching any state.
     const depth = agentConfig.depth ?? 0;
     if (depth > MAX_SUBAGENT_DEPTH) {
         return Promise.reject(new Error(`Sub-agent depth limit reached (${MAX_SUBAGENT_DEPTH}). Agents can only spawn ${MAX_SUBAGENT_DEPTH} level(s) of nested agents.`));
     }
-    // G1: toolset preset. Only "full" is supported in Stufe 1. The literal
-    // type blocks wrong values at compile time; the runtime check catches
-    // callers that bypass TypeScript (e.g. plugin code loaded at runtime).
+    // G1: toolset preset. Only "full" is supported. The literal type blocks
+    // wrong values at compile time; the runtime check catches callers that
+    // bypass TypeScript (e.g. plugin code loaded at runtime).
     const toolset = agentConfig.toolset ?? "full";
     if (toolset !== "full") {
         return Promise.reject(new Error(`Invalid toolset "${toolset}". Only "full" is supported in this version.`));
     }
-    // Check concurrency limit — now reads from the file-backed config so
-    // /sub-agents max <n> edits take effect immediately without a restart.
-    const running = [...activeAgents.values()].filter((a) => a.info.status === "running");
     const maxParallel = getMaxParallelAgents();
-    if (running.length >= maxParallel) {
-        // D4: priority-aware reject messages — give callers context about
-        // WHO is holding the slots so they know whether to wait, cancel,
-        // or give up.
-        const source = agentConfig.source ?? "implicit";
-        const userSlots = running.filter((a) => a.info.source === "user").length;
-        const bgSlots = running.length - userSlots;
+    const queueCap = getQueueCap();
+    const running = runningCount();
+    const queuedLen = pendingQueue.length;
+    // B2: resolve the requested name to a unique variant.
+    const resolved = resolveAgentName(agentConfig.name);
+    const resolvedName = resolved.name;
+    const id = crypto.randomUUID();
+    const timeout = agentConfig.timeout ?? config.subAgentTimeout;
+    const abort = new AbortController();
+    const timeoutId = setTimeout(() => abort.abort(), timeout);
+    const willRunImmediately = running < maxParallel;
+    const canQueue = !willRunImmediately && queueCap > 0 && queuedLen < queueCap;
+    if (!willRunImmediately && !canQueue) {
+        // No slot, no queue room → priority-aware reject
+        clearTimeout(timeoutId);
+        const source = sourceOf(agentConfig);
+        const runningAgents = [...activeAgents.values()].filter((a) => a.info.status === "running");
+        const userSlots = runningAgents.filter((a) => a.info.source === "user").length;
+        const bgSlots = runningAgents.length - userSlots;
         let message;
         if (source === "user") {
             if (bgSlots > 0) {
-                message = `Alle Slots belegt (${running.length}/${maxParallel}), davon ${bgSlots} cron/implicit im Hintergrund. /sub-agents list für Details oder /sub-agents cancel <name>.`;
+                message = `Alle Slots belegt (${running}/${maxParallel}), davon ${bgSlots} cron/implicit im Hintergrund. Queue voll (${queuedLen}/${queueCap}). /subagents list für Details oder /subagents cancel <name>.`;
             }
             else {
-                message = `Alle Slots belegt (${running.length}/${maxParallel}) mit eigenen user-Spawns. /sub-agents cancel <name> oder warten: /sub-agents list`;
+                message = `Alle Slots belegt (${running}/${maxParallel}) mit eigenen user-Spawns. Queue voll (${queuedLen}/${queueCap}). /subagents cancel <name> oder warten.`;
             }
         }
         else {
-            message = `Sub-agent limit reached (${maxParallel}). Wait for a running agent to finish or cancel one.`;
+            message = `Sub-agent limit reached (${maxParallel} running, ${queuedLen}/${queueCap} queued). Wait for a running agent to finish or cancel one.`;
         }
         return Promise.reject(new Error(message));
     }
-    // B2: resolve the requested name to a unique variant. On collision,
-    // append #N where N is the smallest free index ≥ 2.
-    const resolved = resolveAgentName(agentConfig.name);
-    const resolvedName = resolved.name;
-    const id = crypto.randomUUID();
-    const timeout = agentConfig.timeout ?? config.subAgentTimeout;
-    const abort = new AbortController();
-    // Set up timeout
-    const timeoutId = setTimeout(() => abort.abort(), timeout);
     const info = {
         id,
         name: resolvedName,
-        status: "running",
+        status: willRunImmediately ? "running" : "queued",
         startedAt: Date.now(),
         model: agentConfig.model,
         source: agentConfig.source,
         depth,
         parentChatId: agentConfig.parentChatId,
         nameIndex: resolved.index,
+        queuePosition: willRunImmediately ? undefined : queuedLen + 1,
     };
     activeAgents.set(id, { info, abort, delivered: false });
-    // Run in background — don't await
-    runSubAgent(id, agentConfig, abort, resolvedName)
-        .finally(() => {
-        clearTimeout(timeoutId);
-        // Call the onComplete callback if the caller provided one. This is
-        // how cron.ts turns the fire-and-forget spawnSubAgent() into a
-        // Promise that resolves when the work finishes. The callback runs
-        // inside a try/catch so a throwing callback can't break cleanup.
-        const entry = activeAgents.get(id);
-        if (agentConfig.onComplete && entry?.result) {
-            try {
-                agentConfig.onComplete(entry.result);
-            }
-            catch (err) {
-                console.error(`[subagent ${id}] onComplete callback threw:`, err);
-            }
-        }
-        // I3: fire delivery router (non-blocking, errors logged). Dynamic
-        // import keeps the module graph free of circular edges. Guarded by
-        // the `delivered` flag so cancelAllSubAgents (shutdown path) and
-        // this finally() can't both post the result.
-        if (entry?.result && !entry.delivered) {
-            entry.delivered = true;
-            const resultSnapshot = entry.result;
-            const infoSnapshot = entry.info;
-            import("./subagent-delivery.js")
-                .then(({ deliverSubAgentResult }) => deliverSubAgentResult(infoSnapshot, resultSnapshot, {
-                visibility: agentConfig.visibility,
-            }))
-                .catch((err) => console.error(`[subagent ${id}] delivery failed:`, err));
-        }
-        // Auto-cleanup: remove completed agents after 30 minutes
-        setTimeout(() => {
-            const e = activeAgents.get(id);
-            if (e && e.info.status !== "running") {
-                activeAgents.delete(id);
-            }
-        }, 30 * 60 * 1000);
-    });
+    const queuedSpawn = { id, resolvedName, agentConfig, depth, timeoutId };
+    if (willRunImmediately) {
+        startRun(queuedSpawn);
+    }
+    else {
+        pendingQueue.push(queuedSpawn);
+        reindexQueue();
+    }
     return Promise.resolve(id);
 }
 /**
@@ -365,7 +494,21 @@ export function listSubAgents() {
  */
 export function cancelSubAgent(id) {
     const entry = activeAgents.get(id);
-    if (!entry || entry.info.status !== "running")
+    if (!entry)
+        return false;
+    if (entry.info.status === "queued") {
+        // D3: remove from the pending queue, reindex, mark cancelled.
+        const idx = pendingQueue.findIndex((q) => q.id === id);
+        if (idx >= 0) {
+            const [removed] = pendingQueue.splice(idx, 1);
+            if (removed.timeoutId)
+                clearTimeout(removed.timeoutId);
+            reindexQueue();
+        }
+        entry.info.status = "cancelled";
+        return true;
+    }
+    if (entry.info.status !== "running")
         return false;
     entry.abort.abort();
     entry.info.status = "cancelled";
@@ -418,6 +561,16 @@ export async function cancelAllSubAgents(notify = true) {
     // delivered=true so runSubAgent.finally() can't fire a second
     // delivery on the next microtask, (4) queue the I3 delivery.
     const runningEntries = [];
+    // D3: clear the pending queue first so no entry starts during shutdown.
+    for (const q of pendingQueue.splice(0)) {
+        if (q.timeoutId)
+            clearTimeout(q.timeoutId);
+        const entry = activeAgents.get(q.id);
+        if (entry) {
+            entry.info.status = "cancelled";
+            entry.delivered = true; // no delivery for queued-never-ran agents
+        }
+    }
     for (const [id, entry] of activeAgents) {
         if (entry.info.status !== "running")
             continue;

package/dist/tui/index.js

@@ -20,6 +20,7 @@ import { createInterface, cursorTo, clearLine as rlClearLine } from "readline";
 import WebSocket from "ws";
 import http from "http";
 import { initI18n, t } from "../i18n.js";
+import { BOT_VERSION } from "../version.js";
 // Init i18n before anything else
 initI18n();
 // ── ANSI Colors & Styles ────────────────────────────────
@@ -410,11 +411,17 @@ async function handleCommand(cmd) {
             }
             break;
         }
+        case "version":
+        case "v": {
+            console.log(`\n${C.bold}${C.brightCyan}🤖 Alvin Bot${C.reset} ${C.dim}v${BOT_VERSION}${C.reset}`);
+            console.log(`${C.dim}Node ${process.version} · ${process.platform}/${process.arch}${C.reset}\n`);
+            break;
+        }
         case "status":
         case "s": {
             try {
                 const data = await apiGet("/api/status");
-                console.log(`\n${C.bold}${C.brightCyan}${t("status.title")}${C.reset}`);
+                console.log(`\n${C.bold}${C.brightCyan}🤖 Alvin Bot${C.reset} ${C.dim}v${BOT_VERSION}${C.reset}`);
                 console.log(`${C.gray}${"─".repeat(40)}${C.reset}`);
                 if (data.model) {
                     console.log(`  ${C.cyan}${t("status.model")}${C.reset}    ${data.model.model || data.model.name || "?"}`);

package/dist/version.js

@@ -0,0 +1,24 @@
+/**
+ * Central source of truth for the running Alvin Bot version.
+ * Read from package.json once at module load — subsequent imports
+ * return the cached string without touching disk.
+ */
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+function readVersion() {
+    try {
+        // dist/version.js is two levels deep; package.json sits at the root
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(here, "..", "package.json");
+        const raw = readFileSync(pkgPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string")
+            return parsed.version;
+    }
+    catch {
+        /* fall through to unknown */
+    }
+    return "unknown";
+}
+export const BOT_VERSION = readVersion();

package/dist/web/server.js

@@ -29,6 +29,7 @@ import { handleOpenAICompat } from "./openai-compat.js";
 import { addCanvasClient } from "./canvas.js";
 import { BOT_ROOT, ENV_FILE, PUBLIC_DIR, MEMORY_DIR, MEMORY_FILE, SOUL_FILE, DATA_DIR, MCP_CONFIG, SKILLS_DIR } from "../paths.js";
 import { broadcast } from "../services/broadcast.js";
+import { BOT_VERSION } from "../version.js";
 const WEB_PORT = parseInt(process.env.WEB_PORT || "3100");
 const WEB_PASSWORD = process.env.WEB_PASSWORD || "";
 /** The actual port the Web UI is running on (may differ from WEB_PORT if busy). */
@@ -259,7 +260,7 @@ async function handleAPI(req, res, urlPath, body) {
         }
         const { config: appConfig } = await import("../config.js");
         res.end(JSON.stringify({
-            bot: { version: "3.0.0", uptime: process.uptime() },
+            bot: { version: BOT_VERSION, uptime: process.uptime() },
             model: modelInfo,
             memory: { ...memory, vectors: index.entries, indexSize: index.sizeBytes },
             plugins: plugins.length,

package/docs/HANDBOOK.md

@@ -310,6 +310,7 @@ This allows the "scatter-gather" pattern (main → orchestrator → 10 workers)
 - `auto` (default) — source-based routing: implicit stays in the parent stream, user and cron get a banner+final delivery.
 - `banner` — always send a banner+final, even for implicit spawns.
 - `silent` — never send. The result is still stored in the activeAgents map for 30 minutes and pullable via `/subagents result <name>`.
+- **`live`** — stream incremental updates into a single Telegram message as the agent thinks. Only applies to `source: "user"` spawns with a `parentChatId`. The live message is plain text (so half-formed markdown during streaming can't break the edit), updates are throttled to 800 ms between edits, and a separate banner message is posted at the end so you get a completion notification. If the bot API doesn't support `editMessageText` or the live setup fails, we fall through to `banner` mode automatically.
 
 ### 7.6 Inheritance
 
@@ -320,7 +321,29 @@ Sub-agents inherit from the spawning context:
 - **Model and tools** — inherited via the provider registry.
 - **Conversation history** — **not inherited.** Sub-agents receive only their own prompt. This forces clean, self-describing spawn requests.
 
-### 7.7 Shutdown notifications
+### 7.7 Bounded priority queue
+
+When the running pool hits `maxParallel`, new spawn requests land in a bounded queue instead of being rejected immediately.
+
+- **Default cap:** 20 slots. Configure via `/subagents queue <n>` (clamped to 0–200).
+- **Disable:** `/subagents queue 0` — restores the old reject-on-full behavior.
+- **Priority order on drain:** `user > cron > implicit`. Within each priority class, FIFO.
+- **`/subagents list`** shows queued entries with a `#N` suffix indicating their position.
+- **Cancel a queued entry** with `/subagents cancel <name>` — it's removed from the queue without ever starting.
+
+Reject is only triggered when the pool **and** the queue are both full. The reject message is priority-aware and names who's holding the slots.
+
+### 7.8 Stats
+
+`/subagents stats` shows a summary of the last 24 hours of sub-agent runs:
+
+- Total runs + total tokens + total wall time
+- Runs per source (user / cron / implicit)
+- Runs per status (completed / cancelled / timeout / error)
+
+The backing data is an append-only JSON ring buffer at `~/.alvin-bot/subagent-stats.json`. Entries older than 24 hours are pruned automatically. A hard cap of 5000 entries protects against runaway growth on very busy bots.
+
+### 7.9 Shutdown notifications
 
 When you restart the bot (SIGTERM), any still-running sub-agents get a cancellation delivery before the process exits:
 
@@ -433,7 +456,14 @@ All commands are triggered from any platform that supports commands (Telegram, D
 | Command | Purpose |
 |---|---|
 | `/cron` | Manage scheduled jobs |
-| `/subagents` | Manage sub-agents |
+| `/subagents` | Show sub-agent status |
+| `/subagents max <n>` | Set max parallel (0 = auto) |
+| `/subagents queue <n>` | Set bounded-queue cap (0 = disabled) |
+| `/subagents visibility <auto\|banner\|silent\|live>` | Delivery mode |
+| `/subagents list` | List all (queued + running + recent) |
+| `/subagents cancel <name\|id>` | Cancel one |
+| `/subagents result <name\|id>` | Show a completed result |
+| `/subagents stats` | Last 24h run stats (by source + status) |
 | `/webui` | Open web UI URL |
 | `/setup` | Re-run the setup wizard flow from chat |
 | `/restart` | Restart the bot process |
@@ -776,6 +806,13 @@ Alvin Bot follows semver for the **data directory format**. Minor version bumps
 - Memory: no schema change.
 - `.env`: no new required variables. `MAX_SUBAGENTS` and `SUBAGENT_TIMEOUT` are optional.
 
+### 16.3 From 4.6.x to 4.7.0
+
+- Sub-agents: new fields in `sub-agents.json` (`queueCap`, defaults to 20). Old files auto-upgrade.
+- New file `~/.alvin-bot/subagent-stats.json` — auto-created when the first sub-agent finishes.
+- `start`/`stop` now auto-detect the LaunchAgent on macOS. No migration needed; if you previously installed the LaunchAgent in 4.6.0, `alvin-bot start` now correctly reloads it instead of spawning a parallel pm2 process.
+- No new required `.env` variables.
+
 ### 16.3 From git
 
 ```bash

package/package.json

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

package/test/subagent-delivery.test.ts

@@ -167,3 +167,107 @@ describe("subagent-delivery (I3)", () => {
     expect(sentMessages).toHaveLength(0);
   });
 });
+
+describe("subagent-delivery LiveStream (A4)", () => {
+  const edits: Array<{ chatId: number; messageId: number; text: string }> = [];
+  let messageCounter = 100;
+
+  beforeEach(() => {
+    edits.length = 0;
+    messageCounter = 100;
+  });
+
+  async function wireLiveApi() {
+    const mod = await import("../src/services/subagent-delivery.js");
+    mod.__setBotApiForTest({
+      sendMessage: async (chatId: number, text: string) => {
+        sentMessages.push({ chatId, text });
+        return { message_id: messageCounter++ };
+      },
+      sendDocument: async (chatId: number) => {
+        sentDocuments.push({ chatId });
+        return {};
+      },
+      editMessageText: async (chatId: number, messageId: number, text: string) => {
+        edits.push({ chatId, messageId, text });
+        return {};
+      },
+    });
+    return mod;
+  }
+
+  it("start posts an initial 'thinking…' message and records messageId", async () => {
+    const mod = await wireLiveApi();
+    const stream = mod.createLiveStream(555, "code-review");
+    expect(stream).not.toBeNull();
+    await stream!.start();
+
+    expect(sentMessages).toHaveLength(1);
+    expect(sentMessages[0].chatId).toBe(555);
+    expect(sentMessages[0].text).toContain("thinking");
+    expect(stream!.failed).toBe(false);
+  });
+
+  it("update coalesces multiple rapid calls into a single throttled edit", async () => {
+    const mod = await wireLiveApi();
+    const stream = mod.createLiveStream(1, "fast");
+    await stream!.start();
+
+    stream!.update("hello");
+    stream!.update("hello world");
+    stream!.update("hello world and more");
+
+    // Wait for the throttle window to elapse
+    await new Promise((r) => setTimeout(r, 900));
+
+    // Should have produced exactly one edit with the LAST text
+    expect(edits.length).toBe(1);
+    expect(edits[0].text).toContain("hello world and more");
+  });
+
+  it("finalize posts a banner as a new message", async () => {
+    const mod = await wireLiveApi();
+    const stream = mod.createLiveStream(42, "done-agent");
+    await stream!.start();
+    stream!.update("final text");
+    await new Promise((r) => setTimeout(r, 900)); // let flush run
+
+    await stream!.finalize(
+      {
+        id: "x",
+        name: "done-agent",
+        status: "completed",
+        startedAt: Date.now() - 5000,
+        source: "user",
+        depth: 0,
+        parentChatId: 42,
+      },
+      {
+        id: "x",
+        name: "done-agent",
+        status: "completed",
+        output: "final text",
+        tokensUsed: { input: 100, output: 50 },
+        duration: 5000,
+      },
+    );
+
+    // Two sends total: initial "thinking…" + final banner
+    expect(sentMessages.length).toBe(2);
+    const banner = sentMessages[sentMessages.length - 1].text;
+    expect(banner).toContain("done-agent");
+    expect(banner).toContain("completed");
+  });
+
+  it("createLiveStream returns null when bot api lacks editMessageText", async () => {
+    const mod = await import("../src/services/subagent-delivery.js");
+    // Set an api that intentionally has no editMessageText
+    mod.__setBotApiForTest({
+      sendMessage: async () => ({ message_id: 1 }),
+      sendDocument: async () => ({}),
+      // no editMessageText
+    });
+    const stream = mod.createLiveStream(1, "no-edit");
+    expect(stream).toBeNull();
+  });
+});