@gotgenes/pi-subagents 1.0.0

package/dist/ui/agent-widget.js

@@ -0,0 +1,451 @@
+/**
+ * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
+ *
+ * Displays a tree of agents with animated spinners, live stats, and activity descriptions.
+ * Uses the callback form of setWidget for themed rendering.
+ */
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { getConfig } from "../agent-types.js";
+import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
+// ---- Constants ----
+/** Maximum number of rendered lines before overflow collapse kicks in. */
+const MAX_WIDGET_LINES = 12;
+/** Braille spinner frames for animated running indicator. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
+export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+/** Tool name → human-readable action for activity descriptions. */
+const TOOL_DISPLAY = {
+    read: "reading",
+    bash: "running command",
+    edit: "editing",
+    write: "writing",
+    grep: "searching",
+    find: "finding files",
+    ls: "listing",
+};
+// ---- Formatting helpers ----
+/** Format a token count compactly: "33.8k token", "1.2M token". */
+export function formatTokens(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M token`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k token`;
+    return `${count} token`;
+}
+/**
+ * Token count with optional context-fill % and compaction-count annotations.
+ * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
+ * Compaction count rendered as `↻N` in dim.
+ *
+ *   "12.3k token"               — no annotations
+ *   "12.3k token (45%)"         — percent only
+ *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ↻2)"    — both
+ */
+export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
+    const tokenStr = formatTokens(tokens);
+    const annot = [];
+    if (percent !== null) {
+        const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
+        annot.push(theme.fg(color, `${Math.round(percent)}%`));
+    }
+    if (compactions > 0) {
+        annot.push(theme.fg("dim", `↻${compactions}`));
+    }
+    if (annot.length === 0)
+        return tokenStr;
+    return `${tokenStr} (${annot.join(" · ")})`;
+}
+/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+export function formatTurns(turnCount, maxTurns) {
+    return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+}
+/** Format milliseconds as human-readable duration. */
+export function formatMs(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+/** Format duration from start/completed timestamps. */
+export function formatDuration(startedAt, completedAt) {
+    if (completedAt)
+        return formatMs(completedAt - startedAt);
+    return `${formatMs(Date.now() - startedAt)} (running)`;
+}
+/** Get display name for any agent type (built-in or custom). */
+export function getDisplayName(type) {
+    return getConfig(type).displayName;
+}
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export function getPromptModeLabel(type) {
+    const config = getConfig(type);
+    return config.promptMode === "append" ? "twin" : undefined;
+}
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(invocation) {
+    const tags = [];
+    if (!invocation)
+        return { tags };
+    if (invocation.thinking)
+        tags.push(`thinking: ${invocation.thinking}`);
+    if (invocation.isolated)
+        tags.push("isolated");
+    if (invocation.isolation === "worktree")
+        tags.push("worktree");
+    if (invocation.inheritContext)
+        tags.push("inherit context");
+    if (invocation.runInBackground)
+        tags.push("background");
+    if (invocation.maxTurns != null)
+        tags.push(`max turns: ${invocation.maxTurns}`);
+    return { modelName: invocation.modelName, tags };
+}
+/** Truncate text to a single line, max `len` chars. */
+function truncateLine(text, len = 60) {
+    const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
+    if (line.length <= len)
+        return line;
+    return line.slice(0, len) + "…";
+}
+/** Build a human-readable activity string from currently-running tools or response text. */
+export function describeActivity(activeTools, responseText) {
+    if (activeTools.size > 0) {
+        const groups = new Map();
+        for (const toolName of activeTools.values()) {
+            const action = TOOL_DISPLAY[toolName] ?? toolName;
+            groups.set(action, (groups.get(action) ?? 0) + 1);
+        }
+        const parts = [];
+        for (const [action, count] of groups) {
+            if (count > 1) {
+                parts.push(`${action} ${count} ${action === "searching" ? "patterns" : "files"}`);
+            }
+            else {
+                parts.push(action);
+            }
+        }
+        return parts.join(", ") + "…";
+    }
+    // No tools active — show truncated response text if available
+    if (responseText && responseText.trim().length > 0) {
+        return truncateLine(responseText);
+    }
+    return "thinking…";
+}
+// ---- Widget manager ----
+export class AgentWidget {
+    manager;
+    agentActivity;
+    uiCtx;
+    widgetFrame = 0;
+    widgetInterval;
+    /** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
+    finishedTurnAge = new Map();
+    /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+    static ERROR_LINGER_TURNS = 2;
+    /** Whether the widget callback is currently registered with the TUI. */
+    widgetRegistered = false;
+    /** Cached TUI reference from widget factory callback, used for requestRender(). */
+    tui;
+    /** Last status bar text, used to avoid redundant setStatus calls. */
+    lastStatusText;
+    constructor(manager, agentActivity) {
+        this.manager = manager;
+        this.agentActivity = agentActivity;
+    }
+    /** Set the UI context (grabbed from first tool execution). */
+    setUICtx(ctx) {
+        if (ctx !== this.uiCtx) {
+            // UICtx changed — the widget registered on the old context is gone.
+            // Force re-registration on next update().
+            this.uiCtx = ctx;
+            this.widgetRegistered = false;
+            this.tui = undefined;
+            this.lastStatusText = undefined;
+        }
+    }
+    /**
+     * Called on each new turn (tool_execution_start).
+     * Ages finished agents and clears those that have lingered long enough.
+     */
+    onTurnStart() {
+        // Age all finished agents
+        for (const [id, age] of this.finishedTurnAge) {
+            this.finishedTurnAge.set(id, age + 1);
+        }
+        // Trigger a widget refresh (will filter out expired agents)
+        this.update();
+    }
+    /** Ensure the widget update timer is running. */
+    ensureTimer() {
+        if (!this.widgetInterval) {
+            this.widgetInterval = setInterval(() => this.update(), 80);
+        }
+    }
+    /** Check if a finished agent should still be shown in the widget. */
+    shouldShowFinished(agentId, status) {
+        const age = this.finishedTurnAge.get(agentId) ?? 0;
+        const maxAge = ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
+        return age < maxAge;
+    }
+    /** Record an agent as finished (call when agent completes). */
+    markFinished(agentId) {
+        if (!this.finishedTurnAge.has(agentId)) {
+            this.finishedTurnAge.set(agentId, 0);
+        }
+    }
+    /** Render a finished agent line. */
+    renderFinishedLine(a, theme) {
+        const name = getDisplayName(a.type);
+        const modeLabel = getPromptModeLabel(a.type);
+        const duration = formatMs((a.completedAt ?? Date.now()) - a.startedAt);
+        let icon;
+        let statusText;
+        if (a.status === "completed") {
+            icon = theme.fg("success", "✓");
+            statusText = "";
+        }
+        else if (a.status === "steered") {
+            icon = theme.fg("warning", "✓");
+            statusText = theme.fg("warning", " (turn limit)");
+        }
+        else if (a.status === "stopped") {
+            icon = theme.fg("dim", "■");
+            statusText = theme.fg("dim", " stopped");
+        }
+        else if (a.status === "error") {
+            icon = theme.fg("error", "✗");
+            const errMsg = a.error ? `: ${a.error.slice(0, 60)}` : "";
+            statusText = theme.fg("error", ` error${errMsg}`);
+        }
+        else {
+            // aborted
+            icon = theme.fg("error", "✗");
+            statusText = theme.fg("warning", " aborted");
+        }
+        const parts = [];
+        const activity = this.agentActivity.get(a.id);
+        if (activity)
+            parts.push(formatTurns(activity.turnCount, activity.maxTurns));
+        if (a.toolUses > 0)
+            parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+        parts.push(duration);
+        const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+        return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+    }
+    /**
+     * Render the widget content. Called from the registered widget's render() callback,
+     * reading live state each time instead of capturing it in a closure.
+     */
+    renderWidget(tui, theme) {
+        const allAgents = this.manager.listAgents();
+        const running = allAgents.filter(a => a.status === "running");
+        const queued = allAgents.filter(a => a.status === "queued");
+        const finished = allAgents.filter(a => a.status !== "running" && a.status !== "queued" && a.completedAt
+            && this.shouldShowFinished(a.id, a.status));
+        const hasActive = running.length > 0 || queued.length > 0;
+        const hasFinished = finished.length > 0;
+        // Nothing to show — return empty (widget will be unregistered by update())
+        if (!hasActive && !hasFinished)
+            return [];
+        const w = tui.terminal.columns;
+        const truncate = (line) => truncateToWidth(line, w);
+        const headingColor = hasActive ? "accent" : "dim";
+        const headingIcon = hasActive ? "●" : "○";
+        const frame = SPINNER[this.widgetFrame % SPINNER.length];
+        // Build sections separately for overflow-aware assembly.
+        // Each running agent = 2 lines (header + activity), finished = 1 line, queued = 1 line.
+        const finishedLines = [];
+        for (const a of finished) {
+            finishedLines.push(truncate(theme.fg("dim", "├─") + " " + this.renderFinishedLine(a, theme)));
+        }
+        const runningLines = []; // each entry is [header, activity]
+        for (const a of running) {
+            const name = getDisplayName(a.type);
+            const modeLabel = getPromptModeLabel(a.type);
+            const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+            const elapsed = formatMs(Date.now() - a.startedAt);
+            const bg = this.agentActivity.get(a.id);
+            const toolUses = bg?.toolUses ?? a.toolUses;
+            const tokens = getLifetimeTotal(bg?.lifetimeUsage);
+            const contextPercent = getSessionContextPercent(bg?.session);
+            const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, a.compactionCount) : "";
+            const parts = [];
+            if (bg)
+                parts.push(formatTurns(bg.turnCount, bg.maxTurns));
+            if (toolUses > 0)
+                parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
+            if (tokenText)
+                parts.push(tokenText);
+            parts.push(elapsed);
+            const statsText = parts.join(" · ");
+            const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : "thinking…";
+            runningLines.push([
+                truncate(theme.fg("dim", "├─") + ` ${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", a.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`),
+                truncate(theme.fg("dim", "│  ") + theme.fg("dim", `  ⎿  ${activity}`)),
+            ]);
+        }
+        const queuedLine = queued.length > 0
+            ? truncate(theme.fg("dim", "├─") + ` ${theme.fg("muted", "◦")} ${theme.fg("dim", `${queued.length} queued`)}`)
+            : undefined;
+        // Assemble with overflow cap (heading + overflow indicator = 2 reserved lines).
+        const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
+        const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+        const lines = [truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"))];
+        if (totalBody <= maxBody) {
+            // Everything fits — add all lines and fix up connectors for the last item.
+            lines.push(...finishedLines);
+            for (const pair of runningLines)
+                lines.push(...pair);
+            if (queuedLine)
+                lines.push(queuedLine);
+            // Fix last connector: swap ├─ → └─ and │ → space for activity lines.
+            if (lines.length > 1) {
+                const last = lines.length - 1;
+                lines[last] = lines[last].replace("├─", "└─");
+                // If last item is a running agent activity line, fix indent of that line
+                // and fix the header line above it.
+                if (runningLines.length > 0 && !queuedLine) {
+                    // The last two lines are the last running agent's header + activity.
+                    if (last >= 2) {
+                        lines[last - 1] = lines[last - 1].replace("├─", "└─");
+                        lines[last] = lines[last].replace("│  ", "   ");
+                    }
+                }
+            }
+        }
+        else {
+            // Overflow — prioritize: running > queued > finished.
+            // Reserve 1 line for overflow indicator.
+            let budget = maxBody - 1;
+            let hiddenRunning = 0;
+            let hiddenFinished = 0;
+            // 1. Running agents (2 lines each)
+            for (const pair of runningLines) {
+                if (budget >= 2) {
+                    lines.push(...pair);
+                    budget -= 2;
+                }
+                else {
+                    hiddenRunning++;
+                }
+            }
+            // 2. Queued line
+            if (queuedLine && budget >= 1) {
+                lines.push(queuedLine);
+                budget--;
+            }
+            // 3. Finished agents
+            for (const fl of finishedLines) {
+                if (budget >= 1) {
+                    lines.push(fl);
+                    budget--;
+                }
+                else {
+                    hiddenFinished++;
+                }
+            }
+            // Overflow summary
+            const overflowParts = [];
+            if (hiddenRunning > 0)
+                overflowParts.push(`${hiddenRunning} running`);
+            if (hiddenFinished > 0)
+                overflowParts.push(`${hiddenFinished} finished`);
+            const overflowText = overflowParts.join(", ");
+            lines.push(truncate(theme.fg("dim", "└─") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`));
+        }
+        return lines;
+    }
+    /** Force an immediate widget update. */
+    update() {
+        if (!this.uiCtx)
+            return;
+        const allAgents = this.manager.listAgents();
+        // Lightweight existence checks — full categorization happens in renderWidget()
+        let runningCount = 0;
+        let queuedCount = 0;
+        let hasFinished = false;
+        for (const a of allAgents) {
+            if (a.status === "running") {
+                runningCount++;
+            }
+            else if (a.status === "queued") {
+                queuedCount++;
+            }
+            else if (a.completedAt && this.shouldShowFinished(a.id, a.status)) {
+                hasFinished = true;
+            }
+        }
+        const hasActive = runningCount > 0 || queuedCount > 0;
+        // Nothing to show — clear widget
+        if (!hasActive && !hasFinished) {
+            if (this.widgetRegistered) {
+                this.uiCtx.setWidget("agents", undefined);
+                this.widgetRegistered = false;
+                this.tui = undefined;
+            }
+            if (this.lastStatusText !== undefined) {
+                this.uiCtx.setStatus("subagents", undefined);
+                this.lastStatusText = undefined;
+            }
+            if (this.widgetInterval) {
+                clearInterval(this.widgetInterval);
+                this.widgetInterval = undefined;
+            }
+            // Clean up stale entries
+            for (const [id] of this.finishedTurnAge) {
+                if (!allAgents.some(a => a.id === id))
+                    this.finishedTurnAge.delete(id);
+            }
+            return;
+        }
+        // Status bar — only call setStatus when the text actually changes
+        let newStatusText;
+        if (hasActive) {
+            const statusParts = [];
+            if (runningCount > 0)
+                statusParts.push(`${runningCount} running`);
+            if (queuedCount > 0)
+                statusParts.push(`${queuedCount} queued`);
+            const total = runningCount + queuedCount;
+            newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
+        }
+        if (newStatusText !== this.lastStatusText) {
+            this.uiCtx.setStatus("subagents", newStatusText);
+            this.lastStatusText = newStatusText;
+        }
+        this.widgetFrame++;
+        // Register widget callback once; subsequent updates use requestRender()
+        // which re-invokes render() without replacing the component (avoids layout thrashing).
+        if (!this.widgetRegistered) {
+            this.uiCtx.setWidget("agents", (tui, theme) => {
+                this.tui = tui;
+                return {
+                    render: () => this.renderWidget(tui, theme),
+                    invalidate: () => {
+                        // Theme changed — force re-registration so factory captures fresh theme.
+                        this.widgetRegistered = false;
+                        this.tui = undefined;
+                    },
+                };
+            }, { placement: "aboveEditor" });
+            this.widgetRegistered = true;
+        }
+        else {
+            // Widget already registered — just request a re-render of existing components.
+            this.tui?.requestRender();
+        }
+    }
+    dispose() {
+        if (this.widgetInterval) {
+            clearInterval(this.widgetInterval);
+            this.widgetInterval = undefined;
+        }
+        if (this.uiCtx) {
+            this.uiCtx.setWidget("agents", undefined);
+            this.uiCtx.setStatus("subagents", undefined);
+        }
+        this.widgetRegistered = false;
+        this.tui = undefined;
+        this.lastStatusText = undefined;
+    }
+}

package/dist/ui/conversation-viewer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * conversation-viewer.ts — Live conversation overlay for viewing agent sessions.
+ *
+ * Displays a scrollable, live-updating view of an agent's conversation.
+ * Subscribes to session events for real-time streaming updates.
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type Component, type TUI } from "@earendil-works/pi-tui";
+import type { AgentRecord } from "../types.js";
+import type { Theme } from "./agent-widget.js";
+import { type AgentActivity } from "./agent-widget.js";
+/** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
+export declare const VIEWPORT_HEIGHT_PCT = 70;
+export declare class ConversationViewer implements Component {
+    private tui;
+    private session;
+    private record;
+    private activity;
+    private theme;
+    private done;
+    private scrollOffset;
+    private autoScroll;
+    private unsubscribe;
+    private lastInnerW;
+    private closed;
+    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void);
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+    dispose(): void;
+    private viewportHeight;
+    private chromeLines;
+    private invocationLine;
+    private buildContentLines;
+}