alvin-bot 4.5.1 → 4.7.0

package/dist/services/subagents.js

@@ -6,44 +6,286 @@
  * Results are stored and can be retrieved by the caller.
  */
 import os from "os";
+import fs from "fs";
+import { resolve, dirname } from "path";
 import crypto from "crypto";
 import { config } from "../config.js";
+// ── File-based config (persistent, runtime-editable) ───────────────────
+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" || v === "live";
+}
+function loadSubAgentsConfig() {
+    if (configCache)
+        return configCache;
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        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 {
+        // File missing or invalid — seed from env var then default to auto
+        configCache = {
+            maxParallel: Number(process.env.MAX_SUBAGENTS) || 0,
+            visibility: "auto",
+            queueCap: DEFAULT_QUEUE_CAP,
+        };
+    }
+    return configCache;
+}
+function saveSubAgentsConfig(cfg) {
+    try {
+        fs.mkdirSync(dirname(CONFIG_FILE), { recursive: true });
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), "utf-8");
+        configCache = cfg;
+    }
+    catch (err) {
+        console.error("[subagents] failed to write config:", err);
+    }
+}
+/** Resolves max parallel agents, interpreting 0 as "auto = cpu cores capped". */
+export function getMaxParallelAgents() {
+    const cfg = loadSubAgentsConfig();
+    if (cfg.maxParallel === 0) {
+        return Math.min(os.cpus().length, ABSOLUTE_MAX_AGENTS);
+    }
+    return Math.min(Math.max(1, cfg.maxParallel), ABSOLUTE_MAX_AGENTS);
+}
+/** Returns the raw configured value (for display). 0 means "auto". */
+export function getConfiguredMaxParallel() {
+    return loadSubAgentsConfig().maxParallel;
+}
+/** Sets max parallel agents. Value is clamped to [0, ABSOLUTE_MAX_AGENTS].
+ *  Returns the resolved effective value (with auto-expansion if set to 0). */
+export function setMaxParallelAgents(n) {
+    const clamped = Math.max(0, Math.min(Math.floor(n), ABSOLUTE_MAX_AGENTS));
+    const cfg = loadSubAgentsConfig();
+    saveSubAgentsConfig({ ...cfg, maxParallel: clamped });
+    return getMaxParallelAgents();
+}
+/** A4: Current default visibility mode for new spawns. */
+export function getVisibility() {
+    return loadSubAgentsConfig().visibility;
+}
+/**
+ * A4: Set the default visibility mode. Throws if the value is invalid.
+ * Writes through to the on-disk config so restart-resilient.
+ */
+export function setVisibility(mode) {
+    if (!isValidVisibility(mode)) {
+        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) ──────────────────────────────────
+/**
+ * Return all currently-tracked agents whose *base* name matches `base`.
+ * Base name = the part before any "#N" suffix.
+ */
+function agentsByBaseName(base) {
+    const out = [];
+    for (const entry of activeAgents.values()) {
+        const info = entry.info;
+        const entryBase = info.name.replace(/#\d+$/, "");
+        if (entryBase === base)
+            out.push(info);
+    }
+    return out;
+}
+/**
+ * Given a requested name, return a unique variant. If no collision exists,
+ * returns `requested` unchanged (with the base form). Otherwise returns
+ * `base#N` with the smallest free N ≥ 2.
+ */
+function resolveAgentName(requested) {
+    const base = requested.replace(/#\d+$/, "");
+    const siblings = agentsByBaseName(base);
+    if (siblings.length === 0)
+        return { name: base };
+    // Find the smallest free index ≥ 2. The bare base name counts as "#1".
+    const takenIndices = new Set();
+    for (const s of siblings) {
+        const m = s.name.match(/#(\d+)$/);
+        if (m)
+            takenIndices.add(parseInt(m[1], 10));
+        else
+            takenIndices.add(1);
+    }
+    let n = 2;
+    while (takenIndices.has(n))
+        n++;
+    return { name: `${base}#${n}`, index: n };
+}
+/**
+ * Public name-resolution API used by /sub-agents cancel / result.
+ * - Exact name match wins (e.g. "review#2" finds exactly that entry).
+ * - If only one agent matches the base name, returns that one.
+ * - If the caller opted into `ambiguousAsList`, returns a disambiguation
+ *   marker with all candidates instead of a single result.
+ */
+export function findSubAgentByName(name, opts = {}) {
+    // An explicit "base#N" query must always resolve to that exact entry,
+    // even when the caller opted into ambiguity. Otherwise users who type
+    // out the disambiguated form get an unhelpful 'which one?' reply.
+    const hasExplicitSuffix = /#\d+$/.test(name);
+    if (hasExplicitSuffix) {
+        for (const entry of activeAgents.values()) {
+            if (entry.info.name === name)
+                return { ...entry.info };
+        }
+        return null;
+    }
+    // No explicit suffix → base-name query. Ambiguity detection runs here
+    // when the caller opted in and there are multiple siblings.
+    const siblings = agentsByBaseName(name);
+    if (siblings.length === 0)
+        return null;
+    if (opts.ambiguousAsList && siblings.length > 1) {
+        return {
+            ambiguous: true,
+            candidates: siblings.map((s) => ({ ...s })),
+        };
+    }
+    // Without ambiguity opt-in, prefer an exact name match over just the
+    // first sibling — the bare base name is itself a unique key.
+    for (const entry of activeAgents.values()) {
+        if (entry.info.name === name)
+            return { ...entry.info };
+    }
+    return { ...siblings[0] };
+}
 // ── Core execution ──────────────────────────────────────
-async function runSubAgent(id, agentConfig, abort) {
+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();
-        const systemPrompt = `You are a sub-agent named "${agentConfig.name}". Complete the following task autonomously and report your results clearly when done. Working directory: ${agentConfig.workingDir || os.homedir()}`;
+        // C3: inheritCwd (default true) decides whether the parent's working
+        // dir flows through. When false, we fall back to the home directory —
+        // useful for cron jobs that must run in a well-known root regardless
+        // of what the caller was doing.
+        const inheritCwd = agentConfig.inheritCwd ?? true;
+        const effectiveCwd = inheritCwd
+            ? agentConfig.workingDir || os.homedir()
+            : os.homedir();
+        const systemPrompt = `You are a sub-agent named "${resolvedName}". Complete the following task autonomously and report your results clearly when done. Working directory: ${effectiveCwd}`;
         let finalText = "";
         let inputTokens = 0;
         let outputTokens = 0;
         for await (const chunk of registry.queryWithFallback({
             prompt: agentConfig.prompt,
             systemPrompt,
-            workingDir: agentConfig.workingDir || os.homedir(),
+            workingDir: effectiveCwd,
             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;
             }
         }
-        entry.result = {
-            id,
-            name: agentConfig.name,
-            status: "completed",
-            output: finalText,
-            tokensUsed: { input: inputTokens, output: outputTokens },
-            duration: Date.now() - startTime,
-        };
-        entry.info.status = "completed";
+        // If cancelAllSubAgents has already taken over (shutdown path), don't
+        // overwrite the cancelled result it synthesised. Also: if the generator
+        // exited gracefully but the abort signal fired mid-stream (e.g. the
+        // provider's queryWithFallback returned `type:error` and we fell out
+        // of the loop without throwing), mark the run as cancelled rather
+        // than completed — the result output is whatever we buffered.
+        if (entry.result && entry.result.status === "cancelled") {
+            // cancelAllSubAgents already set this; nothing to do.
+        }
+        else if (abort.signal.aborted) {
+            entry.result = {
+                id,
+                name: resolvedName,
+                status: "cancelled",
+                output: finalText,
+                tokensUsed: { input: inputTokens, output: outputTokens },
+                duration: Date.now() - startTime,
+            };
+            entry.info.status = "cancelled";
+        }
+        else {
+            entry.result = {
+                id,
+                name: resolvedName,
+                status: "completed",
+                output: finalText,
+                tokensUsed: { input: inputTokens, output: outputTokens },
+                duration: Date.now() - startTime,
+            };
+            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");
@@ -55,7 +297,7 @@ async function runSubAgent(id, agentConfig, abort) {
                 : "error";
         entry.result = {
             id,
-            name: agentConfig.name,
+            name: resolvedName,
             status,
             output: "",
             tokensUsed: { input: 0, output: 0 },
@@ -65,42 +307,179 @@ async function runSubAgent(id, agentConfig, abort) {
         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;
+}
 /**
- * Spawn an isolated sub-agent that runs in the background.
- * Returns the agent ID immediately (does NOT await completion).
+ * 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;
+}
+/**
+ * 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) {
-    // Check concurrency limit
-    const runningCount = [...activeAgents.values()].filter((a) => a.info.status === "running").length;
-    if (runningCount >= config.maxSubAgents) {
-        return Promise.reject(new Error(`Sub-agent limit reached (${config.maxSubAgents}). Wait for a running agent to finish or cancel one.`));
+    // 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. 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.`));
+    }
+    const maxParallel = getMaxParallelAgents();
+    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();
-    // Set up timeout
     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}/${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}/${maxParallel}) mit eigenen user-Spawns. Queue voll (${queuedLen}/${queueCap}). /subagents cancel <name> oder warten.`;
+            }
+        }
+        else {
+            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));
+    }
     const info = {
         id,
-        name: agentConfig.name,
-        status: "running",
+        name: resolvedName,
+        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 });
-    // Run in background — don't await
-    runSubAgent(id, agentConfig, abort)
-        .finally(() => {
-        clearTimeout(timeoutId);
-        // Auto-cleanup: remove completed agents after 30 minutes
-        setTimeout(() => {
-            const entry = activeAgents.get(id);
-            if (entry && entry.info.status !== "running") {
-                activeAgents.delete(id);
-            }
-        }, 30 * 60 * 1000);
-    });
+    activeAgents.set(id, { info, abort, delivered: false });
+    const queuedSpawn = { id, resolvedName, agentConfig, depth, timeoutId };
+    if (willRunImmediately) {
+        startRun(queuedSpawn);
+    }
+    else {
+        pendingQueue.push(queuedSpawn);
+        reindexQueue();
+    }
     return Promise.resolve(id);
 }
 /**
@@ -115,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";
@@ -129,14 +522,88 @@ export function getSubAgentResult(id) {
     const entry = activeAgents.get(id);
     return entry?.result ?? null;
 }
+/**
+ * Cancel a sub-agent by name (or name#N). Returns true if a running agent
+ * was found and aborted. Uses findSubAgentByName for resolution; in an
+ * ambiguous case (multiple siblings under the same base name, caller did
+ * not disambiguate), cancels the first candidate.
+ */
+export function cancelSubAgentByName(name) {
+    const match = findSubAgentByName(name);
+    if (!match || "ambiguous" in match)
+        return false;
+    return cancelSubAgent(match.id);
+}
+/**
+ * Get a sub-agent's result by name. Returns null if no such agent, no
+ * result yet (still running), or the name is ambiguous without explicit
+ * disambiguation.
+ */
+export function getSubAgentResultByName(name) {
+    const match = findSubAgentByName(name);
+    if (!match || "ambiguous" in match)
+        return null;
+    return getSubAgentResult(match.id);
+}
 /**
  * Cancel all active sub-agents. Used during shutdown.
+ *
+ * When notify=true (default), each running agent gets a Telegram
+ * delivery explaining that it was interrupted by a restart. Errors
+ * during delivery are logged but never block shutdown. The whole
+ * notify phase is capped at 5s so a hung Telegram send can't hold
+ * the process hostage.
  */
-export function cancelAllSubAgents() {
-    for (const [id, entry] of activeAgents) {
-        if (entry.info.status === "running") {
-            entry.abort.abort();
+export async function cancelAllSubAgents(notify = true) {
+    const deliveryPromises = [];
+    // Iterate once: for each running agent (1) abort the SDK stream,
+    // (2) synthesise and store a cancelled SubAgentResult, (3) mark
+    // 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;
+        entry.abort.abort();
+        entry.info.status = "cancelled";
+        const cancelResult = {
+            id,
+            name: entry.info.name,
+            status: "cancelled",
+            output: "⚠️ Agent wurde durch Bot-Restart unterbrochen. Bitte neu triggern.",
+            tokensUsed: { input: 0, output: 0 },
+            duration: Date.now() - entry.info.startedAt,
+        };
+        entry.result = cancelResult;
+        entry.delivered = true;
+        runningEntries.push({ id, info: entry.info, cancelResult });
+    }
+    if (!notify || runningEntries.length === 0)
+        return;
+    // Import once, then reuse. Doing one dynamic import per running agent
+    // races with Vitest's mock-resolution in tests and can occasionally
+    // resolve to the real module instead of the mock for later calls.
+    const { deliverSubAgentResult } = await import("./subagent-delivery.js");
+    for (const { id, info, cancelResult } of runningEntries) {
+        const p = Promise.resolve(deliverSubAgentResult(info, cancelResult)).catch((err) => {
+            console.error(`[subagents] shutdown-notify failed for ${id}:`, err);
+        });
+        deliveryPromises.push(p);
+    }
+    // Wait up to 5s total — long enough for real Telegram sends, short
+    // enough that shutdown isn't held hostage by a hang.
+    await Promise.race([
+        Promise.all(deliveryPromises),
+        new Promise((r) => setTimeout(r, 5000)),
+    ]);
 }

package/dist/services/telegram.js

@@ -9,13 +9,38 @@ export class TelegramStreamer {
     pendingText = null;
     editTimer = null;
     lastSentText = "";
+    currentStatus = null;
+    lastFullText = "";
     constructor(chatId, api, replyToMessageId) {
         this.chatId = chatId;
         this.api = api;
         this.replyTo = replyToMessageId;
     }
+    /**
+     * Set a transient status line (e.g. "📖 Read file.html…") that gets
+     * appended to the current accumulated text. Passing null clears it.
+     * Used to surface tool-use activity so users see real progress instead
+     * of an endless typing indicator.
+     */
+    setStatus(status) {
+        if (this.currentStatus === status)
+            return;
+        this.currentStatus = status;
+        // Re-render with the previously accumulated text so the new status
+        // becomes visible immediately (throttled by the existing flush timer).
+        void this.update(this.lastFullText);
+    }
+    renderWithStatus(fullText) {
+        const truncated = this.truncate(fullText);
+        const hasBody = truncated.length > 0;
+        const body = hasBody ? truncated : "…";
+        if (!this.currentStatus)
+            return body;
+        return hasBody ? `${body}\n\n_${this.currentStatus}_` : `_${this.currentStatus}_`;
+    }
     async update(fullText) {
-        const displayText = sanitizeTelegramMarkdown(this.truncate(fullText) || "...");
+        this.lastFullText = fullText;
+        const displayText = sanitizeTelegramMarkdown(this.renderWithStatus(fullText));
         if (!this.messageId) {
             const opts = { parse_mode: "Markdown" };
             if (this.replyTo)
@@ -52,6 +77,8 @@ export class TelegramStreamer {
         }
     }
     async finalize(fullText) {
+        // Drop any transient status line — final message should be clean text.
+        this.currentStatus = null;
         if (this.editTimer) {
             clearTimeout(this.editTimer);
             this.editTimer = null;