@quintinshaw/pi-dynamic-workflows 1.8.0 → 1.9.0

package/src/workflow-ui.ts

@@ -0,0 +1,496 @@
+/**
+ * Interactive `/workflows` navigator, modeled on Claude Code's view:
+ *
+ *   runs ──enter──▶ phases ──enter──▶ agents ──enter──▶ agent detail
+ *        ◀──esc───        ◀──esc────         ◀──esc────
+ *
+ * Keys: ↑/↓ (or j/k) select · enter/→ drill in · esc/← back (esc at top closes)
+ *       p pause/resume · x stop · r restart · s save · q quit
+ *
+ * The state machine and line rendering are pure and unit-tested; the pi-tui
+ * Component shell (openWorkflowNavigator) wires them to live manager events.
+ */
+
+import type { ExtensionAPI, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { parseKey } from "@earendil-works/pi-tui";
+import type { WorkflowAgentSnapshot, WorkflowSnapshot } from "./display.js";
+import type { PersistedRunState } from "./run-persistence.js";
+import { registerSavedWorkflow } from "./saved-commands.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+import type { WorkflowStorage } from "./workflow-saved.js";
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "·",
+  queued: "·",
+  running: "◆",
+  paused: "⏸",
+  completed: "✓",
+  done: "✓",
+  failed: "✗",
+  error: "✗",
+  aborted: "⊘",
+  skipped: "⊘",
+};
+
+/** Minimal theme surface so rendering is testable without the real Theme class. */
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+const PLAIN: ThemeLike = { fg: (_c, t) => t, bold: (t) => t };
+
+export type ViewKind = "runs" | "phases" | "agents" | "detail";
+
+interface RunRow {
+  runId: string;
+  name: string;
+  status: string;
+  done: number;
+  total: number;
+  tokens: number;
+}
+interface PhaseRow {
+  title: string;
+  done: number;
+  total: number;
+  tokens: number;
+}
+interface AgentRow {
+  id: number;
+  label: string;
+  status: string;
+  phase?: string;
+  tokens?: number;
+}
+
+/** Reads run/phase/agent data from the manager, preferring live snapshots. */
+export class NavigatorModel {
+  constructor(private readonly manager: Pick<WorkflowManager, "listRuns" | "getRun">) {}
+
+  private snapshot(runId: string): { snapshot: WorkflowSnapshot; status: string } | undefined {
+    const live = this.manager.getRun(runId);
+    if (live) return { snapshot: live.snapshot, status: live.status };
+    const p = this.manager.listRuns().find((r) => r.runId === runId);
+    if (!p) return undefined;
+    return { snapshot: persistedToSnapshot(p), status: p.status };
+  }
+
+  runs(): RunRow[] {
+    return this.manager.listRuns().map((p) => {
+      const live = this.manager.getRun(p.runId);
+      const agents = (live?.snapshot.agents ?? p.agents) as WorkflowAgentSnapshot[];
+      return {
+        runId: p.runId,
+        name: live?.snapshot.name ?? p.workflowName,
+        status: live?.status ?? p.status,
+        done: agents.filter((a) => a.status === "done").length,
+        total: agents.length,
+        tokens: (live?.snapshot.tokenUsage ?? p.tokenUsage)?.total ?? 0,
+      };
+    });
+  }
+
+  runName(runId: string): string {
+    return this.snapshot(runId)?.snapshot.name ?? runId;
+  }
+
+  runStatus(runId: string): string {
+    return this.snapshot(runId)?.status ?? "unknown";
+  }
+
+  phases(runId: string): PhaseRow[] {
+    const snap = this.snapshot(runId)?.snapshot;
+    if (!snap) return [];
+    const order = snap.phases.length ? [...snap.phases] : [];
+    const byPhase = new Map<string, AgentRow[]>();
+    for (const a of snap.agents) {
+      const key = a.phase ?? "(no phase)";
+      if (!byPhase.has(key)) byPhase.set(key, []);
+      byPhase.get(key)?.push(a);
+      if (!order.includes(key)) order.push(key);
+    }
+    return order.map((title) => {
+      const agents = byPhase.get(title) ?? [];
+      return {
+        title,
+        done: agents.filter((a) => a.status === "done").length,
+        total: agents.length,
+        tokens: agents.reduce((n, a) => n + (a.tokens ?? 0), 0),
+      };
+    });
+  }
+
+  agents(runId: string, phase: string): AgentRow[] {
+    const snap = this.snapshot(runId)?.snapshot;
+    if (!snap) return [];
+    return snap.agents
+      .filter((a) => (a.phase ?? "(no phase)") === phase)
+      .map((a) => ({ id: a.id, label: a.label, status: a.status, phase: a.phase, tokens: a.tokens }));
+  }
+
+  agentDetail(runId: string, agentId: number): WorkflowAgentSnapshot | undefined {
+    return this.snapshot(runId)?.snapshot.agents.find((a) => a.id === agentId);
+  }
+}
+
+function persistedToSnapshot(p: PersistedRunState): WorkflowSnapshot {
+  return {
+    name: p.workflowName,
+    phases: p.phases,
+    currentPhase: p.currentPhase,
+    logs: p.logs,
+    agents: p.agents.map((a) => ({
+      id: a.id,
+      label: a.label,
+      phase: a.phase,
+      prompt: a.prompt,
+      status: a.status,
+      resultPreview:
+        a.result == null ? undefined : String(typeof a.result === "string" ? a.result : JSON.stringify(a.result)),
+      error: a.error,
+    })),
+    agentCount: p.agents.length,
+    runningCount: p.agents.filter((a) => a.status === "running").length,
+    doneCount: p.agents.filter((a) => a.status === "done").length,
+    errorCount: p.agents.filter((a) => a.status === "error").length,
+    tokenUsage: p.tokenUsage ? { ...p.tokenUsage } : undefined,
+    runId: p.runId,
+  };
+}
+
+/** Navigation state machine: a stack of (view, cursor) frames plus detail scroll. */
+export class NavigatorState {
+  private stack: Array<{ kind: ViewKind; cursor: number; runId?: string; phase?: string; agentId?: number }> = [
+    { kind: "runs", cursor: 0 },
+  ];
+  scroll = 0;
+
+  private top() {
+    return this.stack[this.stack.length - 1];
+  }
+  get kind(): ViewKind {
+    return this.top().kind;
+  }
+  get cursor(): number {
+    return this.top().cursor;
+  }
+  get runId(): string | undefined {
+    return this.top().runId;
+  }
+  get phase(): string | undefined {
+    return this.top().phase;
+  }
+  get agentId(): number | undefined {
+    return this.top().agentId;
+  }
+  get depth(): number {
+    return this.stack.length;
+  }
+
+  /** Clamp the cursor to [0, count). */
+  clamp(count: number) {
+    const t = this.top();
+    t.cursor = count <= 0 ? 0 : Math.max(0, Math.min(t.cursor, count - 1));
+  }
+
+  move(delta: number, count: number) {
+    if (this.kind === "detail") {
+      this.scroll = Math.max(0, this.scroll + delta);
+      return;
+    }
+    if (count <= 0) return;
+    const t = this.top();
+    t.cursor = (t.cursor + delta + count) % count;
+  }
+
+  /** Drill into the selected item. Returns true if the view changed. */
+  drill(model: NavigatorModel): boolean {
+    const t = this.top();
+    if (t.kind === "runs") {
+      const runs = model.runs();
+      const run = runs[t.cursor];
+      if (!run) return false;
+      this.stack.push({ kind: "phases", cursor: 0, runId: run.runId });
+      return true;
+    }
+    if (t.kind === "phases" && t.runId) {
+      const phases = model.phases(t.runId);
+      const ph = phases[t.cursor];
+      if (!ph) return false;
+      this.stack.push({ kind: "agents", cursor: 0, runId: t.runId, phase: ph.title });
+      return true;
+    }
+    if (t.kind === "agents" && t.runId && t.phase) {
+      const agents = model.agents(t.runId, t.phase);
+      const ag = agents[t.cursor];
+      if (!ag) return false;
+      this.scroll = 0;
+      this.stack.push({ kind: "detail", cursor: 0, runId: t.runId, phase: t.phase, agentId: ag.id });
+      return true;
+    }
+    return false;
+  }
+
+  /** Pop one level. Returns false when already at the top (caller should close). */
+  back(): boolean {
+    if (this.stack.length <= 1) return false;
+    this.stack.pop();
+    this.scroll = 0;
+    return true;
+  }
+
+  /** The runId the current view acts on (for pause/stop/save). */
+  activeRunId(model: NavigatorModel): string | undefined {
+    if (this.runId) return this.runId;
+    if (this.kind === "runs") return model.runs()[this.cursor]?.runId;
+    return undefined;
+  }
+}
+
+function pad(n: number): string {
+  return n.toLocaleString();
+}
+
+function fmtTokens(t: number): string {
+  return t > 0 ? `${pad(t)} tok` : "";
+}
+
+/** Build the lines for the current view. Pure: depends only on state + model + theme. */
+export function renderNavigator(
+  state: NavigatorState,
+  model: NavigatorModel,
+  width: number,
+  theme: ThemeLike = PLAIN,
+): string[] {
+  const lines: string[] = [];
+  const sel = (i: number, text: string) =>
+    i === state.cursor ? theme.fg("accent", theme.bold(`❯ ${text}`)) : `  ${text}`;
+  const dim = (t: string) => theme.fg("dim", t);
+
+  if (state.kind === "runs") {
+    const runs = model.runs();
+    state.clamp(runs.length);
+    lines.push(theme.bold("Workflows"));
+    if (!runs.length) lines.push(dim("  No runs yet. Start one with a background workflow."));
+    runs.forEach((r, i) => {
+      const icon = STATUS_ICON[r.status] ?? "?";
+      const meta = [`${r.done}/${r.total}`, fmtTokens(r.tokens)].filter(Boolean).join(" · ");
+      lines.push(sel(i, `${icon} ${r.name}  ${dim(`${r.runId} · ${r.status} · ${meta}`)}`));
+    });
+  } else if (state.kind === "phases" && state.runId) {
+    const phases = model.phases(state.runId);
+    state.clamp(phases.length);
+    lines.push(theme.bold(model.runName(state.runId)) + dim(`  (${model.runStatus(state.runId)})`));
+    phases.forEach((p, i) => {
+      const meta = [`${p.done}/${p.total} agents`, fmtTokens(p.tokens)].filter(Boolean).join(" · ");
+      lines.push(sel(i, `${p.title}  ${dim(meta)}`));
+    });
+  } else if (state.kind === "agents" && state.runId && state.phase) {
+    const agents = model.agents(state.runId, state.phase);
+    state.clamp(agents.length);
+    lines.push(theme.bold(`${model.runName(state.runId)} › ${state.phase}`));
+    agents.forEach((a, i) => {
+      const icon = STATUS_ICON[a.status] ?? "?";
+      const tok = a.tokens ? dim(` ${fmtTokens(a.tokens)}`) : "";
+      lines.push(sel(i, `${icon} ${a.label}${tok}`));
+    });
+  } else if (state.kind === "detail" && state.runId && state.agentId != null) {
+    const a = model.agentDetail(state.runId, state.agentId);
+    lines.push(theme.bold(a ? a.label : "agent"));
+    if (a) {
+      const body: string[] = [];
+      body.push(dim("Status: ") + (a.status ?? ""));
+      if (a.error) body.push(dim("Error: ") + a.error);
+      body.push("", dim("Prompt:"));
+      body.push(...wrap(a.prompt ?? "", width));
+      body.push("", dim("Result:"));
+      body.push(...wrap(a.resultPreview ?? "(none)", width));
+      // Scrollable region.
+      const maxScroll = Math.max(0, body.length - 1);
+      state.scroll = Math.min(state.scroll, maxScroll);
+      lines.push(...body.slice(state.scroll));
+    }
+  }
+
+  lines.push("");
+  lines.push(footerHint(state, theme));
+  return lines;
+}
+
+function footerHint(state: NavigatorState, theme: ThemeLike): string {
+  const parts =
+    state.kind === "detail"
+      ? ["j/k scroll", "esc back"]
+      : ["↑/↓ select", "enter open", "esc back", "p pause", "x stop", "r restart", "s save", "q quit"];
+  return theme.fg("dim", parts.join(" · "));
+}
+
+function wrap(text: string, width: number): string[] {
+  const w = Math.max(20, width - 2);
+  const out: string[] = [];
+  for (const para of String(text).split("\n")) {
+    if (para.length <= w) {
+      out.push(para);
+      continue;
+    }
+    let rest = para;
+    while (rest.length > w) {
+      out.push(rest.slice(0, w));
+      rest = rest.slice(w);
+    }
+    if (rest) out.push(rest);
+  }
+  return out;
+}
+
+/** What a key press should do. Pure mapping from a parsed key id to an action. */
+export type NavAction =
+  | { type: "move"; delta: number }
+  | { type: "drill" }
+  | { type: "back" }
+  | { type: "close" }
+  | { type: "pause" }
+  | { type: "stop" }
+  | { type: "restart" }
+  | { type: "save" }
+  | { type: "none" };
+
+export function keyToAction(keyId: string | undefined, kind: ViewKind): NavAction {
+  switch (keyId) {
+    case "up":
+      return { type: "move", delta: -1 };
+    case "down":
+      return { type: "move", delta: 1 };
+    case "k":
+      return { type: "move", delta: -1 };
+    case "j":
+      return { type: "move", delta: 1 };
+    case "enter":
+    case "return":
+    case "right":
+      return kind === "detail" ? { type: "none" } : { type: "drill" };
+    case "escape":
+    case "esc":
+    case "left":
+      return { type: "back" };
+    case "q":
+      return { type: "close" };
+    case "p":
+      return { type: "pause" };
+    case "x":
+      return { type: "stop" };
+    case "r":
+      return { type: "restart" };
+    case "s":
+      return { type: "save" };
+    default:
+      return { type: "none" };
+  }
+}
+
+function currentCount(state: NavigatorState, model: NavigatorModel): number {
+  if (state.kind === "runs") return model.runs().length;
+  if (state.kind === "phases" && state.runId) return model.phases(state.runId).length;
+  if (state.kind === "agents" && state.runId && state.phase) return model.agents(state.runId, state.phase).length;
+  return 0;
+}
+
+export interface NavigatorOptions {
+  storage?: WorkflowStorage;
+  cwd?: string;
+}
+
+/**
+ * Open the interactive `/workflows` navigator as a focused overlay. Resolves when
+ * the user closes it (esc at the top level, or `q`).
+ */
+export function openWorkflowNavigator(
+  pi: ExtensionAPI,
+  manager: WorkflowManager,
+  ui: ExtensionUIContext,
+  opts: NavigatorOptions = {},
+): Promise<void> {
+  const model = new NavigatorModel(manager);
+  const state = new NavigatorState();
+
+  return ui.custom<void>(
+    (tui: TUI, theme: Theme, _keybindings, done: (r: void) => void) => {
+      const rerender = () => tui.requestRender();
+      const events = ["agentStart", "agentEnd", "phase", "log", "complete", "error", "stopped", "paused", "resumed"];
+      const onEvent = () => rerender();
+      for (const ev of events) manager.on(ev, onEvent);
+      const cleanup = () => {
+        for (const ev of events) manager.off(ev, onEvent);
+      };
+
+      const act = (data: string) => {
+        const action = keyToAction(parseKey(data), state.kind);
+        switch (action.type) {
+          case "move":
+            state.move(action.delta, currentCount(state, model));
+            break;
+          case "drill":
+            state.drill(model);
+            break;
+          case "back":
+            if (!state.back()) {
+              cleanup();
+              done();
+            }
+            break;
+          case "close":
+            cleanup();
+            done();
+            return;
+          case "pause": {
+            const id = state.activeRunId(model);
+            if (id) ui.notify(manager.pause(id) ? `Paused ${id}` : `Cannot pause ${id}`, "info");
+            break;
+          }
+          case "stop": {
+            const id = state.activeRunId(model);
+            if (id) ui.notify(manager.stop(id) ? `Stopped ${id}` : `Cannot stop ${id}`, "info");
+            break;
+          }
+          case "restart":
+            ui.notify("Restarting a single agent isn't supported yet", "warning");
+            break;
+          case "save": {
+            const id = state.activeRunId(model);
+            const run = id ? manager.listRuns().find((r) => r.runId === id) : undefined;
+            if (!run?.script) {
+              ui.notify("No saved run script to save", "warning");
+            } else if (!opts.storage) {
+              ui.notify("Saving is not available (no storage)", "error");
+            } else {
+              const name = run.workflowName || "workflow";
+              const saved = opts.storage.save({
+                name,
+                description: run.workflowName,
+                script: run.script,
+                location: "project",
+              });
+              registerSavedWorkflow(pi, opts.cwd ?? process.cwd(), saved);
+              ui.notify(`Saved /${name}`, "info");
+            }
+            break;
+          }
+          default:
+            return;
+        }
+        rerender();
+      };
+
+      const component: Component & { dispose?(): void } = {
+        render: (width: number) => renderNavigator(state, model, width, theme),
+        handleInput: (data: string) => act(data),
+        invalidate: () => {},
+        dispose: () => cleanup(),
+      };
+      return component;
+    },
+    { overlay: true },
+  );
+}