@yagni-app/code 0.2.1 → 0.3.1

package/dist/extension/subagentRender.js

@@ -0,0 +1,441 @@
+/**
+ * Live progress model + TUI renderers for the `subagent` tool.
+ *
+ * The model half is PURE (mirrors `pipeline/activity.ts`): `applyChildEvent`
+ * folds one NDJSON event from a child into a bounded per-task progress record,
+ * and `finalizeTask` stamps the outcome from the runner's `StageResult`. The
+ * tool carries the folded records in its `details`, so every partial update the
+ * TUI sees is a complete picture of all tasks.
+ *
+ * The renderer half implements pi's per-tool rendering seam (`renderCall` /
+ * `renderResult`). Collapsed-while-running is the two-line pattern: a stable
+ * `agent — task` title over a churning `↳ current tool` line. Completion is a
+ * one-line receipt (`✓ agent · N tool uses · Xk tokens · Ys`); expanded shows
+ * the curated action log and the full report as markdown. String assembly is
+ * kept in pure helpers over a minimal {@link RenderTheme} so tests run against
+ * plain text — renderer exceptions are swallowed by pi (silently degrading to
+ * the bare title bar), so everything here must stay boringly total.
+ */
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { narrationHeadline, toolLabel } from "./pipeline/activity.js";
+import { SPINNER_FRAMES } from "./pipeline/activityFeed.js";
+/** Bound on the retained action log so a chatty child cannot grow details unbounded. */
+export const ACTION_LOG_MAX = 120;
+/** How many of the newest actions the expanded view paints. */
+const EXPANDED_ACTIONS_SHOWN = 30;
+/** Collapsed report preview length, in lines. */
+const REPORT_PREVIEW_LINES = 3;
+/** Task preview width on the running title line. */
+const TASK_PREVIEW_MAX = 64;
+/** Spinner cadence; matches the /go feed's SPINNER_TICK_MS. */
+const SPINNER_TICK_MS = 120;
+const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+export function newTaskProgress(agent, task, startedAt) {
+    return {
+        agent,
+        task,
+        status: "running",
+        exitCode: -1,
+        startedAt,
+        toolCalls: 0,
+        toolErrors: 0,
+        usage: { ...EMPTY_USAGE },
+        actions: [],
+        droppedActions: 0,
+    };
+}
+function pushAction(p, entry) {
+    if (p.actions.length >= ACTION_LOG_MAX) {
+        p.actions.shift();
+        p.droppedActions += 1;
+    }
+    p.actions.push(entry);
+}
+/** Last text part of an assistant message, or undefined. */
+function lastMessageText(ev) {
+    const parts = ev.message?.content ?? [];
+    for (let i = parts.length - 1; i >= 0; i--) {
+        const part = parts[i];
+        if (part?.type === "text" && typeof part.text === "string")
+            return part.text;
+    }
+    return undefined;
+}
+/**
+ * Fold one child NDJSON event into the task's progress. Returns true when the
+ * record changed (the tool emits an update), false for events we drop.
+ */
+export function applyChildEvent(p, ev) {
+    switch (ev.type) {
+        case "tool_execution_start": {
+            const entry = {
+                kind: "action",
+                text: toolLabel(ev.toolName ?? "", ev.args),
+                state: "running",
+            };
+            if (ev.toolCallId !== undefined)
+                entry.toolCallId = ev.toolCallId;
+            pushAction(p, entry);
+            return true;
+        }
+        case "tool_execution_end": {
+            p.toolCalls += 1;
+            if (ev.isError)
+                p.toolErrors += 1;
+            for (let i = p.actions.length - 1; i >= 0; i--) {
+                const a = p.actions[i];
+                if (a.kind !== "action" || a.state !== "running")
+                    continue;
+                if (ev.toolCallId !== undefined && a.toolCallId !== ev.toolCallId)
+                    continue;
+                a.state = ev.isError ? "error" : "done";
+                break;
+            }
+            return true;
+        }
+        case "message_end": {
+            const msg = ev.message;
+            if (msg?.role !== "assistant")
+                return false;
+            p.usage.turns += 1;
+            const u = msg.usage;
+            if (u) {
+                p.usage.input += u.input ?? 0;
+                p.usage.output += u.output ?? 0;
+                p.usage.cacheRead += u.cacheRead ?? 0;
+                p.usage.cacheWrite += u.cacheWrite ?? 0;
+                p.usage.cost += u.cost?.total ?? 0;
+            }
+            const text = lastMessageText(ev);
+            const headline = text !== undefined ? narrationHeadline(text) : null;
+            if (headline)
+                pushAction(p, { kind: "narration", text: headline, state: "done" });
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+/** Stamp the runner's outcome onto the progress record. */
+export function finalizeTask(p, result, endedAt) {
+    // An aborted child can close with exit 0 (SIGTERM close reports a null code),
+    // so the stop reason outranks the exit code for the status glyph.
+    p.status = result.exitCode === 0 && result.stopReason !== "aborted" ? "done" : "error";
+    p.exitCode = result.exitCode;
+    p.endedAt = endedAt;
+    p.usage = { ...result.usage };
+    p.toolCalls = result.toolCalls;
+    p.toolErrors = result.toolErrors;
+    p.report = result.finalOutput;
+    if (result.stopReason)
+        p.stopReason = result.stopReason;
+    if (result.errorMessage)
+        p.errorMessage = result.errorMessage;
+}
+// ── Formatting helpers ────────────────────────────────────────────────────────
+/** Collapse whitespace and clip to `max`, appending an ellipsis when cut. */
+function clip(text, max) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= max)
+        return collapsed;
+    return `${collapsed.slice(0, max - 1)}…`;
+}
+function trimTrailingZero(v) {
+    const s = v.toFixed(1);
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+/** 532 → "532", 41_234 → "41.2k", 1_240_000 → "1.2M". */
+export function formatTokens(n) {
+    if (n < 1000)
+        return String(n);
+    if (n < 1_000_000)
+        return `${trimTrailingZero(n / 1000)}k`;
+    return `${trimTrailingZero(n / 1_000_000)}M`;
+}
+/** 42_000 → "42s", 81_000 → "1m 21s", 3_720_000 → "1h 2m". */
+export function formatDuration(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+function countToolUses(n) {
+    return n === 1 ? "1 tool use" : `${n} tool uses`;
+}
+/** Tokens the child actually generated/consumed (cache reads excluded). */
+function taskTokens(p) {
+    return p.usage.input + p.usage.output;
+}
+/** The most recent still-running tool action, if any. */
+function currentActionText(p) {
+    for (let i = p.actions.length - 1; i >= 0; i--) {
+        const a = p.actions[i];
+        if (a.kind === "action" && a.state === "running")
+            return a.text;
+    }
+    return undefined;
+}
+/** What the child is doing right now: current tool → tool-use count → starting. */
+function liveDetailText(p) {
+    return currentActionText(p) ?? (p.toolCalls > 0 ? countToolUses(p.toolCalls) : "starting…");
+}
+/**
+ * The two-line live status for one running task: a stable `agent — task` title
+ * over the churning current-action line with elapsed time and live tokens.
+ */
+export function runningLines(p, theme, now, frame) {
+    const title = `${frame} ${theme.fg("accent", p.agent)} — ${theme.fg("dim", clip(p.task, TASK_PREVIEW_MAX))}`;
+    let detail = `  ${theme.fg("muted", "↳")} ${theme.fg("toolOutput", liveDetailText(p))}`;
+    detail += theme.fg("dim", ` · ${formatDuration(now - p.startedAt)}`);
+    const tokens = taskTokens(p);
+    if (tokens > 0)
+        detail += theme.fg("dim", ` · ${formatTokens(tokens)} tokens`);
+    return [title, detail];
+}
+/** One-line completion receipt: `✓ agent · N tool uses · Xk tokens · Ys · $c`. */
+export function receiptLine(p, theme) {
+    const parts = [
+        countToolUses(p.toolCalls),
+        `${formatTokens(taskTokens(p))} tokens`,
+        formatDuration((p.endedAt ?? p.startedAt) - p.startedAt),
+    ];
+    if (p.toolErrors > 0)
+        parts.push(`${p.toolErrors} tool ${p.toolErrors === 1 ? "error" : "errors"}`);
+    if (p.usage.cost > 0)
+        parts.push(`$${p.usage.cost.toFixed(2)}`);
+    const name = theme.bold(theme.fg("accent", p.agent));
+    if (p.status === "error") {
+        const reason = p.stopReason ?? (p.exitCode >= 0 ? `exit ${p.exitCode}` : "failed");
+        return `${theme.fg("error", "✗")} ${name} ${theme.fg("error", `failed (${reason})`)} ${theme.fg("dim", `· ${parts.join(" · ")}`)}`;
+    }
+    return `${theme.fg("success", "✓")} ${name} ${theme.fg("dim", `· ${parts.join(" · ")}`)}`;
+}
+/** Aggregate receipt across parallel tasks. */
+function totalLine(tasks, theme) {
+    const toolCalls = tasks.reduce((n, p) => n + p.toolCalls, 0);
+    const tokens = tasks.reduce((n, p) => n + taskTokens(p), 0);
+    const cost = tasks.reduce((n, p) => n + p.usage.cost, 0);
+    const start = Math.min(...tasks.map((p) => p.startedAt));
+    const end = Math.max(...tasks.map((p) => p.endedAt ?? p.startedAt));
+    const parts = [countToolUses(toolCalls), `${formatTokens(tokens)} tokens`, formatDuration(end - start)];
+    if (cost > 0)
+        parts.push(`$${cost.toFixed(2)}`);
+    return theme.fg("dim", `${tasks.length} subagents · ${parts.join(" · ")}`);
+}
+/**
+ * Plain-text (no theme) summary for the partial result's `content`, so headless
+ * consumers and pi's fallback renderer still see live progress.
+ */
+export function progressSummaryText(tasks, now) {
+    const plain = { bold: (s) => s, fg: (_c, s) => s };
+    return tasks
+        .map((p) => p.status === "running"
+        ? `${p.agent}: ${liveDetailText(p)} · ${formatDuration(now - p.startedAt)}`
+        : receiptLine(p, plain))
+        .join("\n");
+}
+/** The harness "Working…" replacement while subagents run. */
+export function formatWorkingMessage(tasks, now) {
+    const toolCalls = tasks.reduce((n, p) => n + p.toolCalls, 0);
+    const started = Math.min(...tasks.map((p) => p.startedAt));
+    const elapsed = formatDuration(now - started);
+    if (tasks.length === 1) {
+        return `subagent ${tasks[0].agent} · ${countToolUses(toolCalls)} · ${elapsed}`;
+    }
+    const running = tasks.filter((p) => p.status === "running").length;
+    const label = running > 0 && running < tasks.length ? `${running}/${tasks.length} subagents` : `${tasks.length} subagents`;
+    return `${label} · ${countToolUses(toolCalls)} · ${elapsed}`;
+}
+/** Title painted the moment the call streams in (before any execution output). */
+export function renderSubagentCall(args, theme, _context) {
+    const title = theme.fg("toolTitle", theme.bold("subagent"));
+    const a = args ?? {};
+    if (a.tasks && a.tasks.length > 0) {
+        let text = `${title} ${theme.fg("accent", `${a.tasks.length} parallel tasks`)}`;
+        for (const t of a.tasks) {
+            text += `\n  ${theme.fg("accent", t.agent ?? "general")} ${theme.fg("dim", clip(t.task ?? "…", TASK_PREVIEW_MAX))}`;
+        }
+        return new Text(text, 0, 0);
+    }
+    let text = `${title} ${theme.fg("accent", a.agent ?? "general")}`;
+    if (a.task)
+        text += `\n  ${theme.fg("dim", clip(a.task, 2 * TASK_PREVIEW_MAX))}`;
+    return new Text(text, 0, 0);
+}
+function fallbackText(result) {
+    const first = result.content.find((c) => c.type === "text" && typeof c.text === "string");
+    return new Text(first?.text ?? "(no output)", 0, 0);
+}
+function actionGlyph(a, theme) {
+    if (a.kind === "narration")
+        return theme.fg("muted", "·");
+    if (a.state === "error")
+        return theme.fg("error", "✗");
+    if (a.state === "running")
+        return theme.fg("muted", "→");
+    return theme.fg("muted", "→");
+}
+function actionLogLines(p, theme, shown) {
+    const lines = [];
+    const tail = p.actions.slice(-shown);
+    const skipped = p.droppedActions + (p.actions.length - tail.length);
+    if (skipped > 0)
+        lines.push(theme.fg("muted", `  … ${skipped} earlier actions`));
+    for (const a of tail) {
+        const color = a.kind === "narration" ? "dim" : a.state === "error" ? "error" : "toolOutput";
+        lines.push(`  ${actionGlyph(a, theme)} ${theme.fg(color, clip(a.text, 110))}`);
+    }
+    return lines;
+}
+/**
+ * Fail-open degradation is still worth seeing: warn (not error — falling back to
+ * plain text is recoverable, nothing to page on) so an unexpected markdown
+ * failure is observable. Once per component, because the render path repaints on
+ * every frame and the "no TUI" case would otherwise flood the log.
+ */
+function warnMarkdownFallback(phase, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+        console.warn(JSON.stringify({
+            source: "yagni-subagent-render",
+            level: "warning",
+            message: "markdown rendering unavailable; falling back to plain text",
+            phase,
+            error: message,
+        }));
+    }
+    catch {
+        console.warn(`[yagni-subagent-render] markdown ${phase} failed: ${message}`);
+    }
+}
+/**
+ * A prose body as markdown when the TUI's markdown theme is available.
+ * `getMarkdownTheme()` hands back a lazy proxy that only throws when a style is
+ * first USED, so the fallback must wrap `render`, not construction — otherwise
+ * an uninitialized theme would blow up mid-paint and pi would silently degrade
+ * the whole row to the bare title bar.
+ */
+export function markdownOrPlain(body, theme) {
+    const plain = new Text(theme.fg("toolOutput", body.trim()), 0, 0);
+    let markdown;
+    try {
+        markdown = new Markdown(body.trim(), 0, 0, getMarkdownTheme());
+    }
+    catch (err) {
+        warnMarkdownFallback("construct", err);
+        return plain;
+    }
+    let warned = false;
+    return {
+        render(width) {
+            try {
+                return markdown.render(width);
+            }
+            catch (err) {
+                if (!warned) {
+                    warned = true;
+                    warnMarkdownFallback("render", err);
+                }
+                return plain.render(width);
+            }
+        },
+        invalidate() {
+            markdown.invalidate?.();
+            plain.invalidate();
+        },
+    };
+}
+/**
+ * Result renderer: live two-line status per task while partial; receipts plus
+ * report preview when collapsed; action log plus full markdown report when
+ * expanded. Drives its own refresh while running via an unref'd interval on
+ * `context.state` (pi has no unmount hook — the final render clears it).
+ */
+export function renderSubagentResult(result, options, theme, context) {
+    const details = result.details;
+    const tasks = details?.tasks;
+    const state = context.state ?? {};
+    if (options.isPartial) {
+        if (!state.timer) {
+            state.timer = setInterval(() => context.invalidate(), SPINNER_TICK_MS);
+            state.timer.unref?.();
+        }
+    }
+    else if (state.timer) {
+        clearInterval(state.timer);
+        delete state.timer;
+    }
+    if (!tasks || tasks.length === 0)
+        return fallbackText(result);
+    if (options.isPartial) {
+        const now = Date.now();
+        const frame = SPINNER_FRAMES[Math.floor(now / SPINNER_TICK_MS) % SPINNER_FRAMES.length];
+        const lines = [];
+        for (const p of tasks) {
+            if (lines.length > 0)
+                lines.push("");
+            if (p.status === "running")
+                lines.push(...runningLines(p, theme, now, frame));
+            else
+                lines.push(receiptLine(p, theme));
+            if (options.expanded)
+                lines.push(...actionLogLines(p, theme, EXPANDED_ACTIONS_SHOWN));
+        }
+        return new Text(lines.join("\n"), 0, 0);
+    }
+    if (options.expanded) {
+        const container = new Container();
+        tasks.forEach((p, i) => {
+            if (i > 0)
+                container.addChild(new Spacer(1));
+            container.addChild(new Text(receiptLine(p, theme), 0, 0));
+            container.addChild(new Text(theme.fg("dim", `  ${clip(p.task, 2 * TASK_PREVIEW_MAX)}`), 0, 0));
+            if (p.errorMessage)
+                container.addChild(new Text(theme.fg("error", `  ${clip(p.errorMessage, 200)}`), 0, 0));
+            const log = actionLogLines(p, theme, EXPANDED_ACTIONS_SHOWN);
+            if (log.length > 0)
+                container.addChild(new Text(log.join("\n"), 0, 0));
+            const report = (p.report ?? "").trim();
+            if (report) {
+                container.addChild(new Spacer(1));
+                container.addChild(markdownOrPlain(report, theme));
+            }
+        });
+        if (tasks.length > 1) {
+            container.addChild(new Spacer(1));
+            container.addChild(new Text(totalLine(tasks, theme), 0, 0));
+        }
+        return container;
+    }
+    // Collapsed, final: receipts + a short report preview per task.
+    const lines = [];
+    let truncated = false;
+    for (const p of tasks) {
+        if (lines.length > 0)
+            lines.push("");
+        lines.push(receiptLine(p, theme));
+        if (p.errorMessage)
+            lines.push(theme.fg("error", `  ${clip(p.errorMessage, 160)}`));
+        const report = (p.report ?? "").trim();
+        if (report) {
+            const reportLines = report.split("\n");
+            for (const l of reportLines.slice(0, REPORT_PREVIEW_LINES)) {
+                lines.push(theme.fg("toolOutput", `  ${l}`));
+            }
+            if (reportLines.length > REPORT_PREVIEW_LINES)
+                truncated = true;
+        }
+        if (p.actions.length > 0)
+            truncated = true;
+    }
+    if (tasks.length > 1)
+        lines.push("", totalLine(tasks, theme));
+    if (truncated)
+        lines.push(theme.fg("muted", "  (ctrl+o to expand)"));
+    return new Text(lines.join("\n"), 0, 0);
+}
+//# sourceMappingURL=subagentRender.js.map

package/dist/extension/subagents.d.ts

@@ -20,10 +20,13 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { runStage } from "./pipeline/runner.js";
-import type { ModelTier, PipelineStage } from "./pipeline/types.js";
+import { type ModelTier, type PipelineStage } from "./pipeline/types.js";
+import { renderSubagentCall, renderSubagentResult } from "./subagentRender.js";
 export declare const SUBAGENT_TOOL_NAME = "subagent";
 export declare const GENERAL_AGENT_NAME = "general";
 export declare const MAX_PARALLEL_SUBAGENTS = 4;
+/** Wider fan-out ceiling while the session is in ultra mode (/ultra). */
+export declare const MAX_PARALLEL_SUBAGENTS_ULTRA = 8;
 /**
  * The default tool surface a subagent gets when its definition declares none:
  * the full working set plus grounded answers, mirroring what a Claude Code
@@ -91,6 +94,8 @@ export interface MakeSubagentToolDeps {
     runStageImpl?: typeof runStage;
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
+    isUltra?: () => boolean;
 }
 export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
     name: string;
@@ -105,6 +110,8 @@ export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
             agent: Type.TOptional<Type.TString>;
         }>>>;
     }>;
+    renderCall: typeof renderSubagentCall;
+    renderResult: typeof renderSubagentResult;
     execute(_toolCallId: string, params: SubagentParams, signal?: AbortSignal, onUpdate?: (update: {
         content: Array<{
             type: "text";
@@ -125,19 +132,15 @@ export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
             text: string;
         }[];
         details: {
-            tasks: {
-                agent: string;
-                task: string;
-                exitCode: number;
-                usage: import("./pipeline/types.js").StageUsage;
-                toolCalls: number;
-            }[];
+            tasks: import("./subagentRender.js").SubagentTaskProgress[];
         };
     }>;
 };
 export interface RegisterSubagentsDeps {
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
+    isUltra?: () => boolean;
 }
 /** Wire the subagent tool and the /agents listing command. */
 export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;