@fyeeme/pi-dynamic-workflows 0.1.1 → 2.0.1

package/README.md

@@ -1,5 +1,12 @@
 # @fyeeme/pi-dynamic-workflows
 
+**2.0.0 — major release** (from 1.1.0 on npm), part of the 2.0 extensions family wave:
+
+- **Composed sub-agent stack** — the extension factory composes [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents) 2.1.1 from its npm dependency: the live agent fleet surface and the `subagent` tool work out of the box; no manifest path wiring, no separate install.
+- **Run persistence** — journaled runs under `.pi/workflows/` (journal + manifest): a re-run resumes cached agent calls keyed by `sha256(workflow + prompt + signature)` with zero re-dispatch, and the manifest tracks live state for inspection.
+- **Per-call budget override** — `run_workflow` accepts a `budget` object that merges over the workflow definition's own `maxAgents`/`maxTokens`, making "halve the fan-out for large diffs" an actual parameter.
+- **Authoring aids shipped** — `workflow-author` skill, `/wf-*` prompts, and seed workflows (`review-local-diff`, `review-extension`) using `import type` for load determinism.
+
 **Deterministic TypeScript workflow orchestration for [pi](https://github.com/earendil-works/pi-mono).**
 
 Define a workflow as a declarative list of typed steps, run it, and get resumable, budget-bounded, abortable execution. Fuses the pi-dynamic-workflows design (10 step primitives + heuristic planner + outcome collectors) with Claude Code's workflow-engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort, dynamic budget, runaway caps).
@@ -20,16 +27,20 @@ A workflow run is a list of steps (`agent` / `code` / `log` / `fan_out` / `loop_
 
 ---
 
-## Install
+**Batteries included**: this package's extension factory composes
+[`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)
+(the single below-editor fleet surface with its conversation viewer, and the `subagent` tool)
+from its version-pinned dependency copy, so workflow runs are observable out
+of the box. A standalone pi-subagents install is optional and coexists
+(idempotent composition).
 
-This is a pi extension package (workspace / local), not yet published to npm. From a pi workspace:
+## Install
 
 ```bash
-npm install --ignore-scripts   # hydrate (the package is a workspace dep)
+pi install npm:@fyeeme/pi-dynamic-workflows
 ```
 
-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).
+This resolves [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents) 2.1.1 from the npm registry (the composed sub-agent stack lights up with no separate install).
 
 Then import the public API from the package root module (a TypeScript barrel; the package ships `.ts` source):
 
@@ -37,9 +48,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-subagents (the below-editor fleet roster —
+> every spawned workflow agent appears there under its stable id; ↓ at an
+> empty editor opens the list, Enter shows an agent's live transcript). 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（零子进程派发）。
@@ -20,6 +20,12 @@
 
 ---
 
+**开箱即用**：本包的扩展工厂会组合
+[`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)
+（实时代理 UI——编辑器上方 widget、FleetView、`/agents`——以及 `subagent`
+工具），且版本钉定在自身依赖副本上，工作流运行的可观测性开箱即得。
+单独安装 pi-subagents 是可选的，二者可共存（组合幂等）。
+
 ## 安装
 
 这是一个 pi 扩展包（workspace / 本地），尚未发布到 npm。在 pi workspace 中：
@@ -28,7 +34,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-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents)（无需保持同级仓库目录结构）。
 
 随后从包根模块导入公共 API（TypeScript barrel，包直接以 `.ts` 源码分发）：
 
@@ -36,7 +42,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-subagents 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中；需先安装 @fyeeme/pi-subagents，见上方提示）。引擎本身也可经上述导入直接使用。
 
 ---
 
@@ -298,6 +304,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,34 +5,31 @@
  * 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-subagents`
+ * 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 { truncateHead } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
 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 piSubagents from "@fyeeme/pi-subagents";
 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;
+import { discoverWorkflowLibrary, loadLibraryWorkflow } from "./src/library.ts";
 
 // ---------------------------------------------------------------------------
 // Parameter schema (the JSON-serializable workflow subset)
 // ---------------------------------------------------------------------------
 
 const BudgetExhaustPolicy = Type.Optional(
-	Type.Union([Type.Literal("throw"), Type.Literal("null")], {
+	StringEnum(["throw", "null"] as const, {
 		description: "Budget-exhaustion policy for this step: \"throw\" (default) aborts the run; \"null\" degrades this step to a null result so siblings/downstream continue (the run result records degraded steps).",
 	}),
 );
@@ -49,7 +46,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,22 +99,38 @@ 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({
-	workflow: WorkflowSchema,
+	source: Type.Optional(
+		StringEnum(["inline", "library"] as const, {
+			description:
+				'Where the workflow comes from. "inline" (default): the `workflow` parameter (JSON subset). "library": a named workflow from the discovered library (bundled workflows/ + project .pi/workflows/lib/, project overrides bundled) — full step set incl. loop_until, loaded through the determinism guard.',
+			default: "inline",
+		}),
+	),
+	name: Type.Optional(
+		Type.String({ description: 'Library workflow name (required for source: "library").' }),
+	),
+	workflow: Type.Optional(WorkflowSchema),
+	budget: Type.Optional(
+		Type.Object(
+			{
+				maxAgents: Type.Optional(Type.Number()),
+				maxTokens: Type.Optional(Type.Number()),
+				maxDurationMs: Type.Optional(Type.Number()),
+			},
+			{
+				description:
+					"Per-call budget override (library mode only — inline workflows declare budget inside `workflow.budget`). Fields merge over the workflow definition's own budget; use it to tighten a library workflow for a large input without editing the definition. Omitted fields keep the definition's values.",
+			},
+		),
+	),
 	input: Type.Optional(Type.String({ description: "Initial ctx.input (also {{input}} in prompts)" })),
 	cwd: Type.Optional(Type.String({ description: "Working dir + journal base. Default: session cwd" })),
 	now: Type.Optional(Type.Number({ description: "Deterministic inception ms (resume seed). Default: Date.now()" })),
@@ -287,234 +300,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
 // ---------------------------------------------------------------------------
@@ -529,6 +314,13 @@ function dropInvalidModel(id: string, model: string | undefined, validIds: Set<s
 }
 
 export default function (pi: ExtensionAPI): void {
+	// Compose the subagent stack (live agent UI — widget / FleetView /agents —
+	// and the `subagent` tool) from the pinned dependency copy. The tool
+	// registers exactly once per process (guard in pi-subagents' index.ts):
+	// coexists with a standalone pi-subagents install and with other consumers
+	// (pi-review) composing it.
+	piSubagents(pi);
+
 	pi.registerTool({
 		name: "run_workflow",
 		label: "Run workflow",
@@ -543,64 +335,85 @@ export default function (pi: ExtensionAPI): void {
 		parameters: RunWorkflowParams,
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			// Scoped-models: when the session restricts models (--models /
-			// enabledModels), validate step models against that scope; otherwise
-			// fall back to the full registry. Invalid ids (e.g. "sonnet") are
-			// dropped so the subprocess uses the default session model.
-			const scoped = ctx.scopedModels;
-			const validIds = scoped && scoped.length > 0
-				? new Set(scoped.map((s) => s.model.id))
-				: new Set(ctx.modelRegistry.getAll().map((m) => m.id));
-			const dropped: string[] = [];
-			const sanitizedSteps = params.workflow.steps.map((s) => {
-				const model = "model" in s ? dropInvalidModel(s.id, s.model, validIds, dropped) : undefined;
-				if (s.type === "classify_route") {
-					// Route/fallback sub-step models must be sanitized too — the schema
-					// promises "Invalid ids are dropped", which routeStepToCode otherwise
-					// passes straight through to the subprocess.
-					const routes = Object.fromEntries(
-						Object.entries(s.routes).map(([cat, rs]) => [
-							cat,
-							rs.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) })),
-						]),
-					) as typeof s.routes;
-					const fallback = s.fallback?.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) }));
-					return { ...s, model, routes, fallback };
+			// Library mode: resolve the named workflow from the discovered
+			// library (ast-guard + jiti via the existing loader), then run it
+			// through the same runner as inline mode. Unknown name → list the
+			// available workflows instead of spawning anything.
+			let workflowDef: WorkflowDefinition | undefined;
+			if (params.source === "library") {
+				if (!params.name)
+					throw new Error('run_workflow: source "library" requires a workflow `name`.');
+				try {
+					const entry = await loadLibraryWorkflow(params.name, params.cwd ?? ctx.cwd);
+					if (!entry) {
+						const lib = await discoverWorkflowLibrary(params.cwd ?? ctx.cwd);
+						const available = [...lib.values()]
+							.map((e) => `- ${e.name}${e.description ? ` — ${e.description}` : ""} (${e.filePath})`)
+							.join("\n");
+						throw new Error(`run_workflow: no library workflow named "${params.name}". Available:\n${available || "(none)"}`);
+					}
+					workflowDef = entry.workflow;
+				} catch (e) {
+					if (e instanceof Error && e.message.startsWith("run_workflow:")) throw e;
+					const msg = e instanceof Error ? e.message : String(e);
+					throw new Error(`run_workflow failed: ${msg}`);
 				}
-				return { ...s, model };
-			});
-			if (dropped.length > 0) {
-				ctx.ui.notify(`Invalid model(s) dropped, using default: ${dropped.join(", ")}`, "warning");
+			} else {
+				if (!params.workflow)
+					throw new Error('run_workflow: provide either a `workflow` (inline) or `name` with source "library".');
 			}
-			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,
-				};
+
+				try {
+					let workflow: WorkflowDefinition;
+					if (params.source === "library") {
+						// Library workflows are authored TS (models already validated at
+						// authoring time; the determinism guard ran at load). A per-call
+						// `budget` merges over the definition's own budget.
+						workflow =
+							workflowDef && params.budget
+								? { ...workflowDef, budget: { ...workflowDef.budget, ...params.budget } }
+								: workflowDef!;
+					} else {
+					// Scoped-models: when the session restricts models (--models /
+					// enabledModels), validate step models against that scope; otherwise
+					// fall back to the full registry. Invalid ids (e.g. "sonnet") are
+					// dropped so the subprocess uses the default session model.
+					const scoped = ctx.scopedModels;
+					const validIds =
+						scoped && scoped.length > 0
+							? new Set(scoped.map((s) => s.model.id))
+							: new Set(ctx.modelRegistry.getAll().map((m) => m.id));
+					const dropped: string[] = [];
+					const sanitizedSteps = params.workflow!.steps.map((s) => {
+						const model = "model" in s ? dropInvalidModel(s.id, s.model, validIds, dropped) : undefined;
+						if (s.type === "classify_route") {
+							// Route/fallback sub-step models must be sanitized too — the schema
+							// promises "Invalid ids are dropped", which routeStepToCode otherwise
+							// passes straight through to the subprocess.
+							const routes = Object.fromEntries(
+								Object.entries(s.routes).map(([cat, rs]) => [
+									cat,
+									rs.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) })),
+								]),
+							) as typeof s.routes;
+							const fallback = s.fallback?.map((r) => ({ ...r, model: dropInvalidModel(`${s.id}.${r.id}`, r.model, validIds, dropped) }));
+							return { ...s, model, routes, fallback };
+						}
+						return { ...s, model };
+					});
+					if (dropped.length > 0) {
+						ctx.ui.notify(`Invalid model(s) dropped, using default: ${dropped.join(", ")}`, "warning");
+					}
+					const sanitizedWorkflow = { ...params.workflow!, steps: sanitizedSteps };
+					workflow = buildWorkflow(sanitizedWorkflow);
+				}
 				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})`,
@@ -608,37 +421,35 @@ export default function (pi: ExtensionAPI): void {
 					`stats: ${result.stats.agents} agent(s), ${result.stats.tokens} tokens, $${result.stats.cost.toFixed(4)}`,
 				];
 				if (result.error) lines.push(`error: ${result.error}`);
+				if (result.journalFile) lines.push(`full run details: ${result.journalFile}`);
+
+				// Failed/aborted runs are tool errors: throw so pi sets isError and
+				// reports the summary to the model (returning a value never sets the
+				// error flag). Completed runs with degraded steps stay a normal result.
+				const text = truncateHead(lines.join("\n"), { maxLines: 2000, maxBytes: 50_000 }).content;
+				if (result.status !== "completed") {
+					throw new Error(text);
+				}
+				const u = result.stats.usage;
 				return {
-					content: [{ type: "text" as const, text: lines.join("\n") }],
+					content: [{ type: "text" as const, text }],
 					details: result,
-					isError: result.status !== "completed",
+					// Surface nested-agent usage so pi's footer //session totals include it.
+					usage: u
+						? {
+								input: u.input,
+								output: u.output,
+								cacheRead: u.cacheRead,
+								cacheWrite: u.cacheWrite,
+								totalTokens: result.stats.tokens,
+								cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: result.stats.cost },
+							}
+						: undefined,
 				};
 			} 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;
+				throw new Error(`run_workflow failed: ${msg}`);
 			}
-			await ctx.ui.custom(
-				(tui, _theme, _kb, done) =>
-					new WorkflowInspect(r, tui, () => done(undefined), lastPhases),
-				{ overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: "80%" } },
-			);
 		},
 	});
 }