@quintinshaw/pi-dynamic-workflows 1.8.0 → 1.9.0

package/dist/workflow-ui.js

@@ -0,0 +1,426 @@
+/**
+ * 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 { parseKey } from "@earendil-works/pi-tui";
+import { registerSavedWorkflow } from "./saved-commands.js";
+const STATUS_ICON = {
+    pending: "·",
+    queued: "·",
+    running: "◆",
+    paused: "⏸",
+    completed: "✓",
+    done: "✓",
+    failed: "✗",
+    error: "✗",
+    aborted: "⊘",
+    skipped: "⊘",
+};
+const PLAIN = { fg: (_c, t) => t, bold: (t) => t };
+/** Reads run/phase/agent data from the manager, preferring live snapshots. */
+export class NavigatorModel {
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    snapshot(runId) {
+        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() {
+        return this.manager.listRuns().map((p) => {
+            const live = this.manager.getRun(p.runId);
+            const agents = (live?.snapshot.agents ?? p.agents);
+            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) {
+        return this.snapshot(runId)?.snapshot.name ?? runId;
+    }
+    runStatus(runId) {
+        return this.snapshot(runId)?.status ?? "unknown";
+    }
+    phases(runId) {
+        const snap = this.snapshot(runId)?.snapshot;
+        if (!snap)
+            return [];
+        const order = snap.phases.length ? [...snap.phases] : [];
+        const byPhase = new Map();
+        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, phase) {
+        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, agentId) {
+        return this.snapshot(runId)?.snapshot.agents.find((a) => a.id === agentId);
+    }
+}
+function persistedToSnapshot(p) {
+    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 {
+    stack = [
+        { kind: "runs", cursor: 0 },
+    ];
+    scroll = 0;
+    top() {
+        return this.stack[this.stack.length - 1];
+    }
+    get kind() {
+        return this.top().kind;
+    }
+    get cursor() {
+        return this.top().cursor;
+    }
+    get runId() {
+        return this.top().runId;
+    }
+    get phase() {
+        return this.top().phase;
+    }
+    get agentId() {
+        return this.top().agentId;
+    }
+    get depth() {
+        return this.stack.length;
+    }
+    /** Clamp the cursor to [0, count). */
+    clamp(count) {
+        const t = this.top();
+        t.cursor = count <= 0 ? 0 : Math.max(0, Math.min(t.cursor, count - 1));
+    }
+    move(delta, count) {
+        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) {
+        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() {
+        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) {
+        if (this.runId)
+            return this.runId;
+        if (this.kind === "runs")
+            return model.runs()[this.cursor]?.runId;
+        return undefined;
+    }
+}
+function pad(n) {
+    return n.toLocaleString();
+}
+function fmtTokens(t) {
+    return t > 0 ? `${pad(t)} tok` : "";
+}
+/** Build the lines for the current view. Pure: depends only on state + model + theme. */
+export function renderNavigator(state, model, width, theme = PLAIN) {
+    const lines = [];
+    const sel = (i, text) => i === state.cursor ? theme.fg("accent", theme.bold(`❯ ${text}`)) : `  ${text}`;
+    const dim = (t) => 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 = [];
+            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, theme) {
+    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, width) {
+    const w = Math.max(20, width - 2);
+    const out = [];
+    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;
+}
+export function keyToAction(keyId, kind) {
+    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, model) {
+    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;
+}
+/**
+ * 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, manager, ui, opts = {}) {
+    const model = new NavigatorModel(manager);
+    const state = new NavigatorState();
+    return ui.custom((tui, theme, _keybindings, done) => {
+        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) => {
+            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 = {
+            render: (width) => renderNavigator(state, model, width, theme),
+            handleInput: (data) => act(data),
+            invalidate: () => { },
+            dispose: () => cleanup(),
+        };
+        return component;
+    }, { overlay: true });
+}

package/extensions/workflow.ts

@@ -1,7 +1,9 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   createWorkflowStorage,
   createWorkflowTool,
+  installResultDelivery,
+  installTaskPanel,
   registerAllSavedWorkflows,
   registerBuiltinWorkflows,
   registerWorkflowCommands,
@@ -20,11 +22,15 @@ export default function extension(pi: ExtensionAPI) {
   registerWorkflowCommands(pi, manager, { storage, cwd });
   registerBuiltinWorkflows(pi, { cwd });
   registerAllSavedWorkflows(pi, cwd, storage);
+  // Deliver a background run's result into the conversation when it finishes.
+  installResultDelivery(pi, manager);
 
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event: unknown, ctx: ExtensionContext) => {
     const active = pi.getActiveTools();
     if (!active.includes(workflowTool.name)) {
       pi.setActiveTools([...active, workflowTool.name]);
     }
+    // Live "workflows running" panel below the input (focus + enter to open).
+    installTaskPanel(pi, manager, ctx.ui, { storage, cwd });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quintinshaw/pi-dynamic-workflows",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Claude-Code-style dynamic workflow orchestration for Pi.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -45,6 +45,7 @@ export {
 } from "./saved-commands.js";
 export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
 export { createStructuredOutputTool } from "./structured-output.js";
+export { installResultDelivery, installTaskPanel, type TaskPanelOptions } from "./task-panel.js";
 export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
 export type {
   AgentOptions,
@@ -63,5 +64,14 @@ export type { SavedWorkflow, WorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
 export { createWorkflowTool } from "./workflow-tool.js";
+export {
+  keyToAction,
+  type NavAction,
+  NavigatorModel,
+  NavigatorState,
+  openWorkflowNavigator,
+  renderNavigator,
+  type ViewKind,
+} from "./workflow-ui.js";
 export type { Worktree } from "./worktree.js";
 export { createWorktree, removeWorktree } from "./worktree.js";

package/src/task-panel.ts

@@ -0,0 +1,103 @@
+/**
+ * Background-run UX, mirroring Claude Code:
+ *  - A live task panel below the input lists in-progress runs while you keep working.
+ *    Focus it (↓) and press enter to open the full navigator.
+ *  - When a background run finishes, its result is delivered back into the
+ *    conversation so the paused task continues with the outcome.
+ */
+
+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 { ManagedRun, WorkflowManager } from "./workflow-manager.js";
+import type { WorkflowStorage } from "./workflow-saved.js";
+import { openWorkflowNavigator } from "./workflow-ui.js";
+
+const RUN_EVENTS = ["agentStart", "agentEnd", "phase", "log", "complete", "error", "stopped", "paused", "resumed"];
+
+export interface TaskPanelOptions {
+  storage?: WorkflowStorage;
+  cwd?: string;
+}
+
+function deliverText(run: ManagedRun): string {
+  const r = run.result?.result as { report?: unknown } | undefined;
+  const body =
+    r && typeof r.report === "string" && r.report.trim() ? r.report : JSON.stringify(run.result?.result, null, 2);
+  const tokens = run.result?.tokenUsage ? ` · ${run.result.tokenUsage.total.toLocaleString()} tokens` : "";
+  const agents = run.result?.agentCount ?? run.snapshot.agentCount;
+  return `✓ Workflow "${run.snapshot.name}" finished (${agents} agents${tokens}).\n\n${body}`;
+}
+
+/**
+ * Deliver a background run's result into the conversation when it completes or
+ * fails. Set up once per extension; idempotent via an internal guard.
+ */
+export function installResultDelivery(pi: ExtensionAPI, manager: WorkflowManager): void {
+  if ((manager as unknown as { __deliveryInstalled?: boolean }).__deliveryInstalled) return;
+  (manager as unknown as { __deliveryInstalled?: boolean }).__deliveryInstalled = true;
+
+  manager.on("complete", ({ runId }: { runId: string }) => {
+    const run = manager.getRun(runId);
+    if (run) void pi.sendMessage({ customType: "workflow-result", content: deliverText(run), display: true });
+  });
+  manager.on("error", ({ runId, error }: { runId: string; error?: { message?: string } }) => {
+    void pi.sendMessage({
+      customType: "workflow-result",
+      content: `✗ Workflow ${runId} failed: ${error?.message ?? "unknown error"}`,
+      display: true,
+    });
+  });
+}
+
+function renderPanel(manager: WorkflowManager, theme: Theme, focused: boolean): string[] {
+  const active = manager.listRuns().filter((r) => r.status === "running" || r.status === "paused");
+  if (!active.length) return [];
+  const rows = active.map((r) => {
+    const live = manager.getRun(r.runId);
+    const agents = live?.snapshot.agents ?? r.agents;
+    const done = agents.filter((a) => a.status === "done").length;
+    const icon = r.status === "paused" ? "⏸" : "◆";
+    const phase = live?.snapshot.currentPhase ? ` · ${live.snapshot.currentPhase}` : "";
+    return `  ${icon} ${r.workflowName}  ${done}/${agents.length} agents${phase}`;
+  });
+  const hint = focused
+    ? theme.fg("accent", "  enter: open · esc: back")
+    : theme.fg("dim", "  ↓ then enter, or /workflows, to open");
+  return [theme.bold(`Workflows running (${active.length}):`), ...rows, hint];
+}
+
+/**
+ * Install the live "workflows running" panel below the editor. Re-rendered on
+ * every manager event; focus + enter opens the navigator.
+ */
+export function installTaskPanel(
+  pi: ExtensionAPI,
+  manager: WorkflowManager,
+  ui: ExtensionUIContext,
+  opts: TaskPanelOptions = {},
+): void {
+  ui.setWidget(
+    "workflow-tasks",
+    (tui: TUI, theme: Theme) => {
+      const onEvent = () => tui.requestRender();
+      for (const ev of RUN_EVENTS) manager.on(ev, onEvent);
+      const comp: Component & { focused?: boolean; dispose?(): void } = {
+        focused: false,
+        render: () => renderPanel(manager, theme, comp.focused ?? false),
+        handleInput: (data: string) => {
+          const key = parseKey(data);
+          if (key === "enter" || key === "return" || key === "right") {
+            void openWorkflowNavigator(pi, manager, ui, opts);
+          }
+        },
+        invalidate: () => {},
+        dispose: () => {
+          for (const ev of RUN_EVENTS) manager.off(ev, onEvent);
+        },
+      };
+      return comp;
+    },
+    { placement: "belowEditor" },
+  );
+}

package/src/workflow-commands.ts

@@ -9,6 +9,7 @@ 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";
+import { openWorkflowNavigator } from "./workflow-ui.js";
 
 const STATUS_ICON: Record<string, string> = {
   pending: "·",
@@ -126,7 +127,18 @@ export function registerWorkflowCommands(
       const print = (text: string) => pi.sendMessage({ customType: "workflows", content: text, display: true });
 
       switch (sub) {
+        case "ui":
         case "list": {
+          // Interactive navigator when a UI is available; plain text otherwise
+          // (print/RPC mode) or when the user explicitly asks for `list`.
+          if (sub !== "list" && ctx.hasUI) {
+            await openWorkflowNavigator(pi, manager, ctx.ui, { storage: opts.storage, cwd: opts.cwd });
+            return;
+          }
+          if (parts.length === 0 && ctx.hasUI) {
+            await openWorkflowNavigator(pi, manager, ctx.ui, { storage: opts.storage, cwd: opts.cwd });
+            return;
+          }
           const runs = manager.listRuns();
           if (!runs.length) {
             await print("No workflow runs yet. Start one with a background workflow (background: true).");