pi-workflow-engine 0.11.0 → 0.13.0

package/.pi/extensions/pi-workflow-engine/src/ui/workflow-viewer-layout.ts

@@ -0,0 +1,51 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+const VIEWPORT_HEIGHT_RATIO = 0.8;
+const VIEWPORT_MARGIN_ROWS = 2;
+
+export const WORKFLOW_VIEWER_OVERLAY_OPTIONS = {
+  overlay: true,
+  overlayOptions: {
+    anchor: "center",
+    width: "80%",
+    minWidth: 40,
+    maxHeight: "80%",
+    margin: 1,
+  },
+} as const;
+
+export function workflowViewerHeight(terminalRows: number): number {
+  const rows = Math.max(1, terminalRows);
+  const availableRows = Math.max(1, rows - VIEWPORT_MARGIN_ROWS);
+  const proportionalRows = Math.floor(rows * VIEWPORT_HEIGHT_RATIO);
+  return Math.min(availableRows, Math.max(3, proportionalRows));
+}
+
+export function fitWorkflowViewerRow(text: string, width: number): string {
+  return truncateToWidth(text, Math.max(0, width), "...", true);
+}
+
+export function fitWorkflowViewerRows(lines: readonly string[], height: number): string[] {
+  const visible = lines.slice(0, Math.max(0, height));
+  return [...visible, ...Array.from({ length: Math.max(0, height - visible.length) }, () => "")];
+}
+
+interface WorkflowViewerViewport<T> {
+  readonly visible: readonly T[];
+  readonly percentage: number;
+}
+
+export function centerWorkflowViewerViewport<T>(
+  rows: readonly T[],
+  height: number,
+  selectedIndex: number,
+): WorkflowViewerViewport<T> {
+  const visibleHeight = Math.max(0, Math.floor(height));
+  const clampedSelection = Math.min(Math.max(0, rows.length - 1), Math.max(0, selectedIndex));
+  const maxStart = Math.max(0, rows.length - visibleHeight);
+  const start = Math.min(maxStart, Math.max(0, clampedSelection - Math.floor(visibleHeight / 2)));
+  const visible = rows.slice(start, start + visibleHeight);
+  const end = Math.min(rows.length, start + visible.length);
+  const percentage = rows.length <= visibleHeight ? 100 : Math.round((end / rows.length) * 100);
+  return { visible, percentage };
+}

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

@@ -1,31 +1,18 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress.ts";
-import { agentDetailParts, agentLabelColor, formatCount, formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
+import type { AgentRowSnapshot, PhaseSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
+import { agentDetailParts, agentLabelColor, formatCount, formatDuration, statusIcon } from "./workflow-format.ts";
 
-const MAX_WIDGET_LINES = 12;
-const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-export interface WorkflowWidget {
-  nextFrame(): void;
-  render(width: number, theme: Theme): string[];
-  invalidate(): void;
-}
-
-export function createWorkflowWidget(snapshotProvider: () => WorkflowProgressSnapshot): WorkflowWidget {
-  return new LiveWorkflowWidget(snapshotProvider);
-}
+const MAX_WIDGET_LINES = 10;
 
 export function renderWorkflowWidgetLines(
   snapshot: WorkflowProgressSnapshot,
-  frame: number,
-  width: number,
   theme: Theme,
 ): string[] {
-  const safeWidth = Math.max(1, width);
   const counts = countAgents(snapshot.phases);
   const active = counts.running + counts.queued;
   const elapsed = formatDuration((snapshot.doneAt ?? Date.now()) - snapshot.startedAt);
-  const spinner = active > 0 ? theme.fg("accent", SPINNER[frame % SPINNER.length]) : theme.fg("success", "✓");
+  const activity = active > 0 ? theme.fg("accent", "●") : theme.fg("success", "✓");
 
   const headingParts = [`${counts.done}/${counts.total} done`, elapsed];
   if (counts.running > 0) headingParts.unshift(`${counts.running} running`);
@@ -33,10 +20,7 @@ export function renderWorkflowWidgetLines(
   if (counts.failed > 0) headingParts.unshift(theme.fg("error", `${counts.failed} failed`));
 
   const lines: string[] = [
-    truncateDisplay(
-      `${spinner} ${theme.bold(snapshot.title)} ${theme.fg("dim", "·")} ${theme.fg("muted", snapshot.currentPhase)} ${theme.fg("dim", "·")} ${headingParts.join(` ${theme.fg("dim", "·")} `)}`,
-      safeWidth,
-    ),
+    `${activity} ${theme.bold(snapshot.title)} ${theme.fg("dim", "·")} ${theme.fg("muted", snapshot.currentPhase)} ${theme.fg("dim", "·")} ${headingParts.join(` ${theme.fg("dim", "·")} `)}`,
   ];
 
   const footer = footerLine(snapshot, theme);
@@ -46,53 +30,13 @@ export function renderWorkflowWidgetLines(
   const visibleBodyLinesToRender = reserveHiddenLine ? body.lines.slice(0, Math.max(0, bodyBudget - 1)) : body.lines;
   const hidden = body.hidden + (body.lines.length - visibleBodyLinesToRender.length);
 
-  for (const line of visibleBodyLinesToRender) lines.push(truncateDisplay(line, safeWidth));
+  lines.push(...visibleBodyLinesToRender);
   if (hidden > 0 && lines.length < MAX_WIDGET_LINES) {
-    lines.push(truncateDisplay(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden} more`)}`, safeWidth));
+    lines.push(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden} more`)}`);
   }
-  if (footer && lines.length < MAX_WIDGET_LINES) lines.push(truncateDisplay(footer, safeWidth));
-
-  return lines.slice(0, MAX_WIDGET_LINES).map((line) => truncateDisplay(line, safeWidth));
-}
-
-class LiveWorkflowWidget implements WorkflowWidget {
-  private frame = 0;
-  private cachedWidth: number | undefined;
-  private cachedFrame: number | undefined;
-  private cachedDoneAt: number | undefined;
-  private cachedLines: string[] | undefined;
-
-  constructor(private readonly snapshotProvider: () => WorkflowProgressSnapshot) {}
+  if (footer && lines.length < MAX_WIDGET_LINES) lines.push(footer);
 
-  nextFrame(): void {
-    this.frame = (this.frame + 1) % SPINNER.length;
-    this.invalidate();
-  }
-
-  render(width: number, theme: Theme): string[] {
-    const snapshot = this.snapshotProvider();
-    if (
-      this.cachedLines &&
-      this.cachedWidth === width &&
-      this.cachedFrame === this.frame &&
-      this.cachedDoneAt === snapshot.doneAt
-    ) {
-      return this.cachedLines;
-    }
-
-    this.cachedLines = renderWorkflowWidgetLines(snapshot, this.frame, width, theme);
-    this.cachedWidth = width;
-    this.cachedFrame = this.frame;
-    this.cachedDoneAt = snapshot.doneAt;
-    return this.cachedLines;
-  }
-
-  invalidate(): void {
-    this.cachedWidth = undefined;
-    this.cachedFrame = undefined;
-    this.cachedDoneAt = undefined;
-    this.cachedLines = undefined;
-  }
+  return lines.slice(0, MAX_WIDGET_LINES);
 }
 
 interface AgentCounts {
@@ -173,9 +117,10 @@ function agentLine(agent: AgentRowSnapshot, theme: Theme): string {
 }
 
 function footerLine(snapshot: WorkflowProgressSnapshot, theme: Theme): string | undefined {
+  const usage = formatWorkflowUsageLine(snapshot.usage);
   const counters = snapshot.counters.slice(0, 4).map((counter) => `${counter.label} ${formatCount(counter.value)}`);
   const latestLog = snapshot.logs[snapshot.logs.length - 1];
-  const parts = counters.length > 0 ? counters : [];
+  const parts = usage ? [usage, ...counters] : counters;
   if (latestLog) parts.push(latestLog);
   if (parts.length === 0) return undefined;
   return `${theme.fg("dim", "└─")} ${theme.fg("dim", parts.join(" · "))}`;

package/.pi/extensions/pi-workflow-engine/src/usage.ts

@@ -6,12 +6,22 @@ export interface WorkflowUsageCost {
   readonly total: number;
 }
 
+export type WorkflowUsageCoverage = "none" | "partial" | "complete";
+
+export interface WorkflowUsageComponentCoverage {
+  readonly input: WorkflowUsageCoverage;
+  readonly output: WorkflowUsageCoverage;
+  readonly cacheRead: WorkflowUsageCoverage;
+  readonly cacheWrite: WorkflowUsageCoverage;
+}
+
 export interface WorkflowUsageTotals {
   readonly input: number;
   readonly output: number;
   readonly cacheRead: number;
   readonly cacheWrite: number;
   readonly totalTokens: number;
+  readonly coverage: WorkflowUsageComponentCoverage;
   readonly cost: WorkflowUsageCost;
 }
 
@@ -36,7 +46,21 @@ export interface WorkflowUsageSink {
 }
 
 const ZERO_COST: WorkflowUsageCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
-const ZERO_TOTALS: WorkflowUsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: ZERO_COST };
+const ZERO_COVERAGE: WorkflowUsageComponentCoverage = {
+  input: "none",
+  output: "none",
+  cacheRead: "none",
+  cacheWrite: "none",
+};
+const ZERO_TOTALS: WorkflowUsageTotals = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  coverage: ZERO_COVERAGE,
+  cost: ZERO_COST,
+};
 
 interface AssistantUsageMessage {
   readonly provider?: string;
@@ -47,6 +71,8 @@ interface AssistantUsageMessage {
 export class WorkflowUsageRecorder implements WorkflowUsageSink {
   private readonly agents: WorkflowAgentUsage[] = [];
 
+  constructor(private readonly onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void) {}
+
   recordAgentSession(input: { label: string; phase?: string; messages: readonly unknown[] }): void {
     const assistantMessages = input.messages.flatMap((message) => {
       const parsed = parseAssistantUsageMessage(message);
@@ -64,6 +90,7 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
       assistantMessages: assistantMessages.length,
       usage,
     });
+    this.onSnapshot?.(this.snapshot());
   }
 
   snapshot(): WorkflowUsageSnapshot {
@@ -79,8 +106,8 @@ export class WorkflowUsageRecorder implements WorkflowUsageSink {
   }
 }
 
-export function createWorkflowUsageRecorder(): WorkflowUsageSink {
-  return new WorkflowUsageRecorder();
+export function createWorkflowUsageRecorder(onSnapshot?: (snapshot: WorkflowUsageSnapshot) => void): WorkflowUsageSink {
+  return new WorkflowUsageRecorder(onSnapshot);
 }
 
 export function emptyWorkflowUsageTotals(): WorkflowUsageTotals {
@@ -96,19 +123,45 @@ export function isWorkflowUsageSnapshot(value: unknown): value is WorkflowUsageS
 
 export function hasWorkflowUsage(snapshot: unknown): snapshot is WorkflowUsageSnapshot {
   if (!isWorkflowUsageSnapshot(snapshot)) return false;
-  return snapshot.assistantMessages > 0 || snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
+  return snapshot.totals.totalTokens > 0 || snapshot.totals.cost.total > 0;
 }
 
 export function formatWorkflowUsageLine(snapshot: unknown): string | undefined {
   if (!hasWorkflowUsage(snapshot)) return undefined;
-  const parts = [`↑${formatUsageCount(snapshot.totals.input)}`, `↓${formatUsageCount(snapshot.totals.output)}`];
-  if (snapshot.totals.cacheRead > 0) parts.push(`R${formatUsageCount(snapshot.totals.cacheRead)}`);
-  if (snapshot.totals.cacheWrite > 0) parts.push(`W${formatUsageCount(snapshot.totals.cacheWrite)}`);
+  const parts = formatWorkflowUsageComponents(snapshot.totals);
   parts.push(`cost $${snapshot.totals.cost.total.toFixed(3)}`);
   parts.push(`agents ${snapshot.agents.length}`);
   return `Usage: ${parts.join(" · ")}`;
 }
 
+function formatWorkflowUsageComponents(totals: WorkflowUsageTotals): string[] {
+  const parts: string[] = [];
+  const completeCacheBreakdown =
+    totals.coverage.cacheRead === "complete" && totals.coverage.cacheWrite === "complete";
+  appendUsageComponent(parts, completeCacheBreakdown ? "fresh" : "input", totals.input, totals.coverage.input);
+  appendUsageComponent(parts, "cache read", totals.cacheRead, totals.coverage.cacheRead);
+  appendUsageComponent(parts, "cache write", totals.cacheWrite, totals.coverage.cacheWrite);
+  appendUsageComponent(parts, "output", totals.output, totals.coverage.output);
+
+  const knownComponents = totals.input + totals.output + totals.cacheRead + totals.cacheWrite;
+  if (parts.length === 0 && totals.totalTokens > 0) parts.push(`tokens ${formatUsageCount(totals.totalTokens)}`);
+  else if (!hasCompleteCoverage(totals.coverage) && totals.totalTokens !== knownComponents) {
+    parts.push(`total ${formatUsageCount(totals.totalTokens)}`);
+  }
+  return parts;
+}
+
+function appendUsageComponent(
+  parts: string[],
+  label: string,
+  value: number,
+  coverage: WorkflowUsageCoverage,
+): void {
+  if (value <= 0 || coverage === "none") return;
+  const count = formatUsageCount(value);
+  parts.push(`${label} ${coverage === "partial" ? `≥${count}` : count}`);
+}
+
 function isWorkflowAgentUsage(value: unknown): value is WorkflowAgentUsage {
   if (!isRecord(value)) return false;
   if (typeof value.label !== "string") return false;
@@ -126,9 +179,20 @@ function isWorkflowUsageTotals(value: unknown): value is WorkflowUsageTotals {
   if (finiteNumber(value.cacheRead) === undefined) return false;
   if (finiteNumber(value.cacheWrite) === undefined) return false;
   if (finiteNumber(value.totalTokens) === undefined) return false;
+  if (!isWorkflowUsageCoverage(value.coverage)) return false;
   return isWorkflowUsageCost(value.cost);
 }
 
+function isWorkflowUsageCoverage(value: unknown): value is WorkflowUsageComponentCoverage {
+  if (!isRecord(value)) return false;
+  return (
+    isCoverageValue(value.input) &&
+    isCoverageValue(value.output) &&
+    isCoverageValue(value.cacheRead) &&
+    isCoverageValue(value.cacheWrite)
+  );
+}
+
 function isWorkflowUsageCost(value: unknown): value is WorkflowUsageCost {
   if (!isRecord(value)) return false;
   return (
@@ -158,14 +222,26 @@ function parseUsageTotals(value: unknown): WorkflowUsageTotals | undefined {
   const output = finiteNumber(value.output);
   const cacheRead = finiteNumber(value.cacheRead);
   const cacheWrite = finiteNumber(value.cacheWrite);
+  const reportedTotal = finiteNumber(value.totalTokens);
   const cost = parseUsageCost(value.cost);
-  if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || !cost) return undefined;
+  if (!cost) return undefined;
+  if (input === undefined && output === undefined && cacheRead === undefined && cacheWrite === undefined && reportedTotal === undefined) {
+    return undefined;
+  }
+  const coverage: WorkflowUsageComponentCoverage = {
+    input: input === undefined ? "none" : "complete",
+    output: output === undefined ? "none" : "complete",
+    cacheRead: cacheRead === undefined ? "none" : "complete",
+    cacheWrite: cacheWrite === undefined ? "none" : "complete",
+  };
+  const componentTotal = (input ?? 0) + (output ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
   return {
-    input,
-    output,
-    cacheRead,
-    cacheWrite,
-    totalTokens: input + output + cacheRead + cacheWrite,
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    totalTokens: hasCompleteCoverage(coverage) ? componentTotal : (reportedTotal ?? componentTotal),
+    coverage,
     cost,
   };
 }
@@ -177,12 +253,20 @@ function parseUsageCost(value: unknown): WorkflowUsageCost | undefined {
   const cacheRead = finiteNumber(value.cacheRead);
   const cacheWrite = finiteNumber(value.cacheWrite);
   const total = finiteNumber(value.total);
-  if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || total === undefined) return undefined;
-  return { input, output, cacheRead, cacheWrite, total };
+  if (total === undefined) return undefined;
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    cacheRead: cacheRead ?? 0,
+    cacheWrite: cacheWrite ?? 0,
+    total,
+  };
 }
 
 function sumTotals(values: readonly WorkflowUsageTotals[]): WorkflowUsageTotals {
-  return values.reduce((sum, value) => addTotals(sum, value), emptyWorkflowUsageTotals());
+  const [first, ...rest] = values;
+  if (!first) return emptyWorkflowUsageTotals();
+  return rest.reduce(addTotals, cloneTotals(first));
 }
 
 function addTotals(left: WorkflowUsageTotals, right: WorkflowUsageTotals): WorkflowUsageTotals {
@@ -192,6 +276,12 @@ function addTotals(left: WorkflowUsageTotals, right: WorkflowUsageTotals): Workf
     cacheRead: left.cacheRead + right.cacheRead,
     cacheWrite: left.cacheWrite + right.cacheWrite,
     totalTokens: left.totalTokens + right.totalTokens,
+    coverage: {
+      input: combineCoverage(left.coverage.input, right.coverage.input),
+      output: combineCoverage(left.coverage.output, right.coverage.output),
+      cacheRead: combineCoverage(left.coverage.cacheRead, right.coverage.cacheRead),
+      cacheWrite: combineCoverage(left.coverage.cacheWrite, right.coverage.cacheWrite),
+    },
     cost: {
       input: left.cost.input + right.cost.input,
       output: left.cost.output + right.cost.output,
@@ -209,10 +299,28 @@ function cloneTotals(value: WorkflowUsageTotals): WorkflowUsageTotals {
     cacheRead: value.cacheRead,
     cacheWrite: value.cacheWrite,
     totalTokens: value.totalTokens,
+    coverage: { ...value.coverage },
     cost: { ...value.cost },
   };
 }
 
+function combineCoverage(left: WorkflowUsageCoverage, right: WorkflowUsageCoverage): WorkflowUsageCoverage {
+  return left === right ? left : "partial";
+}
+
+function hasCompleteCoverage(coverage: WorkflowUsageComponentCoverage): boolean {
+  return (
+    coverage.input === "complete" &&
+    coverage.output === "complete" &&
+    coverage.cacheRead === "complete" &&
+    coverage.cacheWrite === "complete"
+  );
+}
+
+function isCoverageValue(value: unknown): value is WorkflowUsageCoverage {
+  return value === "none" || value === "partial" || value === "complete";
+}
+
 function formatUsageCount(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;