@juicesharp/rpiv-workflow 1.14.0

package/sessions/spawn.ts

@@ -0,0 +1,135 @@
+/**
+ * Session policy dispatch. Owns the three policy-specific decisions the
+ * stage / phase machinery has to make per session: which branch offset
+ * the outcome sees, how the session is opened, and how an
+ * already-established session is sent to.
+ *
+ * Two handlers — `FRESH_HANDLER` and `CONTINUE_HANDLER` — implement the
+ * interface; `handlerFor(policy)` picks. Everything else in the
+ * `sessions/` directory is policy-agnostic.
+ */
+
+import type { SessionPolicy } from "../api.js";
+import type { WorkflowHost } from "../host.js";
+import type { RunnerCtx } from "../types.js";
+
+/**
+ * Three policy-specific decisions that used to live as five ternaries
+ * scattered across sessions.ts:
+ *
+ *   - `branchOffset(captured)` — the offset outcomes apply to skip
+ *     the prior-stage prefix in continue sessions. Fresh ignores the
+ *     stage-side captured value (it's `undefined` from
+ *     `computeBranchOffset` for fresh stages anyway); continue returns
+ *     it as-is.
+ *   - `spawn(ctx, prompt, body, host?)` — open the session and run `body`
+ *     on whichever ctx is valid for that policy (fresh → freshCtx
+ *     inside `withSession`; continue → the supplied ctx, after a
+ *     send+waitForIdle settles the existing session). `cancelled: true`
+ *     means a fresh session was cancelled before `withSession` ran.
+ *   - `send(ctx, msg, host?)` — send into an already-established session
+ *     and wait for it to settle (used by the validation-retry path).
+ *
+ * `host` is the registry-level fallback for continue stages — used only
+ * when `ctx.sendUserMessage` is absent (the outer command ctx at the
+ * very start of a workflow whose first stage is continue-policy).
+ * Everywhere else (continue stages following any other stage),
+ * `ctx.sendUserMessage` is present and preferred because Pi marks the
+ * captured host stale after `ctx.newSession()`. `enforceSessionInvariants`
+ * still requires a host whenever any stage is continue-policy so the
+ * start-stage path has a working fallback. Fresh ignores `host` entirely.
+ */
+export interface SessionPolicyHandler {
+	branchOffset(capturedOffset: number | undefined): number | undefined;
+	spawn(
+		ctx: RunnerCtx,
+		prompt: string,
+		body: (sessionCtx: RunnerCtx) => Promise<void>,
+		host?: WorkflowHost,
+	): Promise<{ cancelled: boolean }>;
+	send(ctx: RunnerCtx, msg: string, host?: WorkflowHost): Promise<void>;
+}
+
+export const FRESH_HANDLER: SessionPolicyHandler = {
+	branchOffset: () => undefined,
+	async spawn(ctx, prompt, body) {
+		const { cancelled } = await ctx.newSession({
+			withSession: async (freshCtx) => {
+				if (!freshCtx.sendUserMessage) {
+					throw new Error("FRESH_HANDLER.spawn: replacement ctx missing sendUserMessage");
+				}
+				await freshCtx.sendUserMessage(prompt);
+				await body(freshCtx);
+			},
+		});
+		return { cancelled };
+	},
+	async send(ctx, msg) {
+		// Inside fresh-policy stages, ctx is the replacement delivered to
+		// `withSession` — Pi guarantees `sendUserMessage` is present there.
+		// The port marks it optional because the outer command ctx lacks it.
+		if (!ctx.sendUserMessage) {
+			throw new Error("FRESH_HANDLER.send: replacement ctx missing sendUserMessage");
+		}
+		await ctx.sendUserMessage(msg);
+	},
+};
+
+export const CONTINUE_HANDLER: SessionPolicyHandler = {
+	branchOffset: (captured) => captured,
+	async spawn(ctx, prompt, body, host) {
+		// Prefer the live `ctx.sendUserMessage` over the captured `host`.
+		// Pi marks the registry-level host handle stale after the first
+		// `ctx.newSession()`, so a continue stage that follows a fresh
+		// stage would throw "extension ctx is stale" if we called
+		// `host.sendUserMessage` here. The inner replacement ctx delivered
+		// to `withSession` always exposes `sendUserMessage` (the port
+		// marks it optional because only the outer command ctx lacks it).
+		// `host` remains the fallback for the workflow-start-with-continue
+		// case where there is no inner ctx yet — `enforceSessionInvariants`
+		// requires a host whenever any stage is continue-policy, so the
+		// fallback can be taken safely.
+		//
+		// Awaiting the send (vs fire-and-forget) lands transport errors on
+		// this stage's halt path; pre-I5b we discarded the promise and the
+		// runner walked the chain blind on rejection.
+		await sendIntoExistingSession(ctx, host, prompt);
+		await ctx.waitForIdle();
+		await body(ctx);
+		return { cancelled: false };
+	},
+	async send(ctx, msg, host) {
+		// Same precedence as spawn: live ctx first, captured host as
+		// fallback. Validation-retry sends always run inside a stage's
+		// session, so `ctx.sendUserMessage` is present in practice; the
+		// host branch is there for symmetry with spawn.
+		await sendIntoExistingSession(ctx, host, msg);
+		await ctx.waitForIdle();
+	},
+};
+
+/**
+ * Send a message into the already-active session. Prefers the live
+ * `ctx.sendUserMessage`; falls back to the captured registry-level
+ * `host.sendUserMessage` only when ctx doesn't expose one (workflow start
+ * with a continue-first-stage). Throws if neither path is available —
+ * `enforceSessionInvariants` should have rejected the workflow before
+ * we land here.
+ */
+async function sendIntoExistingSession(ctx: RunnerCtx, host: WorkflowHost | undefined, msg: string): Promise<void> {
+	if (ctx.sendUserMessage) {
+		await ctx.sendUserMessage(msg);
+		return;
+	}
+	if (host) {
+		await host.sendUserMessage(msg);
+		return;
+	}
+	throw new Error(
+		"CONTINUE_HANDLER: neither ctx.sendUserMessage nor a workflow host available — continue policy requires one of them",
+	);
+}
+
+export function handlerFor(policy: SessionPolicy | undefined): SessionPolicyHandler {
+	return policy === "continue" ? CONTINUE_HANDLER : FRESH_HANDLER;
+}

package/state/index.ts

@@ -0,0 +1,27 @@
+/**
+ * JSONL state public surface. Internal layout lives in `state.ts`'s
+ * header; this barrel re-exports only the symbols the rest of the
+ * package consumes.
+ */
+
+export type {
+	RoutingDecision,
+	RunSummary,
+	StageStatus,
+	WorkflowHeader,
+	WorkflowStage,
+} from "./state.js";
+export {
+	appendRoutingDecision,
+	appendStage,
+	generateRunId,
+	listArtifacts,
+	listRuns,
+	readAllStages,
+	readHeader,
+	readLastStage,
+	readRoutingDecisions,
+	stateFilePath,
+	workflowsDir,
+	writeHeader,
+} from "./state.js";

package/state/paths.ts

@@ -0,0 +1,46 @@
+/**
+ * Path + run-id helpers for the JSONL audit store. Pure functions —
+ * no I/O. Writes and reads import from here so the on-disk layout has
+ * one authoritative source.
+ *
+ *   <cwd>/.rpiv/workflows/<run-id>.jsonl
+ *
+ * The slug format mirrors `skills/_shared/now.mjs` so audit files
+ * sort chronologically by filename.
+ */
+
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Run-id generation (mirrors skills/_shared/now.mjs slug pattern)
+// ---------------------------------------------------------------------------
+
+/** 2 bytes → 4 hex chars; prevents sub-second `/wf` collisions. */
+const RUN_ID_SUFFIX_BYTES = 2;
+const SLUG_FIELD_WIDTH = 2;
+/** "YYYY-MM-DDTHH:MM:SS" — strips fractional + timezone tail of toISOString. */
+const ISO_DATETIME_LENGTH = 19;
+
+/** Format: `YYYY-MM-DD_HH-MM-SS-<4hex>`. `suffix` overridable for tests. */
+export function generateRunId(
+	now: Date = new Date(),
+	suffix: string = randomBytes(RUN_ID_SUFFIX_BYTES).toString("hex"),
+): string {
+	const pad = (n: number) => String(n).padStart(SLUG_FIELD_WIDTH, "0");
+	const iso = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+	const slug = iso.slice(0, ISO_DATETIME_LENGTH).replaceAll(":", "-").replace("T", "_");
+	return `${slug}-${suffix}`;
+}
+
+// ---------------------------------------------------------------------------
+// Directory resolution
+// ---------------------------------------------------------------------------
+
+export function workflowsDir(cwd: string): string {
+	return join(cwd, ".rpiv", "workflows");
+}
+
+export function stateFilePath(cwd: string, runId: string): string {
+	return join(workflowsDir(cwd), `${runId}.jsonl`);
+}

package/state/reads.ts

@@ -0,0 +1,190 @@
+/**
+ * Fail-soft JSONL readers. Shape-filtered, never positional — the same
+ * file can carry a header, stage rows, and routing rows, and readers
+ * pluck whichever rows match their predicate.
+ *
+ * Per-line parse: each `JSON.parse` runs in its own try/catch — a single
+ * truncated trailing line (process killed mid-append, ENOSPC, network
+ * FS hiccup) MUST NOT erase prior rows.
+ *
+ * Public surface:
+ *
+ *   - Per-row readers (`readLastStage`, `readAllStages`,
+ *     `readRoutingDecisions`) — open ONE run's JSONL and project rows
+ *     of the matching shape.
+ *   - Past-runs API (`readHeader`, `listRuns`, `listArtifacts`) —
+ *     header-only or projection-only reads sized for inspect UIs.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import type { Artifact } from "../handle.js";
+import { stateFilePath, workflowsDir } from "./paths.js";
+import type { RoutingDecision, RunSummary, WorkflowHeader, WorkflowStage } from "./state.js";
+
+/**
+ * Reads every line, filters by shape (not position). Header has no
+ * `stageNumber`; routing rows carry `type: "routing"`; stage rows have
+ * `stageNumber: number` and no `type`. Starting at line 0 keeps the first
+ * stage row recoverable even if a transient writeHeader failure left the
+ * file without its header.
+ *
+ * Each line's `JSON.parse` runs in its own try/catch — a truncated trailing
+ * line (process killed mid-`appendFileSync`, ENOSPC, network FS hiccup)
+ * MUST NOT erase prior rows. Malformed lines emit a one-shot warn and are
+ * skipped; readers see every well-formed row that landed on disk.
+ */
+function readJsonlRows<T>(cwd: string, runId: string, match: (row: unknown) => row is T): T[] {
+	let lines: string[];
+	try {
+		const filePath = stateFilePath(cwd, runId);
+		if (!existsSync(filePath)) return [];
+		const content = readFileSync(filePath, "utf-8").trim();
+		if (!content) return [];
+		lines = content.split("\n");
+	} catch (e) {
+		console.warn(`[rpiv-workflow] workflow state: ${e instanceof Error ? e.message : String(e)}`);
+		return [];
+	}
+
+	const rows: T[] = [];
+	for (const line of lines) {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch (e) {
+			console.warn(
+				`[rpiv-workflow] workflow state: skipping malformed JSONL row — ${e instanceof Error ? e.message : String(e)}`,
+			);
+			continue;
+		}
+		if (match(parsed)) rows.push(parsed);
+	}
+	return rows;
+}
+
+const isWorkflowStage = (row: unknown): row is WorkflowStage =>
+	!!row &&
+	typeof (row as { stageNumber?: unknown }).stageNumber === "number" &&
+	typeof (row as { stage?: unknown }).stage === "string";
+
+const isRoutingDecision = (row: unknown): row is RoutingDecision =>
+	!!row && (row as { type?: unknown }).type === "routing";
+
+const isWorkflowHeader = (row: unknown): row is WorkflowHeader =>
+	!!row &&
+	typeof (row as { runId?: unknown }).runId === "string" &&
+	typeof (row as { workflow?: unknown }).workflow === "string" &&
+	typeof (row as { input?: unknown }).input === "string" &&
+	typeof (row as { ts?: unknown }).ts === "string";
+
+// ---------------------------------------------------------------------------
+// Per-run readers
+// ---------------------------------------------------------------------------
+
+export function readLastStage(cwd: string, runId: string): WorkflowStage | undefined {
+	const stages = readJsonlRows(cwd, runId, isWorkflowStage);
+	return stages.length ? stages[stages.length - 1] : undefined;
+}
+
+export function readAllStages(cwd: string, runId: string): WorkflowStage[] {
+	return readJsonlRows(cwd, runId, isWorkflowStage);
+}
+
+export function readRoutingDecisions(cwd: string, runId: string): RoutingDecision[] {
+	return readJsonlRows(cwd, runId, isRoutingDecision);
+}
+
+/**
+ * Project a run's stage rows to the (stage, artifact) pairs that
+ * actually carried at least one artifact. One entry per artifact —
+ * stages with multi-artifact collectors expand to N entries. Used by
+ * `notifyPartialArtifacts` for the failure recap and by past-runs UIs
+ * (the `listRuns` API) for run summaries.
+ *
+ * `stage` is the workflow stage's record key (always present); `skill`
+ * is the Pi skill body when this row recorded a skill stage (absent
+ * for script stages).
+ *
+ * Reads from `output.artifacts` (single source); rows without an
+ * output, or with an empty artifacts list, contribute nothing.
+ */
+export function listArtifacts(
+	cwd: string,
+	runId: string,
+): Array<{ stage: string; skill?: string; artifact: Artifact }> {
+	const out: Array<{ stage: string; skill?: string; artifact: Artifact }> = [];
+	for (const s of readAllStages(cwd, runId)) {
+		const artifacts = s.output?.artifacts;
+		if (!artifacts) continue;
+		for (const artifact of artifacts) out.push({ stage: s.stage, skill: s.skill, artifact });
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Past-runs enumeration (header-only)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read only the first JSONL line and parse it as a `WorkflowHeader`. Used
+ * by `listRuns` so enumerating N past runs reads N first-lines instead
+ * of fully parsing every row in every file. Returns undefined when the
+ * file is missing, empty, or the first line doesn't match the header
+ * shape.
+ *
+ * Fail-soft like every other reader — never throws.
+ */
+export function readHeader(cwd: string, runId: string): WorkflowHeader | undefined {
+	try {
+		const filePath = stateFilePath(cwd, runId);
+		if (!existsSync(filePath)) return undefined;
+		const content = readFileSync(filePath, "utf-8");
+		const firstLine = content.split("\n", 1)[0] ?? "";
+		if (!firstLine) return undefined;
+		const parsed = JSON.parse(firstLine);
+		return isWorkflowHeader(parsed) ? parsed : undefined;
+	} catch {
+		// Malformed JSON or I/O error — caller treats as "header unreadable".
+		return undefined;
+	}
+}
+
+/**
+ * Enumerate every `<cwd>/.rpiv/workflows/<run-id>.jsonl` and return its
+ * header projected as a `RunSummary`. Empty array when the workflows
+ * directory doesn't exist (no runs yet). Files without a valid header
+ * are skipped silently (corrupt / mid-write).
+ *
+ * Header-only reads — full stage rows aren't parsed (see `readHeader`'s
+ * doc). Past-runs UIs page through the summary; opening a specific run
+ * for inspection still calls `readAllStages` / `listArtifacts`.
+ *
+ * Sort is filesystem-order — callers that want chronological order can
+ * sort by `ts` (run-id slug already encodes time, so a string sort on
+ * `runId` is monotonic for runs created on the same host).
+ */
+export function listRuns(cwd: string): RunSummary[] {
+	const dir = workflowsDir(cwd);
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		// Directory doesn't exist (no runs yet) or unreadable — treat as empty.
+		return [];
+	}
+	const summaries: RunSummary[] = [];
+	for (const name of entries) {
+		if (!name.endsWith(".jsonl")) continue;
+		const runId = name.slice(0, -".jsonl".length);
+		const header = readHeader(cwd, runId);
+		if (header)
+			summaries.push({
+				runId: header.runId,
+				workflow: header.workflow,
+				input: header.input,
+				ts: header.ts,
+				trigger: header.trigger,
+			});
+	}
+	return summaries;
+}

package/state/state.ts

@@ -0,0 +1,115 @@
+/**
+ * JSONL state at `.rpiv/workflows/<run-id>.jsonl`. Append-only audit
+ * trail; every line is a self-contained JSON object. All I/O is
+ * fail-soft (logs via console.warn with `[rpiv-workflow]` prefix, never
+ * throws).
+ *
+ * Internally split into three modules:
+ *   - paths.ts  — workflowsDir + stateFilePath + generateRunId
+ *   - writes.ts — tryAppendJsonl + writeHeader + appendStage +
+ *                 appendRoutingDecision
+ *   - reads.ts  — readLastStage + readAllStages + readRoutingDecisions +
+ *                 listArtifacts + readHeader + listRuns
+ *
+ * This file owns the row shapes + types + the public barrel; everything
+ * else lives in a focused module.
+ */
+
+import type { Output } from "../output.js";
+import type { RunTrigger } from "../triggers.js";
+
+// ---------------------------------------------------------------------------
+// Row shapes
+// ---------------------------------------------------------------------------
+
+export type StageStatus = "completed" | "failed" | "skipped" | "aborted";
+
+/**
+ * Audit files are debug artifacts — no migration provided. Readers
+ * shape-filter on `stageNumber`, so any rows that don't satisfy the
+ * current shape are silently skipped.
+ *
+ * Two identity fields:
+ *  - `stage` — the workflow stage's record key. Always present. The
+ *    audit row's "which step ran" answer; stable across skill-body
+ *    overrides and aliased stages.
+ *  - `skill?` — the Pi skill body invoked, when this row records a
+ *    skill stage. Absent for script stages (`StageDef.run`); equal to
+ *    `stage` in the common case where `produces()` / `acts()` defaults
+ *    the skill body to the record key.
+ *
+ * The row no longer carries a top-level `artifact` field — discovery
+ * moved into the collector, and the canonical artifact list lives on
+ * `output.artifacts`. Readers project from there via `listArtifacts`.
+ */
+export interface WorkflowStage {
+	stageNumber: number;
+	stage: string;
+	skill?: string;
+	status: StageStatus;
+	ts: string;
+	output?: Output;
+	/**
+	 * Reason a terminal-failure row was written — mirrors the
+	 * `state.termination.error` set by `recordTerminalFailure`. Present
+	 * only on `status: "failed" | "aborted"` rows; absent on completed /
+	 * skipped rows. Persisting it here means post-mortems work from
+	 * JSONL alone, without depending on a transient `ctx.ui.notify` toast.
+	 */
+	errMsg?: string;
+}
+
+/** First line of the JSONL file. */
+export interface WorkflowHeader {
+	runId: string;
+	workflow: string;
+	input: string;
+	ts: string;
+	/**
+	 * What triggered the run. Optional so older JSONL files (written
+	 * before the trigger field was added) still parse — readers treat
+	 * `undefined` as "trigger unknown."
+	 */
+	trigger?: RunTrigger;
+}
+
+/**
+ * Returned by `listRuns` — projection of a JSONL header for past-run
+ * enumeration UIs. Distinct from `WorkflowHeader` only by intent (this
+ * is the "what you see in a list" shape); kept structurally compatible
+ * so callers that want the raw header can pass `RunSummary` through.
+ */
+export interface RunSummary {
+	runId: string;
+	/** Workflow name (matches `Workflow.name` at run-time). */
+	workflow: string;
+	/** Original `/wf` input the user typed. */
+	input: string;
+	/** ISO-8601 timestamp the run started at — slug-sortable. */
+	ts: string;
+	/** Mirrors `WorkflowHeader.trigger`; undefined for legacy rows. */
+	trigger?: RunTrigger;
+}
+
+export interface RoutingDecision {
+	type: "routing";
+	fromStageIndex: number;
+	fromStage: string;
+	decision: string;
+	ts: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public barrel — paths + writes + reads
+// ---------------------------------------------------------------------------
+
+export { generateRunId, stateFilePath, workflowsDir } from "./paths.js";
+export {
+	listArtifacts,
+	listRuns,
+	readAllStages,
+	readHeader,
+	readLastStage,
+	readRoutingDecisions,
+} from "./reads.js";
+export { appendRoutingDecision, appendStage, writeHeader } from "./writes.js";

package/state/writes.ts

@@ -0,0 +1,58 @@
+/**
+ * Fail-soft JSONL appends. Every public helper here is a thin wrapper
+ * around `tryAppendJsonl` so the write protocol (mkdirSync + append +
+ * stderr warn on throw) lives in one place — changes to atomicity,
+ * checksums, or alternative storage backends touch this file and this
+ * file only.
+ *
+ *   writeHeader              — best-effort; discards the return.
+ *   appendStage              — boolean; allocator gates monotonic counters on it.
+ *   appendRoutingDecision    — boolean; telemetry-not-state, dropped rows surface up.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { stateFilePath, workflowsDir } from "./paths.js";
+import type { RoutingDecision, WorkflowHeader, WorkflowStage } from "./state.js";
+
+/**
+ * Shared append primitive: ensure the workflows directory exists, then
+ * append one JSON-serialised row + newline. Returns true on success;
+ * on any throw, warns to stderr and returns false. The three public
+ * append helpers below are thin wrappers — `writeHeader` discards the
+ * return (best-effort), the others gate counters / telemetry on it.
+ */
+function tryAppendJsonl(cwd: string, runId: string, row: unknown): boolean {
+	try {
+		const dir = workflowsDir(cwd);
+		mkdirSync(dir, { recursive: true });
+		const filePath = stateFilePath(cwd, runId);
+		appendFileSync(filePath, `${JSON.stringify(row)}\n`, "utf-8");
+		return true;
+	} catch (e) {
+		console.warn(`[rpiv-workflow] workflow state: ${e instanceof Error ? e.message : String(e)}`);
+		return false;
+	}
+}
+
+export function writeHeader(cwd: string, header: WorkflowHeader): void {
+	tryAppendJsonl(cwd, header.runId, header);
+}
+
+/** Returns true on successful write — callers gate counters on this. */
+export function appendStage(cwd: string, runId: string, stage: WorkflowStage): boolean {
+	return tryAppendJsonl(cwd, runId, stage);
+}
+
+/**
+ * Returns true on successful write — callers surface the failure to the user
+ * (warning notification + result-envelope flag) so an absent row is not silently
+ * conflated with "deterministic edge, no decision recorded." Unlike `appendStage`,
+ * a dropped routing row does NOT halt the chain: the routing decision has
+ * already been made in memory (see runner.ts `nextNode`), and no in-memory
+ * state mirrors routing rows the way it mirrors stage rows — routing is
+ * write-only telemetry. Halting on telemetry failure would punish the user
+ * for transient disk weather without preserving any invariant.
+ */
+export function appendRoutingDecision(cwd: string, runId: string, row: RoutingDecision): boolean {
+	return tryAppendJsonl(cwd, runId, row);
+}