@d3ara1n/pi-subagent 0.10.4 → 1.0.0

package/src/utils.ts

@@ -1,20 +1,33 @@
 /**
- * Pure helpers for pi-subagent: formatting, sanitization, and the concurrency
- * semaphore. No pi-API or I/O dependencies — safe to unit-test.
+ * Pure helpers for pi-subagent: formatting, sanitization, the concurrency
+ * semaphore, render-side timers, and notification throttling. No pi-API or
+ * I/O dependencies — safe to unit-test.
  */
 
 import * as os from "node:os";
 import type {
   ActivityEntry,
+  FallbackFrom,
+  RunState,
   SubagentDetails,
   SubagentRole,
   SubagentResult,
+  SubagentUsage,
   ToolStatus,
+  WaitDetails,
 } from "./types.ts";
 
 /** Max output chars fed to the main model and the expanded TUI. Larger outputs are compressed (or truncated) to fit. */
 export const MAX_OUTPUT_CHARS = 50_000;
 
+/** Coalesce bursty progress events so the TUI repaints at most this often. */
+export const PROGRESS_THROTTLE_MS = 50;
+
+/** A zeroed usage block — frames and synthesized failures start from this. */
+export function emptyUsage(): SubagentUsage {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
 export function formatTokens(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -22,16 +35,28 @@ export function formatTokens(count: number): string {
   return `${(count / 1000000).toFixed(1)}M`;
 }
 
-export function formatUsageStats(usage: SubagentResult["usage"], model?: string): string {
+/**
+ * Usage parts shared by the TUI stats line and the LLM usage footer.
+ * `withCache` adds the cache-read/write and peak-context figures (TUI only —
+ * the LLM footer stays lean).
+ */
+function usageParts(usage: SubagentUsage, model: string | undefined, withCache: boolean): string[] {
   const parts: string[] = [];
   if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
   if (usage.input) parts.push(`\u2191${formatTokens(usage.input)}`);
   if (usage.output) parts.push(`\u2193${formatTokens(usage.output)}`);
-  if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-  if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+  if (withCache) {
+    if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+    if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+    if (usage.contextTokens) parts.push(`ctx${formatTokens(usage.contextTokens)}`);
+  }
   if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
   if (model) parts.push(model);
-  return parts.join(" ");
+  return parts;
+}
+
+export function formatUsageStats(usage: SubagentUsage, model?: string): string {
+  return usageParts(usage, model, true).join(" ");
 }
 
 /**
@@ -57,6 +82,31 @@ export function elapsedSeconds(r: {
   return undefined;
 }
 
+/**
+ * Elapsed/budget time text for a frame: `42s/900s(+7s)` while budgeted (grace
+ * = time the child spent inside nested delegates, live-computed from an open
+ * pause), `42s` without a budget. null when no time is known (queued frames).
+ */
+export function formatTimePart(r: {
+  exitCode: number;
+  startTime?: number;
+  elapsedMs?: number;
+  budgetMs?: number;
+  graceMs?: number;
+  pauseStart?: number;
+}): string | null {
+  const secs = elapsedSeconds(r);
+  if (secs == null) return null;
+  const budgetSec = r.budgetMs ? Math.round(r.budgetMs / 1000) : 0;
+  const liveGraceMs = (r.graceMs ?? 0) + (r.pauseStart ? Date.now() - r.pauseStart : 0);
+  const graceSec = Math.round(liveGraceMs / 1000);
+  return budgetSec > 0
+    ? graceSec > 0
+      ? `${secs}s/${budgetSec}s(+${graceSec}s)`
+      : `${secs}s/${budgetSec}s`
+    : `${secs}s`;
+}
+
 export type DisplayItem =
   | { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
   | { type: "thinking"; status?: ToolStatus };
@@ -84,8 +134,9 @@ export function formatToolCall(
   fg: (color: string, text: string) => string,
 ): string {
   switch (toolName) {
-    case "delegate": {
+    case "subagent_delegate": {
       const subRole = args.role as string | undefined;
+      // Compact display label — the full tool name is subagent_delegate.
       return fg("muted", "delegate ") + fg("accent", subRole ?? "...");
     }
     case "bash": {
@@ -191,7 +242,127 @@ export function renderDisplayItems(
   return text.trimEnd();
 }
 
-export function isFailedResult(r: SubagentResult): boolean {
+// ── Shared result-view composition ─────────────────────────────
+// Used by the foreground delegate row (./render.ts) and the background
+// wait/check rows (./render-async.ts) so every view renders the same
+// outcome the same way.
+
+/** Plain-text fallback when details are missing (thrown errors, malformed results). */
+export function contentText(result: { content: Array<{ type: string; text?: string }> }): string {
+  const text = result.content[0];
+  return text?.type === "text" && text.text ? text.text : "(no output)";
+}
+
+/** First line of the task, truncated to one row (the always-visible anchor). */
+export function taskPreview(task: string): string {
+  const firstLine = task.split("\n")[0];
+  return firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
+}
+
+/** Status icon for a run frame: ⏸ queued / ⏳ running / ⏱ timeout / ⏲ budget / ✗ failed / ✓ ok */
+export function runIcon(
+  r: { exitCode: number; queued?: boolean; stopReason?: string },
+  fg: (color: string, text: string) => string,
+): string {
+  const state = deriveRunState(r);
+  if (state === "queued") return fg("warning", "\u23F8");
+  if (state === "running") return fg("warning", "\u23F3");
+  if (r.stopReason === "timeout") return fg("warning", "\u23F1");
+  if (r.stopReason === "budget_exceeded") return fg("warning", "\u23F2");
+  if (state === "failed") return fg("error", "\u2717");
+  return fg("success", "\u2713");
+}
+
+/** Failure result-line content: errorMessage → stop-reason label → "failed". */
+function failureResultText(r: {
+  errorMessage?: string;
+  stopReason?: string;
+}): { content: string; col: "warning" | "error" } {
+  const isTimeout = r.stopReason === "timeout";
+  const isBudget = r.stopReason === "budget_exceeded";
+  return {
+    content: r.errorMessage || (isTimeout ? "Timed out" : isBudget ? "Budget exceeded" : "failed"),
+    col: isTimeout || isBudget ? "warning" : "error",
+  };
+}
+
+/** Success result-line content: AI summary → output first line → placeholder. */
+function successResultText(r: {
+  summary?: string;
+  output: string;
+}): { content: string; col: "text" | "muted" } {
+  const firstLine = r.output.trim().split("\n")[0] ?? "";
+  const preview = firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
+  const content = r.summary || preview;
+  return { content: content || "(no output)", col: content ? "text" : "muted" };
+}
+
+/**
+ * Composed terminal result line `<icon> <content>`. Budget stops count as the
+ * failure presentation (their output is partial and the reason matters), even
+ * though the run state itself is "finished". `finishedText` (wait's
+ * "finished") replaces the success chain for status-only views.
+ */
+export function terminalResultLine(
+  r: {
+    exitCode: number;
+    queued?: boolean;
+    stopReason?: string;
+    errorMessage?: string;
+    summary?: string;
+    output: string;
+  },
+  fg: (color: string, text: string) => string,
+  finishedText?: string,
+): string {
+  const icon = runIcon(r, fg);
+  if (isFailedResult(r) || r.stopReason === "budget_exceeded") {
+    const t = failureResultText(r);
+    return `${icon} ${fg(t.col, t.content)}`;
+  }
+  if (finishedText !== undefined) return `${icon} ${fg("text", finishedText)}`;
+  const t = successResultText(r);
+  return `${icon} ${fg(t.col, t.content)}`;
+}
+
+// ── Render-side elapsed-time animation ─────────────────────────
+
+/** Per-row render state slot holding the elapsed-time animation timer. */
+interface ElapsedTimerState {
+  elapsedTimer?: ReturnType<typeof setInterval>;
+}
+
+/**
+ * While a run is live, force a TUI repaint every second so the elapsed time
+ * ticks up even when the child process is idle. Uses context.invalidate()
+ * (pi's official re-render hook) rather than pushing data via onUpdate — the
+ * render recomputes elapsed time fresh from Date.now().
+ */
+export function ensureElapsedTimer(context: {
+  state: Record<string, unknown>;
+  invalidate?: () => void;
+}): void {
+  const state = context.state as ElapsedTimerState;
+  if (state.elapsedTimer) return;
+  if (typeof context.invalidate !== "function") return;
+  state.elapsedTimer = setInterval(() => {
+    try {
+      context.invalidate?.();
+    } catch {
+      /* ignore — invalidate must never break rendering */
+    }
+  }, 1000);
+}
+
+/** Stop the elapsed-time animation once the run reaches a terminal state. */
+export function clearElapsedTimer(context: { state: Record<string, unknown> }): void {
+  const state = context.state as ElapsedTimerState;
+  if (!state.elapsedTimer) return;
+  clearInterval(state.elapsedTimer);
+  state.elapsedTimer = undefined;
+}
+
+export function isFailedResult(r: { exitCode: number; stopReason?: string }): boolean {
   return (
     r.exitCode !== 0 ||
     r.stopReason === "error" ||
@@ -205,12 +376,135 @@ export function hasFailedSubagentResult(details: unknown): boolean {
   return Array.isArray(d?.results) && d.results.some(isFailedResult);
 }
 
+/** Provider-error keywords that make a failed run worth retrying on the fallback role. */
+const PROVIDER_ERROR_RE =
+  /429|quota|rate.?limit|auth|timeout|exhausted|unavailable|503|server error|temporary|declined|overloaded|econnreset|socket hang up|epipe|network|connection/i;
+
 /** Heuristic: does this result look like a provider-side failure worth retrying on the fallback role? */
 export function isProviderError(result: SubagentResult): boolean {
-  const haystack = `${result.stderr || ""}\n${result.errorMessage || ""}`;
-  return /429|quota|rate.?limit|auth|timeout|exhausted|unavailable|503|server error|temporary|declined|overloaded|econnreset|socket hang up|epipe|network|connection/i.test(
-    haystack,
-  );
+  return PROVIDER_ERROR_RE.test(`${result.stderr || ""}\n${result.errorMessage || ""}`);
+}
+
+/** Cap for the stderr tail kept in fallback diagnostics. */
+export const FALLBACK_STDERR_TAIL = 400;
+
+const ANSI_ESCAPE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+
+/**
+ * Best-effort diagnosis from stderr when the child died before any message_end
+ * (e.g. 429 on the very first request — model/errorMessage/stopReason all unset).
+ * Returns the last stderr line mentioning a provider-error keyword: pi prints
+ * the fatal error near exit, so the last match is the most specific.
+ */
+export function extractProviderReason(text: string): string | undefined {
+  const lines = text
+    .replace(ANSI_ESCAPE, "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (PROVIDER_ERROR_RE.test(lines[i])) return lines[i];
+  }
+  return undefined;
+}
+
+/**
+ * Snapshot a failed first attempt for fallback observability.
+ * The fallback retry overwrites the result, so this snapshot is the only
+ * trace of why the first attempt died. stderr is noisy (TUI teardown
+ * escape sequences) — only a truncated tail is kept.
+ *
+ * `requestedModel` fills the model field when the child died before any
+ * message_end — the parent always knows what it asked for.
+ */
+export function buildFallbackFrom(first: SubagentResult, requestedModel?: string): FallbackFrom {
+  const tail = first.stderr.slice(-FALLBACK_STDERR_TAIL).trim();
+  return {
+    model: first.model ?? requestedModel,
+    stopReason: first.stopReason,
+    errorMessage: first.errorMessage || extractProviderReason(tail),
+    stderrTail: tail || undefined,
+  };
+}
+
+/**
+ * One-line human-readable fallback reason, e.g.
+ * `first attempt deepseek-v4-flash failed (Timed out after 900s)`.
+ * Prefer errorMessage; fall back to stopReason, else a generic label.
+ */
+export function formatFallback(f: FallbackFrom): string {
+  const reason = f.errorMessage || f.stopReason || "provider error";
+  const firstLine = reason.split("\n")[0];
+  const short = firstLine.length > 100 ? `${firstLine.slice(0, 100)}...` : firstLine;
+  return `first attempt ${f.model ?? "unknown model"} failed (${short})`;
+}
+
+// ── Background runs (delegate background:true / wait / check) ────────────
+
+/** Derive the lifecycle state of a run from one of its frames (live or terminal). */
+export function deriveRunState(r: { exitCode: number; queued?: boolean; stopReason?: string }): RunState {
+  if (r.exitCode === -1) return r.queued ? "queued" : "running";
+  return isFailedResult(r) ? "failed" : "finished";
+}
+
+/** True when wait tool result details carries the timeout flag. */
+export function isWaitTimedOut(details: unknown): boolean {
+  return (details as WaitDetails | undefined)?.timedOut === true;
+}
+
+/** Human-readable description of what a running subagent is doing right now (latest activity item). */
+export function describeCurrentActivity(r: { activityLog: ActivityEntry[] }): string {
+  const last = r.activityLog[r.activityLog.length - 1];
+  if (!last) return "waiting for first event";
+  if (last.kind === "thinking") return last.status === "running" ? "thinking" : "thought";
+  return formatToolCall(last.toolName ?? "?", last.args ?? {}, (_color, text) => text);
+}
+
+/** Footer appended to terminal results for the main model: `\n\n--- 3 turns ↑12k ↓1k $0.01 model ---` (empty when nothing to show). */
+export function formatUsageFooter(r: { usage: SubagentUsage; model?: string }): string {
+  const parts = usageParts(r.usage, r.model, false);
+  return parts.length > 0 ? `\n\n--- ${parts.join(" ")} ---` : "";
+}
+
+/** Fallback provenance note appended to terminal results (empty when no retry happened). */
+export function formatFallbackNote(r: { fallbackFrom?: FallbackFrom; model?: string }): string {
+  return r.fallbackFrom
+    ? `\n\n--- fallback: ${formatFallback(r.fallbackFrom)}; retried on ${r.model ?? "fallback role"} ---`
+    : "";
+}
+
+/**
+ * Budget-stop note appended to terminal results (empty unless the run was
+ * killed for exceeding its turn/cost budget). Budget stops are intentional
+ * successes, but the reader must know the output is partial.
+ */
+export function formatBudgetNote(r: { stopReason?: string; errorMessage?: string }): string {
+  return r.stopReason === "budget_exceeded"
+    ? `\n\n--- ${r.errorMessage || "Budget exceeded"} ---`
+    : "";
+}
+
+/** LLM-facing text returned by the check tool for one run snapshot. */
+export function formatCheckText(id: string, role: string, r: SubagentResult): string {
+  const state = deriveRunState(r);
+  const head = `${id} (${role})`;
+  if (state === "queued") return `${head}: queued — waiting for a concurrency slot.`;
+  if (state === "running") return `${head}: running — ${describeCurrentActivity(r)}`;
+  if (state === "failed") {
+    return `${head}: failed — ${r.errorMessage || r.stderr || "unknown error"}\n\nPartial output:\n${r.output}${formatFallbackNote(r)}`;
+  }
+  return `${head}: finished\n\n${r.output}${formatBudgetNote(r)}${formatFallbackNote(r)}${formatUsageFooter(r)}`;
+}
+
+/** Freeze a live frame into a static snapshot: stop the elapsed clock and fold the open pause into grace. */
+export function freezeFrame(r: SubagentResult): SubagentResult {
+  return {
+    ...r,
+    startTime: undefined,
+    elapsedMs: r.startTime ? Date.now() - r.startTime : r.elapsedMs,
+    graceMs: (r.graceMs ?? 0) + (r.pauseStart ? Date.now() - r.pauseStart : 0),
+    pauseStart: undefined,
+  };
 }
 
 /**
@@ -298,6 +592,36 @@ export class AsyncSemaphore {
   }
 }
 
+// ── Notification throttling ─────────────────────────────────────
+
+/**
+ * Coalesce bursty notifications into at most one `fire` per
+ * {@link PROGRESS_THROTTLE_MS}. `cancel()` drops any pending fire — call it
+ * when the owning tool call exits, so a stale update never fires afterwards.
+ */
+export function createThrottler(fire: () => void): { notify(): void; cancel(): void } {
+  let pending = false;
+  let handle: ReturnType<typeof setTimeout> | undefined;
+  return {
+    notify() {
+      pending = true;
+      if (handle !== undefined) return;
+      handle = setTimeout(() => {
+        handle = undefined;
+        if (pending) {
+          pending = false;
+          fire();
+        }
+      }, PROGRESS_THROTTLE_MS);
+    },
+    cancel() {
+      if (handle !== undefined) clearTimeout(handle);
+      handle = undefined;
+      pending = false;
+    },
+  };
+}
+
 // ── Timeout policy ────────────────────────────────────────
 
 /**