@quintinshaw/pi-dynamic-workflows 1.7.1 → 1.9.0

package/README.md

@@ -51,7 +51,8 @@ Press `Esc` to cancel a running run; active subagents are aborted and surfaced a
 Ask for a background workflow (the model passes `background: true`) and it runs without blocking your session. Manage it with the `/workflows` command:
 
 ```text
-/workflows                 # list runs (default)
+/workflows                 # open the interactive navigator (plain list in print mode)
+/workflows list            # force the plain-text list
 /workflows status <id>     # watch a running run live (status bar), prints result when done
 /workflows stop <id>       # abort a running run
 /workflows pause <id>      # pause a running run
@@ -98,6 +99,7 @@ return { inventory, summary }
 | `parallel(thunks)` | Run an array of `() => agent(...)` thunks concurrently. Results returned in input order. |
 | `pipeline(items, ...stages)` | Fan items out through sequential stages. Each stage receives `(prev, original, index)`. |
 | `phase(title)` | Mark the current phase for the live progress view. |
+| `workflow(name, args)` | Run a saved workflow inline and return its result (one level deep; shares the global caps). |
 | `log(message)` | Append a workflow-level log line. |
 | `args` | Optional JSON value passed via the tool's `args` parameter. |
 | `budget` | `{ total, spent(), remaining() }` token-budget tracker. |
@@ -146,21 +148,17 @@ Scripts run inside a Node `vm` sandbox. Intentionally unavailable: `Date.now()`,
 - **Structured output** — JSON-Schema-validated subagent results
 - **Real token & cost accounting** — read from each subagent's SDK session (input / output / total / cost), with a character estimate only as fallback when a provider reports no usage; `budget` gates on the real total
 - **Real per-agent / per-phase model routing** — `opts.model` and `meta.phases[].model` actually select the model (resolved against your authed model registry), with graceful fallback
-- **`/workflows` command** — list, inspect, stop, pause, **resume**, and remove background runs; runs started with `background: true` are reachable from the command
+- **`/workflows` interactive navigator** — `/workflows` opens a focused TUI you drill through with the keyboard (runs → phases → agents → agent detail): `↑/↓` (or `j/k`) select, `enter`/`→` open, `esc`/`←` back, `j/k` scroll detail, `p` pause/resume, `x` stop, `s` save, `q` quit. In print/RPC mode it falls back to plain text
+- **Live task panel + background delivery** — while a `background: true` run is going, a "Workflows running" panel sits below the input (focus it and press `enter` to open the navigator); when the run finishes, its result is delivered back into the conversation so your paused task continues
 - **Bundled `/deep-research` & `/adversarial-review`** — `/deep-research` runs real web searches (via built-in `web_search` / `web_fetch` tools), extracts claims, cross-checks them across sources, and reports only what survived; `/adversarial-review` investigates a task then has independent skeptics try to refute each finding, keeping only those that clear an agreement threshold
 - **Saved workflows as `/<name>`** — save a run's script with `/workflows save <name>` and it becomes a reusable slash command; arguments are parsed (`key=value` and positionals) and passed through as `args`
+- **Nested `workflow()`** — call `await workflow('saved-name', args)` inside a script to run a saved workflow inline; nesting is one level deep and shares the parent's concurrency limiter, agent counter, and token budget so the global caps hold
 - **Resume** — each agent result is journaled by a deterministic call index; resuming replays the unchanged prefix from cache (no re-run, no tokens) and runs only new or edited calls live
 - **Worktree isolation** — `isolation: "worktree"` runs an agent in its own git worktree on a throwaway branch, so parallel agents can edit the same files without conflict; the worktree is torn down after (results are not auto-merged), and it falls back to a logged no-op outside a git repo
 - **Safety limits** — 1000-agent cap (`maxAgents`), per-agent timeout (`agentTimeoutMs`), recoverable-vs-fatal error classification
 - **Live progress + token/cost display**, `Esc` to abort
 - **Log persistence** to `.pi/workflows/runs/`
 
-## Roadmap
-
-Tracked toward closer parity with Claude Code dynamic workflows:
-
-- **Nested `workflow()`** to compose saved workflows inline
-
 ## How it works
 
 ```text

package/dist/index.d.ts

@@ -20,8 +20,9 @@ export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export { parseCommandArgs, registerAllSavedWorkflows, registerSavedWorkflow, } 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, JournalEntry, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
+export type { AgentOptions, JournalEntry, SharedRuntime, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
 export type { ManagedRun, WorkflowManagerOptions } from "./workflow-manager.js";
@@ -30,5 +31,6 @@ 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/dist/index.js

@@ -11,10 +11,12 @@ export { buildModelRoutingInstructions, parseModelRoutingFromMeta, resolveModelF
 export { createRunPersistence, generateRunId } from "./run-persistence.js";
 export { parseCommandArgs, registerAllSavedWorkflows, registerSavedWorkflow, } from "./saved-commands.js";
 export { createStructuredOutputTool } from "./structured-output.js";
+export { installResultDelivery, installTaskPanel } from "./task-panel.js";
 export { createWebFetchTool, createWebSearchTool, createWebTools } from "./web-tools.js";
 export { parseWorkflowScript, runWorkflow } from "./workflow.js";
 export { registerWorkflowCommands } from "./workflow-commands.js";
 export { WorkflowManager } from "./workflow-manager.js";
 export { createWorkflowStorage } from "./workflow-saved.js";
 export { createWorkflowTool } from "./workflow-tool.js";
+export { keyToAction, NavigatorModel, NavigatorState, openWorkflowNavigator, renderNavigator, } from "./workflow-ui.js";
 export { createWorktree, removeWorktree } from "./worktree.js";

package/dist/task-panel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 } from "@earendil-works/pi-coding-agent";
+import type { WorkflowManager } from "./workflow-manager.js";
+import type { WorkflowStorage } from "./workflow-saved.js";
+export interface TaskPanelOptions {
+    storage?: WorkflowStorage;
+    cwd?: string;
+}
+/**
+ * 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 declare function installResultDelivery(pi: ExtensionAPI, manager: WorkflowManager): void;
+/**
+ * Install the live "workflows running" panel below the editor. Re-rendered on
+ * every manager event; focus + enter opens the navigator.
+ */
+export declare function installTaskPanel(pi: ExtensionAPI, manager: WorkflowManager, ui: ExtensionUIContext, opts?: TaskPanelOptions): void;

package/dist/task-panel.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { parseKey } from "@earendil-works/pi-tui";
+import { openWorkflowNavigator } from "./workflow-ui.js";
+const RUN_EVENTS = ["agentStart", "agentEnd", "phase", "log", "complete", "error", "stopped", "paused", "resumed"];
+function deliverText(run) {
+    const r = run.result?.result;
+    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, manager) {
+    if (manager.__deliveryInstalled)
+        return;
+    manager.__deliveryInstalled = true;
+    manager.on("complete", ({ runId }) => {
+        const run = manager.getRun(runId);
+        if (run)
+            void pi.sendMessage({ customType: "workflow-result", content: deliverText(run), display: true });
+    });
+    manager.on("error", ({ runId, error }) => {
+        void pi.sendMessage({
+            customType: "workflow-result",
+            content: `✗ Workflow ${runId} failed: ${error?.message ?? "unknown error"}`,
+            display: true,
+        });
+    });
+}
+function renderPanel(manager, theme, focused) {
+    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, manager, ui, opts = {}) {
+    ui.setWidget("workflow-tasks", (tui, theme) => {
+        const onEvent = () => tui.requestRender();
+        for (const ev of RUN_EVENTS)
+            manager.on(ev, onEvent);
+        const comp = {
+            focused: false,
+            render: () => renderPanel(manager, theme, comp.focused ?? false),
+            handleInput: (data) => {
+                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/dist/workflow-commands.js

@@ -4,6 +4,7 @@
  */
 import { recomputeWorkflowSnapshot, renderWorkflowText } from "./display.js";
 import { registerSavedWorkflow } from "./saved-commands.js";
+import { openWorkflowNavigator } from "./workflow-ui.js";
 const STATUS_ICON = {
     pending: "·",
     running: "◆",
@@ -110,7 +111,18 @@ export function registerWorkflowCommands(pi, manager, opts = {}) {
             const id = parts[1];
             const print = (text) => 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).");

package/dist/workflow-manager.d.ts

@@ -23,12 +23,15 @@ export interface ManagedRun {
 export interface WorkflowManagerOptions {
     cwd?: string;
     concurrency?: number;
+    /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
+    loadSavedWorkflow?: (name: string) => string | undefined;
 }
 export declare class WorkflowManager extends EventEmitter {
     private runs;
     private persistence;
     private cwd;
     private concurrency;
+    private loadSavedWorkflow?;
     constructor(options?: WorkflowManagerOptions);
     /**
      * Start a workflow in the background.

package/dist/workflow-manager.js

@@ -10,10 +10,12 @@ export class WorkflowManager extends EventEmitter {
     persistence;
     cwd;
     concurrency;
+    loadSavedWorkflow;
     constructor(options = {}) {
         super();
         this.cwd = options.cwd ?? process.cwd();
         this.concurrency = options.concurrency ?? 8;
+        this.loadSavedWorkflow = options.loadSavedWorkflow;
         this.persistence = createRunPersistence(this.cwd);
     }
     /**
@@ -99,6 +101,7 @@ export class WorkflowManager extends EventEmitter {
                 args,
                 signal: managed.controller.signal,
                 concurrency: this.concurrency,
+                loadSavedWorkflow: this.loadSavedWorkflow,
                 resumeJournal,
                 resumeFromRunId: resumeJournal ? managed.runId : undefined,
                 onAgentJournal: (entry) => {

package/dist/workflow-tool.js

@@ -27,8 +27,9 @@ const workflowToolSchema = Type.Object({
     })),
 });
 export function createWorkflowTool(options = {}) {
+    const storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
     const manager = options.manager ?? new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
-    const _storage = options.storage ?? createWorkflowStorage(options.cwd ?? process.cwd());
+    const loadSavedWorkflow = (name) => storage.load(name)?.script;
     return defineTool({
         name: "workflow",
         label: "Workflow",
@@ -52,6 +53,7 @@ export function createWorkflowTool(options = {}) {
             "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
             "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
             "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+            "For workflow, you may call `await workflow('saved-name', argsObject)` to run a saved workflow inline and use its result; nesting is one level deep only, and the global 16-concurrent / 1000-total caps hold across the nesting.",
         ],
         parameters: workflowToolSchema,
         prepareArguments(args) {
@@ -100,6 +102,7 @@ export function createWorkflowTool(options = {}) {
                     concurrency: options.concurrency,
                     maxAgents: params.maxAgents,
                     agentTimeoutMs: params.agentTimeoutMs,
+                    loadSavedWorkflow,
                     onLog(message) {
                         snapshot.logs.push(message);
                         update();

package/dist/workflow-ui.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 } from "@earendil-works/pi-coding-agent";
+import type { WorkflowAgentSnapshot } from "./display.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+import type { WorkflowStorage } from "./workflow-saved.js";
+/** 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;
+}
+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 declare class NavigatorModel {
+    private readonly manager;
+    constructor(manager: Pick<WorkflowManager, "listRuns" | "getRun">);
+    private snapshot;
+    runs(): RunRow[];
+    runName(runId: string): string;
+    runStatus(runId: string): string;
+    phases(runId: string): PhaseRow[];
+    agents(runId: string, phase: string): AgentRow[];
+    agentDetail(runId: string, agentId: number): WorkflowAgentSnapshot | undefined;
+}
+/** Navigation state machine: a stack of (view, cursor) frames plus detail scroll. */
+export declare class NavigatorState {
+    private stack;
+    scroll: number;
+    private top;
+    get kind(): ViewKind;
+    get cursor(): number;
+    get runId(): string | undefined;
+    get phase(): string | undefined;
+    get agentId(): number | undefined;
+    get depth(): number;
+    /** Clamp the cursor to [0, count). */
+    clamp(count: number): void;
+    move(delta: number, count: number): void;
+    /** Drill into the selected item. Returns true if the view changed. */
+    drill(model: NavigatorModel): boolean;
+    /** Pop one level. Returns false when already at the top (caller should close). */
+    back(): boolean;
+    /** The runId the current view acts on (for pause/stop/save). */
+    activeRunId(model: NavigatorModel): string | undefined;
+}
+/** Build the lines for the current view. Pure: depends only on state + model + theme. */
+export declare function renderNavigator(state: NavigatorState, model: NavigatorModel, width: number, theme?: ThemeLike): string[];
+/** 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 declare function keyToAction(keyId: string | undefined, kind: ViewKind): NavAction;
+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 declare function openWorkflowNavigator(pi: ExtensionAPI, manager: WorkflowManager, ui: ExtensionUIContext, opts?: NavigatorOptions): Promise<void>;
+export {};