@esso0428/pi-subagents 0.17.5 → 0.17.7

package/src/ui/workflow-card.ts

@@ -0,0 +1,470 @@
+/**
+ * workflow-card.ts — the inline transcript card for a running workflow.
+ *
+ * ```
+ * ▸ Workflow  review-changes                       3/7 agents · 1m12s
+ *   Review changed files across dimensions, verify each finding
+ *   ╭─ Review
+ *   │ ├─ ✔ review:bugs      · Explore · haiku · 18.4k · 12 tool calls · 42s
+ *   │ ├─ ⟳ review:perf      · Explore · 8 tool calls · 21s
+ *   │ └─ ⟳ review:security
+ *   ╰─ Verify
+ *     └─ ⟳ verify:auth.ts   · Plan · 3 tool calls · 9s
+ *   ⎿  scanned 41 changed files
+ * ```
+ *
+ * Two things about this file are easy to get wrong.
+ *
+ * **The glyphs are not the dialog's glyphs.** The inline row keys off the *raw*
+ * entry `state` (start | progress | done | error), not the derived display
+ * state, so a skipped or blocked agent renders as a plain ✘ here while the
+ * workflows dialog distinguishes them. `displayState` is deliberately not
+ * consulted below.
+ *
+ * **The layout is pure.** `layoutWorkflowCard` returns coloured segments and
+ * never touches a theme or a terminal, so the same layout drives the `Workflow`
+ * tool's `renderResult` and a standalone session entry (a workflow launched from
+ * a CLI flag has no tool call to attach to). Theme application is the thin
+ * `styleWorkflowCardLines` wrapper on top.
+ *
+ * All state derivation lives in `src/workflow/progress.ts`; this file only
+ * arranges what that module returns.
+ */
+
+import { stripTerminalSequences, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { WorkflowEntryData } from "../workflow/entry.js";
+import type { WorkflowMeta } from "../workflow/meta.js";
+import {
+  buildPhaseGroups,
+  collapse,
+  formatDuration,
+  header,
+  sizeWarning,
+  stats,
+  type WorkflowAgentEntry,
+  type WorkflowEntry,
+  type WorkflowRunStatus,
+} from "../workflow/progress.js";
+import type { Theme } from "./agent-widget.js";
+
+/**
+ * Header re-render cadence. Claude Code ticks the workflow clock once a second,
+ * not at the 80ms spinner cadence — the running glyph is static, so there is
+ * nothing to animate faster than the elapsed time changes.
+ */
+export const WORKFLOW_TICK_MS = 1000;
+
+/** Widest label column before stats stop being aligned and just follow the label. */
+const LABEL_COLUMN_MAX = 28;
+
+/** Fallback width when the caller does not know the terminal's. */
+const DEFAULT_WIDTH = 80;
+
+/* ------------------------------------------------------------------------- *
+ * Glyphs
+ * ------------------------------------------------------------------------- */
+
+export interface WorkflowGlyphs {
+  /** Tool-title pointer, matching the Agent tool's `▸`. */
+  pointer: string;
+  tick: string;
+  cross: string;
+  /** Running/queued. A static glyph, hence no spinner inline. */
+  running: string;
+  /** First and subsequent phase groups. */
+  groupTop: string;
+  /** A group that is neither the first nor the last. */
+  groupMid: string;
+  /** The last phase group. */
+  groupBottom: string;
+  /** Continuation rail under a non-final group. */
+  vertical: string;
+  branch: string;
+  lastBranch: string;
+  /** Log-line prefix, matching the Agent tool's result lines. */
+  log: string;
+  warning: string;
+}
+
+export const UNICODE_GLYPHS: WorkflowGlyphs = {
+  pointer: "▸",
+  tick: "✔",
+  cross: "✘",
+  running: "⟳",
+  groupTop: "╭─",
+  groupMid: "├─",
+  groupBottom: "╰─",
+  vertical: "│",
+  branch: "├─",
+  lastBranch: "└─",
+  log: "⎿",
+  warning: "⚠",
+};
+
+/**
+ * The `figures` ASCII tier, for terminals that cannot draw the box set. Every
+ * glyph keeps its unicode counterpart's column width so the tree stays aligned
+ * either way.
+ */
+export const ASCII_GLYPHS: WorkflowGlyphs = {
+  pointer: ">",
+  tick: "√",
+  cross: "×",
+  running: "*",
+  groupTop: ",-",
+  groupMid: "|-",
+  groupBottom: "`-",
+  vertical: "|",
+  branch: "|-",
+  lastBranch: "`-",
+  log: "\\",
+  warning: "!",
+};
+
+/* ------------------------------------------------------------------------- *
+ * Lines
+ * ------------------------------------------------------------------------- */
+
+/**
+ * pi theme keys. Claude Code's palette maps as success→success, error→error,
+ * subtle→dim, permission→warning for a blocked row and accent for selection;
+ * an undefined colour means "leave it at the terminal default", which is what
+ * the recovered inline mapping asks for on a running row.
+ *
+ * `accent` is unused by the card and exists for the workflows dialog, which
+ * shares these segment types.
+ */
+export type WorkflowCardColor = "success" | "error" | "warning" | "dim" | "muted" | "toolTitle" | "accent";
+
+export interface WorkflowCardSegment {
+  text: string;
+  color?: WorkflowCardColor;
+  bold?: boolean;
+}
+
+export type WorkflowCardLine = WorkflowCardSegment[];
+
+/** The subset of the task record the card reads. */
+export interface WorkflowCardTask {
+  status: WorkflowRunStatus;
+  workflowName?: string;
+  summary?: string;
+  description?: string;
+  startTime: number;
+  endTime?: number;
+  totalPausedMs?: number;
+}
+
+export interface WorkflowCardInput {
+  progress: readonly WorkflowEntry[];
+  task: WorkflowCardTask;
+  meta?: WorkflowMeta;
+  /** Agents the runtime has scheduled, which can exceed those that have reported. */
+  agentCount?: number;
+  /** Total tokens for the size warning; summed from the entries when omitted. */
+  totalTokens?: number;
+  agentCap?: number;
+  tokenCap?: number;
+  now?: number;
+  width?: number;
+  /** Swap in the ASCII glyph tier for terminals without unicode. */
+  ascii?: boolean;
+  /**
+   * Lead with `▸ SubagentWorkflow`.
+   *
+   * True where the card stands alone — the session entry a flag-launched run
+   * writes, which has no tool call above it to say what it is. False as a tool
+   * result, where the call line directly above already does.
+   */
+  showToolTitle?: boolean;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Formatting
+ * ------------------------------------------------------------------------- */
+
+/** `18.4k` / `1.2M` — bare magnitude, since the row already reads as a stat. */
+export function formatCompactTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+  return `${count}`;
+}
+
+/**
+ * One label for the model pair. A fallback that never differed from the primary
+ * would just be noise, so it only shows when the run actually has two models in
+ * play.
+ */
+export function formatModel(
+  entry: WorkflowAgentEntry,
+  opts?: { canonical?: boolean },
+): string | undefined {
+  const { fallbackModel, requestedModel } = entry;
+  // `canonical` is for surfaces with the width for `provider/model-id`; the
+  // tight rows take the short label. Chosen here rather than by the caller
+  // swapping fields, which would leave `fallbackModel` in the other spelling.
+  const model = opts?.canonical ? entry.modelId ?? entry.model : entry.model;
+  const primary = model && fallbackModel && model !== fallbackModel ? `${model}→${fallbackModel}` : model ?? fallbackModel;
+  if (primary === undefined) return undefined;
+  // Disclosed rather than substituted: a model an agent file pinned over the
+  // script's is still a model the script did not get (#182). Same rule as
+  // `buildInvocationTags`' `asked()` — only when the two actually differ, so a
+  // request that was honoured says nothing.
+  return requestedModel !== undefined && requestedModel !== primary
+    ? `${primary} (asked ${requestedModel})`
+    : primary;
+}
+
+/**
+ * The thinking level, and what was asked for when it was not honoured.
+ *
+ * Separate from {@link formatModel} because a row can have one without the
+ * other: an `agent()` that named no model still runs at some level, and a level
+ * pi clamped is worth saying so about even when the model is unremarkable.
+ */
+export function formatThinking(entry: WorkflowAgentEntry): string | undefined {
+  const { thinking, requestedThinking } = entry;
+  if (!thinking) return undefined;
+  return requestedThinking !== undefined && requestedThinking !== thinking
+    ? `thinking: ${thinking} (asked ${requestedThinking})`
+    : `thinking: ${thinking}`;
+}
+
+/**
+ * What a row replayed from a resume journal says instead of a duration.
+ *
+ * Shared with the dialog so both views name the same thing the same way — the
+ * card shows it inline while the run happens, the dialog on the agent's row.
+ */
+export const REPLAYED_ANNOTATION = "from resume journal";
+
+/**
+ * The `·`-separated tail of an agent row, in the recovered order: agentType,
+ * model, tokens, toolCalls, durationMs. Absent values drop out entirely rather
+ * than rendering a placeholder.
+ */
+export function agentStatSegments(entry: WorkflowAgentEntry): string[] {
+  const parts: string[] = [];
+  if (entry.agentType) parts.push(entry.agentType);
+  const model = formatModel(entry);
+  if (model) parts.push(model);
+  if (entry.tokens) parts.push(formatCompactTokens(entry.tokens));
+  if (entry.toolCalls) parts.push(`${entry.toolCalls} tool call${entry.toolCalls === 1 ? "" : "s"}`);
+  if (entry.durationMs) parts.push(formatDuration(entry.durationMs));
+  return parts;
+}
+
+/**
+ * The recovered inline mapping — keyed on the raw entry state. `skipped` and
+ * `blocked` are not distinguished here; that is the dialog's job.
+ */
+function rowGlyph(entry: WorkflowAgentEntry, glyphs: WorkflowGlyphs): WorkflowCardSegment {
+  if (entry.state === "done") return { text: glyphs.tick, color: "success" };
+  if (entry.state === "error") return { text: glyphs.cross, color: "error" };
+  return { text: glyphs.running };
+}
+
+/* ------------------------------------------------------------------------- *
+ * Layout
+ * ------------------------------------------------------------------------- */
+
+/** Trim a line to `width`, cutting inside whichever segment crosses the edge. */
+export function clampLine(line: WorkflowCardLine, width: number): WorkflowCardLine {
+  const clamped: WorkflowCardLine = [];
+  let used = 0;
+  for (const segment of line) {
+    const segmentWidth = visibleWidth(segment.text);
+    if (used + segmentWidth <= width) {
+      clamped.push(segment);
+      used += segmentWidth;
+      continue;
+    }
+    const room = width - used;
+    // truncateToWidth wraps its ellipsis in resets, which would leak escape
+    // codes into a layout that is supposed to be plain text until it is themed.
+    if (room > 0) {
+      clamped.push({ ...segment, text: stripTerminalSequences(truncateToWidth(segment.text, room, "…")) });
+    }
+    return clamped;
+  }
+  return clamped;
+}
+
+const lineWidth = (line: WorkflowCardLine) => line.reduce((sum, s) => sum + visibleWidth(s.text), 0);
+
+/**
+ * Build the card.
+ *
+ * Everything derived — the phase tree, the header counts, the logs, the size
+ * warning — comes from `progress.ts`; what happens here is purely arrangement.
+ */
+export function layoutWorkflowCard(input: WorkflowCardInput): WorkflowCardLine[] {
+  const glyphs = input.ascii ? ASCII_GLYPHS : UNICODE_GLYPHS;
+  const width = Math.max(1, input.width ?? DEFAULT_WIDTH);
+  const now = input.now ?? Date.now();
+
+  const groups = buildPhaseGroups(input.progress, input.meta?.phases);
+  const { agents, logs } = collapse(input.progress);
+  const totals = stats(input.progress, input.agentCount ?? 0);
+  const head = header(input.task, input.meta, groups, input.agentCount ?? 0, now);
+
+  const lines: WorkflowCardLine[] = [];
+
+  // ---- Header: `<name>` with the stats flush right ----
+  // The tool name appears only when nothing above the card already carries it.
+  // As a tool result there is a `▸ SubagentWorkflow …` call line directly above,
+  // and repeating it put two near-identical pointer lines back to back.
+  const left: WorkflowCardLine = input.showToolTitle
+    ? [
+        { text: `${glyphs.pointer} `, color: "toolTitle" },
+        { text: "SubagentWorkflow", color: "toolTitle", bold: true },
+        { text: "  " },
+        { text: head.name, color: "muted" },
+      ]
+    : [{ text: "  " }, { text: head.name, color: "toolTitle", bold: true }];
+  const statsWidth = visibleWidth(head.stats);
+  const clampedLeft = clampLine(left, Math.max(0, width - statsWidth - 1));
+  const gap = Math.max(1, width - lineWidth(clampedLeft) - statsWidth);
+  lines.push([...clampedLeft, { text: " ".repeat(gap) }, { text: head.stats, color: "dim" }]);
+
+  if (head.subtext) lines.push(clampLine([{ text: `  ${head.subtext}`, color: "dim" }], width));
+
+  // ---- Phase tree ----
+  // Stats line up in one column across the whole card, not per group, so the
+  // eye can scan them; a label past the cap just pushes its own stats along.
+  const labelColumn = Math.min(
+    LABEL_COLUMN_MAX,
+    Math.max(0, ...groups.flatMap(group => group.agents.map(a => visibleWidth(a.label)))),
+  );
+
+  groups.forEach((group, groupIndex) => {
+    const lastGroup = groupIndex === groups.length - 1;
+    lines.push(
+      clampLine(
+        [
+          { text: "  " },
+          // One box, not a stack of them: only the first group opens it and
+          // only the last closes it. Everything between branches off the side,
+          // or three phases read as three half-drawn boxes.
+          {
+            text: `${
+              lastGroup ? glyphs.groupBottom
+              : groupIndex === 0 ? glyphs.groupTop
+              : glyphs.groupMid
+            } `,
+            color: "dim",
+          },
+          { text: group.title },
+        ],
+        width,
+      ),
+    );
+
+    const rail = lastGroup ? "  " : `${glyphs.vertical} `;
+    group.agents.forEach((entry, agentIndex) => {
+      const lastAgent = agentIndex === group.agents.length - 1;
+      const segments: WorkflowCardLine = [
+        { text: "  " },
+        { text: rail, color: "dim" },
+        { text: `${lastAgent ? glyphs.lastBranch : glyphs.branch} `, color: "dim" },
+        rowGlyph(entry, glyphs),
+        { text: " " },
+      ];
+
+      // Prepended rather than folded into `agentStatSegments`, which is the
+      // ported stat tail in its recovered order. A replayed agent otherwise
+      // renders as a tick with no tokens and no duration — indistinguishable
+      // from one that somehow did the work for free.
+      const statParts = entry.cached
+        ? [REPLAYED_ANNOTATION, ...agentStatSegments(entry)]
+        : agentStatSegments(entry);
+      const pad = Math.max(0, labelColumn - visibleWidth(entry.label));
+      segments.push({ text: statParts.length > 0 ? entry.label + " ".repeat(pad) : entry.label });
+      for (const part of statParts) {
+        segments.push({ text: " · ", color: "dim" }, { text: part, color: "dim" });
+      }
+      lines.push(clampLine(segments, width));
+    });
+  });
+
+  // ---- log() output, below the tree ----
+  for (const message of logs) {
+    const [first, ...rest] = message.split("\n");
+    lines.push(clampLine([{ text: `  ${glyphs.log}  ${first}`, color: "dim" }], width));
+    for (const continuation of rest) {
+      lines.push(clampLine([{ text: `     ${continuation}`, color: "dim" }], width));
+    }
+  }
+
+  // ---- Size warning ----
+  const totalTokens =
+    input.totalTokens ?? agents.reduce((sum, entry) => sum + (entry.tokens ?? 0), 0);
+  const warning = sizeWarning({
+    scheduledAgents: Math.max(input.agentCount ?? 0, totals.total),
+    startedAgents: totals.started,
+    totalTokens,
+    agentCap: input.agentCap,
+    tokenCap: input.tokenCap,
+  });
+  if (warning) {
+    lines.push(
+      clampLine([{ text: `  ${glyphs.warning} Large workflow · /agents → Workflows to stop`, color: "warning" }], width),
+    );
+  }
+
+  return lines;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Rendering
+ * ------------------------------------------------------------------------- */
+
+/** The card as plain text — what the layout tests assert against. */
+export function plainWorkflowCardLines(lines: readonly WorkflowCardLine[]): string[] {
+  return lines.map(line => line.map(segment => segment.text).join(""));
+}
+
+/** Apply the theme. Nothing here changes the layout, only its colours. */
+export function styleWorkflowCardLines(lines: readonly WorkflowCardLine[], theme: Theme): string[] {
+  return lines.map(line =>
+    line
+      .map(segment => {
+        const text = segment.bold ? theme.bold(segment.text) : segment.text;
+        return segment.color ? theme.fg(segment.color, text) : text;
+      })
+      .join(""),
+  );
+}
+
+/** The card as a component, for a tool result or a session entry renderer. */
+export function renderWorkflowCard(input: WorkflowCardInput, theme: Theme): Text {
+  return new Text(styleWorkflowCardLines(layoutWorkflowCard(input), theme).join("\n"), 0, 0);
+}
+
+/**
+ * The card for a session entry, from the JSON a flag-launched run persisted.
+ *
+ * The same layout the tool result uses, not a second one — the only difference
+ * is `showToolTitle`, because a session entry stands alone and nothing above it
+ * says what it is. Returns undefined for an entry with no data, which is what
+ * pi's renderer contract wants for "nothing to draw".
+ */
+export function renderWorkflowEntryCard(data: WorkflowEntryData | undefined, theme: Theme): Text | undefined {
+  if (!data) return undefined;
+  return renderWorkflowCard(
+    {
+      progress: data.progress,
+      task: {
+        status: data.status,
+        workflowName: data.name,
+        startTime: data.startTime,
+        endTime: data.endTime,
+      },
+      meta: data.meta,
+      agentCount: data.agentCount,
+      totalTokens: data.totalTokens,
+      showToolTitle: true,
+    },
+    theme,
+  );
+}