pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-picker.ts

@@ -0,0 +1,48 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { SelectList, visibleWidth, type Component, type SelectItem, type SelectListTheme } from "@earendil-works/pi-tui";
+import { dot, fit, keyHints } from "./kit.ts";
+
+const MAX_VISIBLE = 10;
+const NAME_GAP = 2;
+
+/**
+ * The `/workflow` picker: pi's own `SelectList` (so names and descriptions align like the slash
+ * autocomplete) under a title, with key hints below, between two rules like pi's native selectors.
+ * Items without a description (the author option) render as a full-width label.
+ */
+export class WorkflowPicker implements Component {
+  private readonly list: SelectList;
+
+  constructor(
+    private readonly items: readonly SelectItem[],
+    private readonly theme: Theme,
+    listTheme: SelectListTheme,
+    done: (value: string | undefined) => void,
+  ) {
+    const nameWidth = Math.max(0, ...items.filter((item) => item.description).map((item) => visibleWidth(item.label))) + NAME_GAP;
+    this.list = new SelectList([...items], Math.min(MAX_VISIBLE, items.length), listTheme, {
+      minPrimaryColumnWidth: nameWidth,
+      maxPrimaryColumnWidth: nameWidth,
+    });
+    this.list.onSelect = (item) => done(item.value);
+    this.list.onCancel = () => done(undefined);
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+
+  render(width: number): string[] {
+    const inner = Math.max(1, width - 2);
+    const rule = this.theme.fg("border", "─".repeat(Math.max(1, width)));
+    const count = this.items.filter((item) => item.description).length;
+    const title = `${this.theme.fg("accent", this.theme.bold("Run a workflow"))}${dot(this.theme)}${this.theme.fg("muted", `${count} available`)}`;
+    const hints = keyHints([["↑↓", "move"], ["enter", "run"], ["esc", "cancel"]], this.theme);
+    const pad = (line: string) => ` ${fit(line, inner)} `;
+    return [rule, pad(title), "", ...this.list.render(inner).map(pad), "", pad(hints), rule];
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-result-renderer.ts

@@ -1,168 +1,281 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Box, type Component, Text } from "@earendil-works/pi-tui";
+import { Box, truncateToWidth, type Component } from "@earendil-works/pi-tui";
 import { isAdvisoryReport, type AdvisoryReportWithStats } from "../advisory-schema.ts";
-import { renderIssueDetails, renderIssuesTable } from "../review/review-format.ts";
-import { toReviewIssues } from "../review/review-issues.ts";
-import { formatCount } from "./workflow-format.ts";
-import { formatWorkflowUsageLine } from "../usage.ts";
-import type { WorkflowPerfDetails, WorkflowResultEnvelope } from "../workflow-execution.ts";
-import { unknownErrorMessage } from "../unknown-error.ts";
-
-export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
+import { isRecord } from "../guards.ts";
+import { findingPathColumn, renderFindingDetail, renderFindingRow, sortIssuesForDisplay } from "../review/review-format.ts";
+import { toReviewIssues, type ReviewIssue } from "../review/review-issues.ts";
+import { formatCount, prettyJson } from "../text.ts";
+import { workflowResultSummary } from "../workflow-execution.ts";
+import { GLYPH, joinParts, severityColor, type Severity } from "./kit.ts";
+import { isResearchReport, renderResearchResult } from "./research-result-renderer.ts";
+import {
+  agentCount,
+  bullets,
+  clips,
+  footerLine,
+  headerLine,
+  indent,
+  innerWidth,
+  labelled,
+  LinesComponent,
+  paragraph,
+  plural,
+  runDetailRows,
+  type HintPair,
+  type ResultFrame,
+  type WorkflowResultHints,
+  type WorkflowResultView,
+} from "./result-layout.ts";
+
+export type { WorkflowResultHints, WorkflowResultView } from "./result-layout.ts";
+
+const COLLAPSED_SUMMARY_LINES = 2;
+const COLLAPSED_GENERIC_LINES = 3;
+const COLLAPSED_FINDINGS = 6;
+
+/** Recognises persisted result-envelope details by the fields every envelope carries. */
+export function isWorkflowResult(value: unknown): value is WorkflowResultView {
   if (!isRecord(value)) return false;
   return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
 }
 
-export interface WorkflowRunDisplayMetadata {
-  readonly runId?: string;
-  readonly resumedFromRunId?: string;
+/** The `workflow-result` message: the result on pi's custom-message background. */
+export function renderWorkflowResult(view: WorkflowResultView, expanded: boolean, theme: Theme, hints: WorkflowResultHints = {}): Component {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(workflowResultComponent(view, expanded, theme, hints));
+  return box;
 }
 
-export interface WorkflowDetailLineInput {
-  readonly usage?: unknown;
-  readonly perf?: WorkflowPerfDetails;
-  readonly metadata?: WorkflowRunDisplayMetadata;
+/** The bare result, for surfaces that already provide a shell (the workflow tool row). */
+export function workflowResultComponent(view: WorkflowResultView, expanded: boolean, theme: Theme, hints: WorkflowResultHints = {}): Component {
+  return new LinesComponent((width) => renderWorkflowResultLines(view, expanded, width, theme, hints));
 }
 
-export function renderWorkflowResult(
-  name: string,
-  result: unknown,
+export function renderWorkflowResultLines(
+  view: WorkflowResultView,
   expanded: boolean,
+  width: number,
   theme: Theme,
-  usage?: unknown,
-  metadata?: WorkflowRunDisplayMetadata,
-  perf?: WorkflowPerfDetails,
-): Component {
-  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
-  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage, metadata, perf), 0, 0));
-  return box;
+  hints: WorkflowResultHints = {},
+): string[] {
+  const frame: ResultFrame = { view, expanded, width, theme, hints };
+  const lines = view.background === true && isInterruptedState(view.status) ? renderInterruptedRun(frame, view.status)
+    : isAdvisoryReport(view.result) ? renderAdvisoryResult(frame, view.result)
+    : isResearchReport(view.result) ? renderResearchResult(frame, view.result)
+    : renderGenericResult(frame);
+  return lines.map((line) => truncateToWidth(line, width, "…"));
 }
 
-export function renderWorkflowResultText(
-  name: string,
-  result: unknown,
-  expanded: boolean,
-  theme: Theme,
-  usage?: unknown,
-  metadata?: WorkflowRunDisplayMetadata,
-  perf?: WorkflowPerfDetails,
-): string {
-  if (isAdvisoryReport(result)) {
-    return renderAdvisoryResult(name, result, expanded, theme, usage, metadata, perf);
+function renderAdvisoryResult(frame: ResultFrame, report: AdvisoryReportWithStats): string[] {
+  const { view, expanded, theme, hints } = frame;
+  const width = innerWidth(frame);
+  const issues = sortIssuesForDisplay(toReviewIssues(report));
+  const incomplete = report.status === "incomplete";
+  const failures = incompleteStages(report.coverage ?? []);
+  const [findings, ...severities] = findingFacts(issues, incomplete, theme);
+  const facts = [
+    incomplete ? theme.fg("warning", "incomplete") : undefined,
+    ...failures.map((failure) => theme.fg("warning", failure)),
+    findings,
+  ];
+  const glyph = incomplete ? theme.fg("warning", GLYPH.warning) : theme.fg("success", GLYPH.done);
+  const lines = [headerLine(glyph, frame, facts, severities)];
+  // An incomplete report's summary restates the header ("Incomplete review: n branch(es) failed…"); show it expanded only.
+  if (expanded || !incomplete) {
+    lines.push(...indent(paragraph(report.summary, width, (line) => theme.fg("text", line), expanded ? undefined : COLLAPSED_SUMMARY_LINES)));
   }
-  return renderGenericWorkflowResult(name, result, expanded, theme, usage, metadata, perf);
-}
+  const gaps = report.gaps ?? [];
+  if (!expanded && gaps.length > 0) lines.push(...indent([gapLine(gaps, theme)]));
 
-function renderAdvisoryResult(
-  name: string,
-  result: AdvisoryReportWithStats,
-  expanded: boolean,
-  theme: Theme,
-  usage?: unknown,
-  metadata?: WorkflowRunDisplayMetadata,
-  perf?: WorkflowPerfDetails,
-): string {
-  const icon = theme.fg("success", "✓");
-  const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
-  const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
-  const stats = statsLine(result.stats, theme);
-  if (stats) lines.push(stats);
-  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
-
-  if (result.findings.length === 0) {
-    lines.push(theme.fg("success", "No findings."));
-    if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
-    return lines.join("\n");
+  if (issues.length > 0) {
+    lines.push("");
+    if (expanded) {
+      issues.forEach((issue, index) => {
+        if (index > 0) lines.push("");
+        lines.push(...indent(renderFindingDetail(issue, width, theme)));
+      });
+    } else {
+      const shown = issues.slice(0, COLLAPSED_FINDINGS);
+      const column = findingPathColumn(shown);
+      lines.push(...indent(shown.map((issue) => renderFindingRow(issue, width, theme, column))));
+      const hidden = issues.length - COLLAPSED_FINDINGS;
+      if (hidden > 0) lines.push(...indent([theme.fg("dim", `+${plural(hidden, "more finding", "more findings")}`)]));
+    }
   }
 
-  const issues = toReviewIssues(name, result);
-  lines.push(theme.fg("dim", "Findings:"));
-  lines.push(renderIssuesTable(issues, theme, { maxRows: expanded ? issues.length : 12 }));
   if (expanded) {
-    for (const issue of issues) {
-      lines.push(renderIssueDetails(issue, theme));
-    }
+    const rows = [
+      ...labelled(frame, "Coverage", coverageItems(report, theme)),
+      ...labelled(frame, "Gaps", gaps.map((gap) => theme.fg("warning", `${GLYPH.failed} ${gap}`)), "  "),
+      ...labelled(frame, "Funnel", funnelItems(report.stats, theme)),
+      ...labelled(frame, "Follow-up", bullets(report.nextSteps), "  "),
+      ...runDetailRows(frame),
+    ];
+    if (rows.length > 0) lines.push("", ...rows);
   }
-  if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
-  return lines.join("\n");
-}
 
-function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): void {
-  lines.push(theme.fg("dim", "Next steps:"));
-  for (const step of nextSteps) {
-    lines.push(`  - ${theme.fg("muted", step)}`);
-  }
+  const pairs: HintPair[] = hints.triage && view.name === "code-review" && issues.length > 0 ? [[hints.triage, "triage"]] : [];
+  const footer = footerLine(frame, pairs, { more: true });
+  if (footer) lines.push(footer);
+  return lines;
 }
 
-function renderGenericWorkflowResult(
-  name: string,
-  result: unknown,
-  expanded: boolean,
-  theme: Theme,
-  usage?: unknown,
-  metadata?: WorkflowRunDisplayMetadata,
-  perf?: WorkflowPerfDetails,
-): string {
-  const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
-  const summary = extractSummary(result);
-  if (summary) lines.push(theme.fg("muted", summary));
-  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
-  if (expanded) lines.push(theme.fg("dim", safeJson(result)));
-  else if (!summary) lines.push(theme.fg("dim", "Result available in expanded view."));
-  return lines.join("\n");
-}
-
-function pushWorkflowDetailLines(lines: string[], theme: Theme, input: WorkflowDetailLineInput): void {
-  for (const line of formatWorkflowDetailLines(input)) {
-    lines.push(theme.fg("dim", line));
-  }
+/** `3 findings · 1 high · 1 medium`, zero severities hidden; `no findings` when the report is clean. */
+function findingFacts(issues: readonly ReviewIssue[], incomplete: boolean, theme: Theme): string[] {
+  if (issues.length === 0) return [theme.fg(incomplete ? "warning" : "success", incomplete ? "no verified findings" : "no findings")];
+  const severities: Severity[] = ["high", "medium", "low"];
+  return [
+    theme.fg("text", plural(issues.length, "finding")),
+    ...severities.flatMap((severity) => {
+      const count = issues.filter((issue) => issue.finding.severity === severity).length;
+      return count > 0 ? [theme.fg(severityColor(severity), `${count} ${severity}`)] : [];
+    }),
+  ];
 }
 
-export function formatWorkflowDetailLines(input: WorkflowDetailLineInput): string[] {
-  return [
-    formatWorkflowRunLine(input.metadata),
-    formatWorkflowUsageLine(input.usage),
-    formatWorkflowPerfLine(input.perf),
-  ].filter((line): line is string => line !== undefined);
+type AdvisoryCoverage = NonNullable<AdvisoryReportWithStats["coverage"]>[number];
+
+const STAGE_AGENTS: Readonly<Record<string, string>> = { Find: "finders", Verify: "verifiers", Challenge: "challengers" };
+
+/** `1 of 5 finders failed`, `Synthesize failed`: one phrase per stage that lost work. */
+function incompleteStages(coverage: readonly AdvisoryCoverage[]): string[] {
+  return coverage.flatMap((stage) => {
+    const missing = stage.failed > 0 ? stage.failed : stage.expected - stage.completed;
+    if (missing <= 0) return [];
+    const outcome = stage.failed > 0 ? "failed" : "missing";
+    if (stage.expected <= 1) return [`${stage.stage} ${outcome}`];
+    return [`${missing} of ${stage.expected} ${STAGE_AGENTS[stage.stage] ?? `${stage.stage} branches`} ${outcome}`];
+  });
 }
 
-export function formatWorkflowRunLine(metadata: WorkflowRunDisplayMetadata | undefined): string | undefined {
-  if (!metadata?.runId) return undefined;
-  return metadata.resumedFromRunId ? `Run: ${metadata.runId} (resumed from ${metadata.resumedFromRunId})` : `Run: ${metadata.runId}`;
+/** The first coverage gap, with a count of the rest: `✗ Find/error-paths: provider failed · +1 more`. */
+function gapLine(gaps: readonly string[], theme: Theme): string {
+  const more = gaps.length > 1 ? theme.fg("dim", ` · +${gaps.length - 1} more`) : "";
+  return `${theme.fg("error", GLYPH.failed)} ${theme.fg("warning", gaps[0] ?? "")}${more}`;
 }
 
-export function formatWorkflowPerfLine(perf: WorkflowPerfDetails | undefined): string | undefined {
-  if (!perf) return undefined;
-  const parts = perf.aggregates.slice(0, 4).map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
-  return parts.length > 0 ? `Perf: ${parts.join(" · ")}` : "Perf: no samples";
+/** `9 of 10 branches complete · Find 4 of 5`: totals, then only the stages that lost work. */
+function coverageItems(report: AdvisoryReportWithStats, theme: Theme): string[] {
+  const coverage = report.coverage ?? [];
+  if (coverage.length === 0) return [];
+  const expected = coverage.reduce((sum, stage) => sum + stage.expected, 0);
+  const completed = coverage.reduce((sum, stage) => sum + stage.completed, 0);
+  const lossy = coverage
+    .filter((stage) => stage.completed < stage.expected)
+    .map((stage) => theme.fg("warning", `${stage.stage} ${stage.completed} of ${stage.expected}${stage.failed > 0 ? ` (${stage.failed} failed)` : ""}`));
+  return [joinParts([theme.fg(lossy.length > 0 ? "warning" : "muted", `${completed} of ${plural(expected, "branch", "branches")} complete`), ...lossy], theme)];
 }
 
-function statsLine(stats: Record<string, string | number> | undefined, theme: Theme): string | undefined {
-  if (!stats) return undefined;
-  const ordered = ["files", "candidates", "dropped", "verified", "kept"];
-  const parts = ordered.flatMap((key) => {
+const FUNNEL_STAGES: readonly (readonly [key: string, singular: string, pluralLabel: string])[] = [
+  ["files", "file", "files"],
+  ["candidates", "candidate", "candidates"],
+  ["verified", "verified", "verified"],
+  ["kept", "kept", "kept"],
+];
+
+/** `3 files → 3 candidates → 3 verified → 3 kept · 1 refuted`, zero side counts hidden. */
+function funnelItems(stats: AdvisoryReportWithStats["stats"], theme: Theme): string[] {
+  if (!stats) return [];
+  const known = new Set(FUNNEL_STAGES.map(([key]) => key));
+  const stages = FUNNEL_STAGES.flatMap(([key, singular, pluralLabel]) => {
     const value = stats[key];
     if (value === undefined) return [];
-    return [`${key} ${typeof value === "number" ? formatCount(value) : value}`];
+    return [typeof value === "number" ? `${formatCount(value)} ${value === 1 ? singular : pluralLabel}` : `${value} ${pluralLabel}`];
   });
-  if (parts.length === 0) return undefined;
-  return theme.fg("dim", parts.join(" · "));
+  const extras = Object.entries(stats).flatMap(([key, value]) => {
+    if (known.has(key) || value === 0 || value === "") return [];
+    return [`${typeof value === "number" ? formatCount(value) : value} ${key}`];
+  });
+  const funnel = stages.join(theme.fg("dim", ` ${GLYPH.arrow} `));
+  const line = joinParts([funnel ? theme.fg("muted", funnel) : undefined, ...extras.map((extra) => theme.fg("muted", extra))], theme);
+  return line ? [line] : [];
+}
+
+function renderGenericResult(frame: ResultFrame): string[] {
+  const { view, expanded, theme } = frame;
+  const width = innerWidth(frame);
+  const summary = workflowResultSummary(view.result);
+  const legacyBackground = view.background === true;
+  const agents = agentCount(view);
+  const facts = [theme.fg("success", "done"), agents > 0 ? theme.fg("muted", plural(agents, "agent")) : undefined];
+  const lines = [headerLine(theme.fg("success", GLYPH.done), frame, facts)];
+
+  const json = resultJson(view.result, summary !== undefined);
+  let more = json !== undefined;
+  if (summary) {
+    const style = (line: string) => theme.fg("text", line);
+    lines.push(...indent(paragraph(summary, width, style, expanded ? undefined : COLLAPSED_GENERIC_LINES)));
+    more ||= clips(summary, width, COLLAPSED_GENERIC_LINES);
+  } else if (!expanded) {
+    lines.push(...indent([theme.fg("dim", resultShape(view.result))]));
+  }
+  if (expanded && json !== undefined) {
+    if (summary) lines.push("");
+    lines.push(...indent(jsonLines(json, width, theme)));
+  }
+  if (expanded) {
+    const rows = runDetailRows(frame, { agents: false });
+    if (rows.length > 0) lines.push("", ...rows);
+  }
+
+  const pairs: HintPair[] = legacyBackground ? [["/workflow:runs", "run history"]] : [];
+  const footer = footerLine(frame, pairs, { more: more || Boolean(view.runId) });
+  if (footer) lines.push(footer);
+  return lines;
 }
 
-function extractSummary(value: unknown): string | undefined {
-  if (typeof value === "string") return value;
-  if (isRecord(value) && typeof value.summary === "string") return value.summary;
-  return undefined;
+/** The result as pretty JSON, minus the summary already shown above it; undefined when nothing is left. */
+function resultJson(result: unknown, summaryShown: boolean): string | undefined {
+  if (typeof result === "string") return undefined;
+  if (!summaryShown || !isRecord(result)) return prettyJson(result);
+  const rest = Object.entries(result).filter(([key]) => key !== "summary");
+  return rest.length > 0 ? prettyJson(Object.fromEntries(rest)) : undefined;
 }
 
-function safeJson(value: unknown): string {
-  try {
-    return JSON.stringify(value, null, 2) ?? String(value);
-  } catch (error) {
-    return unknownErrorMessage(error);
+/** What a summary-less result holds: `result · areas, risks, notes` or `result · 12 items`. */
+function resultShape(result: unknown): string {
+  if (result === undefined || result === null) return "no result";
+  if (Array.isArray(result)) return `result · ${plural(result.length, "item")}`;
+  if (isRecord(result)) {
+    const keys = Object.keys(result);
+    return keys.length === 0 ? "empty result" : `result · ${keys.join(", ")}`;
   }
+  return `result · ${String(result)}`;
+}
+
+/** Pretty JSON, each long line wrapped under its own indentation. */
+function jsonLines(json: string, width: number, theme: Theme): string[] {
+  return json.split("\n").flatMap((line) => {
+    const depth = line.length - line.trimStart().length;
+    const lead = " ".repeat(depth);
+    return paragraph(line.trimStart(), Math.max(8, width - depth - 2), (part) => part).map((part, index) =>
+      theme.fg("dim", `${index === 0 ? lead : `${lead}  `}${part}`));
+  });
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+type InterruptedState = "failed" | "stopped" | "paused";
+
+function isInterruptedState(status: unknown): status is InterruptedState {
+  return status === "failed" || status === "stopped" || status === "paused";
+}
+
+/** A background run that ended without a result: what happened, and where to resume it. */
+function renderInterruptedRun(frame: ResultFrame, status: InterruptedState): string[] {
+  const { view, expanded, theme } = frame;
+  const color = status === "failed" ? "error" : "warning";
+  const glyph = theme.fg(color, status === "failed" ? GLYPH.failed : GLYPH.warning);
+  const lines = [headerLine(glyph, frame, [theme.fg(color, status)])];
+  const summary = workflowResultSummary(view.result);
+  if (summary) {
+    lines.push(...indent(paragraph(summary, innerWidth(frame), (line) => theme.fg("muted", line), expanded ? undefined : COLLAPSED_GENERIC_LINES)));
+  }
+  if (expanded) {
+    const rows = runDetailRows(frame);
+    if (rows.length > 0) lines.push("", ...rows);
+  }
+  const footer = footerLine(frame, [["/workflow:runs", status === "failed" ? "resume or restart" : "resume"]], {
+    more: Boolean(view.runId) || (summary !== undefined && clips(summary, innerWidth(frame), COLLAPSED_GENERIC_LINES)),
+  });
+  if (footer) lines.push(footer);
+  return lines;
 }