@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/subagents.js

@@ -0,0 +1,626 @@
+/**
+ * Sub-agent (Task/Agent tool) transcript reader — issue #37.
+ *
+ * When a chat agent spawns a sub-agent via the `Task` tool (classic Claude Code)
+ * or the `Agent` tool (Agent SDK), the sub-agent runs its own turn whose full
+ * step-by-step transcript is written to disk alongside the parent session:
+ *
+ *   <projectDir>/.chats/<sessionId>/subagents/agent-<hex>.jsonl        // the steps
+ *   <projectDir>/.chats/<sessionId>/subagents/agent-<hex>.meta.json    // linking sidecar
+ *
+ * The `.meta.json` sidecar is the key linking artifact:
+ *   { "agentType", "description", "toolUseId", "spawnDepth" }
+ * Its `toolUseId` ties the sub-agent transcript back to the parent turn's
+ * `Task`/`Agent` tool_use block, so we can render each sub-agent's activity
+ * underneath the tool block that launched it.
+ *
+ * herdctl deliberately filters these `isSidechain` files out of session
+ * discovery (they'd clutter the top-level chat list), and its parsed
+ * `ChatToolCall` carries neither the tool input nor the `toolUseId`. Rather than
+ * change upstream, we read the raw transcript here (paddock already owns the
+ * `.chats/` layout via `transcripts.ts`) and reuse core's exported
+ * `parseSessionMessages` — the expensive jsonl→messages parsing — on each
+ * sub-agent file. Discovery lives here; parsing stays in core.
+ */
+import { promises as fs, createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { parseSessionMessages } from "@herdctl/core";
+import { projectChatsDir } from "./transcripts.js";
+import { readSessionTokenUsage, readSessionTokenUsageFile, } from "./usage.js";
+import { estimateCostUsdByModel } from "./models.js";
+/** Tool names that launch a sub-agent. `Task` = classic Claude Code, `Agent` = Agent SDK. */
+export const SUBAGENT_TOOL_NAMES = new Set(["Task", "Agent"]);
+/**
+ * Extract every `Task`/`Agent` `tool_use` block from a single raw SDK message,
+ * with `subagent_type` + `description` read directly from the tool input. Returns
+ * [] for any message that carries no sub-agent launch (the common case). This is
+ * the live counterpart to {@link readTaskToolUses} (which recovers the same fields
+ * from the transcript on disk): it lets ws-turn enrich the live `chat:tool_start`
+ * / `chat:tool_call` frames as the launch streams, closing the "generic launch-ack
+ * live, only enriches on refresh" gap (#429). The message shape is loosely typed
+ * in core, so every field access is guarded.
+ */
+export function extractSubagentLaunches(m) {
+    const content = m?.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const block of content) {
+        const b = block;
+        if (b?.type === "tool_use" && b.name && SUBAGENT_TOOL_NAMES.has(b.name) && typeof b.id === "string") {
+            out.push({
+                toolUseId: b.id,
+                subagentType: str(b.input?.subagent_type),
+                description: str(b.input?.description),
+            });
+        }
+    }
+    return out;
+}
+/** Both sessionId and toolUseId are path segments — keep them inside `.chats/`. */
+export const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+// ---------------------------------------------------------------------------
+// mtime-keyed memo (issue #147)
+//
+// Opening a sub-agent-bearing chat used to re-stream the whole main transcript a
+// second time (to recover Task/Agent tool_use ids that core's parser drops) and
+// read every sub-agent .jsonl in full — on *every* open, including a plain
+// refresh of an unchanged chat. Transcripts are immutable except when a new turn
+// appends (which bumps mtime), so memoize these per-file reads keyed on the
+// file's mtime: a refresh of an unchanged chat now skips both the second parse
+// and the sub-agent reads. Mirrors core's mtime caches (herdctl #351).
+// ---------------------------------------------------------------------------
+/**
+ * Max files retained per mtime cache.
+ *
+ * Was 64, which a real project blows straight through: one live-scale project
+ * holds 514 transcript files across 234 chats, so a single sweep of
+ * `/chats/usage` evicted every entry before the next sweep could reuse one — the
+ * cache was pure overhead. Measured on that corpus (issue #537), raising the cap
+ * took the warm full-project usage call from ~440ms to ~29ms.
+ *
+ * The entries are token tallies and tool-use records, not transcript text, so
+ * this is cheap: forcing every one of the 1,515 sessions in that corpus through
+ * both the usage and sub-agent-listing paths and then running GC retained
+ * **1.4 MB** at this cap versus **1.3 MB** at 64 — a ~0.1 MB difference for a
+ * 15× speedup.
+ */
+export const MTIME_CACHE_MAX = 1024;
+const taskUsesCache = new Map();
+const durationCache = new Map();
+const usageCache = new Map();
+/** The file's mtime in epoch ms, or undefined if it can't be stat'd. */
+export async function statMtimeMs(file) {
+    try {
+        return (await fs.stat(file)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Return the cached value if the recorded mtime still matches (LRU-touch on hit). */
+export function mtimeCacheGet(cache, file, mtimeMs) {
+    const entry = cache.get(file);
+    if (entry && entry.mtimeMs === mtimeMs) {
+        cache.delete(file);
+        cache.set(file, entry); // re-insert to mark most-recently-used
+        return { hit: true, value: entry.value };
+    }
+    return { hit: false };
+}
+/** Store a value against the file's mtime, evicting the least-recently-used past the cap. */
+export function mtimeCacheSet(cache, file, mtimeMs, value) {
+    cache.set(file, { mtimeMs, value });
+    while (cache.size > MTIME_CACHE_MAX) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+}
+/**
+ * Stream the main session transcript and recover, in file order, every
+ * `Task`/`Agent` tool_use that was **paired** with a tool_result. Pairing is
+ * tracked so the returned list aligns 1:1 with herdctl's parsed tool messages
+ * for completed calls.
+ *
+ * Paired-only by design — {@link readTaskUsesFromFile} exposes the in-flight
+ * launches separately, and mixing them here would break that alignment.
+ */
+export async function readTaskToolUses(projectDir, sessionId) {
+    return (await readTaskUsesForSession(projectDir, sessionId)).paired;
+}
+/**
+ * Both halves of a session's Task/Agent launches. `sessionId` is a path segment,
+ * so it is validated here — every caller reaches the transcript through this.
+ */
+async function readTaskUsesForSession(projectDir, sessionId) {
+    if (!SAFE_SEGMENT.test(sessionId))
+        return { paired: [], pending: [] };
+    return readTaskUsesFromFile(path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`));
+}
+/**
+ * Recover Task/Agent tool_uses (in order, split paired vs in-flight) from an
+ * arbitrary transcript file — the main session file, or a sub-agent's own
+ * transcript (which lets a sub-agent's nested launches be enriched for recursive
+ * expansion).
+ */
+async function readTaskUsesFromFile(file) {
+    const mtimeMs = await statMtimeMs(file);
+    if (mtimeMs !== undefined) {
+        const cached = mtimeCacheGet(taskUsesCache, file, mtimeMs);
+        if (cached.hit)
+            return cached.value;
+    }
+    const value = await readTaskUsesFromFileUncached(file);
+    if (mtimeMs !== undefined)
+        mtimeCacheSet(taskUsesCache, file, mtimeMs, value);
+    return value;
+}
+async function readTaskUsesFromFileUncached(file) {
+    const byId = new Map();
+    const order = [];
+    const resultIds = new Set();
+    const stream = createReadStream(file, { encoding: "utf8" });
+    stream.on("error", () => undefined);
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            const content = parsed.message?.content;
+            if (!Array.isArray(content))
+                continue;
+            for (const block of content) {
+                const b = block;
+                if (b?.type === "tool_use" && b.name && SUBAGENT_TOOL_NAMES.has(b.name) && b.id) {
+                    if (!byId.has(b.id)) {
+                        order.push(b.id);
+                        byId.set(b.id, {
+                            toolUseId: b.id,
+                            subagentType: str(b.input?.subagent_type),
+                            description: str(b.input?.description),
+                            prompt: str(b.input?.prompt),
+                        });
+                    }
+                }
+                else if (b?.type === "tool_result" && typeof b.tool_use_id === "string") {
+                    resultIds.add(b.tool_use_id);
+                }
+            }
+        }
+    }
+    catch {
+        return { paired: [], pending: [] };
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return {
+        paired: order.filter((id) => resultIds.has(id)).map((id) => byId.get(id)),
+        pending: order.filter((id) => !resultIds.has(id)).map((id) => byId.get(id)),
+    };
+}
+/**
+ * Live sub-agent enrichment for a tool frame (issue #429). When the tool is a
+ * `Task`/`Agent` launch this turn already recovered (via {@link extractSubagentLaunches}),
+ * return the real sub-agent type + title plus `hasSubagent: true`, so the client
+ * renders the enriched, expandable card the moment the launch streams — instead of
+ * the generic "Agent · <ms>" launch-ack that only filled in on refresh. A safe
+ * spread for any non-sub-agent tool (returns an empty object). `hasSubagent` is set
+ * optimistically: a `Task`/`Agent` launch is expected to write a sub-agent
+ * transcript, and the client's expand path degrades gracefully (a "waiting…"
+ * placeholder) until the sidecar appears on disk.
+ */
+export function subagentLaunchFields(launches, toolName, toolUseId) {
+    if (!toolUseId || !SUBAGENT_TOOL_NAMES.has(toolName))
+        return {};
+    const l = launches.get(toolUseId);
+    return { subagentType: l?.subagentType, description: l?.description, hasSubagent: true };
+}
+/**
+ * Read the `subagents/*.meta.json` sidecars for a session, keyed by `toolUseId`.
+ * Returns an empty map when the session has no sub-agents (the common case) or
+ * the directory is missing/unreadable.
+ */
+export async function listSubagents(projectDir, sessionId) {
+    const out = new Map();
+    if (!SAFE_SEGMENT.test(sessionId))
+        return out;
+    const dir = path.join(projectChatsDir(projectDir), sessionId, "subagents");
+    const entries = await fs.readdir(dir).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.endsWith(".meta.json"))
+            continue;
+        const raw = await fs.readFile(path.join(dir, entry), "utf8").catch(() => null);
+        if (raw === null)
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (typeof meta.toolUseId !== "string")
+            continue;
+        // This sub-agent's own id is the `<hex>` of its `agent-<hex>.meta.json` filename
+        // (the sidecar records only its PARENT's id, not its own); `parentAgentId` links
+        // it to the sub-agent that spawned it. Together they build the tree for the cost
+        // rollup. An empty id (a malformed name) is dropped to undefined.
+        const agentId = entry.replace(/^agent-/, "").replace(/\.meta\.json$/, "") || undefined;
+        out.set(meta.toolUseId, {
+            toolUseId: meta.toolUseId,
+            agentType: str(meta.agentType),
+            description: str(meta.description),
+            spawnDepth: typeof meta.spawnDepth === "number" ? meta.spawnDepth : undefined,
+            agentId,
+            parentAgentId: str(meta.parentAgentId),
+            // The transcript is the sidecar's sibling: agent-<hex>.meta.json → agent-<hex>.jsonl
+            transcriptPath: path.join(dir, entry.replace(/\.meta\.json$/, ".jsonl")),
+        });
+    }
+    return out;
+}
+/**
+ * Parse a single sub-agent's transcript into messages, reusing core's parser.
+ * Returns [] when the `toolUseId` doesn't correspond to a known sub-agent or the
+ * transcript is missing. Both segments are validated to stay inside `.chats/`.
+ */
+export async function readSubagentMessages(projectDir, sessionId, toolUseId) {
+    if (!SAFE_SEGMENT.test(sessionId) || !SAFE_SEGMENT.test(toolUseId))
+        return [];
+    const subagents = await listSubagents(projectDir, sessionId);
+    const meta = subagents.get(toolUseId);
+    if (!meta)
+        return [];
+    const messages = await parseSessionMessages(meta.transcriptPath).catch(() => []);
+    if (!hasSubagentTool(messages))
+        return messages;
+    // A sub-agent may itself spawn sub-agents (spawnDepth > 1). Their sidecars are
+    // flat in the SAME session's subagents/ dir, so enriching this transcript's own
+    // Task/Agent blocks against `subagents` lets the UI expand them recursively.
+    const taskUses = await readTaskUsesFromFile(meta.transcriptPath);
+    const [durations, costs] = await Promise.all([
+        subagentDurations(subagents),
+        subagentCosts(subagents),
+    ]);
+    return attachSubagentFields(messages, taskUses, subagents, durations, costs);
+}
+/**
+ * Enrich a session's parsed messages: attach the recovered sub-agent fields
+ * (`toolUseId`, `subagentType`, `description`, `prompt`, `hasSubagent`) to every
+ * `Task`/`Agent` tool message, joining by file order. Non-Task tool calls and
+ * sessions without sub-agents pass through unchanged (a cheap early return).
+ */
+export async function enrichWithSubagents(projectDir, sessionId, messages) {
+    if (!hasSubagentTool(messages))
+        return messages;
+    const [taskUses, subagents] = await Promise.all([
+        readTaskUsesForSession(projectDir, sessionId),
+        listSubagents(projectDir, sessionId),
+    ]);
+    const [durations, costs] = await Promise.all([
+        subagentDurations(subagents),
+        subagentCosts(subagents),
+    ]);
+    return attachSubagentFields(messages, taskUses, subagents, durations, costs);
+}
+/**
+ * Compute each sub-agent's run time (ms) from the first→last timestamp in its
+ * own transcript. Keyed by toolUseId. Runs once per session on chat open (only
+ * over that session's sub-agent files), so the cost is bounded to the open chat.
+ */
+async function subagentDurations(subagents) {
+    const out = new Map();
+    await Promise.all([...subagents.values()].map(async (m) => {
+        const ms = await readSubagentDurationMs(m.transcriptPath);
+        if (ms !== undefined)
+            out.set(m.toolUseId, ms);
+    }));
+    return out;
+}
+/**
+ * The elapsed wall-clock of a sub-agent transcript: the delta between its first
+ * and last `timestamp`. Scans for timestamps without a full JSON parse; returns
+ * undefined if the file is missing or has < 2 timestamps.
+ */
+async function readSubagentDurationMs(file) {
+    const mtimeMs = await statMtimeMs(file);
+    if (mtimeMs !== undefined) {
+        const cached = mtimeCacheGet(durationCache, file, mtimeMs);
+        if (cached.hit)
+            return cached.value;
+    }
+    const value = await readSubagentDurationMsUncached(file);
+    // Cache even undefined (missing/malformed) so a repeat open of an unchanged,
+    // duration-less transcript doesn't re-read the whole file every time.
+    if (mtimeMs !== undefined)
+        mtimeCacheSet(durationCache, file, mtimeMs, value);
+    return value;
+}
+async function readSubagentDurationMsUncached(file) {
+    const raw = await fs.readFile(file, "utf8").catch(() => null);
+    if (raw === null)
+        return undefined;
+    const matches = [...raw.matchAll(/"timestamp":"([^"]+)"/g)];
+    if (matches.length < 2)
+        return undefined;
+    const first = Date.parse(matches[0][1]);
+    const last = Date.parse(matches[matches.length - 1][1]);
+    if (Number.isNaN(first) || Number.isNaN(last) || last < first)
+        return undefined;
+    return last - first;
+}
+/**
+ * Compute each sub-agent's estimated API-rate cost (USD), keyed by toolUseId, as
+ * the RECURSIVE total of the sub-agent PLUS every sub-agent it (transitively)
+ * spawned. Runs once per session on chat open, over that session's sub-agent files.
+ *
+ * The sub-agent tree comes from the `.meta.json` sidecars: each carries its
+ * `parentAgentId`, and its own agent id is its `agent-<hex>` transcript name (see
+ * {@link listSubagents}). For each node we merge the per-model token usage across
+ * its whole subtree, then price once ({@link estimateCostUsdByModel}). Merging
+ * TOKEN USAGE (rather than summing already-priced dollars) is what keeps an
+ * unpriced-model descendant from zeroing out its priced neighbours: the result is
+ * `null` only when the entire subtree has no priceable usage (e.g. a leaf that ran
+ * on a model with no known pricing and spawned nothing), and a number otherwise.
+ *
+ * COST ONLY. Duration is deliberately NOT rolled up ({@link subagentDurations}
+ * stays per-agent): nested children run in PARALLEL, so their wall-clock overlaps
+ * the parent's and each other's — summing durations would badly overstate elapsed
+ * time. Dollar cost, by contrast, is additive regardless of concurrency, so a
+ * subtree total is meaningful. The chat grand-total
+ * ({@link readSessionTokenUsageWithSubagents}) is a SEPARATE value that already
+ * flat-sums every sub-agent once (issue #242) — untouched here, and no
+ * double-count, since these per-card subtree totals are never summed together.
+ */
+async function subagentCosts(subagents) {
+    const metas = [...subagents.values()];
+    // 1. Each sub-agent's OWN per-model token usage (parallel, mtime-memoized reads).
+    const ownByModel = new Map();
+    await Promise.all(metas.map(async (m) => {
+        const usage = await readSubagentUsageFile(m.transcriptPath);
+        ownByModel.set(m.toolUseId, usage.byModel);
+    }));
+    // 2. Build the tree: agentId → meta, and parentAgentId → child agentIds. A
+    //    depth-1 sub-agent has no parentAgentId (its parent is the main session), so
+    //    it's a root; only links to a KNOWN sub-agent id form an edge.
+    const metaByAgentId = new Map();
+    for (const m of metas)
+        if (m.agentId)
+            metaByAgentId.set(m.agentId, m);
+    const childrenOf = new Map();
+    for (const m of metas) {
+        if (m.agentId && m.parentAgentId && metaByAgentId.has(m.parentAgentId)) {
+            const kids = childrenOf.get(m.parentAgentId) ?? [];
+            kids.push(m.agentId);
+            childrenOf.set(m.parentAgentId, kids);
+        }
+    }
+    // 3. For each node, DFS its subtree (self + all transitive descendants), merging
+    //    per-model usage, then price once. `seen` guards against a malformed cyclic link.
+    const out = new Map();
+    for (const m of metas) {
+        const merged = {};
+        const seen = new Set();
+        const visit = (toolUseId, agentId) => {
+            mergeByModelInto(merged, ownByModel.get(toolUseId) ?? {});
+            if (!agentId)
+                return;
+            for (const childId of childrenOf.get(agentId) ?? []) {
+                if (seen.has(childId))
+                    continue;
+                seen.add(childId);
+                const child = metaByAgentId.get(childId);
+                if (child)
+                    visit(child.toolUseId, child.agentId);
+            }
+        };
+        if (m.agentId)
+            seen.add(m.agentId);
+        visit(m.toolUseId, m.agentId);
+        out.set(m.toolUseId, estimateCostUsdByModel(merged));
+    }
+    return out;
+}
+/** Add one per-model usage map into a running accumulator (mirrors the fold in
+ *  {@link mergeSubagentUsage}). Used by the recursive cost rollup. */
+function mergeByModelInto(target, src) {
+    for (const [model, t] of Object.entries(src)) {
+        const b = (target[model] ??= {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        });
+        b.inputTokens += t.inputTokens;
+        b.outputTokens += t.outputTokens;
+        b.cacheReadTokens += t.cacheReadTokens;
+        b.cacheCreationTokens += t.cacheCreationTokens;
+    }
+}
+/**
+ * Cumulative token usage of a single sub-agent transcript, memoized on its mtime.
+ * The shared primitive behind both the per-card cost rollup ({@link subagentCosts})
+ * and the chat-total roll-up ({@link readSessionTokenUsageWithSubagents}), so a
+ * chat open parses each sub-agent file at most once.
+ */
+async function readSubagentUsageFile(file) {
+    const mtimeMs = await statMtimeMs(file);
+    if (mtimeMs !== undefined) {
+        const cached = mtimeCacheGet(usageCache, file, mtimeMs);
+        if (cached.hit)
+            return cached.value;
+    }
+    const usage = await readSessionTokenUsageFile(file);
+    if (mtimeMs !== undefined)
+        mtimeCacheSet(usageCache, file, mtimeMs, usage);
+    return usage;
+}
+/**
+ * A chat's cumulative token usage *including every sub-agent it spawned* (issue
+ * #242).
+ *
+ * The per-chat cost/token headline (issue #152) originally priced only the main
+ * transcript, but a chat's `Task`/`Agent` sub-agents run in their own sibling
+ * transcripts (`.chats/<sessionId>/subagents/agent-*.jsonl`) — so a chat that
+ * fanned work out to sub-agents under-reported its true spend, sometimes by ~90%.
+ * This folds those transcripts back in: the four token totals and the per-model
+ * buckets gain every sub-agent's usage, so both the token figure and the
+ * per-model-priced dollar estimate reflect the whole chat.
+ *
+ * `contextTokens` and `turnCount` stay main-only: those describe the parent's
+ * last-turn context-window fill (what the ContextMeter shows), a distinct concept
+ * from lifetime spend — each sub-agent has its own, separate context window.
+ *
+ * No double-counting: herdctl writes sub-agent (`isSidechain`) turns to the
+ * sibling files, never into the main transcript, so `main + sub-agents` is a
+ * clean sum. Nested sub-agents (spawnDepth > 1) sit flat in the same `subagents/`
+ * dir, so their usage is included too. Returns the main usage unchanged when the
+ * chat spawned no sub-agents (the common case — a cheap early return).
+ */
+export async function readSessionTokenUsageWithSubagents(projectDir, sessionId) {
+    const main = await readSessionTokenUsage(projectDir, sessionId);
+    if (!SAFE_SEGMENT.test(sessionId))
+        return main;
+    const dir = path.join(projectChatsDir(projectDir), sessionId, "subagents");
+    const entries = await fs.readdir(dir).catch(() => []);
+    const files = entries.filter((e) => e.endsWith(".jsonl"));
+    if (files.length === 0)
+        return main;
+    const subUsages = await Promise.all(files.map((f) => readSubagentUsageFile(path.join(dir, f))));
+    return mergeSubagentUsage(main, subUsages);
+}
+/**
+ * Fold sub-agent usages into a *copy* of the main usage. Builds fresh token
+ * buckets rather than mutating `main.byModel` / the sub-agents' cached objects —
+ * both come straight out of mtime caches and must stay pristine. Pricing stays
+ * per-model (buckets keyed by `message.model`), so a sub-agent that ran on a
+ * different, pricier model than the parent is costed at its own rate.
+ */
+function mergeSubagentUsage(main, subs) {
+    const byModel = {};
+    const add = (model, t) => {
+        const b = (byModel[model] ??= {
+            inputTokens: 0,
+            outputTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        });
+        b.inputTokens += t.inputTokens;
+        b.outputTokens += t.outputTokens;
+        b.cacheReadTokens += t.cacheReadTokens;
+        b.cacheCreationTokens += t.cacheCreationTokens;
+    };
+    for (const [model, t] of Object.entries(main.byModel))
+        add(model, t);
+    let { hasData, inputTotal, outputTotal, cacheReadTotal, cacheCreationTotal } = main;
+    for (const s of subs) {
+        if (!s.hasData)
+            continue;
+        hasData = true;
+        inputTotal += s.inputTotal;
+        outputTotal += s.outputTotal;
+        cacheReadTotal += s.cacheReadTotal;
+        cacheCreationTotal += s.cacheCreationTotal;
+        for (const [model, t] of Object.entries(s.byModel))
+            add(model, t);
+    }
+    return {
+        hasData,
+        turnCount: main.turnCount,
+        contextTokens: main.contextTokens,
+        inputTotal,
+        outputTotal,
+        cacheReadTotal,
+        cacheCreationTotal,
+        byModel,
+    };
+}
+/** True when any message is a Task/Agent tool call worth enriching. */
+function hasSubagentTool(messages) {
+    return messages.some((m) => m.toolCall && SUBAGENT_TOOL_NAMES.has(m.toolCall.toolName));
+}
+/**
+ * Attach recovered sub-agent fields to each Task/Agent tool message by joining
+ * against `taskUses` in file order (both are file-ordered; only paired uses are
+ * present, so the join stays aligned). Other messages pass through untouched.
+ */
+function attachSubagentFields(messages, taskUses, subagents, durations, costs) {
+    let i = 0;
+    let p = 0;
+    return messages.map((m) => {
+        if (!m.toolCall || !SUBAGENT_TOOL_NAMES.has(m.toolCall.toolName))
+            return m;
+        // An in-flight (`pending`) tool_use has no matching tool_result yet, and
+        // core@5.24.0 injects it into the parsed stream so it stays visible on
+        // rehydration (herdctl#399). It is joined off its OWN cursor against the
+        // in-flight launches, never off the paired one — consuming a paired slot here
+        // would shift every following completed sub-agent's enrichment onto the wrong
+        // call (the parallel case: a running Agent inheriting a finished sibling's
+        // `toolUseId`/`hasSubagent` and wrongly rendering as expandable).
+        //
+        // Enriching it at all is what keeps the running-sub-agents bar alive across a
+        // re-mount: the bar's candidates need `toolUseId` + `hasSubagent`, which the
+        // live `chat:tool_start` frame supplies but rehydration used to drop — so
+        // navigating away from a running chat and back emptied the bar for the rest of
+        // the run, with no way to recover short of the sub-agent finishing (#622).
+        if (m.toolCall.pending) {
+            const use = taskUses.pending[p++];
+            if (!use)
+                return m;
+            return {
+                ...m,
+                toolCall: {
+                    ...m.toolCall,
+                    toolUseId: use.toolUseId,
+                    subagentType: use.subagentType,
+                    description: use.description,
+                    prompt: use.prompt,
+                    // Optimistic, exactly as the live path does (see `subagentLaunchFields`):
+                    // the sidecar may not be on disk for the first moment of the run, and the
+                    // client's expand/poll paths already degrade to "starting…" until it is.
+                    hasSubagent: true,
+                    // Deliberately NO `subagentDurationMs`: it is derived from the first→last
+                    // timestamp of a transcript that is still growing, so setting it here
+                    // would both freeze a bogus part-way duration onto the card AND mark the
+                    // sub-agent finished — `useRunningSubagents` drops any card that has one.
+                },
+            };
+        }
+        const use = taskUses.paired[i++];
+        if (!use)
+            return m;
+        return {
+            ...m,
+            toolCall: {
+                ...m.toolCall,
+                toolUseId: use.toolUseId,
+                subagentType: use.subagentType,
+                description: use.description,
+                prompt: use.prompt,
+                hasSubagent: subagents.has(use.toolUseId),
+                subagentDurationMs: durations.get(use.toolUseId),
+                subagentCostUsd: costs.get(use.toolUseId),
+            },
+        };
+    });
+}
+/** Coerce a JSON value to a trimmed non-empty string, else undefined. */
+function str(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const t = v.trim();
+    return t.length ? t : undefined;
+}