@rulvar/rulvar 1.20.0 → 1.22.0

package/README.md

@@ -2,11 +2,20 @@
 
 The batteries-included Rulvar install: re-exports the entire
 `@rulvar/core` surface plus both first-class adapters (`anthropic`,
-`openai`), the terminal progress renderer, and `recommendedDefaults`,
+`openai`), two terminal progress renderers, and `recommendedDefaults`,
 the only place the project names strong default models for the
 orchestrate and plan roles. Also installable through the unscoped alias
 package `rulvar`, which re-exports this one.
 
+The renderers are `progress()`, the live view (one row per agent with a
+status glyph, a running timer, token counts, and USD, per-role
+sub-timings when one call spans several invocation phases, the run
+header with spend against the ceiling, and a final per-role cost
+summary; repaints in place on a TTY and degrades to append-only lines in
+pipes and CI), and `renderProgress()`, the minimal one line per
+lifecycle fact. Both consume the public `WorkflowEvent` stream and
+nothing else.
+
 Part of [Rulvar](https://rulvar.com), an embeddable TypeScript engine
 for durable, budget-bounded multi-agent LLM workflows, where a completed
 LLM call is never paid for twice. Full documentation:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { InvocationRole, ModelSpec, QualityFloors, WorkflowEvent } from "@rulvar/core";
+import { InvocationRole, ModelSpec, QualityFloors, RunHandle, WorkflowEvent } from "@rulvar/core";
 import { ANTHROPIC_MODELS, AnthropicAdapterOptions, anthropic } from "@rulvar/anthropic";
 import { OPENAI_MODELS, OpenAiAdapterOptions, openai } from "@rulvar/openai";
 export * from "@rulvar/core";
@@ -16,6 +16,69 @@ interface RenderProgressOptions {
 */
 declare function renderProgress(events: AsyncIterable<WorkflowEvent>, options?: RenderProgressOptions): Promise<void>;
 //#endregion
+//#region src/live-progress.d.ts
+/** Raw output sink; chunks may contain ANSI and partial lines. */
+interface ProgressSink {
+  write(chunk: string): void;
+  isTTY?: boolean;
+  columns?: number;
+  rows?: number;
+}
+/** Injectable time source; every() returns a cancel function. */
+interface ProgressClock {
+  now(): number;
+  every(ms: number, fn: () => void): () => void;
+}
+type ProgressMode = "auto" | "tty" | "lines" | "off";
+interface ProgressOptions {
+  /** Defaults to process.stderr so application stdout stays clean. */
+  sink?: ProgressSink;
+  /** Defaults to a monotonic clock (performance.now) plus setInterval. */
+  clock?: ProgressClock;
+  /**
+  * 'auto' (default) picks 'tty' when the sink reports a TTY and the
+  * environment is not CI or TERM=dumb, else 'lines'.
+  */
+  mode?: ProgressMode;
+  /** Repaints per second in tty mode, clamped to 1..30. Default 10. */
+  fps?: number;
+  /** SGR colors. Default: true in tty mode unless NO_COLOR is set. */
+  color?: boolean;
+  /** Column override. Default sink.columns, else 80. */
+  width?: number;
+  /** Body rows before the oldest completed rows collapse. Default 24. */
+  maxRows?: number;
+  /** Header title. Default: the workflow name from run:start. */
+  title?: string;
+}
+interface ProgressHandle {
+  /** The resolved mode after auto detection. */
+  readonly mode: "tty" | "lines" | "off";
+  /** Settles after the final frame is written; never rejects. */
+  readonly done: Promise<void>;
+  /** Force an immediate repaint outside the tick (tests, custom pacing). */
+  render(): void;
+  /**
+  * Idempotent. final=true (default) paints the settle frame; false
+  * freezes the current frame in scrollback. Always restores the cursor
+  * and resolves `done`.
+  */
+  stop(final?: boolean): void;
+}
+type ProgressSource = RunHandle<unknown> | Promise<RunHandle<unknown>> | AsyncIterable<WorkflowEvent>;
+/**
+* Attaches a live progress view to a run and returns its handle. Accepts
+* a RunHandle (subscribes through `on()`, leaving `handle.events` free
+* for the host, and enriches the final frame from `RunOutcome.cost`;
+* `orchestrate` returns exactly such a handle, so
+* `progress(orchestrate(...))` composes directly), a promise resolving
+* to a handle (for wrappers that construct one asynchronously), or a
+* raw WorkflowEvent iterable (the gapless path for resumes:
+* `progress(resumed.events)`; note it consumes that one-shot iterable).
+* The view auto-stops when the run settles.
+*/
+declare function progress(source: ProgressSource, options?: ProgressOptions): ProgressHandle;
+//#endregion
 //#region src/defaults.d.ts
 /**
 * Drop-in engine defaults: `createEngine({ ..., defaults: { routing:
@@ -31,4 +94,4 @@ declare const recommendedDefaults: {
   floors: QualityFloors;
 };
 //#endregion
-export { ANTHROPIC_MODELS, type AnthropicAdapterOptions, OPENAI_MODELS, type OpenAiAdapterOptions, type RenderProgressOptions, anthropic, openai, recommendedDefaults, renderProgress };
+export { ANTHROPIC_MODELS, type AnthropicAdapterOptions, OPENAI_MODELS, type OpenAiAdapterOptions, type ProgressClock, type ProgressHandle, type ProgressMode, type ProgressOptions, type ProgressSink, type ProgressSource, type RenderProgressOptions, anthropic, openai, progress, recommendedDefaults, renderProgress };

package/dist/index.js

@@ -1,7 +1,21 @@
+import { sanitizeTerminalText } from "@rulvar/core";
 import { ANTHROPIC_MODELS, anthropic } from "@rulvar/anthropic";
 import { OPENAI_MODELS, openai } from "@rulvar/openai";
 export * from "@rulvar/core";
 //#region src/render-progress.ts
+/**
+* Minimal terminal progress renderer (M1-T10): consumes the WorkflowEvent
+* stream of a RunHandle and writes one line per lifecycle fact. Plain
+* lines, no cursor control: readable in CI logs and pipes as well as TTYs.
+*
+* Event stream contract: https://docs.rulvar.com/guide/observability
+* (the terminal progress renderer is one of the four stream consumers).
+*
+* Every emitted line passes through the shared terminal sanitizer before
+* it reaches the sink, so an untrusted provider/tool/log string can never
+* inject a control sequence or a second physical line (v1.21.0 review
+* P2-1).
+*/
 function usd(amount) {
 	return `${amount.toFixed(4)} USD`;
 }
@@ -10,9 +24,10 @@ function usd(amount) {
 * the final run:end line.
 */
 async function renderProgress(events, options) {
-	const write = options?.write ?? ((line) => {
+	const sink = options?.write ?? ((line) => {
 		process.stderr.write(`${line}\n`);
 	});
+	const write = (line) => sink(sanitizeTerminalText(line));
 	const logs = options?.logs ?? true;
 	for await (const event of events) switch (event.type) {
 		case "run:start":
@@ -49,6 +64,587 @@ async function renderProgress(events, options) {
 	}
 }
 //#endregion
+//#region src/live-progress.ts
+/**
+* Live terminal progress view (v1.21.0): a claude-workflows-style tree
+* over the WorkflowEvent stream, one row per agent with a status glyph,
+* a running timer, token counts, and USD, plus per-role sub-timings when
+* one agent call spans several invocation phases (loop, summarize,
+* finalize, extract). The minimal line-per-event `renderProgress` stays
+* untouched next door; this renderer is the rich, cursor-addressed
+* sibling with an append-only fallback for pipes and CI.
+*
+* Honesty rules inherited from the event contract
+* (https://docs.rulvar.com/guide/observability): exact token counts
+* exist only at `agent:end`, so running rows show elapsed time and a
+* tilde-marked character estimate from `agent:stream` deltas; run-level
+* USD is live through `budget:update`; per-role dollars appear in the
+* final summary only when the source is a RunHandle (they come from
+* `RunOutcome.cost.byRole`, not from any event). Replayed lifecycle
+* events render dim with a `replay` tag, never spin, and never add to
+* totals: the authoritative money numbers are `budget:update.spentUsd`
+* and `run:end.totalUsd`, which are immune to replay double counting.
+*
+* The reducer is defensive by contract: unknown event types are ignored
+* and every dynamic field, including the required ones, is read
+* defensively (optional chaining with fallbacks), so a malformed event
+* degrades a row rather than throwing and stopping the view; an unknown
+* parent span attaches at the root, and a mid-run attach synthesizes a
+* root instead of failing.
+*/
+/**
+* Positive-integer option normalization (v1.21.0 review P3-2): a
+* non-finite or below-minimum caller value falls back rather than
+* poisoning the geometry (a NaN width breaks the clip, a NaN fps yields
+* a NaN interval). Fractions floor.
+*/
+function posIntOption(value, fallback, min) {
+	if (value === void 0 || !Number.isFinite(value)) return fallback;
+	return Math.max(min, Math.floor(value));
+}
+function fmtDuration(ms) {
+	if (!Number.isFinite(ms) || ms < 0) ms = 0;
+	const s = ms / 1e3;
+	if (s < 10) return `${s.toFixed(1)}s`;
+	if (s < 60) return `${String(Math.floor(s))}s`;
+	const minutes = Math.floor(s / 60);
+	if (minutes < 60) return `${String(minutes)}m ${String(Math.floor(s % 60)).padStart(2, "0")}s`;
+	return `${String(Math.floor(minutes / 60))}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+function fmtTokens(count) {
+	if (count < 1e3) return String(count);
+	if (count < 1e4) return `${(count / 1e3).toFixed(1)}k`;
+	if (count < 1e6) return `${String(Math.round(count / 1e3))}k`;
+	return `${(count / 1e6).toFixed(1)}M`;
+}
+function fmtUsd(amount) {
+	if (amount === 0) return "$0";
+	if (amount >= 100) return `$${String(Math.round(amount))}`;
+	if (amount >= 1) return `$${amount.toFixed(2)}`;
+	if (amount >= .01) return `$${amount.toFixed(3)}`;
+	return `$${amount.toFixed(4)}`;
+}
+function bar(spent, ceiling, cells) {
+	const ratio = ceiling <= 0 ? 1 : Math.min(1, spent / ceiling);
+	const filled = Math.round(ratio * cells);
+	return "#".repeat(filled) + ".".repeat(cells - filled);
+}
+const SPINNER = [
+	"|",
+	"/",
+	"-",
+	"\\"
+];
+const SGR_STRIP = /* @__PURE__ */ new RegExp("\\u001B\\[[0-9;]*m", "gu");
+function newState(title) {
+	return {
+		...title === void 0 ? {} : { title },
+		resumed: false,
+		status: "running",
+		spentUsd: 0,
+		nodes: /* @__PURE__ */ new Map(),
+		roots: [],
+		notices: [],
+		wakes: 0,
+		admitted: 0,
+		rejected: 0,
+		dirty: true
+	};
+}
+function nodeOf(state, event, kind, title) {
+	const existing = state.nodes.get(event.spanId);
+	if (existing !== void 0) return existing;
+	const node = {
+		spanId: event.spanId,
+		...event.parentSpanId === void 0 ? {} : { parentSpanId: event.parentSpanId },
+		kind,
+		title,
+		status: "running",
+		replayed: event.replayed === true,
+		roles: [],
+		streamedChars: 0,
+		toolCount: 0,
+		children: [],
+		startedAt: 0
+	};
+	state.nodes.set(event.spanId, node);
+	const parent = event.parentSpanId === void 0 || event.parentSpanId === event.spanId ? void 0 : state.nodes.get(event.parentSpanId);
+	if (parent !== void 0) parent.children.push(event.spanId);
+	else state.roots.push(event.spanId);
+	return node;
+}
+/**
+* Untrusted wire strings (model ids, tool names, error messages, log
+* text, workflow and label metadata) may carry control characters and
+* escape sequences that break the repaint arithmetic or leak terminal
+* control. The shared core sanitizer strips C0, DEL, C1, and whole
+* ESC-initiated CSI/OSC/DCS sequences before interpolation; the
+* renderer's own SGR is added by paint() afterward (v1.21.0 review
+* P2-1).
+*/
+const scrub = sanitizeTerminalText;
+function agentTitle(event) {
+	const base = event.agentType === void 0 || event.agentType === "" ? "agent" : scrub(event.agentType);
+	return event.label === void 0 || event.label === "" ? base : `${base} (${scrub(event.label)})`;
+}
+/** The tool event's span is the agent's own span or a child of it. */
+function toolTarget(state, event) {
+	return state.nodes.get(event.spanId) ?? (event.parentSpanId === void 0 ? void 0 : state.nodes.get(event.parentSpanId));
+}
+function applyEvent(state, event, now) {
+	state.dirty = true;
+	switch (event.type) {
+		case "run:start":
+			state.runId = event.runId;
+			state.resumed = event.resumed === true;
+			state.startedAt ??= now;
+			state.title ??= scrub(event.workflow);
+			break;
+		case "run:end":
+			state.status = event.status;
+			state.totalUsd = event.totalUsd;
+			state.endedAt = now;
+			for (const node of state.nodes.values()) {
+				if (node.endedAt === void 0 && node.kind !== "phase") {
+					node.endedAt = now;
+					if (node.status === "running" || node.status === "queued") node.status = "interrupted";
+				}
+				const open = node.roles.at(-1);
+				if (open !== void 0 && open.endedAt === void 0) open.endedAt = now;
+			}
+			break;
+		case "phase:start": {
+			const node = nodeOf(state, event, "phase", scrub(event.phase));
+			node.startedAt = now;
+			node.status = "ok";
+			break;
+		}
+		case "budget:update":
+			state.spentUsd = event.spentUsd;
+			state.ceilingUsd = event.remainingUsd === null ? void 0 : event.spentUsd + event.remainingUsd;
+			break;
+		case "log":
+			if (event.level === "warn" || event.level === "error") {
+				state.notices.push(scrub(`${event.level}: ${event.msg}`));
+				if (state.notices.length > 2) state.notices.shift();
+			}
+			break;
+		case "external:waiting":
+			state.banner = scrub(`waiting on external: ${event.key}`);
+			break;
+		case "approval:pending":
+			state.banner = scrub(`approval pending: ${event.toolName}`);
+			break;
+		case "child:start": {
+			const node = nodeOf(state, event, "child", scrub(`${event.workflow} (${event.scope})`));
+			node.startedAt = now;
+			break;
+		}
+		case "child:end": {
+			const node = state.nodes.get(event.spanId);
+			if (node !== void 0) {
+				node.status = event.status;
+				node.endedAt = now;
+			}
+			break;
+		}
+		case "agent:queued": {
+			const node = nodeOf(state, event, "agent", agentTitle(event));
+			node.status = "queued";
+			node.startedAt = now;
+			break;
+		}
+		case "agent:start": {
+			state.banner = void 0;
+			const node = nodeOf(state, event, "agent", agentTitle(event));
+			if (node.status === "queued" || node.roles.length === 0) node.startedAt = now;
+			node.status = "running";
+			node.model = scrub(event.model);
+			if (event.replayed === true) node.replayed = true;
+			const open = node.roles.at(-1);
+			if (open !== void 0 && open.endedAt === void 0) open.endedAt = now;
+			node.roles.push({
+				role: event.role,
+				startedAt: now
+			});
+			break;
+		}
+		case "agent:stream": {
+			const node = state.nodes.get(event.spanId);
+			if (node !== void 0) node.streamedChars += event.delta.length;
+			break;
+		}
+		case "agent:error": {
+			const node = state.nodes.get(event.spanId);
+			if (node !== void 0) node.badge = event.willRetry ? "retry" : scrub(`error: ${event.error?.message ?? ""}`);
+			break;
+		}
+		case "agent:schema-retry": {
+			const node = state.nodes.get(event.spanId);
+			if (node !== void 0) node.badge = `schema ${String(event.attempt)}/${String(event.maxAttempts)}`;
+			break;
+		}
+		case "agent:end": {
+			state.banner = void 0;
+			const node = nodeOf(state, event, "agent", agentTitle(event));
+			node.status = event.status;
+			node.endedAt = now;
+			node.usage = {
+				input: event.usage?.inputTokens ?? 0,
+				output: event.usage?.outputTokens ?? 0
+			};
+			node.costUsd = event.costUsd;
+			if (event.replayed === true) node.replayed = true;
+			if (node.status === "ok") node.badge = void 0;
+			const open = node.roles.at(-1);
+			if (open !== void 0 && open.endedAt === void 0) open.endedAt = now;
+			break;
+		}
+		case "tool:start": {
+			const node = toolTarget(state, event);
+			if (node !== void 0) node.toolActive = scrub(event.toolName);
+			break;
+		}
+		case "tool:end": {
+			const node = toolTarget(state, event);
+			if (node !== void 0) {
+				node.toolActive = void 0;
+				node.toolCount += 1;
+				if (event.outcome === "denied") node.badge = scrub(`tool ${event.toolName} denied`);
+			}
+			break;
+		}
+		case "orchestrator:woke":
+			state.wakes += 1;
+			break;
+		case "spawn:admitted":
+			state.admitted += 1;
+			break;
+		case "spawn:rejected":
+			state.rejected += 1;
+			state.notices.push(`spawn rejected: ${event.code}`);
+			if (state.notices.length > 2) state.notices.shift();
+			break;
+		default: break;
+	}
+}
+const GLYPHS = {
+	ok: "*",
+	running: "",
+	queued: "o",
+	error: "x",
+	cancelled: "x",
+	exhausted: "x",
+	interrupted: "x",
+	escalated: "!"
+};
+function paint(text, code, style) {
+	return style.color ? `[${code}m${text}` : text;
+}
+function nodeRow(node, now, spinner, style) {
+	const running = node.endedAt === void 0 && node.status === "running";
+	const glyph = running ? node.replayed ? "*" : spinner : GLYPHS[node.status] ?? "*";
+	const parts = [glyph === "" ? spinner : glyph, node.title];
+	if (node.model !== void 0) parts.push(paint(node.model, "2", style));
+	const currentRole = node.roles.at(-1)?.role;
+	if (currentRole !== void 0 && currentRole !== "loop") parts.push(paint(`> ${currentRole}`, "36", style));
+	if (node.replayed) parts.push(paint("replay", "2", style));
+	else if (node.startedAt > 0 && node.kind !== "phase") {
+		const elapsed = (node.endedAt ?? now) - node.startedAt;
+		parts.push(fmtDuration(elapsed));
+	}
+	if (node.usage !== void 0) parts.push(`in ${fmtTokens(node.usage.input)} out ${fmtTokens(node.usage.output)}`);
+	else if (running && node.streamedChars > 0) parts.push(paint(`~${fmtTokens(Math.ceil(node.streamedChars / 4))} out`, "2", style));
+	if (node.costUsd !== void 0 && !node.replayed) parts.push(fmtUsd(node.costUsd));
+	if (node.toolActive !== void 0) parts.push(paint(`tool: ${node.toolActive}`, "33", style));
+	else if (node.toolCount > 0) parts.push(paint(`${String(node.toolCount)} tool${node.toolCount === 1 ? "" : "s"}`, "2", style));
+	if (node.badge !== void 0) parts.push(paint(node.badge, node.badge.startsWith("error") ? "31" : "33", style));
+	if (node.status === "queued") parts.push(paint("queued", "2", style));
+	return parts.join("  ");
+}
+function roleRow(node, now) {
+	if (node.roles.length < 2) return;
+	return `roles: ${node.roles.map((slice) => {
+		const elapsed = (slice.endedAt ?? now) - slice.startedAt;
+		return `${slice.role} ${fmtDuration(elapsed)}${slice.endedAt === void 0 ? ".." : ""}`;
+	}).join(" · ")}`;
+}
+function composeTree(state, now, spinner, style) {
+	const lines = [];
+	const visited = /* @__PURE__ */ new Set();
+	const walk = (spanId, depth) => {
+		const node = state.nodes.get(spanId);
+		if (node === void 0 || visited.has(spanId)) return;
+		visited.add(spanId);
+		const indent = "  ".repeat(depth + 1);
+		if (node.kind === "phase") lines.push(`${indent}${paint(`[${node.title}]`, "1", style)}`);
+		else {
+			lines.push(indent + nodeRow(node, now, spinner, style));
+			const roles = roleRow(node, now);
+			if (roles !== void 0) lines.push(indent + "  " + paint(roles, "2", style));
+		}
+		for (const child of node.children) walk(child, depth + 1);
+	};
+	for (const root of state.roots) walk(root, 0);
+	return lines;
+}
+function composeFrame(state, now, tick, style, width, maxRows, maxHeight) {
+	const spinner = SPINNER[tick % SPINNER.length];
+	const lines = [];
+	const running = state.endedAt === void 0;
+	const head = [running ? spinner : state.status === "ok" ? "*" : "x", state.title ?? "run"];
+	if (state.runId !== void 0) head.push(paint(`run ${state.runId}`, "2", style));
+	if (state.resumed) head.push(paint("(resumed)", "2", style));
+	if (state.startedAt !== void 0) head.push(fmtDuration((state.endedAt ?? now) - state.startedAt));
+	const spent = state.totalUsd ?? state.spentUsd;
+	if (state.ceilingUsd !== void 0) {
+		head.push(`${fmtUsd(spent)} / ${fmtUsd(state.ceilingUsd)}`);
+		head.push(bar(spent, state.ceilingUsd, 12));
+	} else if (spent > 0) head.push(fmtUsd(spent));
+	lines.push(head.join("  "));
+	let body = composeTree(state, now, spinner, style);
+	if (body.length > maxRows) {
+		const hidden = body.length - maxRows;
+		body = [paint(`  ... ${String(hidden)} earlier rows hidden`, "2", style), ...body.slice(hidden)];
+	}
+	lines.push(...body);
+	if (state.wakes + state.admitted + state.rejected > 0) lines.push("  " + paint(`orch: wakes ${String(state.wakes)} · spawns ${String(state.admitted)} admitted, ${String(state.rejected)} rejected`, "2", style));
+	if (state.banner !== void 0 && running) lines.push("  " + paint(state.banner, "33", style));
+	for (const notice of state.notices) lines.push("  " + paint(notice, "33", style));
+	if (!running) {
+		const roleCosts = state.cost?.byRole;
+		if (roleCosts !== void 0) {
+			const nonzero = Object.entries(roleCosts).filter(([, value]) => value > 0);
+			if (nonzero.length > 0) lines.push("  " + nonzero.map(([role, value]) => `${role} ${fmtUsd(value)}`).join(" · "));
+		}
+		lines.push(`${state.status === "ok" ? "*" : "x"} ${state.status}` + (state.totalUsd === void 0 ? "" : `  total ${fmtUsd(state.totalUsd)}`));
+	}
+	let clamped = lines;
+	if (maxHeight !== void 0 && lines.length > maxHeight && maxHeight >= 3) {
+		const keepTail = Math.min(running ? 1 : 3, maxHeight - 2);
+		const hidden = lines.length - 1 - keepTail - 1;
+		clamped = [
+			lines[0] ?? "",
+			paint(`  ... ${String(hidden)} lines hidden (terminal too short)`, "2", style),
+			...lines.slice(lines.length - keepTail)
+		];
+	}
+	const limit = Math.max(0, width - 1);
+	return clamped.map((line) => {
+		const plain = line.replace(SGR_STRIP, "");
+		if (plain.length <= limit) return line;
+		return limit >= 4 ? plain.slice(0, limit - 3) + "..." : plain.slice(0, limit);
+	});
+}
+function defaultSink() {
+	return process.stderr;
+}
+function defaultClock() {
+	return {
+		now: () => performance.now(),
+		every: (ms, fn) => {
+			const timer = setInterval(fn, ms);
+			return () => clearInterval(timer);
+		}
+	};
+}
+function resolveMode(option, sink) {
+	if (option !== void 0 && option !== "auto") return option;
+	const dumb = process.env.TERM === "dumb" || process.env.CI !== void 0;
+	return sink.isTTY === true && !dumb ? "tty" : "lines";
+}
+function isHandle(source) {
+	return typeof source.on === "function" && typeof source.result?.then === "function";
+}
+/** Every event type the reducer renders; handle mode subscribes per type. */
+const CONSUMED_TYPES = [
+	"run:start",
+	"run:end",
+	"phase:start",
+	"budget:update",
+	"log",
+	"external:waiting",
+	"approval:pending",
+	"child:start",
+	"child:end",
+	"agent:queued",
+	"agent:start",
+	"agent:stream",
+	"agent:error",
+	"agent:schema-retry",
+	"agent:end",
+	"tool:start",
+	"tool:end",
+	"orchestrator:woke",
+	"spawn:admitted",
+	"spawn:rejected"
+];
+/**
+* Attaches a live progress view to a run and returns its handle. Accepts
+* a RunHandle (subscribes through `on()`, leaving `handle.events` free
+* for the host, and enriches the final frame from `RunOutcome.cost`;
+* `orchestrate` returns exactly such a handle, so
+* `progress(orchestrate(...))` composes directly), a promise resolving
+* to a handle (for wrappers that construct one asynchronously), or a
+* raw WorkflowEvent iterable (the gapless path for resumes:
+* `progress(resumed.events)`; note it consumes that one-shot iterable).
+* The view auto-stops when the run settles.
+*/
+function progress(source, options) {
+	const sink = options?.sink ?? defaultSink();
+	const clock = options?.clock ?? defaultClock();
+	const mode = resolveMode(options?.mode, sink);
+	const style = { color: options?.color ?? (mode === "tty" && process.env.NO_COLOR === void 0) };
+	const columns = posIntOption(sink.columns, 80, 1);
+	const rows = posIntOption(sink.rows, 32, 3);
+	const width = posIntOption(options?.width, columns, 1);
+	const maxRows = posIntOption(options?.maxRows, Math.max(6, Math.min(24, rows - 8)), 1);
+	const fps = Math.min(30, posIntOption(options?.fps, 10, 1));
+	const state = newState(options?.title === void 0 ? void 0 : scrub(options.title));
+	let settled = false;
+	let resolveDone = () => void 0;
+	const done = new Promise((resolve) => {
+		resolveDone = resolve;
+	});
+	if (mode === "off") {
+		if (!isHandle(source) && typeof source.then === "function") source.catch(() => void 0);
+		settled = true;
+		resolveDone();
+		return {
+			mode,
+			done,
+			render: () => void 0,
+			stop: () => void 0
+		};
+	}
+	let tick = 0;
+	let paintedLines = 0;
+	let lastLinesBudgetAt;
+	const paintFrame = () => {
+		const rawRows = sink.rows;
+		const maxHeight = typeof rawRows === "number" && Number.isFinite(rawRows) ? Math.max(3, Math.floor(rawRows) - 1) : void 0;
+		const frame = composeFrame(state, clock.now(), tick, style, width, maxRows, maxHeight);
+		const erase = paintedLines > 0 ? `[${String(paintedLines)}A` : "";
+		sink.write(erase + frame.join("\n") + "\n");
+		paintedLines = frame.length;
+		state.dirty = false;
+	};
+	const lineFor = (event, now) => {
+		switch (event.type) {
+			case "run:start": return `run ${event.runId} started: ${event.workflow}${event.resumed ? " (resumed)" : ""}`;
+			case "phase:start": return `phase: ${event.phase}`;
+			case "agent:start": {
+				const node = state.nodes.get(event.spanId);
+				const inner = node !== void 0 && node.roles.length > 1;
+				return `agent ${agentTitle(event)} -> ${event.model} (${event.role})${inner ? " [inner phase]" : ""}`;
+			}
+			case "agent:end": {
+				const node = state.nodes.get(event.spanId);
+				const elapsed = node === void 0 || node.replayed || node.startedAt <= 0 ? "" : ` in ${fmtDuration((node.endedAt ?? now) - node.startedAt)}`;
+				const roles = node !== void 0 && node.roles.length > 1 ? ` [${node.roles.map((slice) => slice.role).join(" > ")}]` : "";
+				return `agent ${agentTitle(event)} ${event.status}${elapsed}: in ${fmtTokens(event.usage?.inputTokens ?? 0)} out ${fmtTokens(event.usage?.outputTokens ?? 0)}, ${fmtUsd(event.costUsd)}${roles}${event.replayed === true ? " (replay)" : ""}`;
+			}
+			case "agent:error": return `agent ${agentTitle(event)} error: ${event.error?.message ?? ""}` + (event.willRetry ? " (will retry)" : "");
+			case "budget:update":
+				if (lastLinesBudgetAt !== void 0 && now - lastLinesBudgetAt < 1e3) return;
+				lastLinesBudgetAt = now;
+				return `budget: ${fmtUsd(event.spentUsd)}` + (event.remainingUsd === null ? "" : ` of ${fmtUsd(event.spentUsd + event.remainingUsd)}`);
+			case "log": return event.level === "warn" || event.level === "error" ? `[${event.level}] ${event.msg}` : void 0;
+			case "external:waiting": return `waiting on external: ${event.key}`;
+			case "approval:pending": return `approval pending: ${event.toolName}`;
+			case "run:end": return `run finished: ${event.status} (total ${fmtUsd(event.totalUsd)})`;
+			default: return;
+		}
+	};
+	const onEvent = (event) => {
+		const now = clock.now();
+		applyEvent(state, event, now);
+		if (mode === "lines") {
+			const line = lineFor(event, now);
+			if (line !== void 0) sink.write(scrub(line) + "\n");
+		}
+	};
+	const finishLines = () => {
+		const roleCosts = state.cost?.byRole;
+		if (roleCosts === void 0) return;
+		const nonzero = Object.entries(roleCosts).filter(([, value]) => value > 0);
+		if (nonzero.length > 0) sink.write(`cost by role: ${nonzero.map(([r, v]) => `${r} ${fmtUsd(v)}`).join(", ")}\n`);
+	};
+	let cancelTick;
+	let unsubscribe = [];
+	const handleApi = {
+		mode,
+		done,
+		render: () => {
+			if (!settled && mode === "tty") {
+				tick += 1;
+				paintFrame();
+			}
+		},
+		stop: (final = true) => {
+			if (settled) return;
+			settled = true;
+			cancelTick?.();
+			for (const off of unsubscribe) off();
+			unsubscribe = [];
+			if (mode === "tty") {
+				if (final) paintFrame();
+				sink.write("\x1B[?25h");
+			} else if (final) finishLines();
+			resolveDone();
+		}
+	};
+	if (mode === "tty") {
+		sink.write("\x1B[?25l");
+		cancelTick = clock.every(Math.round(1e3 / fps), () => {
+			if (settled) return;
+			tick += 1;
+			const anyRunning = state.endedAt === void 0;
+			if (state.dirty || anyRunning) paintFrame();
+		});
+	}
+	const attachHandle = (handle) => {
+		if (settled) {
+			handle.result.catch(() => void 0);
+			return;
+		}
+		for (const type of CONSUMED_TYPES) unsubscribe.push(handle.on(type, onEvent));
+		handle.result.then((outcome) => {
+			state.cost = outcome.cost;
+			state.status = outcome.status;
+			state.totalUsd = outcome.cost.totalUsd;
+			state.endedAt ??= clock.now();
+		}).catch((thrown) => {
+			state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+			state.endedAt ??= clock.now();
+		}).finally(() => {
+			handleApi.stop(true);
+		});
+	};
+	if (isHandle(source)) attachHandle(source);
+	else if (typeof source.then === "function") source.then((handle) => {
+		attachHandle(handle);
+	}).catch((thrown) => {
+		state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+		state.endedAt ??= clock.now();
+		handleApi.stop(true);
+	});
+	else (async () => {
+		try {
+			for await (const event of source) {
+				if (settled) break;
+				onEvent(event);
+			}
+		} catch (thrown) {
+			state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+		} finally {
+			state.endedAt ??= clock.now();
+			handleApi.stop(true);
+		}
+	})();
+	return handleApi;
+}
+//#endregion
 //#region src/defaults.ts
 /**
 * Drop-in engine defaults: `createEngine({ ..., defaults: { routing:
@@ -98,4 +694,4 @@ const recommendedDefaults = {
 	} }
 };
 //#endregion
-export { ANTHROPIC_MODELS, OPENAI_MODELS, anthropic, openai, recommendedDefaults, renderProgress };
+export { ANTHROPIC_MODELS, OPENAI_MODELS, anthropic, openai, progress, recommendedDefaults, renderProgress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/rulvar",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Rulvar umbrella package: re-exports @rulvar/core, both first-class adapters, the file store, and the terminal progress renderer. Also installable through the unscoped alias package rulvar, which re-exports this one.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,16 +22,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.20.0",
-    "@rulvar/anthropic": "1.20.0",
-    "@rulvar/openai": "1.20.0"
+    "@rulvar/core": "1.22.0",
+    "@rulvar/anthropic": "1.22.0",
+    "@rulvar/openai": "1.22.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
     "zod": "^4.4.3",
-    "@rulvar/testing": "1.20.0"
+    "@rulvar/testing": "1.22.0"
   },
   "repository": {
     "type": "git",