@rulvar/cli 1.48.0 → 1.50.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as processIo } from "./io-BK1hP3Od.js";
+import { r as runCli, t as processIo } from "./io-DK9Ji_H2.js";
 import { sanitizeTerminalText } from "@rulvar/core";
 import { inspect } from "node:util";
 //#region src/cli.ts

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as looksLikeFile, a as resumeCommand, c as driveRun, d as attachProgress, f as renderEventLine, g as loadWorkflowModule, h as loadCliConfig, i as inspectCommand, l as reportOutcome, m as assembleEngine, n as HELP, o as runCommand, p as DEFAULT_STORE_DIR, r as runCli, s as runsLsCommand, t as processIo, u as strictExitCode } from "./io-BK1hP3Od.js";
+import { _ as looksLikeFile, a as resumeCommand, c as driveRun, d as attachProgress, f as renderEventLine, g as loadWorkflowModule, h as loadCliConfig, i as inspectCommand, l as reportOutcome, m as assembleEngine, n as HELP, o as runCommand, p as DEFAULT_STORE_DIR, r as runCli, s as runsLsCommand, t as processIo, u as strictExitCode } from "./io-DK9Ji_H2.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, readRunMeta, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
@@ -775,8 +775,13 @@ function createWorker(engine, options) {
 * tracer)` maps the spanId tree of a run 1:1 onto OTel spans: one span
 * per rulvar span, parented per the span hierarchy (run > phase >
 * agent > tool > child), with start/end timestamps from the lifecycle
-* events. Events without an own span (log, budget:update) attach as span
-* events on their enclosing span.
+* events; each agent:phase pair additionally becomes a child span of
+* its agent span keyed (spanId, invocation), carrying the phase's role,
+* model, usage, and cost. Events without an own span (log,
+* budget:update) attach as span events on their enclosing span. An
+* opener for an already-open span never duplicates it (replayed
+* re-emissions mark the original; a pre-RV-207 stream's extra per-phase
+* agent:start cannot leak the agent span unended).
 *
 * `@opentelemetry/api` ^1.9 is an OPTIONAL peer: the CLI has no OTel
 * dependency, and the exporter is typed against a minimal structural
@@ -799,11 +804,24 @@ function msOf(ts) {
 /** The OTel status codes (UNSET 0, OK 1, ERROR 2); inlined to avoid the peer. */
 const STATUS_OK = 1;
 const STATUS_ERROR = 2;
+/**
+* Usage, cost, and retry attributes on a closing span, defensively: the
+* exporter tolerates foreign or truncated streams, so absent fields
+* simply do not become attributes.
+*/
+function setUsageAttributes(open, event, retryKey, retries) {
+	if (open === void 0) return;
+	if (typeof event.usage?.inputTokens === "number") open.span.setAttribute("gen_ai.usage.input_tokens", event.usage.inputTokens);
+	if (typeof event.usage?.outputTokens === "number") open.span.setAttribute("gen_ai.usage.output_tokens", event.usage.outputTokens);
+	if (typeof event.costUsd === "number") open.span.setAttribute("rulvar.cost_usd", event.costUsd);
+	if (typeof retries === "number") open.span.setAttribute(retryKey, retries);
+}
 function spanName(event) {
 	switch (event.type) {
 		case "run:start": return `run ${event.workflow}`;
 		case "phase:start": return `phase ${event.phase}`;
 		case "agent:start": return `agent ${event.agentType || "(anon)"} ${event.role}`;
+		case "agent:phase:start": return `invocation ${event.role}`;
 		case "tool:start": return `tool ${event.toolName}`;
 		case "child:start": return `workflow ${event.workflow}`;
 		default: return event.type;
@@ -822,6 +840,12 @@ function openAttributes(event, runId) {
 		attrs["gen_ai.request.model"] = event.model;
 		attrs["gen_ai.operation.name"] = event.role;
 	}
+	if (event.type === "agent:phase:start") {
+		attrs["rulvar.agent_type"] = event.agentType;
+		attrs["gen_ai.request.model"] = event.model;
+		attrs["gen_ai.operation.name"] = event.role;
+		attrs["rulvar.invocation"] = event.invocation;
+	}
 	if (event.type === "tool:start") attrs["rulvar.tool_name"] = event.toolName;
 	for (const [key, value] of Object.entries(attrs)) if (typeof value === "string") attrs[key] = maskSecrets(value);
 	return attrs;
@@ -838,12 +862,13 @@ async function toOtel(run, tracer, options = {}) {
 	const stack = [];
 	let created = 0;
 	const { contextApi, setSpan } = options;
-	const startSpan = (event) => {
-		if (event.replayed === true && openBySpanId.has(event.spanId)) {
-			openBySpanId.get(event.spanId)?.span.setAttribute("rulvar.replayed", true);
+	const startSpan = (event, key = event.spanId, parentKey) => {
+		const parentId = parentKey ?? event.parentSpanId;
+		if (openBySpanId.has(key)) {
+			if (event.replayed === true) openBySpanId.get(key)?.span.setAttribute("rulvar.replayed", true);
 			return;
 		}
-		const parent = event.parentSpanId === void 0 ? void 0 : openBySpanId.get(event.parentSpanId);
+		const parent = parentId === void 0 ? void 0 : openBySpanId.get(parentId);
 		const parentContext = parent !== void 0 && contextApi !== void 0 && setSpan !== void 0 ? setSpan(contextApi.active(), parent.span) : void 0;
 		const span = tracer.startSpan(spanName(event), {
 			startTime: msOf(event.ts),
@@ -852,10 +877,10 @@ async function toOtel(run, tracer, options = {}) {
 		created += 1;
 		const open = {
 			span,
-			spanId: event.spanId,
-			...event.parentSpanId === void 0 ? {} : { parentSpanId: event.parentSpanId }
+			spanId: key,
+			...parentId === void 0 ? {} : { parentSpanId: parentId }
 		};
-		openBySpanId.set(event.spanId, open);
+		openBySpanId.set(key, open);
 		stack.push(open);
 	};
 	const endSpan = (spanId, ts, status, message) => {
@@ -880,7 +905,17 @@ async function toOtel(run, tracer, options = {}) {
 			case "run:end":
 				endSpan(event.spanId, event.ts, event.status);
 				break;
+			case "agent:phase:start":
+				startSpan(event, `${event.spanId}#${event.invocation}`, event.spanId);
+				break;
+			case "agent:phase:end": {
+				const key = `${event.spanId}#${event.invocation}`;
+				setUsageAttributes(openBySpanId.get(key), event, "rulvar.retries", event.retries);
+				endSpan(key, event.ts, event.outcome);
+				break;
+			}
 			case "agent:end":
+				setUsageAttributes(openBySpanId.get(event.spanId), event, "rulvar.retry_count", event.retryCount);
 				endSpan(event.spanId, event.ts, event.status);
 				break;
 			case "tool:end":
@@ -889,6 +924,15 @@ async function toOtel(run, tracer, options = {}) {
 			case "child:end":
 				endSpan(event.spanId, event.ts, event.status);
 				break;
+			case "determinism:warning":
+				(openBySpanId.get(event.spanId) ?? stack[stack.length - 1])?.span.addEvent("determinism:warning", {
+					"rulvar.entry_seq": event.seq,
+					"rulvar.determinism.category": event.category,
+					"rulvar.determinism.provenance": event.provenance,
+					...event.file === void 0 ? {} : { "code.filepath": maskSecrets(event.file) },
+					...event.line === void 0 ? {} : { "code.lineno": event.line }
+				});
+				break;
 			default: (openBySpanId.get(event.spanId) ?? stack[stack.length - 1])?.span.addEvent(event.type, { "rulvar.entry_seq": event.seq });
 		}
 	}

package/dist/{io-BK1hP3Od.js → io-DK9Ji_H2.js}

@@ -1,4 +1,4 @@
-import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, LeaseHeldError, auditRuns, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, parseModelRef, priceUsdOf, proposalStatement, readRunMeta, reconcileRunMeta, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
+import { ConfigError, FileModelKnowledgeStore, INBOX_PROPOSAL_TTL_DAYS, JsonlFileStore, LeaseHeldError, auditRuns, claimExpired, claimExpiry, compilePermissionPreset, costReportFromJournal, createEngine, hashRunArgs, hashRunOutput, lastRunSettle, parseModelRef, priceUsdOf, proposalStatement, readRunMeta, reconcileRunMeta, remeasureQueue, resolvePricing, runProfile, sanitizeTerminalText } from "@rulvar/core";
 import { join, resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
@@ -197,12 +197,18 @@ function rawEventLine(event) {
 		case "run:start": return `run ${str(event.runId)} ${event.resumed === true ? "resumed" : "started"} (workflow ${str(event.workflow)})`;
 		case "phase:start": return `phase ${str(event.phase)}`;
 		case "agent:start": return `${replayMark}agent ${who}${str(event.label) === "" ? "" : ` [${str(event.label)}]`} ${str(event.role)} on ${str(event.model)}`;
-		case "agent:end": return `${replayMark}agent ${who} ${str(event.status)} (${money(num(event.costUsd))}, ${String(num(event.usage?.inputTokens) + num(event.usage?.outputTokens))} tok)${event.usageApprox === true ? " approx" : ""}`;
+		case "agent:phase:start": return `${replayMark}agent ${who} ${str(event.role)} phase on ${str(event.model)}`;
+		case "agent:phase:end": return `${replayMark}agent ${who} ${str(event.role)} phase ${str(event.outcome)} (${money(num(event.costUsd))}, ${String(num(event.usage?.inputTokens) + num(event.usage?.outputTokens))} tok, ${String(num(event.durationMs))}ms${num(event.retries) > 0 ? `, ${String(num(event.retries))} retries` : ""})`;
+		case "agent:end": return `${replayMark}agent ${who} ${str(event.status)} (${money(num(event.costUsd))}, ${String(num(event.usage?.inputTokens) + num(event.usage?.outputTokens))} tok${num(event.retryCount) > 0 ? `, ${String(num(event.retryCount))} retries` : ""})${event.usageApprox === true ? " approx" : ""}`;
 		case "agent:error": return `agent ${who} error: ${str(event.error?.message)}${event.willRetry === true ? " (will retry)" : ""}`;
 		case "agent:queued": return `agent ${who} queued`;
 		case "tool:start": return `${replayMark}tool ${str(event.toolName)}`;
 		case "tool:end": return `${replayMark}tool ${str(event.toolName)} ${str(event.outcome)} (${String(num(event.durationMs))}ms)`;
 		case "approval:pending": return `approval pending: tool ${str(event.toolName)} (entry ${String(num(event.entryRef))})`;
+		case "determinism:warning": {
+			const where = str(event.file) === "" ? str(event.frame) : `at ${str(event.file)}:${String(num(event.line))}:${String(num(event.column))}`;
+			return `determinism ${str(event.category)} (${str(event.provenance)}) ${where}`;
+		}
 		case "log": return event.level === "debug" ? void 0 : `${str(event.level)}: ${str(event.msg)}`;
 		case "run:end": return `run ${str(event.runId)} ${str(event.status)}${event.usageApprox === true ? " (cost approx)" : ""}`;
 		default: return;
@@ -219,12 +225,15 @@ function attachProgress(handle, io) {
 		"run:start",
 		"phase:start",
 		"agent:start",
+		"agent:phase:start",
+		"agent:phase:end",
 		"agent:end",
 		"agent:error",
 		"agent:queued",
 		"tool:start",
 		"tool:end",
 		"approval:pending",
+		"determinism:warning",
 		"log",
 		"run:end"
 	]) detachers.push(handle.on(type, forward));
@@ -437,6 +446,16 @@ const GRAMMAR = {
 			{ name: "strict" }
 		]
 	},
+	replay: {
+		command: "replay",
+		positionals: ["<runId>"],
+		flags: [
+			ARGS,
+			STORE,
+			{ name: "assert-no-live" },
+			{ name: "compare-output-hash" }
+		]
+	},
 	"runs ls": {
 		command: "runs ls",
 		positionals: [],
@@ -560,6 +579,7 @@ function helpCommandLines() {
 	const top = [
 		GRAMMAR.run,
 		GRAMMAR.resume,
+		GRAMMAR.replay,
 		GRAMMAR["runs ls"],
 		GRAMMAR["runs audit"],
 		GRAMMAR.inspect,
@@ -863,6 +883,92 @@ async function resumeCommand(argv, context) {
 	return parsed.values.strict === true ? strictExitCode(outcome, base, context.io) : base;
 }
 /**
+* `rulvar replay` (RV-209): replay-strict verification of a recorded
+* run. Resumes under the engine's dry-run mode (zero journal or meta
+* writes, zero adapter calls; the first would-be-live call is a typed
+* JournalMissError settle), then reports the replay accounting, every
+* determinism warning the re-executed body raised (with its localized
+* frame), and the output digest comparison against the journaled
+* settle. `--assert-no-live` exits nonzero unless the replay was pure
+* (zero misses, zero reruns); `--compare-output-hash` exits nonzero
+* unless the replayed result's JCS sha256 equals the recorded
+* `outputHash`. Without flags the command reports and exits 0, so it
+* can sit in a pipeline as a diagnostic before it gates anything.
+* Args follow the resume binding exactly, but there is no
+* --allow-args-change here: changed args change the logical run, and a
+* verification against a different logical run proves nothing.
+*/
+async function replayCommand(argv, context) {
+	const parsed = parseCommand(GRAMMAR.replay, argv);
+	const runId = parsed.positionals[0];
+	const rawArgs = parsed.values.args;
+	const args = parseArgsJson(rawArgs);
+	const argsGiven = rawArgs !== void 0;
+	const assertNoLive = parsed.values["assert-no-live"] === true;
+	const compareOutputHash = parsed.values["compare-output-hash"] === true;
+	const store = parsed.values.store;
+	const assembled = assembleEngine({
+		config: await loadCliConfig(context.cwd),
+		...store === void 0 ? {} : { storePath: store },
+		cwd: context.cwd
+	});
+	const meta = await readRunMeta(assembled.store, runId);
+	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
+	enforceArgsBinding({
+		meta,
+		argsGiven,
+		args,
+		allowChange: false,
+		io: context.io
+	});
+	const name = meta.workflowName;
+	const workflow = name === void 0 ? void 0 : assembled.workflows[name];
+	if (workflow === void 0) throw new ConfigError(`run '${runId}' was started from workflow '${name ?? "(unknown)"}'; register it under that name in rulvar.config.mjs workflows to replay (replay requires the in-process workflow value)`);
+	const handle = assembled.engine.resume(runId, workflow, {
+		args,
+		dryRun: true
+	});
+	const warnings = [];
+	const consumer = (async () => {
+		for await (const event of handle.events) if (event.type === "determinism:warning") warnings.push(event);
+	})().catch(() => void 0);
+	const outcome = await handle.result;
+	const preview = await handle.preview;
+	await consumer;
+	const recorded = lastRunSettle(await assembled.store.load(runId));
+	const io = context.io;
+	io.err(`replay of '${sanitizeTerminalText(runId)}' (zero journal or meta writes, zero adapter calls):`);
+	io.err(`  hits: ${preview.hits}  misses: ${preview.misses}  reruns: ${preview.reruns}  skipped: ${preview.skipped}`);
+	io.err(recorded === void 0 ? "  recorded settle: none (journal predates the settle entry)" : `  recorded settle: ${recorded.runStatus}`);
+	io.err(`  replayed settle: ${outcome.status}`);
+	if (outcome.error !== void 0 && outcome.error.code !== "journal_miss") io.err(`  error: ${sanitizeTerminalText(outcome.error.message)}`);
+	for (const warning of warnings) {
+		const where = warning.file === void 0 ? warning.frame : `at ${warning.file}:${warning.line ?? "?"}:${warning.column ?? "?"}`;
+		io.err(`  determinism: ${warning.category} (${warning.provenance}) ${sanitizeTerminalText(where)}`);
+	}
+	let exit = 0;
+	if (assertNoLive) if (preview.misses === 0 && preview.reruns === 0 && outcome.error?.code !== "journal_miss") io.err("  assert-no-live: PASS (pure replay, zero would-be-live calls)");
+	else {
+		io.err(`  assert-no-live: FAIL (misses ${preview.misses}, reruns ${preview.reruns}: a real resume would perform new paid work)`);
+		exit = 1;
+	}
+	if (compareOutputHash) {
+		const replayedHash = hashRunOutput(outcome.value);
+		if (recorded?.outputHash === void 0) {
+			io.err("  compare-output-hash: FAIL (the recorded settle carries no output hash: the run predates it, settled without a value, or the value is not JCS-serializable)");
+			exit = 1;
+		} else if (replayedHash === void 0) {
+			io.err("  compare-output-hash: FAIL (the replayed run produced no hashable value)");
+			exit = 1;
+		} else if (replayedHash === recorded.outputHash) io.err(`  compare-output-hash: PASS (${replayedHash.slice(0, 12)})`);
+		else {
+			io.err(`  compare-output-hash: FAIL (recorded ${recorded.outputHash.slice(0, 12)}, replayed ${replayedHash.slice(0, 12)}: the workflow does not reproduce its output)`);
+			exit = 1;
+		}
+	}
+	return exit;
+}
+/**
 * The stranded run probe and reconciler (fenced run state RFC, phase
 * 3): audits every run the catalog lists against its journal, prints
 * the divergences worker sweeps can never see, and with --repair
@@ -1430,6 +1536,12 @@ runs audit compares every run's meta row against its journal and names
 the divergences worker sweeps cannot see (a stranded run's terminal
 meta over live journal work); --repair rewrites the sound ones from
 the journal under a brief lease, exit 1 while any divergence remains.
+replay verifies a recorded run without paying: a dry-run resume (zero
+journal or meta writes, zero adapter calls) that reports replay
+accounting, localized determinism warnings, and the output digest;
+--assert-no-live exits 1 unless the replay is pure, and
+--compare-output-hash exits 1 unless the replayed result's digest
+equals the journaled one.
 plan asks the planner model (role plan) to write a workflow script,
 lints and self-repairs it, then runs it in the worker sandbox; --dry-run
 prints the accepted script without running. Both stages are paid runs
@@ -1458,6 +1570,7 @@ async function runCli(argv, options) {
 		switch (command) {
 			case "run": return await runCommand(rest, context);
 			case "resume": return await resumeCommand(rest, context);
+			case "replay": return await replayCommand(rest, context);
 			case "runs": {
 				const [sub, ...subRest] = rest;
 				if (sub === "ls") return await runsLsCommand(subRest, context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Rulvar shell: run/resume/runs/inspect/plan/kb commands, TUI progress, createServer, createWorker, OTel exporter.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,17 +22,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.48.0"
+    "@rulvar/core": "1.50.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.48.0",
-    "@rulvar/store-sqlite": "1.48.0",
-    "@rulvar/planner": "1.48.0",
-    "@rulvar/evals": "1.48.0",
-    "@rulvar/plan": "1.48.0"
+    "@rulvar/testing": "1.50.0",
+    "@rulvar/store-sqlite": "1.50.0",
+    "@rulvar/planner": "1.50.0",
+    "@rulvar/plan": "1.50.0",
+    "@rulvar/evals": "1.50.0"
   },
   "bin": {
     "rulvar": "./dist/cli.js"