@fyeeme/pi-dynamic-workflows 0.1.1 → 1.1.0

package/README.md

@@ -29,7 +29,7 @@ npm install --ignore-scripts   # hydrate (the package is a workspace dep)
 ```
 
 This resolves [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)
-(`^0.3.0`, from the npm registry — no sibling-repo layout requirement).
+(`^0.5.0`, from the npm registry — no sibling-repo layout requirement).
 
 Then import the public API from the package root module (a TypeScript barrel; the package ships `.ts` source):
 
@@ -37,9 +37,11 @@ Then import the public API from the package root module (a TypeScript barrel; th
 import { defineWorkflow, runWorkflow } from "@fyeeme/pi-dynamic-workflows/src/index.ts";
 ```
 
-> The package's `pi.extensions` entry (`./index.ts`) registers the `run_workflow`
-> tool and the `/wf-inspect` command. The engine is also fully usable via the
-> imports shown here.
+> The package's `pi.extensions` entry registers the `run_workflow` tool plus
+> the shared sub-agent UI from pi-subagent-core (live agent widget above the
+> editor, FleetView below it, and the `/agents` transcript viewer — every
+> spawned workflow agent appears there under its step id). The engine is also
+> fully usable via the imports shown here.
 
 ---
 

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 **为 [pi](https://github.com/earendil-works/pi-mono) 打造的确定性 TypeScript 工作流编排。**
 
-把工作流定义成一份类型化的声明式步骤列表，运行后即可获得**可恢复、受预算约束、可中止**的执行。融合 pi-dynamic-workflows 设计（9 个步骤原语 + 启发式 planner + outcome 收集器）与 Claude Code 工作流引擎的协调机制（确定性沙箱、缓存键恢复、按 agent 中止、动态预算、失控上限）。
+把工作流定义成一份类型化的声明式步骤列表，运行后即可获得**可恢复、受预算约束、可中止**的执行。融合 pi-dynamic-workflows 设计（10 个步骤原语 + 启发式 planner + outcome 收集器）与 Claude Code 工作流引擎的协调机制（确定性沙箱、缓存键恢复、按 agent 中止、动态预算、失控上限）。
 
 语言：[English](README.md) | **中文**
 
@@ -10,7 +10,7 @@
 
 ## 为什么需要它
 
-一次运行 = 一份步骤列表（`agent` / `code` / `fan_out` / `loop_until` / `adversarial` / `tournament` / `classify_route`）。引擎保证：
+一次运行 = 一份步骤列表（`agent` / `code` / `log` / `fan_out` / `loop_until` / `loop_until_dry` / `adversarial` / `tournament` / `classify_route` / `sub_workflow`）。引擎保证：
 
 - **确定性** —— workflow `.ts` 文件经 AST 守卫，禁止 `Date.now()` / `Math.random()` / `new Date()`；run id 是 `(timestamp, sequence)` 的纯函数。
 - **恢复即不重派** —— 每个 agent 调用以 `sha256(workflow + prompt + signature)` 为键写入 journal；重跑同一 workflow 会回放缓存的 agent（零子进程派发）。
@@ -28,7 +28,7 @@
 npm install --ignore-scripts   # 水合（本包是 workspace 依赖）
 ```
 
-这会解析 npm registry 上的 [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)（`^0.3.0`，无需保持同级仓库目录结构）。
+这会解析 npm registry 上的 [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)（`^0.5.0`，无需保持同级仓库目录结构）。
 
 随后从包根模块导入公共 API（TypeScript barrel，包直接以 `.ts` 源码分发）：
 
@@ -36,7 +36,7 @@ npm install --ignore-scripts   # 水合（本包是 workspace 依赖）
 import { defineWorkflow, runWorkflow } from "@fyeeme/pi-dynamic-workflows/src/index.ts";
 ```
 
-> 包的 `pi.extensions` 入口（`./index.ts`）目前仍是脚手架——把 `run_workflow` 工具接进 pi 是后续工作。引擎本身已可经上述导入直接使用。
+> 包的 `pi.extensions` 入口注册 `run_workflow` 工具，并接入 pi-subagent-core 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中）。引擎本身也可经上述导入直接使用。
 
 ---
 
@@ -298,6 +298,8 @@ const result = await runWorkflow({ workflow: wf, cwd: tempDir, now: 1000, dispat
 | `adversarial` | `produce`、`rubric[]`、`judges?`、`minPass?` | `{ candidate, passed, passCount, judges }` |
 | `tournament` | `candidates`、`judges`、`produce` | `{ candidates, winner, judges }` |
 | `classify_route` | `classifier`、`routes: Record<cat, Step[]>`、`fallback?` | `{ category, matched, route, routeStatus }` |
+| `sub_workflow` | `workflow: WorkflowDefinition`、`input?`、`inheritBudget?` | `{ steps, status, workflowName, error }` |
+| `loop_until_dry` | `agent(item, i)`、`keyOf?`、`merge?`、`maxRounds?`、`dryThreshold?` | 发现项组成的数组 |
 
 每个步骤都接受 `id`、`retry?: { maxRetries }` 与
 `onBudgetExhaust?: "throw" | "null"`——`"null"` 下预算耗尽时该步骤返回 `null`

package/index.ts

@@ -5,27 +5,20 @@
  * workflow from within pi. The engine (src/runner) does the work; this entry
  * only adapts the agent's JSON args into the code-form WorkflowDefinition and
  * runs it with the default dispatch (real `pi --mode json` subprocesses).
+ *
+ * Live progress UI is delegated to the shared `@fyeeme/pi-subagent-core`
+ * extension (registered via the `pi.extensions` manifest alongside this
+ * entry): every spawned workflow agent notifies the process-global monitor
+ * through spawnAgent, rendering in the shared above-editor agent widget, the
+ * below-editor FleetView, and the `/agents` transcript viewer. This package
+ * ships no widget/command of its own — a former `wf:progress` widget and
+ * `/wf-inspect` command were removed in favor of that shared surface.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { buildRenderGroups, type PhaseDef } from "./src/ui-groups.ts";
-import { BOLD, CYAN, DIM, GREEN, RED, YELLOW, fmtTokens, stepIdOf } from "./src/format.ts";
 import { defineWorkflow, runWorkflow } from "./src/index.ts";
-import type { AgentCallId, Budget, RunResult, StageType, StepContext, StepDefinition, StepResult, StepStats, WorkflowDefinition } from "./src/types.ts";
+import type { Budget, StepContext, StepDefinition, WorkflowDefinition } from "./src/types.ts";
 import { WorkflowError } from "./src/errors.ts";
-import type { AgentLifecycleListeners } from "./src/lifecycle.ts";
-import { WorkflowInspect } from "./src/inspect.ts";
-
-/** Last completed run, exposed to /wf-inspect for interactive review. */
-let lastRunResult: RunResult | null = null;
-
-/** Phases of the most recent run — handed to /wf-inspect so the post-run view
- *  groups steps the same way the live widget did (C1 consistency). */
-let lastPhases: readonly PhaseDef[] | undefined;
-
-/** Active widget during a run — lets /wf-inspect show a live snapshot
- *  before the run completes (lastRunResult is only set post-run). */
-let activeWidget: { snapshot(): RunResult } | null = null;
 
 // ---------------------------------------------------------------------------
 // Parameter schema (the JSON-serializable workflow subset)
@@ -49,7 +42,7 @@ const StepSchema = Type.Union([
 	Type.Object({
 		id: Type.String(),
 		type: Type.Literal("log"),
-		message: Type.String({ description: "Narrative line emitted into the progress widget (zero dispatch / zero tokens)" }),
+		message: Type.String({ description: "Narrative line fired via the onLog lifecycle listener (zero dispatch / zero tokens)" }),
 		onBudgetExhaust: BudgetExhaustPolicy,
 	}),
 	Type.Object({
@@ -102,18 +95,11 @@ const BudgetSchema = Type.Object({
 	maxDurationMs: Type.Optional(Type.Number()),
 });
 
-const PhaseSchema = Type.Object({
-	title: Type.String({ description: "Phase display name" }),
-	detail: Type.Optional(Type.String({ description: "Short detail shown next to the phase title" })),
-	stepIds: Type.Array(Type.String(), { description: "Step ids belonging to this phase" }),
-});
-
 const WorkflowSchema = Type.Object({
 	name: Type.String(),
 	description: Type.Optional(Type.String()),
 	steps: Type.Array(StepSchema),
 	budget: Type.Optional(BudgetSchema),
-	phases: Type.Optional(Type.Array(PhaseSchema, { description: "Group steps into phases for progress-tree UI" })),
 });
 
 const RunWorkflowParams = Type.Object({
@@ -287,234 +273,6 @@ type StepData =
 			onBudgetExhaust?: "throw" | "null";
 	  };
 
-// ---------------------------------------------------------------------------
-// Progress widget — bridges lifecycle events → TUI setWidget
-// ---------------------------------------------------------------------------
-
-type CallStatus = "running" | "done" | "failed" | "skipped" | "retried" | "cached";
-
-interface CallInfo {
-	readonly stepId: string;
-	readonly status: CallStatus;
-	readonly tokens: number;
-	readonly model?: string;
-}
-
-export function buildProgressWidget(
-	steps: readonly { id: string; type: string }[],
-	setWidget: (lines: string[] | undefined) => void,
-	setStatus: (text: string | undefined) => void,
-	phases?: readonly PhaseDef[],
-): AgentLifecycleListeners & { cleanup(): void; snapshot(): RunResult } {
-	const start = Date.now();
-	let lastStreamRender = 0;
-	// Once cleanup() runs (run finished), late events from the abort window — the
-	// SIGTERM→SIGKILL grace period during which a child can still emit streamed
-	// deltas — must not re-create the panel via render()/setWidget.
-	let disposed = false;
-	const calls = new Map<AgentCallId, CallInfo>();
-	// C2: narrative lines emitted by `log` steps, keyed by step id.
-	const logLines = new Map<string, string>();
-	// C3: accumulated streaming text per in-flight call (delta chunks from onUpdate).
-	const streamText = new Map<string, string>();
-	// Live output capture: callId → the settled agent's final text (from onAgentEnd
-	// `output`), so a live snapshot shows REAL results, not fabricated progress text.
-	const callOutputs = new Map<string, string>();
-	// Every step starts at 0 expected agents; onAgentStart/onAgentCacheHit
-	// increment as calls fire (fan_out totals emerge at runtime). Pre-seeding
-	// non-fan_out steps to 1 double-counted (1→2 on start), leaving completed
-	// single-agent steps stuck showing [1/2].
-	const expected = new Map(steps.map((s) => [s.id, 0]));
-
-	// C1+D1: phase grouping — shared pure builder (also used by /wf-inspect).
-	const renderGroups = buildRenderGroups(steps, (s) => s.id, phases);
-
-	// callId format: `${stepId}#${n}` (e.g. "fan#2", "adv#produce") — see src/format.ts stepIdOf.
-
-	function render(): void {
-		const picons: Record<string, string> = {
-			done: GREEN("✓"),
-			failed: RED("✗"),
-			skipped: YELLOW("⏭"),
-			running: YELLOW("⏳"),
-			cached: GREEN("↻"),
-		};
-
-		const lines: string[] = [];
-		const renderStep = (s: { id: string; type: string }, indent: boolean): void => {
-			// C2: a `log` step renders as a distinct narrative line, not an agent row.
-			if (s.type === "log") {
-				const msg = logLines.get(s.id);
-				if (msg !== undefined) lines.push(`${indent ? "    " : "  "}${DIM(msg)}`);
-				return;
-			}
-			const total = expected.get(s.id) ?? 0;
-			const entries = [...calls.values()].filter((c) => c.stepId === s.id);
-			const running = entries.some((c) => c.status === "running");
-			const failed = entries.filter((c) => c.status === "failed").length;
-			const skipped = entries.filter((c) => c.status === "skipped").length;
-			const done = entries.filter((c) => c.status === "done" || c.status === "cached").length;
-			const cached = entries.filter((c) => c.status === "cached").length;
-			const tokens = entries.reduce((sum, c) => sum + c.tokens, 0);
-			const models = new Set(entries.map((c) => c.model).filter((m): m is string => Boolean(m)));
-
-			const icon = failed > 0 ? picons.failed
-				: skipped > 0 && done === 0 ? picons.skipped
-				: total > 0 && done >= total ? (cached > 0 ? picons.cached : picons.done)
-				: running ? picons.running
-				: DIM("○");
-
-			const progress = total > 1 ? ` [${done}/${total}]` : "";
-			const tok = tokens > 0 ? ` · ${fmtTokens(tokens)} tok` : "";
-			// A8/C4: show the serving model when known (single model shown; mixed
-			// fan_out models collapse to a count to avoid a noisy line).
-			const modelTag = models.size === 1 ? ` · ${[...models][0]}` : models.size > 1 ? ` · ${models.size} models` : "";
-			const pad = indent ? "    " : "  ";
-			lines.push(`${pad}${icon} ${s.id}${progress}${tok}${modelTag}`);
-		};
-
-		// Every phase group renders its header — a phase interrupted by ungrouped
-		// items produces two groups; deduplicating the second header would leave
-		// an indented, header-less orphan row (review L2).
-		for (const g of renderGroups) {
-			if (g.kind === "phase" && g.title) {
-				lines.push(`  ${BOLD(g.title)}${g.detail ? DIM(` — ${g.detail}`) : ""}`);
-			}
-			for (const s of g.items) renderStep(s, g.kind === "phase");
-		}
-
-		// C3: streaming tail — the most-recently-started running call's accumulated
-		// text, truncated to the last 3 lines, so concurrent fan-out previews only
-		// the active call instead of flooding the widget.
-		const running = [...calls.entries()].reverse().find(([id, c]) => c.status === "running" && streamText.has(id));
-		if (running) {
-			const [id] = running;
-			const text = streamText.get(id) ?? "";
-			const tail = text.split("\n").slice(-3);
-			for (const ln of tail) {
-				const clipped = ln.length > 100 ? `${ln.slice(0, 99)}…` : ln;
-				if (clipped) lines.push(DIM(`    ↳ ${clipped}`));
-			}
-		}
-
-
-		setWidget(lines.length > 0 ? lines : void 0);
-
-		const all = [...calls.values()];
-		const allDone = all.filter((c) => c.status !== "running").length;
-		const totalTokens = all.reduce((sum, c) => sum + c.tokens, 0);
-		const elapsed = ((Date.now() - start) / 1000).toFixed(0);
-		setStatus(`wf ${allDone}/${calls.size} agents · ${fmtTokens(totalTokens)} tok · ${elapsed}s`);
-	}
-
-	const record = (callId: string, status: CallStatus, tokens = 0, model?: string): void => {
-		if (disposed) return; // late settle after cleanup — do not re-create the panel
-		calls.set(callId, { stepId: stepIdOf(callId), status, tokens, model });
-		render();
-	};
-
-	return {
-		cleanup() {
-			disposed = true;
-			calls.clear();
-			streamText.clear();
-			setWidget(void 0);
-			setStatus(void 0);
-		},
-		/** Build a synthetic RunResult from the live calls map, so /wf-inspect
-		 *  can show in-progress agents before the run finishes. */
-		snapshot(): RunResult {
-			const snapSteps: StepResult[] = steps.map((s) => {
-				const entries = [...calls.values()].filter((c) => c.stepId === s.id);
-				const total = expected.get(s.id) ?? 0;
-				const done = entries.filter((c) => c.status === "done" || c.status === "cached").length;
-				const failed = entries.filter((c) => c.status === "failed").length;
-				const running = entries.filter((c) => c.status === "running").length;
-				const cached = entries.filter((c) => c.status === "cached").length;
-				const tokens = entries.reduce((sum, c) => sum + c.tokens, 0);
-				const status: StepResult["status"] = s.type === "log"
-					? "done" // narrative line, no agent call — never "skipped"
-					: failed > 0 ? "failed" : done >= total && total > 0 ? "done" : running > 0 ? "running" : "skipped";
-				// Real outputs from settled calls — NOT the fabricated `[n/m] running`
-				// progress string (that leaked into the detail pane as fake results).
-				const settled = [...calls.entries()]
-					.filter(([callId, c]) => c.stepId === s.id)
-					.map(([callId]) => callOutputs.get(callId))
-					.filter((o): o is string => Boolean(o));
-				const results = settled.length > 0
-					? (s.type === "fan_out" ? settled : settled[0])
-					: undefined;
-				return {
-					id: s.id,
-					type: s.type as StageType,
-					status,
-					results,
-					stats: { tokens, cost: 0, durationMs: 0, agents: entries.length, failures: failed },
-				};
-			});
-			const all = [...calls.values()];
-			const stats: StepStats = {
-				tokens: all.reduce((sum, c) => sum + c.tokens, 0),
-				cost: 0,
-				durationMs: Date.now() - start,
-				agents: all.length,
-				failures: all.filter((c) => c.status === "failed").length,
-			};
-			return { runId: "live", status: "completed", steps: snapSteps, stats };
-		},
-		onAgentStart(callId) {
-			const stepId = stepIdOf(callId);
-			expected.set(stepId, (expected.get(stepId) ?? 0) + 1);
-			record(callId, "running");
-		},
-		onAgentEnd(callId, ok, stats, model, output) {
-			// A skipped/retried/cached call's subprocess still settles (abort →
-			// notifyEnd(false)); do not overwrite the already-recorded terminal
-			// state with a "failed" stamp — the run's own bookkeeping marks the
-			// step skipped/retried, so the widget must show the same.
-			const cur = calls.get(callId);
-			if (cur && cur.status !== "running") {
-				streamText.delete(callId);
-				return;
-			}
-			record(callId, ok ? "done" : "failed", stats?.tokens ?? 0, model);
-			streamText.delete(callId); // free the accumulated tail once the call settles
-			if (output) callOutputs.set(callId, output);
-		},
-		onAgentSkip(callId) {
-			record(callId, "skipped");
-		},
-		onAgentRetry(callId) {
-			record(callId, "retried");
-		},
-		onAgentCacheHit(callId) {
-			const stepId = stepIdOf(callId);
-			expected.set(stepId, (expected.get(stepId) ?? 0) + 1);
-			record(callId, "cached");
-		},
-		onLog(stepId, message) {
-			if (disposed) return;
-			logLines.set(stepId, message);
-			render();
-		},
-		onUpdate(callId, partial) {
-			if (disposed) return;
-			// Bound the accumulated tail: the widget only ever renders the last 3
-			// lines (each clipped to ~100 chars), so keeping the full stream alive
-			// for the call's duration is pure memory growth on long generations.
-			streamText.set(callId, ((streamText.get(callId) ?? "") + partial).slice(-4096));
-			// Throttle: a high-frequency stream (fan_out × many deltas) would otherwise
-			// trigger a full O(steps×calls) render() per chunk. Bound to ~20fps; the
-			// final onAgentEnd render always fires, so the settled state is exact.
-			const nowMs = Date.now();
-			if (nowMs - lastStreamRender >= 50) {
-				lastStreamRender = nowMs;
-				render();
-			}
-		},
-	};
-}
-
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -573,34 +331,15 @@ export default function (pi: ExtensionAPI): void {
 				ctx.ui.notify(`Invalid model(s) dropped, using default: ${dropped.join(", ")}`, "warning");
 			}
 			const sanitizedWorkflow = { ...params.workflow, steps: sanitizedSteps };
-			const widget = buildProgressWidget(
-				sanitizedWorkflow.steps,
-				(lines) => ctx.ui.setWidget("wf:progress", lines),
-				(text) => ctx.ui.setStatus("wf:summary", text),
-				sanitizedWorkflow.phases,
-			);
-			activeWidget = widget;
-			lastPhases = sanitizedWorkflow.phases;
 			try {
 				const workflow = buildWorkflow(sanitizedWorkflow);
-				const listeners: AgentLifecycleListeners = {
-					onAgentStart: widget.onAgentStart,
-					onAgentEnd: widget.onAgentEnd,
-					onAgentSkip: widget.onAgentSkip,
-					onAgentRetry: widget.onAgentRetry,
-					onAgentCacheHit: widget.onAgentCacheHit,
-					onLog: widget.onLog,
-					onUpdate: widget.onUpdate,
-				};
 				const result = await runWorkflow({
 					workflow,
 					input: params.input,
 					cwd: params.cwd ?? ctx.cwd,
 					now: params.now ?? Date.now(),
 					signal,
-					listeners,
 				});
-				lastRunResult = result;
 
 				const lines = [
 					`workflow "${workflow.name}" → ${result.status} (run ${result.runId})`,
@@ -616,29 +355,7 @@ export default function (pi: ExtensionAPI): void {
 			} catch (e) {
 				const msg = e instanceof Error ? e.message : String(e);
 				return { content: [{ type: "text" as const, text: `run_workflow failed: ${msg}` }], details: { error: msg }, isError: true };
-			} finally {
-				activeWidget = null;
-				ctx.ui.setWidget("wf:progress", void 0);
-				widget.cleanup();
-			}
-		},
-	});
-
-	pi.registerCommand("wf-inspect", {
-		description: "Inspect the current/last workflow run (↑↓ select, enter detail, esc exit)",
-		handler: async (_args, ctx) => {
-			// Prefer a live snapshot while a run is in progress; fall back to
-			// the last completed result once the run has finished.
-			const r = activeWidget?.snapshot() ?? lastRunResult;
-			if (!r) {
-				ctx.ui.notify("No workflow run yet — run run_workflow first", "warning");
-				return;
 			}
-			await ctx.ui.custom(
-				(tui, _theme, _kb, done) =>
-					new WorkflowInspect(r, tui, () => done(undefined), lastPhases),
-				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "80%" } },
-			);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-dynamic-workflows",
-  "version": "0.1.1",
+  "version": "1.1.0",
   "description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
   ],
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.ts",
+      "./node_modules/@fyeeme/pi-subagent-core/sub-agent.ts"
     ]
   },
   "scripts": {
@@ -36,7 +37,7 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@fyeeme/pi-subagent-core": "^0.3.2"
+    "@fyeeme/pi-subagent-core": "^0.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.84.1",

package/src/format.ts

@@ -1,22 +1,13 @@
 /**
- * src/format.ts — shared display/parsing helpers (progress widget + /wf-inspect + runner).
+ * src/format.ts — shared parsing helper used by the runner.
  *
- * fmtTokens + ANSI color helpers: used by `buildProgressWidget` (index.ts) and
- * `WorkflowInspect` (src/inspect.ts) — one copy so the two UIs cannot drift.
  * stepIdOf: callId → step-id attribution, used by the runner (degraded-step
- * accounting) and the widget (grouping by step). Extracted from the verbatim
- * duplicates that used to live in each file.
+ * accounting, sibling abort scoping) and by the engine's dispatchOpts (the
+ * monitor `displayName` for the shared sub-agent UI). The former ANSI color
+ * helpers + fmtTokens were progress-widget/`/wf-inspect` rendering aids and
+ * were removed together with those surfaces (live progress is now rendered by
+ * the shared @fyeeme/pi-subagent-core extension).
  */
-export const GREEN = (s: string): string => `\x1b[32m${s}\x1b[0m`;
-export const RED = (s: string): string => `\x1b[31m${s}\x1b[0m`;
-export const YELLOW = (s: string): string => `\x1b[33m${s}\x1b[0m`;
-export const DIM = (s: string): string => `\x1b[2m${s}\x1b[0m`;
-export const CYAN = (s: string): string => `\x1b[36m${s}\x1b[0m`;
-export const BOLD = (s: string): string => `\x1b[1m${s}\x1b[0m`;
-
-export function fmtTokens(n: number): string {
-	return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
-}
 
 /** Extract the step id from a callId of the form `${stepId}#${n}` (e.g.
  *  "fan#2", "adv#produce", "cr#classify"). Falls back to the whole callId when

package/src/runner/stage-executor.ts

@@ -985,6 +985,11 @@ function dispatchOpts(
 		systemPrompt: spec.systemPrompt,
 		signal,
 		allowChildRecursion,
+		// UI display name for the shared sub-agent widget/FleetView (purely
+		// observational metadata consumed by the pi-subagent-core monitor): the
+		// step id ("fan", "adv"), so workflow rows are distinguishable from other
+		// agents. Cache hits never spawn, so they never appear — zero dispatch.
+		displayName: stepIdOf(callId),
 		// C3: bridge the spawn's streamed deltas to the lifecycle onUpdate listener,
 		// attributed to this callId. When no listener is registered, the subprocess
 		// drops the deltas (its onUpdate stays undefined — same as before).

package/src/types.ts

@@ -247,23 +247,11 @@ export interface StepRetry {
 	 * spec revision; add `retryStage` back with implementation when ready. */
 }
 
-/** A phase groups related steps for UI progress-tree rendering.
- *  Steps not assigned to any phase render under an implicit default group. */
-export interface PhaseDefinition {
-	readonly title: string;
-	readonly detail?: string;
-	readonly stepIds: readonly string[];
-	/** Optional model override for all agents in this phase. */
-	readonly model?: string;
-}
-
 export interface WorkflowDefinition {
 	readonly name: string;
 	readonly description?: string;
 	readonly steps: readonly StepDefinition[];
 	readonly budget?: Budget;
-	/** Optional phase groupings for progress-tree UI rendering. */
-	readonly phases?: readonly PhaseDefinition[];
 }
 
 /** Typed identity helper: gives a workflow literal full union checking. */

package/src/inspect.ts

@@ -1,237 +0,0 @@
-/**
- * WorkflowInspect — fullscreen overlay viewer with a master-detail split.
- *
- * Opened via `/wf-inspect` as an overlay (`ctx.ui.custom(..., { overlay: true })`)
- * sized to ~90% × 80% of the terminal. The body is split into two panes that
- * fill the wide overlay instead of wasting it on a single narrow column:
- *
- *   ┌─ STEPS (left ~30%) ──────┬─ DETAIL (right ~70%) ──────────────┐
- *   │ ✓ gather   · 1.2k tok    │ collected 3 sources on topic X     │
- *   │▸✓ fan      · 8.4k tok    │ [fan#1] Research alpha.            │
- *   │ ○ refine   · pending     │ 8.4k tok · 3 agent(s) · 1240ms     │
- *   └──────────────────────────┴────────────────────────────────────┘
- *
- * Left: compact step list (always visible, ↑↓/j/k selects, auto-scrolls).
- * Right: the selected step's full results + stats (PgUp/PgDn/Shift+↑↓/Home/End
- * scrolls the detail). No toggle — detail is always shown for the selection.
- * esc/q exits.
- */
-import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { RunResult, StepResult } from "./types.ts";
-import { buildRenderGroups, type PhaseDef } from "./ui-groups.ts";
-import { BOLD, CYAN, DIM, GREEN, RED, YELLOW, fmtTokens } from "./format.ts";
-
-/** Overlay maxHeight percentage — keep in sync with the index.ts overlayOptions. */
-const VIEWPORT_HEIGHT_PCT = 80;
-/** header(1) + sep(1) + col-header(1) + sep(1) + [body] + sep(1) + footer(1). */
-const CHROME_LINES = 6;
-const MIN_VIEWPORT = 3;
-/** Left pane share of the width (rest goes to the detail pane + separator). */
-const LEFT_PCT = 0.3;
-const MIN_LEFT = 16;
-
-/** Minimal TUI surface WorkflowInspect needs. Narrower than full `TUI`. */
-export interface InspectTUI {
-	requestRender(): void;
-	terminal: { readonly rows: number };
-}
-
-function statusIcon(status: StepResult["status"]): string {
-	switch (status) {
-		case "done":
-			return GREEN("✓");
-		case "failed":
-			return RED("✗");
-		case "skipped":
-			return YELLOW("⏭");
-		default:
-			return YELLOW("⏳");
-	}
-}
-
-/** Fit a (possibly ANSI-colored) string into exactly `w` visible columns:
- *  truncate with … if too long, pad with spaces if too short. */
-function field(s: string, w: number): string {
-	return truncateToWidth(s, w, "…", true);
-}
-
-export class WorkflowInspect {
-	private readonly result: RunResult;
-	private readonly tui: InspectTUI;
-	private readonly close: () => void;
-	private readonly phases?: readonly PhaseDef[];
-	private selected = 0;
-	/** Right-pane (detail) scroll offset; reset to 0 whenever selection changes. */
-	private detailScroll = 0;
-	/** Left-pane scroll offset; auto-adjusted to keep the selection visible. */
-	private leftScroll = 0;
-	/** Last known detail content height (set during render). Lets PgUp/PgDn
-	 *  clamp an Infinity detailScroll (set by End) before arithmetic, so
-	 *  End→PgUp is not swallowed by Infinity - vp = Infinity. */
-	private lastMaxDetailScroll = 0;
-	/** step index → row index within buildLeftLines() (phase title lines shift
-	 *  step rows past their raw array index — selection must scroll by row). */
-	private rowOfStep = new Map<number, number>();
-
-	constructor(result: RunResult, tui: InspectTUI, close: () => void, phases?: readonly PhaseDef[]) {
-		this.result = result;
-		this.tui = tui;
-		this.close = close;
-		this.phases = phases;
-	}
-
-	private viewportHeight(): number {
-		const rows = this.tui.terminal.rows > 0 ? this.tui.terminal.rows : 24;
-		return Math.max(MIN_VIEWPORT, Math.floor((rows * VIEWPORT_HEIGHT_PCT) / 100) - CHROME_LINES);
-	}
-
-	handleInput(data: string): void {
-		if (matchesKey(data, "escape") || data === "q" || data === "Q") {
-			this.close();
-			return;
-		}
-		const n = this.result.steps.length;
-		if (n === 0) return;
-		const vp = this.viewportHeight();
-		// Right-pane (detail) scroll.
-		if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
-			// End may have left detailScroll as the Infinity sentinel (clamped to a
-			// finite value only on the next render) — clamp before arithmetic so
-			// Infinity - vp stays Infinity and PgUp appears dead.
-			const cur = Math.min(this.detailScroll, this.lastMaxDetailScroll);
-			this.detailScroll = Math.max(0, cur - vp);
-			this.tui.requestRender();
-			return;
-		}
-		if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
-			const cur = Math.min(this.detailScroll, this.lastMaxDetailScroll);
-			this.detailScroll = cur + vp;
-			this.tui.requestRender();
-			return;
-		}
-		if (matchesKey(data, "home")) {
-			this.detailScroll = 0;
-			this.tui.requestRender();
-			return;
-		}
-		if (matchesKey(data, "end")) {
-			this.detailScroll = Number.POSITIVE_INFINITY;
-			this.tui.requestRender();
-			return;
-		}
-		// Selection moves — reset the detail pane to the top of the new step.
-		if (matchesKey(data, "up") || data === "k") {
-			this.selected = (this.selected - 1 + n) % n;
-			this.detailScroll = 0;
-			this.tui.requestRender();
-		} else if (matchesKey(data, "down") || data === "j") {
-			this.selected = (this.selected + 1) % n;
-			this.detailScroll = 0;
-			this.tui.requestRender();
-		}
-	}
-
-	invalidate(): void {
-		// No cached render state.
-	}
-
-	render(width: number): string[] {
-		const r = this.result;
-		const w = Math.max(width, 40);
-		const leftW = Math.max(MIN_LEFT, Math.floor(w * LEFT_PCT));
-		const rightW = Math.max(20, w - leftW - 1); // -1 for the "│" separator
-		const sep = DIM("│");
-		const hr = DIM("─".repeat(w));
-		const out: string[] = [];
-
-		// --- Header (full width) ---
-		const degraded = r.degradedSteps?.length ? ` · ${r.degradedSteps.length} degraded` : "";
-		const errTag = r.errorCategory ? ` [${r.errorCategory}]` : "";
-		const head = `${BOLD(`workflow ${CYAN(r.runId)} → ${r.status}`)}  ${DIM(`${r.stats.agents} agents · ${fmtTokens(r.stats.tokens)} tok · ${(r.stats.durationMs / 1000).toFixed(1)}s${degraded}`)}`;
-		out.push(field(r.error ? RED(`${head}  ${r.error}${errTag}`) : head, w));
-		out.push(hr);
-
-		// --- Column header ---
-		const selStep = r.steps[this.selected];
-		const colLeft = BOLD("STEPS");
-		const colRight = DIM(`DETAIL${selStep ? ` · ${selStep.id} (${selStep.type})` : ""}`);
-		out.push(field(colLeft, leftW) + sep + field(colRight, rightW));
-		out.push(hr);
-
-		// --- Body: two panes zipped row-by-row ---
-		const vp = this.viewportHeight();
-		const leftLines = this.buildLeftLines(leftW);
-		// Keep the selected step visible in the left pane. leftLines may start
-		// with phase title rows, so the selection's ROW (not its raw step index)
-		// drives the window — otherwise phases push the selected step off-screen.
-		const selRow = this.rowOfStep.get(this.selected) ?? this.selected;
-		if (selRow < this.leftScroll) this.leftScroll = selRow;
-		else if (selRow >= this.leftScroll + vp) this.leftScroll = selRow - vp + 1;
-		this.leftScroll = Math.max(0, Math.min(this.leftScroll, Math.max(0, leftLines.length - vp)));
-
-		const rightLines = selStep ? this.buildRightLines(selStep) : [DIM("(no step)")];
-		const maxDetailScroll = Math.max(0, rightLines.length - vp);
-		this.lastMaxDetailScroll = maxDetailScroll;
-		this.detailScroll = Math.max(0, Math.min(this.detailScroll, maxDetailScroll));
-
-		for (let i = 0; i < vp; i++) {
-			const l = field(leftLines[this.leftScroll + i] ?? "", leftW);
-			const rr = field(rightLines[this.detailScroll + i] ?? "", rightW);
-			out.push(l + sep + rr);
-		}
-
-		// --- Footer ---
-		out.push(hr);
-		const footL = DIM("↑↓/j/k select · PgUp/PgDn/Shift+↑↓ scroll detail · Home/End · esc exit");
-		const dPct = rightLines.length <= vp ? "all" : `${Math.round(((this.detailScroll + vp) / rightLines.length) * 100)}%`;
-		const footR = DIM(`${this.detailScroll}/${rightLines.length} (${dPct}) · ${this.selected + 1}/${r.steps.length} steps`);
-		out.push(field(footL, leftW) + sep + field(footR, rightW));
-		return out;
-	}
-
-	/** Left pane: one compact line per step (status · id · type · tokens). */
-	private buildLeftLines(w: number): string[] {
-		const idxOf = new Map(this.result.steps.map((s, i) => [s.id, i]));
-		const groups = buildRenderGroups(this.result.steps, (s) => s.id, this.phases);
-		const lines: string[] = [];
-		const rowOf = new Map<number, number>();
-		// Every phase group renders its header (a phase interrupted by ungrouped
-		// items produces two groups; deduplicating the second header would leave
-		// an indented, header-less orphan row).
-		for (const g of groups) {
-			if (g.kind === "phase" && g.title) {
-				lines.push(field(BOLD(g.title), w));
-			}
-			for (const s of g.items) {
-				const i = idxOf.get(s.id) ?? 0;
-				rowOf.set(i, lines.length);
-				const sel = i === this.selected;
-				const tok = s.stats.tokens > 0 ? ` · ${fmtTokens(s.stats.tokens)} tok` : "";
-				const body = `${statusIcon(s.status)} ${s.id} ${DIM(`(${s.type})${tok}`)}`;
-				lines.push(field(sel ? `${CYAN("▸")}${BOLD(body)}` : ` ${body}`, w));
-			}
-		}
-		this.rowOfStep = rowOf;
-		return lines;
-	}
-
-	/** Right pane: the selected step's full results + a stats footer line.
-	 *  `results === undefined` means a live snapshot with nothing settled yet —
-	 *  show an honest "in progress" marker instead of JSON.stringify(undefined). */
-	private buildRightLines(s: StepResult): string[] {
-		const lines: string[] = [];
-		if (s.results === undefined) {
-			lines.push(DIM("(in progress — no agent output settled yet)"));
-		} else {
-			const body = typeof s.results === "string" ? s.results : JSON.stringify(s.results, null, 2);
-			for (const ln of body.split("\n")) lines.push(DIM(ln));
-		}
-		lines.push("");
-		lines.push(DIM(`${fmtTokens(s.stats.tokens)} tok · ${s.stats.agents} agent(s) · ${s.stats.durationMs}ms · ${s.stats.failures} fail`));
-		return lines;
-	}
-
-	dispose(): void {
-		// Nothing to release.
-	}
-}

package/src/ui-groups.ts

@@ -1,43 +0,0 @@
-/**
- * Shared phase-grouping logic (C1+D1) — used by the live progress widget
- * (index.ts) and the `/wf-inspect` view (src/inspect.ts) so both render with
- * identical grouping. Extracted as a pure function so it is unit-testable.
- *
- * Declared phases carry a header; ungrouped items collect into a header-less
- * default group interleaved at declaration order. When no phases are declared
- * (or none match), the whole item list is one default group (flat render).
- */
-
-export interface PhaseDef {
-	readonly title: string;
-	readonly detail?: string;
-	readonly stepIds: readonly string[];
-}
-
-export interface RenderGroup<T> {
-	readonly kind: "phase" | "default";
-	readonly title?: string;
-	readonly detail?: string;
-	readonly items: T[];
-}
-
-export function buildRenderGroups<T>(
-	items: readonly T[],
-	getId: (item: T) => string,
-	phases?: readonly PhaseDef[],
-): RenderGroup<T>[] {
-	const stepPhase = new Map<string, { title: string; detail?: string }>();
-	if (phases && phases.length > 0) {
-		for (const ph of phases) for (const sid of ph.stepIds) stepPhase.set(sid, { title: ph.title, detail: ph.detail });
-	}
-	const groups: RenderGroup<T>[] = [];
-	for (const item of items) {
-		const ph = stepPhase.get(getId(item));
-		const key = ph ? `phase:${ph.title}` : "default";
-		const last = groups[groups.length - 1];
-		const lastKey = last ? (last.kind === "phase" ? `phase:${last.title}` : "default") : "";
-		if (last && lastKey === key) last.items.push(item);
-		else groups.push(ph ? { kind: "phase", title: ph.title, detail: ph.detail, items: [item] } : { kind: "default", items: [item] });
-	}
-	return groups;
-}