@fyeeme/pi-dynamic-workflows 1.1.0 → 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.5.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):
 
@@ -38,10 +49,10 @@ import { defineWorkflow, runWorkflow } from "@fyeeme/pi-dynamic-workflows/src/in
 ```
 
 > 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.
+> 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

@@ -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.5.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` 入口注册 `run_workflow` 工具，并接入 pi-subagent-core 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中）。引擎本身也可经上述导入直接使用。
+> 包的 `pi.extensions` 入口注册 `run_workflow` 工具，并接入 pi-subagents 的共享子代理 UI（编辑器上方实时 agent widget、下方 FleetView、`/agents` 转录查看器——每个工作流 agent 以其 step id 出现在其中；需先安装 @fyeeme/pi-subagents，见上方提示）。引擎本身也可经上述导入直接使用。
 
 ---
 

package/index.ts

@@ -6,7 +6,7 @@
  * 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`
+ * 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
@@ -15,17 +15,21 @@
  * `/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 piSubagents from "@fyeeme/pi-subagents";
 import { defineWorkflow, runWorkflow } from "./src/index.ts";
 import type { Budget, StepContext, StepDefinition, WorkflowDefinition } from "./src/types.ts";
 import { WorkflowError } from "./src/errors.ts";
+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).",
 	}),
 );
@@ -103,7 +107,30 @@ const WorkflowSchema = Type.Object({
 });
 
 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,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",
@@ -301,38 +335,78 @@ 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 };
-			try {
-				const workflow = buildWorkflow(sanitizedWorkflow);
+
+				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,
@@ -347,14 +421,34 @@ 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 };
+				throw new Error(`run_workflow failed: ${msg}`);
 			}
 		},
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-dynamic-workflows",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "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",
@@ -22,14 +22,22 @@
     "*.ts",
     "src/**/*.ts",
     "sessions/**/*.ts",
+    "workflows/**/*.ts",
+    "skills/**/*.md",
+    "prompts/**/*.md",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./index.ts",
-      "./node_modules/@fyeeme/pi-subagent-core/sub-agent.ts"
+      "./index.ts"
+    ],
+    "skills": [
+      "skills/workflow-author"
+    ],
+    "prompts": [
+      "prompts"
     ]
   },
   "scripts": {
@@ -37,20 +45,20 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@fyeeme/pi-subagent-core": "^0.5.0"
+    "@fyeeme/pi-subagents": "2.1.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.84.1",
-    "@earendil-works/pi-coding-agent": ">=0.84.1",
-    "@earendil-works/pi-tui": ">=0.84.1",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
     "jiti": ">=2.0.0",
     "typebox": ">=1.0.0",
     "typescript": ">=5.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.1",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.1",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/node": "22.19.19",
     "jiti": "2.7.0",
     "typebox": "1.1.38",

package/prompts/implement-and-review.md

@@ -0,0 +1,29 @@
+---
+description: Implement → review → fix loop via successive subagent calls
+argument-hint: <what to implement>
+---
+Execute this three-stage loop with the `subagent` tool — one call per stage.
+You are the coordinator: pass each stage's complete output text into the next
+stage's `task` yourself (chain mode no longer exists).
+
+1. **Implement** — call `subagent` with agent `worker`, task: $@ plus any repo
+   context it needs. Ask for the final implementation summary in the result.
+
+2. **Review** — call `subagent` with agent `reviewer`. Its task must begin:
+   "Review the following implementation." followed by the worker's COMPLETE
+   result verbatim, plus the files/areas touched.
+
+3. **Fix** — if and only if the reviewer reported issues, one more `worker`
+   call: "Apply this feedback to your earlier implementation." followed by the
+   reviewer's findings verbatim.
+
+Rules:
+
+- Forward results between stages verbatim — never paraphrase or summarize;
+  each subagent has zero memory of its predecessor.
+- Run stages strictly sequentially; a later stage always needs the earlier
+  stage's full output as input.
+- Skip stages 2–3 only for trivial changes (< ~20 lines, no behavior change);
+  state explicitly that you did so and why.
+- Finish by reporting: what was implemented, the review verdict, and anything
+  still open.

package/prompts/wf-review.md

@@ -0,0 +1,30 @@
+---
+description: Heavy review pipeline via deterministic workflow (budget + resume + adversarial verify)
+---
+Run the heavy review pipeline now. Target: $@
+
+First resolve the diff yourself (run `git diff` against the appropriate
+range — upstream merge-base if configured, else HEAD; pass the diff text as
+the workflow `input`).
+
+Then call `run_workflow` with `source: "library"`:
+
+- For a plain local diff → name `review-local-diff` (5 finders at
+  parallelism 4, adversarial verify judges 3 / minPass 2, budget 12 agents /
+  2M tokens).
+- For changed packages under an extensions submodule → name
+  `review-extension` (one reviewer per changed package at parallelism 3).
+
+Budget guidance: pass a per-call `budget` override on the run_workflow call —
+halve `maxAgents` when the diff exceeds ~150 files; without an override the
+workflow's own declared budget applies.
+
+Resume behavior: on journal keys already present from a prior partial run
+the engine skips completed steps — do not re-dispatch them yourself.
+
+When the run completes, report the merged, verified findings via
+`review_report` (if available) or as a markdown list ranked most-severe
+first.
+
+For tuning the pipeline itself (steps, rubric, determinism constraints),
+load the workflow-author skill.

package/sessions/spawn.ts

@@ -3,7 +3,7 @@
  *
  * Thin barrel over src/agent/dispatch.ts: the spawn registry + per-agent
  * abort primitives. The core spawn implementation lives in
- * `@fyeeme/pi-subagent-core`; skip/retry (workflows-specific) stay in
+ * `@fyeeme/pi-subagents`; skip/retry (workflows-specific) stay in
  * dispatch.ts.
  */
 export {

package/skills/workflow-author/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: workflow-author
+description: "Author and tune deterministic workflow definitions for run_workflow: step-type selection, rubric writing, the single-file determinism constraint, budget/parallelism as declared data, and resume semantics."
+---
+
+# Authoring workflow-library definitions
+
+A library workflow is a single `.ts` file under `.pi/workflows/lib/`
+(project) or the package's bundled `workflows/` (reference examples:
+`review-local-diff`, `review-extension`). It exports a workflow and becomes
+runnable by name (`run_workflow` with `source: "library"`) on the next call —
+dropping the file in IS the registration; no code change, no restart.
+
+## The hard constraint: single-file determinism
+
+The loader runs the ast determinism guard on the entry source and REJECTS
+`Date.now()`, `Math.random()`, and `new Date()` **before** executing. This is
+not a style rule — cache-key resume is only sound when the same workflow
+source produces the same cache keys. The guard scans **only the entry file**:
+a helper imported from another file could smuggle in non-determinism and
+silently break resume. Therefore: **library workflows must stay
+single-file.** Inline everything; if you need `now`, the engine passes it
+(the `now` run parameter / `ctx` plumbing) — never read the clock yourself.
+
+## Choosing step types
+
+| Need | Step | Notes |
+|---|---|---|
+| One LLM call | `agent` | prompt may be a function of `ctx.input` / `ctx.step(id)` |
+| N parallel calls over a list | `fan_out` | `over` may be dynamic (`ctx => …`); declare `parallelism`; `merge` folds results |
+| Produce + judge | `adversarial` | rubric criteria become judge prompts; `judges`/`minPass` (majority default) |
+| Best-of-N | `tournament` | candidates × judges |
+| Route by classification | `classify_route` | classifier replies `{category}`; routes + fallback |
+| Iterate to convergence | `loop_until` | `until` condition + `maxIterations` (TS-only — library files only, not inline JSON) |
+| Zero-token narrative | `log` | journal annotation only |
+
+## Writing rubrics (adversarial / tournament)
+
+A rubric entry is a judge prompt, not a checkbox. Write each criterion as a
+falsifiable, self-contained sentence: `"finding is concretely actionable
+(file:line present)"` — not `"quality"`. 2–4 criteria; a judge that cannot
+verify a criterion from the material in front of it will guess, and guessing
+flattens the verdict distribution.
+
+## Budget and parallelism are data
+
+`budget: { maxAgents, maxTokens, maxDurationMs }` at the workflow level and
+`parallelism` on fan-out steps are declared fields the engine enforces
+(fan-out pre-checks the batch fits; a step exceeding budget follows its
+`onBudgetExhaust` policy — throw, or degrade to null). Tune them by editing
+the file; orchestration prompts may also pass tighter values per call.
+
+## Resume semantics
+
+Every dispatched call is cache-keyed (workflow source + prompts + inputs).
+Re-running with unchanged definition and inputs skips completed steps from
+the journal — do not "help" by re-dispatching; change an input only when you
+want a step actually re-run. Editing the workflow source changes the keys:
+that is the intended way to invalidate stale cache.
+
+## Checklist before shipping a library workflow
+
+1. Single file, and imports type-only: `import type { WorkflowDefinition } from ...` (erased at load — nothing outside the file executes, so the entry-only guard scan covers everything). NEVER value-import the engine by relative path: from `.pi/workflows/lib/` it does not resolve (bricking the whole library), and any value import puts un-scanned code on the load path. Plain `export const workflow = { name, steps }` with no import at all works too (the loader validates shape, not `defineWorkflow`).
+2. No `Date.now` / `Math.random` / `new Date` anywhere in the source.
+3. `name` is unique and descriptive (it is the invocation key); `description`
+   one line — it appears in the unknown-name listing.
+4. Budget and parallelism declared, sized to the worst expected input.
+5. Verified locally: `run_workflow` with `source: "library"`, then re-run to
+   see journal hits skip completed steps.

package/src/agent/dispatch.ts

@@ -3,7 +3,7 @@
  *
  * The core spawn primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
  * `createSpawnRegistry`, `abortAgent`, `getPiInvocation` + the registry/
- * options/result types) lives in the shared `@fyeeme/pi-subagent-core`
+ * options/result types) lives in the shared `@fyeeme/pi-subagents`
  * package — extracted from the duplicate copies that used to live here and
  * in pi-review. This module keeps the workflows-specific layer on top:
  * `skipAgent`/`retryAgent` (with `AbortReason` semantics) and the lifecycle
@@ -19,7 +19,7 @@
  */
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
 import { notifyRetry, notifySkip } from "../lifecycle.ts";
-import type { AgentSpawnRegistry } from "@fyeeme/pi-subagent-core";
+import type { AgentSpawnRegistry } from "@fyeeme/pi-subagents";
 
 // Re-export the core dispatch surface so existing importers of this module
 // (`../agent/dispatch.ts`) keep working unchanged.
@@ -29,7 +29,7 @@ export {
 	getPiInvocation,
 	mapWithConcurrencyLimit,
 	spawnAgent,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 export type {
 	AgentAbortMap,
 	AgentCallId,
@@ -37,7 +37,7 @@ export type {
 	AgentSpawnRegistry,
 	AgentSpawnResult,
 	AgentUsage,
-} from "@fyeeme/pi-subagent-core";
+} from "@fyeeme/pi-subagents";
 
 export type AbortReason = "user-skip" | "user-retry";
 

package/src/format.ts

@@ -6,7 +6,7 @@
  * 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).
+ * the shared @fyeeme/pi-subagents extension).
  */
 
 /** Extract the step id from a callId of the form `${stepId}#${n}` (e.g.

package/src/library.ts

@@ -0,0 +1,143 @@
+/**
+ * src/library.ts — named workflow library: the persistence layer for
+ * workflows (PR3 of the sandwich refactor).
+ *
+ * Workflows are single-file `.ts` definitions (full step set including the
+ * TS-only steps like loop_until) discovered from:
+ *
+ *   1. project — nearest `.pi/workflows/lib/` walking up from cwd
+ *   2. bundled — this package's own `workflows/` directory (seed workflows)
+ *
+ * The project entry overrides a bundled entry of the same name. Discovery and
+ * loading go through the existing loader (jiti + the ast determinism guard),
+ * so a library workflow is rejected before execution when its source
+ * smuggles in non-deterministic APIs — the precondition cache-key resume
+ * relies on.
+ *
+ * The library directory is deliberately distinct from the journal output
+ * tree (`.pi/workflows/runs/<runId>/`): definitions and run state never
+ * collide. Adding a workflow = dropping a file; no code change.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadWorkflowModule } from "./loader.ts";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { WorkflowDefinition } from "./types.ts";
+
+/** This file lives at <pkg>/src/ → the bundled library is <pkg>/workflows. */
+const PKG_ROOT = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const BUNDLED_LIB_DIR = path.join(PKG_ROOT, "workflows");
+
+/** Project-level library directory, relative to the project root. */
+const PROJECT_LIB_REL = path.join(CONFIG_DIR_NAME, "workflows", "lib");
+
+/** One library entry, after loading the module. */
+export interface LibraryEntry {
+	readonly name: string;
+	readonly description?: string;
+	readonly filePath: string;
+	readonly workflow: WorkflowDefinition;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Nearest project library dir walking up from cwd (like agent discovery). */
+export function findProjectLibDir(cwd: string): string | null {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		const candidate = path.join(dir, PROJECT_LIB_REL);
+		if (isDirectory(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/** Library directories in priority order (later wins on name collision). */
+function libDirs(cwd: string): string[] {
+	const dirs = [BUNDLED_LIB_DIR];
+	const project = findProjectLibDir(cwd);
+	if (project) dirs.push(project);
+	return dirs;
+}
+
+function isValidWorkflow(value: unknown): value is WorkflowDefinition {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		typeof (value as WorkflowDefinition).name === "string" &&
+		Array.isArray((value as WorkflowDefinition).steps)
+	);
+}
+
+/** Load one workflow file: ast-guard + jiti import + shape validation. */
+async function loadEntry(filePath: string): Promise<LibraryEntry | null> {
+	try {
+		const mod = (await loadWorkflowModule({ filePath })) as {
+			workflow?: unknown;
+			default?: unknown;
+		};
+		const wf = mod.workflow ?? mod.default;
+		if (!isValidWorkflow(wf)) return null;
+		return {
+			name: wf.name,
+			description: wf.description,
+			filePath,
+			workflow: wf,
+		};
+	} catch (err) {
+		// Fail-fast, deliberately: a library file that fails the determinism
+		// guard or errors at import must NOT silently disappear from the
+		// available list (a poisoned entry re-appearing would break cache-key
+		// resume). The error names the offending file; remove or fix the file
+		// to restore discovery. Shape-invalid files (below) are the exception
+		// — they are skipped silently as non-workflows.
+		throw new Error(`library workflow ${path.basename(filePath)} failed to load: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * Discover the library: load every `.ts` workflow in the library dirs and
+ * index by workflow name (later dirs override earlier same-name entries).
+ * A file whose module import or the determinism guard check FAILS aborts the
+ * whole discovery with an error naming the file (fail-fast — see loadEntry);
+ * a file that imports cleanly but is not a valid workflow shape is skipped
+ * silently.
+ */
+export async function discoverWorkflowLibrary(cwd: string): Promise<Map<string, LibraryEntry>> {
+	const byName = new Map<string, LibraryEntry>();
+	for (const dir of libDirs(cwd)) {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue; // unreadable/missing dir — skip
+		}
+		for (const entry of entries) {
+			if (!entry.name.endsWith(".ts") || entry.name.startsWith(".")) continue;
+			if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+			const loaded = await loadEntry(path.join(dir, entry.name));
+			if (loaded) byName.set(loaded.name, loaded);
+		}
+	}
+	return byName;
+}
+
+/** Resolve one workflow by name, or null when not in the library. */
+export async function loadLibraryWorkflow(
+	name: string,
+	cwd: string,
+): Promise<LibraryEntry | null> {
+	// Fast path: only load the files that could define the name. Files export
+	// the workflow's name, so discovery is required either way — but skipping
+	// the project/bundled distinction keeps override semantics identical.
+	const lib = await discoverWorkflowLibrary(cwd);
+	return lib.get(name) ?? null;
+}

package/src/runner/index.ts

@@ -14,6 +14,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import { BudgetPool } from "../budget/index.ts";
 import { Journal, type RunManifest } from "../cache/index.ts";
 import type { AgentLifecycleListeners } from "../lifecycle.ts";
@@ -81,7 +82,7 @@ export async function runWorkflow(opts: RunWorkflowOptions): Promise<RunResult>
 	const budget = opts.budget ?? workflow.budget ?? {};
 	const journalDir =
 		opts.journalDir ??
-		path.join(cwd, ".pi", "workflows", sanitizeWorkflowName(workflow.name));
+		path.join(cwd, CONFIG_DIR_NAME, "workflows", sanitizeWorkflowName(workflow.name));
 
 	await fs.promises.mkdir(journalDir, { recursive: true });
 	const journal = new Journal({ dir: journalDir });

package/src/runner/stage-executor.ts

@@ -986,7 +986,7 @@ function dispatchOpts(
 		signal,
 		allowChildRecursion,
 		// UI display name for the shared sub-agent widget/FleetView (purely
-		// observational metadata consumed by the pi-subagent-core monitor): the
+		// observational metadata consumed by the pi-subagents 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),
@@ -1018,6 +1018,12 @@ function usageStats(res: AgentSpawnResult, durationMs: number, ok: boolean): Ste
 		durationMs,
 		agents: 1,
 		failures: ok ? 0 : 1,
+		usage: {
+			input: res.usage.input,
+			output: res.usage.output,
+			cacheRead: res.usage.cacheRead,
+			cacheWrite: res.usage.cacheWrite,
+		},
 	};
 }
 
@@ -1028,6 +1034,20 @@ function addStats(a: StepStats, b: StepStats): StepStats {
 		durationMs: a.durationMs + b.durationMs,
 		agents: a.agents + b.agents,
 		failures: a.failures + b.failures,
+		usage: mergeUsage(a.usage, b.usage),
+	};
+}
+
+function mergeUsage(
+	a: StepStats["usage"],
+	b: StepStats["usage"],
+): StepStats["usage"] {
+	if (!a && !b) return undefined;
+	return {
+		input: (a?.input ?? 0) + (b?.input ?? 0),
+		output: (a?.output ?? 0) + (b?.output ?? 0),
+		cacheRead: (a?.cacheRead ?? 0) + (b?.cacheRead ?? 0),
+		cacheWrite: (a?.cacheWrite ?? 0) + (b?.cacheWrite ?? 0),
 	};
 }
 
@@ -1038,14 +1058,16 @@ export function aggregateStats(stats: readonly StepStats[], durationMs: number):
 	let agents = 0;
 	let failures = 0;
 	let dur = 0;
+	let usage: StepStats["usage"];
 	for (const s of stats) {
 		tokens += s.tokens;
 		cost += s.cost;
 		agents += s.agents;
 		failures += s.failures;
 		dur += s.durationMs;
+		usage = mergeUsage(usage, s.usage);
 	}
-	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures };
+	return { tokens, cost, durationMs: durationMs > 0 ? durationMs : dur, agents, failures, usage };
 }
 
 function withDuration(stats: StepStats, start: number): StepStats {

package/src/types.ts

@@ -55,6 +55,15 @@ export interface StepStats {
 	readonly durationMs: number;
 	readonly agents: number;
 	readonly failures: number;
+	/** Nested-LLM usage split, populated for agent-dispatch steps and surfaced
+	 *  as `usage` on the run_workflow tool result (pi usage accounting). Absent
+	 *  for zero-dispatch steps (code/log) and journals written before this field. */
+	readonly usage?: {
+		readonly input: number;
+		readonly output: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+	};
 }
 
 export interface StepResult<T = unknown> {

package/workflows/review-extension.ts

@@ -0,0 +1,51 @@
+/**
+ * Seed library workflow: review-extension — the extensions-submodule review
+ * fan-out distilled from this repository's review-local-extensions-fanout
+ * pipeline: scope the changed packages first, then one reviewer per changed
+ * extension directory (parallelism 3), then merge.
+ *
+ * Input: newline-separated list of changed paths under packages/extensions
+ * (or a single path). Prompts use prompt functions (ctx.input /
+ * ctx.step(id)) — the TS API does not substitute {{...}} tokens.
+ * Runtime-single-file: `import type` is erased at load (see
+ * review-local-diff.ts).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+export const workflow: WorkflowDefinition = {
+	name: "review-extension",
+	description: "Review each changed extension package: one reviewer per package (parallelism 3), merged findings",
+	budget: { maxAgents: 9, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "scope",
+			type: "agent",
+			prompt: (ctx) =>
+				"The input lists changed paths under packages/extensions. Reduce it to the set of " +
+				"distinct top-level extension directories (e.g. \"pi-review\", \"pi-subagents\"). " +
+				"Return ONLY the directory names, one per line, no commentary.\n\n" +
+				String(ctx.input),
+		},
+		{
+			id: "reviewers",
+			type: "fan_out",
+			over: (ctx) =>
+				String(ctx.step("scope").results)
+					.split("\n")
+					.map((l) => l.trim())
+					.filter(Boolean),
+			parallelism: 3,
+			agent: (pkg, _index, ctx) => ({
+				prompt:
+					`Review the uncommitted changes in packages/extensions/${pkg} (run ` +
+					`\`git -C packages/extensions/${pkg} diff\` yourself; read the touched files for ` +
+					`context). Report findings as \`file:line\` — one-line summary — the concrete cost. ` +
+					`Cover correctness, reuse, simplification, efficiency, altitude. Report only.\n\n` +
+					`Changed paths:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+	],
+};
+
+export default workflow;

package/workflows/review-local-diff.ts

@@ -0,0 +1,64 @@
+/**
+ * Seed library workflow: review-local-diff — the local-diff review pipeline
+ * actually run in this repository (distilled from the .pi/workflows journals
+ * of review-local-changes / review-local-extensions-fanout runs).
+ *
+ * Input: the unified diff to review (run input). Fan out one finder per
+ * angle (parallelism 4), adversarially verify a merged candidate list, and
+ * return the verified findings. Budget and parallelism are declared here as
+ * data — the engine enforces them.
+ *
+ * Prompts reference run context via prompt FUNCTIONS (ctx.input /
+ * ctx.step(id)) — the {{...}} template tokens are the inline-JSON tool
+ * surface only; the TS API never substitutes them in plain strings.
+ *
+ * Runtime-single-file: `import type` is erased at load, so nothing outside
+ * this file executes and the ast determinism guard's entry-only scan covers
+ * everything that runs (a VALUE import from another file would not be
+ * scanned — keep imports type-only).
+ */
+import type { WorkflowDefinition } from "../src/index.ts";
+
+const ANGLES = ["correctness", "reuse", "simplification", "efficiency", "altitude"] as const;
+
+export const workflow: WorkflowDefinition = {
+	name: "review-local-diff",
+	description: "Fan out diff-scoped finders, adversarially verify the merged candidates, return verified findings",
+	budget: { maxAgents: 12, maxTokens: 2_000_000 },
+	steps: [
+		{
+			id: "finders",
+			type: "fan_out",
+			over: () => [...ANGLES],
+			parallelism: 4,
+			agent: (angle, _index, ctx) => ({
+				prompt:
+					`You are a code-review finder for the "${angle}" angle. Review the diff below. ` +
+					`Report each finding as \`file:line\` — one-line summary — the concrete cost ` +
+					`(for correctness: the input/state that triggers it → wrong output). Report only; ` +
+					`an empty list is a valid answer.\n\nDiff:\n${ctx.input}`,
+			}),
+			merge: (results) => results.join("\n---\n"),
+		},
+		{
+			id: "verify",
+			type: "adversarial",
+			produce: {
+				prompt: (ctx) =>
+					"Dedup and merge these code-review findings into a numbered candidate list " +
+					"(same defect + same location + same reason → keep one; different reasons for " +
+					"the same line are NOT duplicates — keep both). Return only the numbered list.\n\n" +
+					String(ctx.step("finders").results),
+			},
+			rubric: [
+				"finding is concretely actionable (file:line present)",
+				"the failure scenario or cost is stated and realistic",
+				"not a duplicate of another kept finding",
+			],
+			judges: 3,
+			minPass: 2,
+		},
+	],
+};
+
+export default workflow;