alvin-bot 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.7.0] — 2026-04-11
+
+### ✨ Sub-Agents Stufe 2 — live-stream, bounded queue, 24h stats
+
+Stufe 2 of the sub-agents refinement spec lands alongside the same-day 4.6.0 release. Everything here builds on the Stufe 1 foundation and is fully unit-tested (85 passing tests).
+
+#### A4 Live-Stream for user-spawns
+
+`/subagents visibility live` enables a new delivery mode where user-spawned sub-agents stream their text incrementally into a single Telegram message, then post a completion banner as a separate message.
+
+Implementation in `src/services/subagent-delivery.ts`:
+
+- `LiveStream` class with `start()` / `update()` / `finalize()`
+- `start()` posts an initial `⏳ <name> thinking…` placeholder and records its `message_id`
+- `update()` is called on every text chunk from the agent's generator; it coalesces rapid updates via a throttle window of **800 ms** so we never exceed Telegram's edit rate limit. Multiple `update()` calls within the window collapse into a single edit with the latest accumulated text.
+- `finalize()` flushes any pending text, replaces the `thinking…` header with the final body, then sends a new banner message so the user gets a completion notification (edits don't trigger push notifications).
+- The live-stream message uses **plain text** (no `parse_mode`) so half-formed markdown during streaming can never cause an edit to be rejected. The final banner does use markdown.
+
+Wiring in `runSubAgent`:
+
+- Detects `effectiveVisibility === "live"` AND `source === "user"` AND `parentChatId`. Cron and implicit spawns are never live-streamed — cron because there's no interactive watcher, implicit because the parent Claude stream already shows everything inline.
+- Creates the `LiveStream` via `createLiveStream()` before the for-await loop.
+- Calls `liveStream.update(chunk.text)` on every text chunk.
+- Calls `liveStream.finalize(info, result)` after the loop and marks `entry.delivered = true` so `spawnSubAgent.finally()` skips the regular `deliverSubAgentResult` path. If finalize fails, the `delivered` flag stays false and the normal banner delivery fires as a fallback.
+- Falls back to `"banner"` mode transparently if the bot API doesn't support `editMessageText` (e.g. during tests or if `attachBotApi` was never called).
+
+Tests added in `test/subagent-delivery.test.ts`:
+
+- `start` posts an initial placeholder and stores the message_id
+- `update` coalesces rapid calls into a single throttled edit within the 800 ms window
+- `finalize` posts a banner as a new message
+- `createLiveStream` returns `null` when `editMessageText` is missing
+
+#### D3 Bounded priority queue
+
+Previously, hitting `maxParallel` returned a hard reject. Now spawn requests that don't fit run into a **bounded priority queue**:
+
+- Default cap: **20** slots (configurable via `/subagents queue <n>`, clamped to 0–200)
+- Setting cap to 0 disables the queue entirely and restores the old reject-on-full behavior
+- Priority order on drain: **user > cron > implicit**
+- FIFO within each priority class
+- Drains automatically when a running agent finishes — the `runSubAgent.finally()` now calls `drainQueue()` after cleanup
+
+New fields:
+
+- `SubAgentsConfig.queueCap: number` — persisted in `~/.alvin-bot/sub-agents.json`
+- `SubAgentInfo.status: "queued"` — new valid state
+- `SubAgentInfo.queuePosition?: number` — 1-based position in the queue, shown in `/subagents list` as `#N`
+
+Functions in `subagents.ts`:
+
+- `getQueueCap()` / `setQueueCap(n)` — public config accessors
+- `drainQueue()` — called from `runSubAgent.finally()`, pops in priority order and transitions entries from `queued` to `running`
+- `popHighestPriorityQueued()` — internal FIFO-per-priority scan
+- `reindexQueue()` — keeps `SubAgentInfo.queuePosition` in sync after pop/cancel
+- `cancelSubAgent()` now handles queued entries by removing them from the queue without starting `runSubAgent` at all
+- `cancelAllSubAgents()` clears the pending queue before cancelling running agents, so shutdown doesn't spawn anything new
+- `spawnSubAgent()` is split: queue decision first (run immediately vs queue vs reject), then `startRun()` helper starts the background loop
+
+Reject messages stay priority-aware (D4) but now mention queue saturation:
+
+- `user` spawn + pool full + cron/implicit in pool + queue full → *"Alle Slots belegt (N/M), davon X cron/implicit im Hintergrund. Queue voll (Q/C). /subagents list für Details …"*
+- `user` spawn + pool full + user in pool + queue full → *"Alle Slots belegt (N/M) mit eigenen user-Spawns. Queue voll (Q/C). /subagents cancel <name> oder warten."*
+- Non-user spawns + pool + queue full → *"Sub-agent limit reached (N running, Q/C queued). Wait for a running agent to finish or cancel one."*
+
+Tests added in `test/subagents-queue.test.ts`:
+
+- Default cap is 20
+- Clamping (negative → 0, above 200 → 200, fractional floors)
+- Round-trip through disk
+- Third spawn at full pool lands as `status: "queued"` with `queuePosition: 1`
+- Queue drains automatically when a running agent finishes
+- Priority order: user spawns drain before cron at the same moment
+- `cancelSubAgent` removes a queued entry
+
+The existing priority-reject tests now explicitly set `queueCap = 0` to test the old reject path, and a new "queue enabled" test fills both pool and queue before asserting the reject message.
+
+#### H3 24-hour run stats
+
+New module `src/services/subagent-stats.ts` — a simple append-only JSON ring buffer persisted to `~/.alvin-bot/subagent-stats.json`. Each completed sub-agent run appends one entry:
+
+```ts
+{
+  completedAt: number;
+  name: string;
+  source: "user" | "cron" | "implicit";
+  status: "completed" | "timeout" | "error" | "cancelled";
+  durationMs: number;
+  inputTokens: number;
+  outputTokens: number;
+}
+```
+
+On every load or append, entries older than 24 hours are pruned. A hard cap of 5000 entries protects against unbounded growth on high-frequency bots.
+
+Accessors:
+
+- `recordSubAgentRun(info, result)` — called from `runSubAgent.finally()` as a non-blocking side effect. Errors are logged but don't affect delivery.
+- `getSubAgentStats()` — returns a `StatsSummary` with totals, per-source breakdown, and per-status counts.
+
+New Telegram command **`/subagents stats`** renders the summary:
+
+```
+📊 Sub-Agent Stats — last 24h
+
+Total: 44 runs · 165k in / 89k out · 12m
+
+By source:
+  👤 user:     12 runs · 45k in / 22k out
+  ⏰ cron:      8 runs · 31k in / 15k out
+  🔗 implicit: 24 runs · 89k in / 52k out
+
+By status:
+  ✅ completed: 42
+  ⚠️ cancelled: 1
+  ⏱️ timeout:   0
+  ❌ error:     1
+```
+
+The JSON backing file is a deliberate short-term choice. When the SQLite migration lands (already scoped in a separate memory entry as `project_alvinbot_sqlite_migration.md`), we swap the backend without touching `getSubAgentStats()` or `recordSubAgentRun()` — both are designed as a narrow interface.
+
+Tests added in `test/subagent-stats.test.ts`:
+
+- Fresh install returns zeros
+- Recording 3 runs updates totals + per-source breakdown
+- Persistence + reload round-trip
+- Entries older than 24h are pruned on load
+- `byStatus` tracks cancelled/error/timeout separately
+
+### 🖥 CLI: `alvin-bot start` / `stop` now auto-detect LaunchAgent
+
+The `start` and `stop` commands previously always went through pm2. That created a conflict after `alvin-bot launchd install`: the LaunchAgent ran the bot, but `alvin-bot start` would happily spawn a second instance via pm2, and `alvin-bot stop` would try to stop a pm2 process that didn't exist.
+
+Now both commands check for `~/Library/LaunchAgents/com.alvinbot.app.plist` on macOS and switch transparently:
+
+- **`alvin-bot start`** with a LaunchAgent present → `launchctl kickstart -k gui/$UID/com.alvinbot.app` (or `launchctl load -w` if not loaded yet). No pm2 involvement.
+- **`alvin-bot stop`** with a LaunchAgent present → `launchctl unload -w` (doesn't remove the plist, just stops the daemon).
+- **`alvin-bot start`** on macOS without a LaunchAgent → pm2 path + a helpful tip: *"💡 Tip: on macOS with Claude Code, switch to launchd for automatic Keychain access: alvin-bot launchd install"*.
+
+Linux and Windows users are unaffected — they always get the pm2 path.
+
+### 🐛 Other
+
+- `/subagents queue` is registered in the usage string for en/de/es/fr.
+- `/subagents stats` is registered in the usage string for en/de/es/fr.
+- `/subagents visibility` usage now lists `live` as a valid mode.
+- Removed the leftover `alvin-bot-4.5.1.tgz` from the repo root.
+
 ## [4.6.0] — 2026-04-11
 
 ### ✨ Sub-Agents Stufe 1 — context-aware delivery, name-first addressing, shutdown notifications

package/bin/cli.js

@@ -1396,40 +1396,93 @@ switch (cmd) {
     const fg = process.argv.includes("--foreground") || process.argv.includes("-f");
     if (fg) {
       import("../dist/index.js");
-    } else {
-      // Start via PM2 (background, survives terminal close, auto-restart on crash)
-      try {
-        execSync("pm2 --version", { stdio: "pipe" });
-      } catch {
-        // PM2 not installed — install it
-        console.log("Installing PM2 for background operation...");
+      break;
+    }
+
+    // On macOS, if a LaunchAgent plist already exists, we're in "launchd
+    // mode" — don't start pm2 in parallel. Reload the LaunchAgent instead
+    // so a plain `alvin-bot start` still works as "bring the bot up".
+    if (process.platform === "darwin") {
+      const { plistPath, label } = launchdPaths();
+      if (existsSync(plistPath)) {
+        console.log(`🚀 Detected existing LaunchAgent (${label})`);
+        console.log(`   Reloading via 'launchctl kickstart -k'...`);
         try {
-          execSync("npm install -g pm2", { stdio: "inherit", timeout: 60000 });
+          execSync(`launchctl kickstart -k gui/$(id -u)/${label}`, {
+            stdio: "inherit",
+            shell: "/bin/zsh",
+          });
         } catch {
-          console.log("Could not install PM2. Starting in foreground instead.");
-          console.log("Tip: Install PM2 manually (npm install -g pm2) to run in background.\n");
-          await import("../dist/index.js");
-          break;
+          // Maybe unloaded — load it fresh
+          try {
+            execSync(`launchctl load -w "${plistPath}"`, { stdio: "inherit" });
+          } catch (err) {
+            console.log(`❌ launchctl load failed: ${err.message}`);
+            process.exit(1);
+          }
         }
+        console.log("\n✅ Bot is running via launchd.");
+        console.log("   Status: alvin-bot launchd status");
+        console.log("   Stop:   alvin-bot stop");
+        console.log("   Logs:   ~/.alvin-bot/logs/alvin-bot.out.log");
+        process.exit(0);
       }
-      const cliPath = resolve(join(import.meta.dirname, "cli.js"));
+    }
+
+    // Fall-through: pm2 path (Linux, Windows, or macOS without LaunchAgent)
+    try {
+      execSync("pm2 --version", { stdio: "pipe" });
+    } catch {
+      console.log("Installing PM2 for background operation...");
       try {
-        // Stop existing instance if running
-        execSync("pm2 delete alvin-bot", { stdio: "pipe" });
-      } catch { /* not running — fine */ }
-      execSync(`pm2 start "${cliPath}" --name alvin-bot -- start --foreground`, {
-        stdio: "inherit",
-        timeout: 15000,
-      });
-      console.log("\n✅ Bot is running in the background.");
-      console.log("   Logs:    pm2 logs alvin-bot");
-      console.log("   Stop:    alvin-bot stop");
-      console.log("   Restart: alvin-bot start\n");
-      process.exit(0);
+        execSync("npm install -g pm2", { stdio: "inherit", timeout: 60000 });
+      } catch {
+        console.log("Could not install PM2. Starting in foreground instead.");
+        console.log("Tip: Install PM2 manually (npm install -g pm2) to run in background.\n");
+        await import("../dist/index.js");
+        break;
+      }
     }
-    break;
+    const cliPath = resolve(join(import.meta.dirname, "cli.js"));
+    try {
+      execSync("pm2 delete alvin-bot", { stdio: "pipe" });
+    } catch { /* not running — fine */ }
+    execSync(`pm2 start "${cliPath}" --name alvin-bot -- start --foreground`, {
+      stdio: "inherit",
+      timeout: 15000,
+    });
+    console.log("\n✅ Bot is running in the background via PM2.");
+    console.log("   Logs:    pm2 logs alvin-bot");
+    console.log("   Stop:    alvin-bot stop");
+    console.log("   Restart: alvin-bot start");
+    if (process.platform === "darwin") {
+      console.log("");
+      console.log("   💡 Tip: on macOS with Claude Code, switch to launchd for");
+      console.log("      automatic Keychain access:  alvin-bot launchd install");
+    }
+    console.log("");
+    process.exit(0);
   }
   case "stop": {
+    // On macOS with a LaunchAgent, stopping means unloading the LaunchAgent,
+    // not asking pm2 to stop a process it never managed.
+    if (process.platform === "darwin") {
+      const { plistPath, label } = launchdPaths();
+      if (existsSync(plistPath)) {
+        console.log(`⏹  Stopping LaunchAgent (${label})...`);
+        try {
+          execSync(`launchctl unload -w "${plistPath}"`, { stdio: "inherit" });
+          console.log("✅ LaunchAgent stopped.");
+          console.log("   (The plist is still installed. To remove it: alvin-bot launchd uninstall)");
+        } catch (err) {
+          console.log(`❌ launchctl unload failed: ${err.message}`);
+          process.exit(1);
+        }
+        process.exit(0);
+      }
+    }
+
+    // Fall-through: pm2 path
     try {
       execSync("pm2 stop alvin-bot", { stdio: "inherit", timeout: 10000 });
     } catch {

package/dist/handlers/commands.js

@@ -1728,7 +1728,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, } = await import("../services/subagents.js");
+        const { listSubAgents, cancelSubAgent, getSubAgentResult, getMaxParallelAgents, getConfiguredMaxParallel, setMaxParallelAgents, findSubAgentByName, getVisibility, setVisibility, getQueueCap, setQueueCap, } = await import("../services/subagents.js");
         const arg = (ctx.match || "").trim();
         const tokens = arg.split(/\s+/).filter(Boolean);
         const sub = tokens[0]?.toLowerCase() || "";
@@ -1741,7 +1741,8 @@ export function registerCommands(bot) {
             const ageLabel = ageSec < 60 ? `${ageSec}s` : ageSec < 3600 ? `${Math.floor(ageSec / 60)}m` : `${Math.floor(ageSec / 3600)}h`;
             const sourceBadge = a.source === "cron" ? "⏰" : a.source === "implicit" ? "🔗" : "👤";
             const depthTag = a.depth > 0 ? ` d${a.depth}` : "";
-            return `${indent}${sourceBadge} \`${shortId(a.id)}\` ${a.name} (${a.status}, ${ageLabel}${depthTag})`;
+            const queueTag = a.status === "queued" && a.queuePosition ? ` #${a.queuePosition}` : "";
+            return `${indent}${sourceBadge} \`${shortId(a.id)}\` ${a.name} (${a.status}${queueTag}, ${ageLabel}${depthTag})`;
         };
         // /sub-agents max <n>
         if (sub === "max") {
@@ -1754,7 +1755,50 @@ export function registerCommands(bot) {
             await ctx.reply(t("bot.subagents.maxSet", lang, { n, eff: effective }), { parse_mode: "Markdown" });
             return;
         }
-        // /sub-agents visibility <auto|banner|silent>
+        // /subagents stats — show rolling 24h run stats (H3)
+        if (sub === "stats") {
+            const { getSubAgentStats } = await import("../services/subagent-stats.js");
+            const s = getSubAgentStats();
+            const formatTok = (n) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(1)}k`);
+            const formatDur = (ms) => {
+                const sec = Math.floor(ms / 1000);
+                if (sec < 60)
+                    return `${sec}s`;
+                const m = Math.floor(sec / 60);
+                return `${m}m`;
+            };
+            const lines = [
+                `📊 *Sub-Agent Stats* — last ${s.windowHours}h`,
+                ``,
+                `*Total:* ${s.total.runs} runs · ${formatTok(s.total.inputTokens)} in / ${formatTok(s.total.outputTokens)} out · ${formatDur(s.total.totalDurationMs)}`,
+                ``,
+                `*By source:*`,
+                `  👤 user:     ${s.bySource.user.runs} runs · ${formatTok(s.bySource.user.inputTokens)} in / ${formatTok(s.bySource.user.outputTokens)} out`,
+                `  ⏰ cron:     ${s.bySource.cron.runs} runs · ${formatTok(s.bySource.cron.inputTokens)} in / ${formatTok(s.bySource.cron.outputTokens)} out`,
+                `  🔗 implicit: ${s.bySource.implicit.runs} runs · ${formatTok(s.bySource.implicit.inputTokens)} in / ${formatTok(s.bySource.implicit.outputTokens)} out`,
+                ``,
+                `*By status:*`,
+                `  ✅ completed: ${s.byStatus.completed}`,
+                `  ⚠️ cancelled: ${s.byStatus.cancelled}`,
+                `  ⏱️ timeout:   ${s.byStatus.timeout}`,
+                `  ❌ error:     ${s.byStatus.error}`,
+            ];
+            await ctx.reply(lines.join("\n"), { parse_mode: "Markdown" });
+            return;
+        }
+        // /subagents queue <n> — set bounded-queue cap (0 disables queue)
+        if (sub === "queue") {
+            const n = parseInt(tokens[1] || "", 10);
+            if (isNaN(n)) {
+                const current = getQueueCap();
+                await ctx.reply(`Queue cap: *${current}* (${current === 0 ? "disabled" : "bounded"})\nUsage: \`/subagents queue <n>\` (0 disables the queue, max 200)`, { parse_mode: "Markdown" });
+                return;
+            }
+            const effective = setQueueCap(n);
+            await ctx.reply(`✅ Queue cap set to *${effective}* ${effective === 0 ? "(queue disabled — full pool rejects immediately)" : ""}`, { parse_mode: "Markdown" });
+            return;
+        }
+        // /sub-agents visibility <auto|banner|silent|live>
         if (sub === "visibility") {
             const mode = tokens[1];
             if (!mode) {

package/dist/i18n.js

@@ -519,10 +519,10 @@ const strings = {
         fr: "Durée : {sec}s · Tokens : {in}/{out}",
     },
     "bot.subagents.usage": {
-        en: "Commands:\n/subagents — show status\n/subagents max <n> — set parallel limit (0=auto)\n/subagents visibility <auto|banner|silent> — delivery mode\n/subagents list — list all\n/subagents cancel <name|id> — cancel one\n/subagents result <name|id> — show result",
-        de: "Befehle:\n/subagents — Status anzeigen\n/subagents max <n> — Parallel-Limit setzen (0=auto)\n/subagents visibility <auto|banner|silent> — Delivery-Modus\n/subagents list — alle anzeigen\n/subagents cancel <name|id> — abbrechen\n/subagents result <name|id> — Ergebnis anzeigen",
-        es: "Comandos:\n/subagents — ver estado\n/subagents max <n> — establecer límite (0=auto)\n/subagents visibility <auto|banner|silent> — modo de entrega\n/subagents list — listar todos\n/subagents cancel <nombre|id> — cancelar uno\n/subagents result <nombre|id> — ver resultado",
-        fr: "Commandes :\n/subagents — état\n/subagents max <n> — limite parallèle (0=auto)\n/subagents visibility <auto|banner|silent> — mode de livraison\n/subagents list — lister tous\n/subagents cancel <nom|id> — annuler un\n/subagents result <nom|id> — voir résultat",
+        en: "Commands:\n/subagents — show status\n/subagents max <n> — set parallel limit (0=auto)\n/subagents visibility <auto|banner|silent|live> — delivery mode\n/subagents queue <n> — bounded-queue cap (0 = disabled)\n/subagents stats — last 24h run stats\n/subagents list — list all\n/subagents cancel <name|id> — cancel one\n/subagents result <name|id> — show result",
+        de: "Befehle:\n/subagents — Status anzeigen\n/subagents max <n> — Parallel-Limit setzen (0=auto)\n/subagents visibility <auto|banner|silent|live> — Delivery-Modus\n/subagents list — alle anzeigen\n/subagents cancel <name|id> — abbrechen\n/subagents result <name|id> — Ergebnis anzeigen",
+        es: "Comandos:\n/subagents — ver estado\n/subagents max <n> — establecer límite (0=auto)\n/subagents visibility <auto|banner|silent|live> — modo de entrega\n/subagents list — listar todos\n/subagents cancel <nombre|id> — cancelar uno\n/subagents result <nombre|id> — ver resultado",
+        fr: "Commandes :\n/subagents — état\n/subagents max <n> — limite parallèle (0=auto)\n/subagents visibility <auto|banner|silent|live> — mode de livraison\n/subagents list — lister tous\n/subagents cancel <nom|id> — annuler un\n/subagents result <nom|id> — voir résultat",
     },
     "bot.subagents.visibilityLabel": {
         en: "Visibility:",
@@ -537,10 +537,10 @@ const strings = {
         fr: "✅ Visibilité réglée sur *{mode}*",
     },
     "bot.subagents.visibilityInvalid": {
-        en: "❌ Invalid mode _{mode}_. Use: auto | banner | silent",
-        de: "❌ Ungültiger Modus _{mode}_. Nutze: auto | banner | silent",
-        es: "❌ Modo inválido _{mode}_. Usa: auto | banner | silent",
-        fr: "❌ Mode invalide _{mode}_. Utilise : auto | banner | silent",
+        en: "❌ Invalid mode _{mode}_. Use: auto | banner | silent | live",
+        de: "❌ Ungültiger Modus _{mode}_. Nutze: auto | banner | silent | live",
+        es: "❌ Modo inválido _{mode}_. Usa: auto | banner | silent | live",
+        fr: "❌ Mode invalide _{mode}_. Utilise : auto | banner | silent | live",
     },
     // Relative time formatting (formatRelativeTime helper)
     "bot.time.justNow": {

package/dist/index.js

@@ -134,6 +134,7 @@ if (hasTelegram) {
     attachBotApi({
         sendMessage: (chatId, text, opts) => botRef.api.sendMessage(chatId, text, opts),
         sendDocument: (chatId, doc, opts) => botRef.api.sendDocument(chatId, doc, opts),
+        editMessageText: (chatId, messageId, text, opts) => botRef.api.editMessageText(chatId, messageId, text, opts),
     });
     // Auth middleware — alle Messages durchlaufen das
     bot.use(authMiddleware);

package/dist/services/subagent-delivery.js

@@ -53,6 +53,157 @@ function buildBanner(info, result) {
     const to = formatTokens(result.tokensUsed.output);
     return `${icon} *${info.name}* ${result.status} · ${dur} · ${ti} in / ${to} out`;
 }
+// ── A4 Live-Stream ──────────────────────────────────────────
+/**
+ * Per-spawn live-stream state. Edits a single Telegram message as the
+ * sub-agent produces text, throttled to ~800ms between edits. Posts a
+ * separate banner message at finalize so the user gets a completion
+ * notification (edits don't trigger Telegram notifications).
+ *
+ * The live message uses plain text (no parse_mode) so half-formed
+ * markdown during streaming can never crash the edit. The final banner
+ * does use markdown.
+ */
+const LIVE_EDIT_THROTTLE_MS = 800;
+const LIVE_INITIAL_TEXT = (name) => `⏳ ${name} thinking…`;
+export class LiveStream {
+    api;
+    chatId;
+    agentName;
+    messageId = null;
+    lastEditAt = 0;
+    pendingText = null;
+    pendingTimer = null;
+    started = false;
+    failed = false;
+    constructor(api, chatId, agentName) {
+        this.api = api;
+        this.chatId = chatId;
+        this.agentName = agentName;
+    }
+    /** Post the initial placeholder message. Called before the first chunk. */
+    async start() {
+        if (!this.api.editMessageText) {
+            this.failed = true;
+            console.warn(`[subagent-live] bot api has no editMessageText — falling back`);
+            return;
+        }
+        try {
+            const initial = LIVE_INITIAL_TEXT(this.agentName);
+            const msg = await this.api.sendMessage(this.chatId, initial);
+            const msgId = msg.message_id;
+            if (typeof msgId === "number") {
+                this.messageId = msgId;
+                this.lastEditAt = Date.now();
+                this.started = true;
+            }
+            else {
+                console.warn(`[subagent-live] sendMessage returned no message_id`);
+                this.failed = true;
+            }
+        }
+        catch (err) {
+            console.error(`[subagent-live] start failed:`, err);
+            this.failed = true;
+        }
+    }
+    /**
+     * Record a new accumulated text state. Will schedule a throttled edit
+     * ~800ms after the previous edit. Later updates that arrive before
+     * the throttled flush coalesce — only the latest text is used.
+     */
+    update(text) {
+        if (!this.started || this.failed || this.messageId === null)
+            return;
+        this.pendingText = text;
+        if (this.pendingTimer)
+            return;
+        const elapsed = Date.now() - this.lastEditAt;
+        const delay = Math.max(0, LIVE_EDIT_THROTTLE_MS - elapsed);
+        this.pendingTimer = setTimeout(() => {
+            this.flush().catch((err) => {
+                console.warn(`[subagent-live] scheduled flush failed:`, err);
+            });
+        }, delay);
+    }
+    async flush() {
+        this.pendingTimer = null;
+        if (!this.pendingText || this.messageId === null || this.failed)
+            return;
+        if (!this.api.editMessageText) {
+            this.failed = true;
+            return;
+        }
+        // Cap edit length — Telegram rejects >4096 chars
+        const body = this.pendingText.slice(0, MAX_TG_CHUNK);
+        const display = `⏳ ${this.agentName}\n\n${body}`;
+        try {
+            await this.api.editMessageText(this.chatId, this.messageId, display);
+            this.lastEditAt = Date.now();
+        }
+        catch (err) {
+            // "message is not modified" is harmless (same content as before)
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!/not modified/i.test(msg)) {
+                console.warn(`[subagent-live] edit failed:`, msg);
+            }
+        }
+        this.pendingText = null;
+    }
+    /**
+     * Flush any pending edit, then post the final banner as a new message
+     * so the user gets a notification. The live-stream message stays in
+     * place as the body; the banner is a separate message above/below it.
+     */
+    async finalize(info, result) {
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+        if (this.pendingText) {
+            await this.flush();
+        }
+        this.started = false;
+        if (this.failed)
+            return;
+        // One last edit to remove the "thinking…" header (replace with final text)
+        if (this.messageId !== null && this.api.editMessageText) {
+            const finalBody = (result.output?.trim() || "(empty output)").slice(0, MAX_TG_CHUNK);
+            const finalDisplay = `${info.name}\n\n${finalBody}`;
+            try {
+                await this.api.editMessageText(this.chatId, this.messageId, finalDisplay);
+            }
+            catch {
+                // If the final edit fails, the "thinking…" header stays —
+                // the banner below will still communicate completion.
+            }
+        }
+        // Post the banner as a new message (notification-triggering)
+        const banner = buildBanner(info, result);
+        try {
+            await this.api.sendMessage(this.chatId, banner, { parse_mode: "Markdown" });
+        }
+        catch (err) {
+            console.error(`[subagent-live] finalize banner failed:`, err);
+            this.failed = true;
+            throw err;
+        }
+    }
+}
+/**
+ * Factory for LiveStream — returns null if the bot api isn't attached
+ * yet, or if the api doesn't support editMessageText. Callers check
+ * the return value and fall back to normal delivery if null.
+ */
+export function createLiveStream(chatId, agentName) {
+    const api = getBotApi();
+    if (!api || !api.editMessageText) {
+        console.warn(`[subagent-live] no compatible bot api — live mode unavailable`);
+        return null;
+    }
+    return new LiveStream(api, chatId, agentName);
+}
+// ── Main delivery entry point ───────────────────────────────
 /**
  * Main delivery entry point. Resolves the effective visibility (override →
  * config default), then dispatches to the source-specific renderer.
@@ -68,6 +219,10 @@ 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.
     const api = getBotApi();
     if (!api) {
         console.warn(`[subagent-delivery] no bot api available for ${info.name}`);