@jopqior/pi-subagents 1.0.0

package/src/ui/agent-widget.ts

@@ -0,0 +1,333 @@
+/**
+ * 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 { AgentTypeRegistry } from "#src/config/agent-types";
+import type { Subagent } from "#src/lifecycle/subagent";
+import type { SubagentManager, SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import type { CompactionInfo } from "#src/types";
+import { ERROR_STATUSES, type Theme } from "#src/ui/display";
+import { renderWidgetLines, type WidgetAgent } from "#src/ui/widget-renderer";
+
+// ---- Types ----
+
+/** Minimal agent shape needed for widget lifecycle decisions. */
+interface AgentSummary {
+  readonly id: string;
+  readonly status: string;
+  readonly completedAt?: number;
+}
+
+/** Lightweight state snapshot used by AgentWidget.update() to decide what to show. */
+export interface WidgetState {
+  readonly runningCount: number;
+  readonly queuedCount: number;
+  readonly hasFinished: boolean;
+  /** True when runningCount > 0 || queuedCount > 0. Included for call-site readability. */
+  readonly hasActive: boolean;
+}
+
+/**
+ * Count agents by status and return a lightweight state snapshot.
+ * Pure function — no IO, no side effects. Exported for direct unit testing.
+ */
+export function assembleWidgetState(
+  agents: readonly AgentSummary[],
+  shouldShowFinished: (agentId: string, status: string) => boolean,
+): WidgetState {
+  let runningCount = 0;
+  let queuedCount = 0;
+  let hasFinished = false;
+  for (const a of agents) {
+    if (a.status === "running") { runningCount++; }
+    else if (a.status === "queued") { queuedCount++; }
+    else if (a.completedAt && shouldShowFinished(a.id, a.status)) { hasFinished = true; }
+  }
+  const hasActive = runningCount > 0 || queuedCount > 0;
+  return { runningCount, queuedCount, hasFinished, hasActive };
+}
+
+/** The slice of the TUI the widget factory callback touches. */
+export interface TuiSurface {
+  readonly terminal: { readonly columns: number };
+  requestRender(): void;
+}
+
+export type UICtx = {
+  setStatus(key: string, text: string | undefined): void;
+  setWidget(
+    key: string,
+    content: undefined | ((tui: TuiSurface, theme: Theme) => { render(): string[]; invalidate(): void }),
+    options?: { placement?: "aboveEditor" | "belowEditor" },
+  ): void;
+};
+
+// ---- Widget manager ----
+
+export class AgentWidget implements SubagentManagerObserver {
+  private uiCtx: UICtx | undefined;
+  private widgetFrame = 0;
+  private widgetInterval: ReturnType<typeof setInterval> | undefined;
+  /** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
+  private finishedTurnAge = new Map<string, number>();
+  /** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+  private static readonly ERROR_LINGER_TURNS = 2;
+
+  /** Whether the widget callback is currently registered with the TUI. */
+  private widgetRegistered = false;
+  /** Cached TUI reference from widget factory callback, used for requestRender(). */
+  private tui: TuiSurface | undefined;
+  /** Last status bar text, used to avoid redundant setStatus calls. */
+  private lastStatusText: string | undefined;
+
+  constructor(
+    private manager: SubagentManager,
+    private registry: AgentTypeRegistry,
+  ) {}
+
+  /** Set the UI context (captured at session_start). */
+  setUICtx(ctx: UICtx) {
+    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 (turn_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();
+  }
+
+  // ---- SubagentManagerObserver: react to lifecycle, self-drive the timer ----
+
+  /** A subagent started running — ensure the update loop is live and render. */
+  onSubagentStarted(_record: Subagent) {
+    this.startLoop();
+  }
+
+  /** A background subagent was created (queued) — ensure the loop is live and render. */
+  onSubagentCreated(_record: Subagent) {
+    this.startLoop();
+  }
+
+  /** A subagent completed — render so the finished state is seeded and shown. */
+  onSubagentCompleted(_record: Subagent) {
+    this.update();
+  }
+
+  /**
+   * A subagent went back to running — ensure the loop is live and render.
+   * `startLoop` rather than `update`: the timer stops once nothing is running,
+   * and a resumed agent is running again.
+   */
+  onSubagentResuming(_record: Subagent) {
+    this.startLoop();
+  }
+
+  /** A subagent finished a resume — render so the refreshed result is shown. */
+  onSubagentResumed(_record: Subagent) {
+    this.update();
+  }
+
+  /** A subagent's session compacted — render to refresh the compaction count. */
+  onSubagentCompacted(_record: Subagent, _info: CompactionInfo) {
+    this.update();
+  }
+
+  /** Start the update timer (if not already running) and render immediately. */
+  private startLoop() {
+    this.ensureTimer();
+    this.update();
+  }
+
+  /** Ensure the widget update timer is running. */
+  private ensureTimer() {
+    this.widgetInterval ??= setInterval(() => this.update(), 80);
+  }
+
+  /** Check if a finished agent should still be shown in the widget. */
+  private shouldShowFinished(agentId: string, status: string): boolean {
+    const age = this.finishedTurnAge.get(agentId) ?? 0;
+    const maxAge = ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
+    return age < maxAge;
+  }
+
+  /**
+   * Background agents only — the widget's sole audience (ADR-0004 Decision A).
+   * Foreground runs are rendered by the `subagent` tool's inline `onUpdate` stream,
+   * so funneling both `listAgents()` call sites through this accessor applies the
+   * background predicate exactly once at the source.
+   *
+   * The predicate reads the record's own resolved mode. It formerly re-derived
+   * it from a per-call display snapshot only the tool door ever built — so every
+   * SDK-spawned agent was filtered out permanently (#724).
+   */
+  private listBackgroundAgents(): Subagent[] {
+    return this.manager.listAgents().filter(record => record.isBackground);
+  }
+
+  /** Project a live Subagent record onto a pure-data WidgetAgent snapshot. */
+  private toWidgetAgent(record: Subagent): WidgetAgent {
+    return {
+      id: record.id,
+      type: record.type,
+      status: record.status,
+      description: record.description,
+      toolUses: record.toolUses,
+      startedAt: record.startedAt,
+      completedAt: record.completedAt,
+      error: record.error,
+      lifetimeUsage: record.lifetimeUsage,
+      compactionCount: record.compactionCount,
+      turnCount: record.turnCount,
+      maxTurns: record.maxTurns,
+      activeTools: record.activeTools,
+      responseText: record.responseText,
+      awaitingSelection: record.awaitingSelection,
+      contextPercent: record.getContextPercent(),
+    };
+  }
+
+  /** Delegate rendering to the pure widget-renderer module. */
+  private renderWidget(tui: TuiSurface, theme: Theme): string[] {
+    return renderWidgetLines({
+      agents: this.listBackgroundAgents().map(r => this.toWidgetAgent(r)),
+      registry: this.registry,
+      spinnerFrame: this.widgetFrame,
+      terminalWidth: tui.terminal.columns,
+      theme,
+      shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
+    });
+  }
+
+  /**
+   * Unregister the widget, clear the status bar, stop the interval timer, and
+   * purge stale `finishedTurnAge` entries for agents no longer in `backgroundAgents`.
+   * Called only from `update`'s idle path — not from `dispose`.
+   */
+  private clearWidget(backgroundAgents: readonly AgentSummary[]): void {
+    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; }
+    for (const [id] of this.finishedTurnAge) {
+      if (!backgroundAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+    }
+  }
+
+  /**
+   * Compute the status bar text from the current widget state and call
+   * `setStatus` only when it differs from the last cached value.
+   */
+  private updateStatusBar(state: WidgetState): void {
+    let newStatusText: string | undefined;
+    if (state.hasActive) {
+      const statusParts: string[] = [];
+      if (state.runningCount > 0) statusParts.push(`${state.runningCount} running`);
+      if (state.queuedCount > 0) statusParts.push(`${state.queuedCount} queued`);
+      const total = state.runningCount + state.queuedCount;
+      newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
+    }
+    if (newStatusText !== this.lastStatusText) {
+      this.uiCtx!.setStatus("subagents", newStatusText);
+      this.lastStatusText = newStatusText;
+    }
+  }
+
+  /**
+   * Seed linger tracking for any newly-observed finished agent.
+   * The widget owns detection of completions it observes via `listAgents()`,
+   * so no external bookkeeping call is needed.
+   * Idempotent — only seeds when an entry is absent, so repeated updates within
+   * a turn neither reset nor advance the age.
+   */
+  private seedFinishedAgents(agents: readonly AgentSummary[]): void {
+    for (const a of agents) {
+      if (a.completedAt && !this.finishedTurnAge.has(a.id)) {
+        this.finishedTurnAge.set(a.id, 0);
+      }
+    }
+  }
+
+  /** Force an immediate widget update. */
+  update() {
+    if (!this.uiCtx) return;
+
+    const backgroundAgents = this.listBackgroundAgents();
+    this.seedFinishedAgents(backgroundAgents);
+    const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
+
+    if (!state.hasActive && !state.hasFinished) {
+      this.clearWidget(backgroundAgents);
+      return;
+    }
+
+    this.updateStatusBar(state);
+    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();
+    }
+  }
+
+  /**
+   * Release everything the widget acquired: the update interval and both
+   * registrations on the session's `UICtx`.
+   *
+   * Disposal is final. Dropping the `UICtx` makes `update()` return at its
+   * first line, so a notification arriving afterwards — the terminal transition
+   * an abort drives synchronously — cannot re-register what this released.
+   * `setUICtx()` re-arms the widget if a context ever arrives again.
+   */
+  dispose() {
+    if (this.widgetInterval) {
+      clearInterval(this.widgetInterval);
+      this.widgetInterval = undefined;
+    }
+    if (this.uiCtx) {
+      this.uiCtx.setWidget("agents", undefined);
+      this.uiCtx.setStatus("subagents", undefined);
+    }
+    this.uiCtx = undefined;
+    this.widgetRegistered = false;
+    this.tui = undefined;
+    this.lastStatusText = undefined;
+  }
+}

package/src/ui/bounded-lines.ts

@@ -0,0 +1,45 @@
+/**
+ * bounded-lines.ts — a TUI component that spends exactly one terminal row per line.
+ *
+ * Pi's `Text` word-wraps, so a single long line becomes as many rows as it needs
+ * and a line-count cap does not bound the height of a result. This component
+ * clips instead of wrapping, which makes the row count equal to the line count
+ * at every width — the bound `get_subagent_result` renders under (#636).
+ *
+ * Clipping is by display columns via pi-tui's `truncateToWidth`, so a wide glyph
+ * costs the two columns it actually occupies rather than the one code unit it
+ * is stored in.
+ *
+ * A line carrying its own line break is cut at the first one, because the terminal
+ * would otherwise spend a row on each segment and the bound would rest on every
+ * caller's care rather than on this component. Pi's own `TruncatedText` cuts at
+ * the first newline for the same reason.
+ */
+
+import type { Component } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+/** Renders pre-themed lines one-to-one onto terminal rows, clipped to the viewport. */
+export class BoundedLines implements Component {
+	constructor(private readonly lines: readonly string[]) {}
+
+	render(width: number): string[] {
+		return this.lines.map((line) => truncateToWidth(firstLineOf(line), width));
+	}
+
+	/** Required by `Component`; nothing is cached between renders, so there is nothing to discard. */
+	// fallow-ignore-next-line unused-class-member
+	invalidate(): void {}
+}
+
+/**
+ * The text up to the first line break of any flavour.
+ *
+ * Vertical tab and form feed count: a VT100-class terminal moves the cursor down
+ * a row for each exactly as it does for a line feed, and both are zero-width, so
+ * a width-based clip would pass them through to cost a row of their own.
+ */
+function firstLineOf(line: string): string {
+	const breakAt = line.search(/[\r\n\v\f]/);
+	return breakAt === -1 ? line : line.slice(0, breakAt);
+}

package/src/ui/display.ts

@@ -0,0 +1,180 @@
+/**
+ * display.ts — Pure formatting helpers and display utilities for agent UI.
+ *
+ * All functions are stateless and dependency-free (no SDK, no widget lifecycle).
+ * Consumed by the widget, the menu, tool modules, and the notification renderer.
+ */
+
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { AgentInvocation, SubagentType } from "#src/types";
+import { GLYPHS } from "#src/ui/glyphs";
+
+// ---- Types ----
+
+export type Theme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+/** Metadata attached to Agent tool results for custom rendering. */
+export interface AgentDetails {
+  displayName: string;
+  description: string;
+  subagentType: string;
+  toolUses: number;
+  tokens: string;
+  durationMs: number;
+  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+  /** Human-readable description of what the agent is currently doing. */
+  activity?: string;
+  /** Current spinner frame index (for animated running indicator). */
+  spinnerFrame?: number;
+  /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
+  modelName?: string;
+  /** Notable config tags (e.g. ["thinking: high", "inherit context"]). */
+  tags?: string[];
+  /** Current turn count. */
+  turnCount?: number;
+  /** Effective max turns (undefined = unlimited). */
+  maxTurns?: number;
+  agentId?: string;
+  error?: string;
+}
+
+// ---- Constants ----
+
+/** 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"]);
+
+/** Private pending-selection activity shown while public status stays `running`. */
+export const PENDING_SELECTION_ACTIVITY = "Awaiting model/thinking selection";
+
+/** Tool name → human-readable action for activity descriptions. */
+const TOOL_DISPLAY: Record<string, string> = {
+  read: "reading",
+  bash: "running command",
+  edit: "editing",
+  write: "writing",
+  grep: "searching",
+  find: "finding files",
+  ls: "listing",
+};
+
+// ---- Pure formatters ----
+
+/** Format a token count compactly: "33.8k token", "1.2M token". */
+export function formatTokens(count: number): string {
+  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 (see `glyphs.ts`).
+ *
+ *   "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: number,
+  percent: number | null,
+  theme: Theme,
+  compactions = 0,
+): string {
+  const tokenStr = formatTokens(tokens);
+  const annot: string[] = [];
+  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", `${GLYPHS.compactions}${compactions}`));
+  }
+  if (annot.length === 0) return tokenStr;
+  const sep = theme.fg("dim", " · ");
+  return `${tokenStr} ${theme.fg("dim", "(")}${annot.join(sep)}${theme.fg("dim", ")")}`;
+}
+
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
+export function formatTurns(turnCount: number, maxTurns?: number | null): string {
+  return maxTurns != null
+    ? `${GLYPHS.turns}${turnCount}≤${maxTurns}`
+    : `${GLYPHS.turns}${turnCount}`;
+}
+
+/** Format milliseconds as human-readable duration. */
+export function formatMs(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** Format duration from start/completed timestamps. */
+export function formatDuration(startedAt: number, completedAt?: number): string {
+  if (completedAt) return formatMs(completedAt - startedAt);
+  return `${formatMs(Date.now() - startedAt)} (running)`;
+}
+
+// ---- Display helpers ----
+
+/** Get display name for any agent type (built-in or custom). */
+export function getDisplayName(type: SubagentType, registry: AgentConfigLookup): string {
+  const config = registry.resolveAgentConfig(type);
+  return config.displayName ?? config.name;
+}
+
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export function getPromptModeLabel(type: SubagentType, registry: AgentConfigLookup): string | undefined {
+  const config = registry.resolveAgentConfig(type);
+  return config.promptMode === "append" ? "twin" : undefined;
+}
+
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(
+  invocation: AgentInvocation | undefined,
+): { modelName?: string; tags: string[] } {
+  const tags: string[] = [];
+  if (!invocation) return { tags };
+  if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
+  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: string, len = 60): string {
+  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: ReadonlyMap<string, string>, responseText?: string): string {
+  if (activeTools.size > 0) {
+    const groups = new Map<string, number>();
+    for (const toolName of activeTools.values()) {
+      const action = TOOL_DISPLAY[toolName] ?? toolName;
+      groups.set(action, (groups.get(action) ?? 0) + 1);
+    }
+
+    const parts: string[] = [];
+    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…";
+}

package/src/ui/glyphs.ts

@@ -0,0 +1,62 @@
+/**
+ * glyphs.ts — the semantic display-glyph vocabulary for the agent UI.
+ *
+ * Pi's TUI sizes each terminal cell with `get-east-asian-width`, which reports
+ * one cell for every glyph below. A glyph that no monospace font covers is
+ * therefore drawn by a proportional fallback font whose advance overruns that
+ * cell and collides with the next column — the defect in #669. East Asian Width
+ * does not detect this: the offending glyph and its replacement are both width 1.
+ *
+ * Before adding or changing a glyph, measure its monospace coverage:
+ *
+ *   fc-list ":charset=<codepoint>:spacing=100" family | cut -d, -f1 | sort -u | grep -v LastResort
+ *
+ * Coverage on macOS 15, counted in families:
+ *
+ *   ↻ U+21BB turns          1  (Menlo)
+ *   ⇊ U+21CA compactions    1  (Menlo)
+ *   ✓ U+2713 success        6
+ *   ✗ U+2717 failure        6
+ *   ▸ U+25B8 tool call      6
+ *   ■ U+25A0 stopped        9
+ *   ● U+25CF agents active  9
+ *   ○ U+25CB agents idle    9
+ *   ◦ U+25E6 queued         9
+ *   ⎿ U+23BF sub-line       0  — pi house style, tracked in #683
+ *   ◍ U+25CD streaming      1  (Menlo), tracked in #683
+ *   ⠋…⠏ spinner frames      0  — pi house style, tracked in #683
+ *
+ * Glyphs are written here as literal characters rather than `\uXXXX` escapes, so
+ * a non-ASCII scan of `src/` (`rg -n '[^\x00-\x7f]' src --glob '*.ts'`) surfaces
+ * this file plus only layout and punctuation. Box-drawing characters stay at
+ * their render sites: they are layout, not vocabulary.
+ */
+
+/** Semantic indicator glyphs rendered in the widget, inline results, and notifications. */
+export const GLYPHS = {
+  /** Turn count, as `↻5≤30`. */
+  turns: "↻",
+  /** Session compaction count, annotating the token field. */
+  compactions: "⇊",
+  /** Completed outcome, also used dim/warning for a wrapped-up agent. */
+  success: "✓",
+  /** Error or aborted outcome. */
+  failure: "✗",
+  /** Stopped outcome. */
+  stopped: "■",
+  /** Continuation line beneath a result or activity line. */
+  subLine: "⎿",
+  /** Inline tool-call heading marker. */
+  toolCall: "▸",
+  /** Live streaming activity in the session transcript. */
+  streaming: "◍",
+  /** Queued-agents marker in the widget. */
+  queued: "◦",
+  /** Widget heading while agents are active. */
+  agentsActive: "●",
+  /** Widget heading while no agents are active. */
+  agentsIdle: "○",
+} as const;
+
+/** Braille spinner frames for the animated running indicator. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];