pi-workflow-engine 0.1.1 → 0.3.0

package/src/progress.ts

@@ -1,9 +1,63 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import type { WorkflowLaneItemStatus, WorkflowProgressEvent } from "./types.ts";
+import { statusText } from "./ui/workflow-format.ts";
+import { createWorkflowWidget, type WorkflowWidget } from "./ui/workflow-widget.ts";
+
+export type AgentRowStatus = "queued" | "running" | "done" | "failed";
+
+export interface AgentRowSnapshot {
+  readonly id: number;
+  readonly label: string;
+  readonly status: AgentRowStatus;
+  readonly startedAt?: number;
+  readonly doneAt?: number;
+  readonly toolUses: number;
+  readonly lastTool?: string;
+  readonly error?: string;
+}
+
+export interface PhaseSnapshot {
+  readonly title: string;
+  readonly agents: readonly AgentRowSnapshot[];
+}
+
+export interface WorkflowCounterSnapshot {
+  readonly key: string;
+  readonly label: string;
+  readonly value: number;
+}
+
+export interface WorkflowLaneItemSnapshot {
+  readonly lane: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly status: WorkflowLaneItemStatus;
+  readonly details?: string;
+  readonly createdAt: number;
+}
+
+export interface WorkflowProgressSnapshot {
+  readonly title: string;
+  readonly startedAt: number;
+  readonly doneAt?: number;
+  readonly currentPhase: string;
+  readonly phases: readonly PhaseSnapshot[];
+  readonly counters: readonly WorkflowCounterSnapshot[];
+  readonly summary: readonly [string, string | number][];
+  readonly lanes: readonly [string, readonly WorkflowLaneItemSnapshot[]][];
+  readonly logs: readonly string[];
+}
 
 interface AgentRow {
+  id: number;
   label: string;
-  status: "running" | "done";
+  status: AgentRowStatus;
+  startedAt?: number;
+  doneAt?: number;
+  toolUses: number;
   lastTool?: string;
+  error?: string;
 }
 
 interface Phase {
@@ -11,21 +65,48 @@ interface Phase {
   agents: AgentRow[];
 }
 
+interface WorkflowCounter {
+  key: string;
+  label: string;
+  value: number;
+}
+
+interface WorkflowLaneItem {
+  lane: string;
+  title: string;
+  subtitle?: string;
+  status: WorkflowLaneItemStatus;
+  details?: string;
+  createdAt: number;
+}
+
+const LOG_LIMIT = 24;
+
 /**
- * Renders a live phase/agent tree into the pi TUI via `ctx.ui.setWidget`.
- * In non-interactive modes (print/JSON/RPC) it falls back to terse stderr breadcrumbs
- * so it never corrupts stdout.
+ * Tracks live workflow state for widgets, footer/status text, result renderers,
+ * and headless stderr breadcrumbs.
  */
 export class ProgressTracker {
   private readonly phases: Phase[] = [];
   private readonly logs: string[] = [];
-  private current = "Workflow";
+  private readonly counters = new Map<string, WorkflowCounter>();
+  private readonly summary = new Map<string, string | number>();
+  private readonly lanes = new Map<string, WorkflowLaneItem[]>();
+  private readonly startedAt = Date.now();
+  private doneAt: number | undefined;
+  private currentPhase = "Workflow";
+  private nextAgentId = 1;
+  private widget: WorkflowWidget | undefined;
+  private widgetRegistered = false;
+  private tui: Pick<TUI, "requestRender"> | undefined;
+  private widgetInterval: ReturnType<typeof setInterval> | undefined;
+  private lastStatusText: string | undefined;
 
   constructor(
     private readonly ctx: ExtensionContext,
     private readonly title: string,
   ) {
-    this.ensurePhase(this.current);
+    this.ensurePhase(this.currentPhase);
   }
 
   private ensurePhase(title: string): Phase {
@@ -38,7 +119,7 @@ export class ProgressTracker {
   }
 
   phase(title: string): void {
-    this.current = title;
+    this.currentPhase = title;
     this.ensurePhase(title);
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
     this.render();
@@ -46,31 +127,121 @@ export class ProgressTracker {
 
   log(message: string): void {
     this.logs.push(message);
-    if (this.logs.length > 6) this.logs.shift();
+    while (this.logs.length > LOG_LIMIT) this.logs.shift();
     if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
     this.render();
   }
 
-  agentStart(phase: string | undefined, label: string): void {
-    this.ensurePhase(phase ?? this.current).agents.push({ label, status: "running" });
+  event(event: WorkflowProgressEvent): void {
+    switch (event.type) {
+      case "counter":
+        this.counters.set(event.key, { key: event.key, label: event.label, value: event.value });
+        break;
+      case "counter_delta": {
+        const current = this.counters.get(event.key);
+        this.counters.set(event.key, {
+          key: event.key,
+          label: event.label,
+          value: (current?.value ?? 0) + event.delta,
+        });
+        break;
+      }
+      case "lane_item": {
+        const lane = this.lanes.get(event.lane) ?? [];
+        lane.push({
+          lane: event.lane,
+          title: event.title,
+          subtitle: event.subtitle,
+          status: event.status,
+          details: event.details,
+          createdAt: Date.now(),
+        });
+        this.lanes.set(event.lane, lane);
+        break;
+      }
+      case "summary":
+        this.summary.set(event.key, event.value);
+        break;
+    }
+    this.render();
+  }
+
+  agentQueued(phase: string | undefined, label: string): number {
+    const id = this.nextAgentId++;
+    this.ensurePhase(phase ?? this.currentPhase).agents.push({ label, id, status: "queued", toolUses: 0 });
+    this.render();
+    return id;
+  }
+
+  agentStart(phase: string | undefined, label: string, id?: number): void {
+    const row = id === undefined ? undefined : this.findRowById(id);
+    if (row) {
+      row.status = "running";
+      row.startedAt = Date.now();
+      row.error = undefined;
+    } else {
+      this.ensurePhase(phase ?? this.currentPhase).agents.push({
+        label,
+        id: this.nextAgentId++,
+        status: "running",
+        startedAt: Date.now(),
+        toolUses: 0,
+      });
+    }
     this.render();
   }
 
-  agentTool(label: string, tool: string): void {
-    const row = this.findRow(label);
-    if (row) row.lastTool = tool;
+  agentTool(label: string, tool: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      row.lastTool = tool;
+      row.toolUses += 1;
+    }
     this.render();
   }
 
-  agentDone(label: string): void {
-    const row = this.findRow(label);
-    if (row && row.status === "running") row.status = "done";
+  agentDone(label: string, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row && row.status !== "failed") {
+      row.status = "done";
+      row.doneAt = Date.now();
+    }
     this.render();
   }
 
-  private findRow(label: string): AgentRow | undefined {
+  agentFailed(label: string, error: unknown, id?: number): void {
+    const row = this.findRow(label, id);
+    if (row) {
+      row.status = "failed";
+      row.doneAt = Date.now();
+      row.error = errorMessage(error);
+    }
+    this.render();
+  }
+
+  snapshot(): WorkflowProgressSnapshot {
+    return {
+      title: this.title,
+      startedAt: this.startedAt,
+      doneAt: this.doneAt,
+      currentPhase: this.currentPhase,
+      phases: this.phases.map((phase) => ({
+        title: phase.title,
+        agents: phase.agents.map((agent) => ({ ...agent })),
+      })),
+      counters: [...this.counters.values()].map((counter) => ({ ...counter })),
+      summary: [...this.summary.entries()],
+      lanes: [...this.lanes.entries()].map(([lane, items]) => [lane, items.map((item) => ({ ...item }))]),
+      logs: [...this.logs],
+    };
+  }
+
+  private findRow(label: string, id?: number): AgentRow | undefined {
+    if (id !== undefined) return this.findRowById(id);
     for (let i = this.phases.length - 1; i >= 0; i--) {
-      const running = this.phases[i].agents.find((agent) => agent.label === label && agent.status === "running");
+      const running = this.phases[i].agents.find(
+        (agent) => agent.label === label && (agent.status === "running" || agent.status === "queued"),
+      );
       if (running) return running;
     }
     for (let i = this.phases.length - 1; i >= 0; i--) {
@@ -80,29 +251,93 @@ export class ProgressTracker {
     return undefined;
   }
 
+  private findRowById(id: number): AgentRow | undefined {
+    for (const phase of this.phases) {
+      const row = phase.agents.find((agent) => agent.id === id);
+      if (row) return row;
+    }
+    return undefined;
+  }
+
   private lines(): string[] {
     const out: string[] = [`⚙ ${this.title}`];
     for (const phase of this.phases) {
       if (phase.agents.length === 0 && phase.title === "Workflow") continue;
       out.push(`  ${phase.title}`);
       for (const agent of phase.agents) {
-        const icon = agent.status === "done" ? "✓" : "⏳";
+        const icon = agent.status === "done" ? "✓" : agent.status === "failed" ? "✗" : agent.status === "queued" ? "○" : "⏳";
         const tool = agent.status === "running" && agent.lastTool ? ` · ${agent.lastTool}` : "";
-        out.push(`    ${icon} ${agent.label}${tool}`);
+        const error = agent.status === "failed" && agent.error ? ` · ${agent.error}` : "";
+        out.push(`    ${icon} ${agent.label}${tool}${error}`);
       }
     }
-    for (const line of this.logs) out.push(`  · ${line}`);
+    const counterLine = [...this.counters.values()].map((counter) => `${counter.label}: ${counter.value}`).join(" · ");
+    if (counterLine) out.push(`  ${counterLine}`);
+    for (const line of this.logs.slice(-6)) out.push(`  · ${line}`);
     return out;
   }
 
   private render(): void {
-    if (this.ctx.hasUI) this.ctx.ui.setWidget("workflow", this.lines());
+    if (!this.ctx.hasUI) return;
+    this.ensureWidget();
+    this.widget?.invalidate();
+    this.tui?.requestRender();
+    this.publishStatus();
+  }
+
+  private publishStatus(): void {
+    const next = statusText(this.snapshot(), this.ctx.ui.theme);
+    if (next === this.lastStatusText) return;
+    this.ctx.ui.setStatus("workflow", next);
+    this.lastStatusText = next;
+  }
+
+  private ensureWidget(): void {
+    if (this.widgetRegistered) return;
+    this.widget = createWorkflowWidget(() => this.snapshot());
+    this.ctx.ui.setWidget(
+      "workflow",
+      (tui, theme) => {
+        this.tui = tui;
+        return {
+          render: (width?: number) => this.widget?.render(width ?? tui.terminal.columns, theme) ?? [],
+          invalidate: () => this.widget?.invalidate(),
+        };
+      },
+      { placement: "aboveEditor" },
+    );
+    this.widgetRegistered = true;
+    this.startWidgetTimer();
   }
 
-  /** Clear the widget; optionally leave a one-line status in the footer. */
+  private startWidgetTimer(): void {
+    if (this.widgetInterval !== undefined) return;
+    this.widgetInterval = setInterval(() => {
+      this.widget?.nextFrame();
+      this.tui?.requestRender();
+    }, 100);
+  }
+
+  private stopWidgetTimer(): void {
+    if (this.widgetInterval === undefined) return;
+    clearInterval(this.widgetInterval);
+    this.widgetInterval = undefined;
+  }
+
+  /** Clear live workflow surfaces; optionally leave a one-line final status. */
   done(status?: string): void {
+    this.doneAt = Date.now();
+    this.stopWidgetTimer();
     if (!this.ctx.hasUI) return;
     this.ctx.ui.setWidget("workflow", undefined);
     this.ctx.ui.setStatus("workflow", status);
+    this.lastStatusText = status;
+    this.widgetRegistered = false;
+    this.widget = undefined;
+    this.tui = undefined;
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/types.ts

@@ -8,7 +8,34 @@ export interface WorkflowMeta {
   phases?: Array<{ title: string }>;
 }
 
+export interface WorkflowRunStats {
+  files: number;
+  candidates: number;
+  verified: number;
+  kept: number;
+  [key: string]: string | number;
+}
+
+export interface WorkflowRunOptions {
+  inspect?: boolean;
+}
+
 /** Options for a single `agent()` call. */
+export type WorkflowLaneItemStatus = "pending" | "running" | "success" | "warning" | "error";
+
+export type WorkflowProgressEvent =
+  | { type: "counter"; key: string; label: string; value: number }
+  | { type: "counter_delta"; key: string; label: string; delta: number }
+  | {
+      type: "lane_item";
+      lane: string;
+      title: string;
+      subtitle?: string;
+      status: WorkflowLaneItemStatus;
+      details?: string;
+    }
+  | { type: "summary"; key: string; value: string | number };
+
 export interface AgentOptions<S extends TSchema = TSchema> {
   /** Label shown in the progress tree (e.g. "find:logic-bugs"). */
   label?: string;
@@ -44,6 +71,8 @@ export interface WorkflowApi {
   phase(title: string): void;
   /** Emit a progress line. */
   log(message: string): void;
+  /** Emit a structured progress event for native workflow UI surfaces. */
+  progress(event: WorkflowProgressEvent): void;
   /** Raw argument string passed after the workflow name. */
   args: string;
   /** Working directory of the host session (typically the repo root). */

package/src/ui/workflow-format.ts

@@ -0,0 +1,83 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { WorkflowProgressSnapshot } from "../progress.ts";
+import type { WorkflowLaneItemStatus } from "../types.ts";
+
+export type WorkflowDisplayStatus = WorkflowLaneItemStatus | "queued" | "done" | "failed";
+export type WorkflowThemeColor = Parameters<Theme["fg"]>[0];
+
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "0s";
+  if (ms < 1_000) return `${Math.round(ms)}ms`;
+
+  const totalSeconds = Math.floor(ms / 1_000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return seconds === 0 ? `${minutes}m` : `${minutes}m ${seconds}s`;
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes === 0 ? `${hours}h` : `${hours}h ${remainingMinutes}m`;
+}
+
+export function formatCount(n: number): string {
+  if (!Number.isFinite(n)) return "0";
+  const sign = n < 0 ? "-" : "";
+  const value = Math.abs(n);
+  if (value < 1_000) return `${Math.trunc(n)}`;
+  if (value < 1_000_000) return `${sign}${formatCompact(value / 1_000)}k`;
+  return `${sign}${formatCompact(value / 1_000_000)}m`;
+}
+
+export function statusIcon(status: WorkflowDisplayStatus, theme: Theme): string {
+  switch (status) {
+    case "success":
+    case "done":
+      return theme.fg("success", "✓");
+    case "warning":
+      return theme.fg("warning", "!");
+    case "error":
+    case "failed":
+      return theme.fg("error", "✗");
+    case "running":
+      return theme.fg("accent", "●");
+    case "queued":
+    case "pending":
+      return theme.fg("dim", "○");
+  }
+}
+
+export function badge(label: string, color: WorkflowThemeColor, theme: Theme): string {
+  return theme.fg(color, `[${label}]`);
+}
+
+export function truncateDisplay(text: string, width: number): string {
+  if (width <= 0) return "";
+  return truncateToWidth(text, width);
+}
+
+export function statusText(snapshot: WorkflowProgressSnapshot, theme: Theme): string | undefined {
+  if (snapshot.doneAt !== undefined) return undefined;
+
+  const agents = snapshot.phases.flatMap((phase) => phase.agents);
+  const complete = agents.filter((agent) => agent.status === "done" || agent.status === "failed").length;
+  const active = agents.filter((agent) => agent.status === "running" || agent.status === "queued").length;
+  const total = agents.length;
+  const kept = snapshot.counters.find((counter) => counter.key === "kept" || counter.label.toLowerCase() === "kept");
+  const displayName = snapshot.title === "code-review" ? "review" : snapshot.title;
+
+  const parts = [theme.fg("accent", displayName), theme.fg("muted", snapshot.currentPhase)];
+  if (total > 0) parts.push(theme.fg("muted", `${complete}/${total}`));
+  if (kept) parts.push(theme.fg("success", `${formatCount(kept.value)} kept`));
+  else if (active > 0) parts.push(theme.fg("muted", `${active} active`));
+
+  return parts.join(theme.fg("dim", " · "));
+}
+
+function formatCompact(value: number): string {
+  if (value >= 100) return `${Math.round(value)}`;
+  const rounded = Math.round(value * 10) / 10;
+  return Number.isInteger(rounded) ? `${rounded}` : rounded.toFixed(1);
+}