@juicesharp/rpiv-workflow 1.14.0

package/docs/workflow-basics.md

@@ -0,0 +1,122 @@
+# Workflow Basics
+
+A workflow chains Pi skills into a typed multi-stage graph with audited JSONL state, predicate routing, and per-stage output validation. Workflows are **skill-agnostic** — they name skills by their installed name, and the runner dispatches `/skill:<name>` via Pi's native skill loader.
+
+## Table of Contents
+
+- [Running workflows](#running-workflows)
+- [File structure](#file-structure)
+- [Layer merging](#layer-merging)
+- [Config files](#config-files)
+- [Pack files](#pack-files)
+- [Example](#example)
+
+## Running workflows
+
+```bash
+/wf                        # Preview every loaded workflow
+/wf <name>                 # Preview one workflow's stage graph
+/wf <name> <input>         # Run a workflow with <input> piped to the start stage
+```
+
+Running `/wf` without arguments shows a list of every loaded workflow and its stages. Running `/wf <name>` without input shows that workflow's stage graph in detail. The `<input>` string becomes the start stage's prompt.
+
+## File structure
+
+```
+<cwd>/.rpiv-workflow/
+├── workflows.config.ts       # The project's workflow config (hand-edited)
+└── workflows/                # Pack files (installable bundles)
+    ├── my-pipeline.ts
+    └── ship.ts
+
+~/.config/rpiv-workflow/
+├── workflows.config.ts       # User-level config
+└── workflows/                # User-level packs
+```
+
+Every workflow file is TypeScript, loaded via `jiti` (no build step required). Import the authoring DSL from `@juicesharp/rpiv-workflow`:
+
+```typescript
+import { defineWorkflow, produces, acts, gate, gt, eq } from "@juicesharp/rpiv-workflow";
+```
+
+## Layer merging
+
+The loader merges workflows from five layers. Each later layer overrides earlier by workflow name:
+
+```
+built-in (registered by sibling packages like rpiv-pi)
+  ← user packs        (~/.config/rpiv-workflow/workflows/*.ts, alpha-sorted)
+  ← user config       (~/.config/rpiv-workflow/workflows.config.ts)
+  ← project packs     (<cwd>/.rpiv-workflow/workflows/*.ts, alpha-sorted)
+  ← project config    (<cwd>/.rpiv-workflow/workflows.config.ts)
+```
+
+Within a layer, the config file wins by workflow name over pack files. Only the config file may set the `default` workflow (the one `/wf <input>` runs without specifying a name). Defaults cascade: `project config > user config > first registered workflow`.
+
+## Config files
+
+The config file (`workflows.config.ts`) is the one TypeScript file you hand-edit. It accepts three default-export shapes:
+
+```typescript
+// 1. A single Workflow
+import { defineWorkflow, produces, acts } from "@juicesharp/rpiv-workflow";
+export default defineWorkflow({
+  name: "ship",
+  start: "implement",
+  stages: { implement: acts(), commit: acts() },
+  edges: { implement: "commit", commit: "stop" },
+});
+
+// 2. A Workflow[] with a single entry
+export default [/* one workflow */];
+
+// 3. The envelope form — required when shipping multiple workflows
+export default {
+  workflows: [/* many */],
+  default: "ship",   // which one `/wf <input>` runs without a name
+};
+```
+
+## Pack files
+
+Pack files (`workflows/*.ts`) are installable bundles others can drop in. They accept only `Workflow | Workflow[]`. Packs **cannot** set `default` — that lives in the config file.
+
+```typescript
+// workflows/my-pipeline.ts
+import { defineWorkflow, produces, acts } from "@juicesharp/rpiv-workflow";
+export default defineWorkflow({
+  name: "my-pipeline",
+  start: "research",
+  stages: { research: produces({ outcome: myOutcome }), implement: acts() },
+  edges: { research: "implement", implement: "stop" },
+});
+```
+
+This is what makes installable workflow packs safe: a pack contributes new workflows without overriding the user's default.
+
+## Example
+
+A minimal workflow that chains two skills:
+
+```typescript
+import { defineWorkflow, produces, acts } from "@juicesharp/rpiv-workflow";
+
+export default defineWorkflow({
+  name: "review-and-ship",
+  start: "code-review",
+  stages: {
+    "code-review": produces({ outcome: myOutcome }),
+    commit: acts(),
+  },
+  edges: {
+    "code-review": "commit",
+    commit: "stop",
+  },
+});
+```
+
+Save this as `.rpiv-workflow/workflows.config.ts` in your project, then run `/wf review-and-ship implement auth feature`.
+
+For the full DSL reference (all stage factories, routing, outcomes, validators), see [workflow-authoring.md](./workflow-authoring.md).

package/docs-protocol.ts

@@ -0,0 +1,106 @@
+/**
+ * System prompt protocol for rpiv-workflow documentation delivery.
+ *
+ * Prepends a documentation reference block to the system prompt every turn
+ * via `before_agent_start`, following the same pattern as rpiv-args'
+ * skill-invocation protocol (`packages/rpiv-args/args.ts:439`). The block
+ * tells the agent where to find rpiv-workflow's authoring docs and when to
+ * read them — the agent reads the docs on-demand via the `read` tool.
+ *
+ * The protocol is small (~200 bytes) and identical every turn, so it
+ * benefits from Pi's prompt caching (same amortization as
+ * `SKILL_INVOCATION_PROTOCOL` in rpiv-args).
+ *
+ * This module has zero Pi type imports — the host interface declares only
+ * the `on("before_agent_start", ...)` shape needed for registration.
+ * At runtime, Pi passes the full ExtensionAPI which structurally satisfies
+ * this interface.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Absolute path to the rpiv-workflow package root. Resolved from this
+ * file's location via `import.meta.url` — works in both development
+ * (monorepo source) and production (installed npm package).
+ */
+const PACKAGE_ROOT = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = join(PACKAGE_ROOT, "docs");
+
+// ---------------------------------------------------------------------------
+// Protocol
+// ---------------------------------------------------------------------------
+
+/**
+ * System prompt protocol prepended every turn. Cached after first build
+ * so bytes are identical every turn → prompt-cache hit after turn 1
+ * (same posture as rpiv-args' `SKILL_INVOCATION_PROTOCOL`).
+ *
+ * Mirrors Pi's own "When asked about:" routing table pattern — path
+ * references + routing instructions, no inline content.
+ */
+let protocolCache: string | undefined;
+
+export function getDocsProtocol(): string {
+	if (protocolCache) return protocolCache;
+
+	protocolCache = [
+		"",
+		"rpiv-workflow documentation (read only when the user asks about creating, modifying, or troubleshooting workflows):",
+		`- Workflow basics: ${join(DOCS_DIR, "workflow-basics.md")}`,
+		`- Authoring DSL reference: ${join(DOCS_DIR, "workflow-authoring.md")}`,
+		"- When asked about workflows, read the relevant docs file(s) before generating any workflow code",
+		"- Generated workflow files must pass validateWorkflow() — verify before writing",
+		"",
+	].join("\n");
+
+	return protocolCache;
+}
+
+// ---------------------------------------------------------------------------
+// Host interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal host interface for docs-protocol registration. Declares only the
+ * `on` shape needed for `before_agent_start`. At runtime, Pi passes the
+ * full ExtensionAPI which structurally satisfies this.
+ *
+ * Not exported as part of rpiv-workflow's public type surface — internal
+ * to the extension wiring in `index.ts`.
+ */
+export interface DocsProtocolHost {
+	on(event: "before_agent_start", handler: (event: { systemPrompt: string }) => { systemPrompt: string }): void;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/**
+ * `before_agent_start` handler. Read-then-prepend — never replace,
+ * replacement clobbers prior extensions (rpiv-args, rpiv-pi guidance, etc.).
+ *
+ * Exported for testing.
+ */
+export function handleBeforeAgentStart(event: { systemPrompt: string }): { systemPrompt: string } {
+	return { systemPrompt: getDocsProtocol() + event.systemPrompt };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the docs-protocol `before_agent_start` hook with the host.
+ * Called from the extension's default export alongside
+ * `registerWorkflowCommand`.
+ */
+export function registerDocsProtocol(host: DocsProtocolHost): void {
+	host.on("before_agent_start", handleBeforeAgentStart);
+}

package/fanout.ts

@@ -0,0 +1,96 @@
+/**
+ * Fanout iteration. When a stage opts in via `StageDef.fanout`, the runner
+ * calls the user's `FanoutFn` to get a list of units and iterates one Pi
+ * session per unit. This module owns the iteration loop; `runner.ts`
+ * injects its primitives via `FanoutDeps` so the module never imports
+ * back (cycle-free).
+ *
+ * No markdown regex, no per-convention counter, no cap — rpiv-workflow
+ * stays convention-agnostic. Consumers (rpiv-pi etc.) own the FanoutFn
+ * body and any safety bounds it needs.
+ */
+
+import type { FanoutUnit } from "./api.js";
+import { buildLifecycleContext, skillStageRef } from "./lifecycle.js";
+import { MSG_STAGE_COMPLETE, STATUS_FANOUT_UNIT, STATUS_KEY } from "./messages.js";
+import type { FanoutSession, RunContext, RunnerCtx } from "./types.js";
+
+export interface FanoutDeps {
+	runFanoutSession: (ctx: RunnerCtx, session: FanoutSession) => Promise<void>;
+	/**
+	 * Resume the chain after the fanout node's units finish. Receives the
+	 * fanout node's name so the routing layer can look up the outgoing
+	 * edge from it.
+	 */
+	advanceAfter: (curCtx: RunnerCtx, completedName: string, completedIdx: number, run: RunContext) => Promise<void>;
+}
+
+/**
+ * `skill` is the bundled skill body (threaded by the runner), not the node
+ * name. Aliased nodes (e.g. `implement-after-revise` invoking `implement`)
+ * tag unit rows + prompts with the skill body so audit consumers don't see
+ * two labels for the same work. Caller verifies node + fanout shape before
+ * invoking (see `runStage`).
+ *
+ * `currentName` is the fanout node's name in the workflow — passed to
+ * `advanceAfter` once the final unit completes so the routing layer can
+ * look up the outgoing edge from it.
+ *
+ * `units` was already produced by the user's `FanoutFn`; the iteration loop
+ * walks it in order. `p` is the 1-based index into `units` for the next
+ * session to run — the continuation-style self-call increments it.
+ */
+export async function runFanout(
+	curCtx: RunnerCtx,
+	stageIdx: number,
+	currentName: string,
+	skill: string,
+	p: number,
+	units: readonly FanoutUnit[],
+	run: RunContext,
+	deps: FanoutDeps,
+): Promise<void> {
+	const { cwd, runId, totalStages, state } = run;
+
+	if (p > units.length) {
+		curCtx.ui.notify(MSG_STAGE_COMPLETE(skill), "info");
+		await deps.advanceAfter(curCtx, currentName, stageIdx, run);
+		return;
+	}
+
+	const unit = units[p - 1]!;
+	curCtx.ui.setStatus(STATUS_KEY, STATUS_FANOUT_UNIT(stageIdx + 1, totalStages, skill, unit.label));
+
+	const lifecycleCtx = buildLifecycleContext({
+		cwd,
+		runId,
+		workflow: run.workflow.name,
+		totalStages: run.totalStages,
+		trigger: run.trigger,
+		state,
+	});
+	await run.lifecycle.fire(
+		curCtx,
+		"onFanoutUnitStart",
+		skillStageRef(currentName, stageIdx + 1, skill),
+		unit,
+		p,
+		lifecycleCtx,
+	);
+
+	await deps.runFanoutSession(curCtx, {
+		cwd,
+		runId,
+		state,
+		prompt: `/skill:${skill} ${unit.prompt}`,
+		stageName: currentName,
+		skill,
+		lifecycle: run.lifecycle,
+		runIdentity: { workflow: run.workflow.name, totalStages: run.totalStages, trigger: run.trigger },
+		unitIndex: p,
+		label: unit.label,
+		id: unit.id,
+		stageIndex: stageIdx,
+		onSuccess: (freshCtx) => runFanout(freshCtx, stageIdx, currentName, skill, p + 1, units, run, deps),
+	});
+}

package/host.ts

@@ -0,0 +1,97 @@
+/**
+ * Host ports — the contract the workflow runtime needs from its host
+ * environment, expressed in workflow-domain vocabulary.
+ *
+ * The package never re-exports `@earendil-works/pi-coding-agent` types
+ * from its public surface. Pi's `ExtensionAPI` / `ExtensionCommandContext`
+ * / `ReplacedSessionContext` structurally satisfy these ports, so
+ * embedders pass their Pi handles directly without casting; consumers
+ * wanting to drive the runtime from a non-Pi adapter implement these two
+ * interfaces.
+ *
+ *  - `WorkflowHost`    — registry-level host (default-export ctor + continue-policy sender).
+ *  - `WorkflowContext` — per-command ctx passed into `runWorkflow`, also the
+ *                        replacement ctx delivered to `newSession`'s `withSession`
+ *                        callback. `sendUserMessage` is optional at the type
+ *                        level (the outer command ctx may not carry one) but
+ *                        the runtime guarantees it is present inside
+ *                        `withSession`.
+ *
+ * Compile-time tripwire: `host.test.ts` asserts Pi's concrete types
+ * extend these ports. If Pi's API drifts (a method renames, a signature
+ * tightens), `npm run check` fails immediately on that file.
+ */
+
+/**
+ * Registry-level host. Default-exported function receives this; the
+ * runner also uses it for continue-policy stages (sends into the
+ * already-streaming agent) and for skill-registration preflight.
+ *
+ * The three methods we touch on Pi's `ExtensionAPI`. Anything beyond
+ * these is invisible to the runtime.
+ */
+export interface WorkflowHost {
+	/** Register a slash command. Used by the `/wf` entry point. */
+	registerCommand(
+		name: string,
+		options: {
+			description?: string;
+			handler: (args: string, ctx: WorkflowContext) => Promise<void>;
+		},
+	): void;
+	/**
+	 * Send a user message into the active agent stream. Used by the
+	 * continue-policy session handler.
+	 *
+	 * Pi declares this `void` at the type level but returns a Promise at
+	 * runtime; we declare `void | Promise<void>` so `await` is safe in
+	 * either world.
+	 */
+	sendUserMessage(content: string): void | Promise<void>;
+	/** Enumerate currently registered slash commands. Used by skill-registration preflight. */
+	getCommands(): ReadonlyArray<{ name: string; source: string }>;
+}
+
+/**
+ * Per-command host ctx. Embedders hand this to `runWorkflow`; the
+ * runner threads it (and any replacement ctx returned by `newSession`)
+ * through stages.
+ *
+ * Exhaustive list of members the runtime touches — adding any reach
+ * outside this list is a port-widening decision, not an oversight.
+ *
+ * `sendUserMessage` is declared optional because the outer command ctx
+ * Pi delivers to a `/wf` handler does not carry one — only the
+ * replacement ctx inside `newSession`'s `withSession` callback does. The
+ * runtime guarantees it is present in that callback; callers outside
+ * `withSession` must not rely on it.
+ */
+export interface WorkflowContext {
+	cwd: string;
+	hasUI: boolean;
+	ui: {
+		notify(message: string, level?: "info" | "warning" | "error"): void;
+		setStatus(key: string, text: string | undefined): void;
+	};
+	sessionManager: {
+		getBranch(): unknown;
+	};
+	isIdle(): boolean;
+	waitForIdle(): Promise<void>;
+	/**
+	 * Open a fresh session and run `withSession` on the replacement ctx.
+	 * Returns `{ cancelled: true }` if the host declined to spawn (user
+	 * dismissed the swap, etc.). `cancelled: false` implies the outer
+	 * ctx is now invalidated — all further work runs on the replacement
+	 * delivered to `withSession`.
+	 */
+	newSession(options: {
+		withSession: (replacement: WorkflowContext) => Promise<void>;
+	}): Promise<{ cancelled: boolean }>;
+	/**
+	 * Present on the replacement ctx delivered inside `withSession`; not
+	 * present on the outer command ctx. The runtime narrows internally
+	 * before calling.
+	 */
+	sendUserMessage?(content: string): Promise<void>;
+}

package/index.ts

@@ -0,0 +1,230 @@
+/**
+ * rpiv-workflow — Pi extension entry point.
+ *
+ * Registers the `/wf` slash command and (optionally) exposes the workflow
+ * runtime as a programmatic API for sibling packages that want to
+ * contribute built-in workflows via `registerBuiltIns(...)`.
+ *
+ * Skill-agnostic: the runner sends `/skill:<name>` via Pi's native skill
+ * dispatch — workflows can name any skill installed in Pi's search path
+ * (`~/.pi/agent/skills/`, `<cwd>/.pi/skills/`, or settings-declared
+ * `skillPaths[]`). This package ships ZERO built-in workflows. Bundles
+ * like `@juicesharp/rpiv-pi` opt in by calling `registerBuiltIns(...)`
+ * from their own extension entry.
+ *
+ * ─── Public surface, grouped by audience ────────────────────────────────
+ *
+ *   1. Authoring DSL — `./api.js`, `./predicates.js`, `./typebox-adapter.js`
+ *      What a `workflows.config.ts` author imports to declare a workflow:
+ *      `defineWorkflow`, `produces`, `acts`, `terminal`, `defineRoute`, `gate`,
+ *      `Workflow`, `StageDef`, `EdgeFn`, `EdgeTarget`, `EdgeContext`,
+ *      `StageSchema`, `StageKind`, `SessionPolicy`, `OutputSpec`,
+ *      `READS_DATA`, the runtime-mirror `*_VALUES` arrays, the
+ *      `gt`/`gte`/`lt`/`lte`/`eq` predicate helpers, and `typeboxSchema`
+ *      (the TypeBox adapter).
+ *
+ *   2. Runner (programmatic embedders) — `./runner/index.js`, `./host.js`
+ *      Drive a workflow from outside `/wf`: `runWorkflow`,
+ *      `RunWorkflowOptions`, `RunWorkflowResult`. Embedders type their
+ *      host handles against `WorkflowHost` / `WorkflowContext` (the host
+ *      ports) — Pi's `ExtensionAPI` / `ExtensionCommandContext` /
+ *      `ReplacedSessionContext` structurally satisfy them, so the
+ *      values pass through without casting.
+ *
+ *   3. Loader (programmatic embedders) — `./load/index.js`
+ *      Materialise the merged workflow registry: `loadWorkflows`,
+ *      `LoadedWorkflows`, `Issue`, `LoadIssue`, `ConfigLayer`,
+ *      `OverlayPaths`, `projectOverlayPaths`, `userOverlayPaths`.
+ *
+ *   4. Built-in registry (sibling packages) — `./built-ins.js`
+ *      Contribute workflows to the lowest config layer:
+ *      `registerBuiltIns`. (`getBuiltIns` is test-only and lives on
+ *      `@juicesharp/rpiv-workflow/internal`.)
+ *
+ *   5. Output envelope + bundled outcomes — `./output.js`,
+ *      `./outcomes/index.js`, `./handle.js`
+ *      Inter-stage data channel (`Output<K, D>`, `OutputMeta`,
+ *      `Artifact`, `ArtifactHandle` + constructors `fs`/`url`/
+ *      `opaque`/`inline`/`handleToString`) + bundled outcomes
+ *      (`sideEffectOutcome`, `gitCommitOutcome`, `GitCommitData`,
+ *      `gitHeadSnapshot`, `GitHeadSnapshot`) + the bundled
+ *      collector/parser catalog wireable into any custom `OutputSpec`:
+ *        - collectors: `transcriptPathCollector` (regex over assistant
+ *          text), `toolCallCollector` (universal tool_use observer),
+ *          `workspaceDiffCollector` (git status diff pre/post),
+ *          `gitCommitCollector` (commit detection), the wrappers
+ *          `directoryPathCollector` / `urlCollector`, plus composition
+ *          `unionCollectors` and the empty-list primitive `noopCollector`.
+ *        - parsers: `jsonBodyParser` (parses primary fs body),
+ *          `gitCommitParser`.
+ *      The `.rpiv/artifacts/<bucket>/<file>.md` outcome + the
+ *      markdown-frontmatter parser live in `@juicesharp/rpiv-pi`
+ *      (`rpivArtifactMdOutcome` / `frontmatterParser`) — those are
+ *      rpiv conventions, not framework defaults.
+ *
+ *   6. Custom-outcome authoring surface — `./output.js`
+ *      `OutputSpec<Snapshot, Kind, Data>` (collector + optional parser),
+ *      `ArtifactCollector`, `ArtifactParser`, `CollectCtx`,
+ *      `CollectResult`, `ParseCtx`, `ParseResult`, `SnapshotCtx`,
+ *      `SnapshotFn`. Sugar: `defineCollector` / `defineParser`.
+ *
+ *   7. Validation surfaces — `./validate-workflow.js`,
+ *      `./validate-output.js`
+ *      `validateWorkflow`, `WorkflowValidationIssue`,
+ *      `validateOutputData`, `SchemaValidationFailure`.
+ *
+ *   8. Persistence (low-level — JSONL inspect) — `./state/index.js`
+ *      Read past runs at `<cwd>/.rpiv/workflows/<run-id>.jsonl`:
+ *      `listRuns`, `readHeader`, `readLastStage`, `listArtifacts`,
+ *      `stateFilePath`, `workflowsDir`, `RunSummary`,
+ *      `WorkflowHeader`, `WorkflowStage`. `recordStage` lives on
+ *      `@juicesharp/rpiv-workflow/internal` (test-only — rpiv-pi's
+ *      `[I3]` regression test pokes it directly; runner owns row
+ *      writes, embedders never need it).
+ *
+ *   9. Runtime types — `./types.js`
+ *      `RunState`.
+ *
+ * Per-module deep imports (`from "@juicesharp/rpiv-workflow/api.js"`)
+ * are NOT supported across the package boundary.
+ *
+ * ─── Pi-coupling boundary ───────────────────────────────────────────────
+ *
+ * The package's public type surface names ZERO `@earendil-works/pi-coding-agent`
+ * types. Every host capability the runtime needs is declared as a
+ * workflow-owned port in `./host.js`:
+ *
+ *   • `WorkflowHost`     — registry-level (default export + continue sends)
+ *   • `WorkflowContext`  — per-command ctx for `runWorkflow`; also the
+ *                          replacement ctx delivered to `newSession`'s
+ *                          `withSession` callback. `sendUserMessage` is
+ *                          optional at the type level (the outer command
+ *                          ctx omits it); the runtime guarantees it is
+ *                          present inside `withSession`.
+ *
+ * Pi's `ExtensionAPI` / `ExtensionCommandContext` are structurally
+ * compatible with these ports — embedders pass their existing Pi handles
+ * directly. A future non-Pi host implements the three port interfaces.
+ *
+ * The package no longer imports any value from
+ * `@earendil-works/pi-coding-agent` — `parseFrontmatter` moved to
+ * `@juicesharp/rpiv-pi` along with the rpiv-flavoured outcome
+ * (`rpivArtifactMdOutcome`). The peer dep stays for `pi-tui` types
+ * structural-compatibility only.
+ *
+ * `host.test.ts` carries a compile-time tripwire that fails immediately
+ * if Pi's types drift below the port's required shape.
+ */
+
+import { registerWorkflowCommand } from "./command.js";
+import { type DocsProtocolHost, registerDocsProtocol } from "./docs-protocol.js";
+import type { WorkflowHost } from "./host.js";
+
+export {
+	type ActsScriptFn,
+	acts,
+	type DefineRouteOptions,
+	defineRoute,
+	defineWorkflow,
+	type EdgeContext,
+	type EdgeFn,
+	type EdgeTarget,
+	type FanoutContext,
+	type FanoutFn,
+	type FanoutUnit,
+	gate,
+	marksReadsData,
+	ON_INVALID_VALUES,
+	type OnInvalid,
+	type ProducesScriptFn,
+	produces,
+	READS_DATA,
+	type ScriptContext,
+	SESSION_POLICIES,
+	type SessionPolicy,
+	STAGE_KINDS,
+	type StageDef,
+	type StageKind,
+	type StageSchema,
+	terminal,
+	type Workflow,
+} from "./api.js";
+export { registerBuiltIns } from "./built-ins.js";
+export {
+	type Artifact,
+	type ArtifactHandle,
+	fs,
+	handleToString,
+	inline,
+	opaque,
+	url,
+} from "./handle.js";
+export type { WorkflowContext, WorkflowHost } from "./host.js";
+export { type LifecycleContext, type LifecycleListeners, registerLifecycle, type StageRef } from "./lifecycle.js";
+export type { ConfigLayer, Issue, LoadedWorkflows, LoadIssue, OverlayPaths } from "./load/index.js";
+export { loadWorkflows, projectOverlayPaths, userOverlayPaths } from "./load/index.js";
+export {
+	type DirectoryPathCollectorOpts,
+	directoryPathCollector,
+	type GitCommitData,
+	type GitHeadSnapshot,
+	gitCommitCollector,
+	gitCommitOutcome,
+	gitCommitParser,
+	gitHeadSnapshot,
+	jsonBodyParser,
+	noopCollector,
+	sideEffectOutcome,
+	type ToolCall,
+	type ToolCallCollectorOpts,
+	type TranscriptPathCollectorOpts,
+	toolCallCollector,
+	transcriptPathCollector,
+	type UrlCollectorOpts,
+	unionCollectors,
+	urlCollector,
+	type WorkspaceDiffCollectorOpts,
+	type WorkspaceDiffSnapshot,
+	workspaceDiffCollector,
+} from "./outcomes/index.js";
+export type {
+	ArtifactCollector,
+	ArtifactParser,
+	CollectCtx,
+	CollectResult,
+	Output,
+	OutputMeta,
+	OutputSpec,
+	ParseCtx,
+	ParseResult,
+	SnapshotCtx,
+	SnapshotFn,
+} from "./output.js";
+export { defineCollector, defineParser } from "./output-spec.js";
+export { eq, gt, gte, lt, lte, type Predicate } from "./predicates.js";
+export { type RunWorkflowOptions, type RunWorkflowResult, runWorkflow } from "./runner/index.js";
+export {
+	listArtifacts,
+	listRuns,
+	type RunSummary,
+	readHeader,
+	readLastStage,
+	stateFilePath,
+	type WorkflowHeader,
+	type WorkflowStage,
+	workflowsDir,
+} from "./state/index.js";
+export { DEFAULT_TRIGGER, type RunTrigger } from "./triggers.js";
+export { typeboxSchema } from "./typebox-adapter.js";
+export type { RunState } from "./types.js";
+export { type SchemaValidationFailure, validateOutputData } from "./validate-output.js";
+export { validateWorkflow, type WorkflowValidationIssue } from "./validate-workflow.js";
+
+export default function (host: WorkflowHost): void {
+	registerWorkflowCommand(host);
+	// Pi passes the full ExtensionAPI at runtime, which has on().
+	// WorkflowHost doesn't declare on() to keep the programmatic-embedder
+	// surface narrow. Cast to satisfy the type — Pi always provides the
+	// full API.
+	registerDocsProtocol(host as unknown as DocsProtocolHost);
+}