@rulvar/cli 1.0.0

package/dist/index.js

@@ -0,0 +1,760 @@
+import { a as resumeCommand, c as driveRun, d as renderEventLine, f as DEFAULT_STORE_DIR, g as looksLikeFile, h as loadWorkflowModule, i as inspectCommand, l as reportOutcome, m as loadCliConfig, n as HELP, o as runCommand, p as assembleEngine, r as runCli, s as runsLsCommand, t as processIo, u as attachProgress } from "./io-DUfUn6KG.js";
+import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
+//#region src/server.ts
+/**
+* createServer (M8-T01): the HTTP shell over the public engine API
+* (docs/02, section 8.2; FR-702). Canonical signature
+* `createServer({ engine, workflows })` returning
+* `{ fetch(req: Request): Promise<Response> }`; the journal store comes
+* from the engine (Engine.stores, docs/06 10.2, M8 entry amendment).
+*
+* Routes:
+*   POST /runs                     start a run of a registered workflow
+*   GET  /runs/:id                 run status and outcome
+*   GET  /runs/:id/events          SSE event stream (Last-Event-ID resume)
+*   POST /runs/:id/external/:key   resolve an awaitExternal suspension
+*   GET  /runs/:id/cost            CostReport
+*
+* Authentication is explicitly out of scope: the server is host-embedded
+* and auth belongs to host middleware (docs/14, OQ-16). SSE reconnection
+* maps Last-Event-ID to the event seq (the per-run telemetry counter,
+* docs/09, section 1.1); replay is at-least-once by design, matching the
+* journal-backed re-emission contract (docs/09, section 1.5: consumers
+* deduplicate on `replayed`).
+*
+* The server is a single-process shell: it tracks the runs it started
+* (or resumed) in memory and serves everything else from the engine's
+* stores. A resolution posted for a run that is NOT live in this process
+* is the documented offline append (docs/03, section 8: load, compute
+* next seq, append, under a lease where the store is leasable); such a
+* run resumes on a queue worker (createWorker, M8-T02), not here,
+* because original run arguments are not journaled in v1 (docs/14,
+* OQ-21).
+*/
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+const wallClock = Date.now.bind(globalThis);
+function json(status, body) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: JSON_HEADERS
+	});
+}
+function errorStatus(error) {
+	switch (error.code) {
+		case "config":
+		case "invalid_resolution":
+		case "non_serializable_value": return 400;
+		case "lease_held":
+		case "journal_compat": return 409;
+		default: return 500;
+	}
+}
+function errorResponse(thrown) {
+	if (thrown instanceof RulvarError) return json(errorStatus(thrown), { error: thrown.toWire() });
+	return json(500, { error: {
+		code: "error",
+		message: thrown instanceof Error ? thrown.message : String(thrown),
+		retryable: false
+	} });
+}
+function sseFrame(event) {
+	return `id: ${event.seq}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+function isLeasable(store) {
+	const candidate = store;
+	return typeof candidate.acquire === "function" && typeof candidate.renew === "function" && typeof candidate.release === "function";
+}
+/** The approval-suspension resolution key (docs/08, section 3.6). */
+const APPROVAL_KEY_PREFIX = "approval:";
+function suspensionKeyOf(entry) {
+	if (entry.status !== "suspended") return;
+	if (entry.kind === "external") {
+		const key = entry.value?.key;
+		return typeof key === "string" ? key : void 0;
+	}
+	if (entry.kind === "approval") return `${APPROVAL_KEY_PREFIX}${entry.seq}`;
+}
+function createServer(options) {
+	const { engine, workflows } = options;
+	const journal = engine.stores.journal;
+	const runs = /* @__PURE__ */ new Map();
+	/** Pumps one resume segment's events into the buffer and the feeds. */
+	function attach(run, handle) {
+		run.handle = handle;
+		run.outcome = void 0;
+		(async () => {
+			for await (const event of handle.events) {
+				run.buffer.push(event);
+				for (const feed of [...run.feeds]) feed(event);
+			}
+		})().catch(() => void 0);
+		handle.result.then((outcome) => {
+			run.outcome = outcome;
+			if (outcome.status !== "suspended") {
+				run.done = true;
+				for (const feed of [...run.feeds]) feed(null);
+				run.feeds.clear();
+				if (options.retention !== void 0) (async () => {
+					const meta = await metaOf(run.runId);
+					if (meta !== void 0 && options.retention?.(meta) === true) {
+						await engine.deleteRun(run.runId);
+						runs.delete(run.runId);
+					}
+				})().catch(() => void 0);
+			}
+		}).catch(() => void 0);
+	}
+	function track(runId, workflowName, args, handle) {
+		const run = {
+			runId,
+			workflowName,
+			args,
+			buffer: [],
+			feeds: /* @__PURE__ */ new Set(),
+			handle,
+			done: false,
+			queue: Promise.resolve()
+		};
+		runs.set(runId, run);
+		attach(run, handle);
+		return run;
+	}
+	async function metaOf(runId) {
+		return (await journal.listRuns()).find((meta) => meta.runId === runId);
+	}
+	async function startRun(req) {
+		let body;
+		try {
+			body = await req.json();
+		} catch {
+			return json(400, { error: {
+				code: "config",
+				message: "request body is not valid JSON"
+			} });
+		}
+		const name = body.workflow;
+		if (typeof name !== "string" || name.length === 0) return json(400, { error: {
+			code: "config",
+			message: "body requires { workflow: '<registered name>' }"
+		} });
+		const workflow = workflows[name];
+		if (workflow === void 0) return json(400, { error: {
+			code: "config",
+			message: `no workflow named '${name}' in the registry (docs/06, section 10.4)`
+		} });
+		const runOptions = {
+			...body.options?.runId === void 0 ? {} : { runId: body.options.runId },
+			...body.options?.budgetUsd === void 0 ? {} : { budgetUsd: body.options.budgetUsd },
+			...body.options?.name === void 0 ? {} : { name: body.options.name },
+			...body.options?.tags === void 0 ? {} : { tags: body.options.tags },
+			...body.options?.deadlineAt === void 0 ? {} : { deadlineAt: body.options.deadlineAt }
+		};
+		const handle = engine.run(workflow, body.args, runOptions);
+		track(handle.runId, name, body.args, handle);
+		return new Response(JSON.stringify({
+			runId: handle.runId,
+			status: "running",
+			workflow: name
+		}), {
+			status: 201,
+			headers: {
+				...JSON_HEADERS,
+				location: `/runs/${handle.runId}`
+			}
+		});
+	}
+	async function runStatus(runId) {
+		const run = runs.get(runId);
+		if (run !== void 0) {
+			const outcome = run.outcome;
+			if (outcome === void 0) return json(200, {
+				runId,
+				status: "running",
+				workflow: run.workflowName,
+				live: true
+			});
+			return json(200, {
+				runId,
+				status: outcome.status,
+				workflow: run.workflowName,
+				live: true,
+				...outcome.value === void 0 ? {} : { value: outcome.value },
+				...outcome.error === void 0 ? {} : { error: outcome.error },
+				pending: outcome.pending,
+				dropped: outcome.dropped.length,
+				usage: outcome.usage
+			});
+		}
+		const meta = await metaOf(runId);
+		if (meta === void 0) return json(404, { error: {
+			code: "config",
+			message: `run '${runId}' not found`
+		} });
+		return json(200, {
+			runId,
+			status: meta.status,
+			live: false,
+			...meta.workflowName === void 0 ? {} : { workflow: meta.workflowName },
+			...meta.name === void 0 ? {} : { name: meta.name },
+			...meta.tags === void 0 ? {} : { tags: meta.tags },
+			updatedAt: meta.updatedAt
+		});
+	}
+	async function runEvents(runId, req) {
+		const run = runs.get(runId);
+		if (run === void 0) {
+			if (await metaOf(runId) === void 0) return json(404, { error: {
+				code: "config",
+				message: `run '${runId}' not found`
+			} });
+			const empty = new ReadableStream({ start(controller) {
+				controller.enqueue(new TextEncoder().encode(": run is not live in this process\n\n"));
+				controller.close();
+			} });
+			return new Response(empty, {
+				status: 200,
+				headers: {
+					"content-type": "text/event-stream",
+					"cache-control": "no-cache"
+				}
+			});
+		}
+		const lastEventId = req.headers.get("last-event-id");
+		const encoder = new TextEncoder();
+		let feed;
+		const stream = new ReadableStream({
+			start(controller) {
+				let startIndex = 0;
+				if (lastEventId !== null) {
+					const cursor = Number(lastEventId);
+					if (Number.isFinite(cursor)) {
+						for (let i = run.buffer.length - 1; i >= 0; i -= 1) if (run.buffer[i].seq === cursor) {
+							startIndex = i + 1;
+							break;
+						}
+					}
+				}
+				for (const event of run.buffer.slice(startIndex)) controller.enqueue(encoder.encode(sseFrame(event)));
+				if (run.done) {
+					controller.close();
+					return;
+				}
+				feed = (event) => {
+					if (event === null) {
+						try {
+							controller.close();
+						} catch {}
+						return;
+					}
+					try {
+						controller.enqueue(encoder.encode(sseFrame(event)));
+					} catch {}
+				};
+				run.feeds.add(feed);
+			},
+			cancel() {
+				if (feed !== void 0) run.feeds.delete(feed);
+			}
+		});
+		return new Response(stream, {
+			status: 200,
+			headers: {
+				"content-type": "text/event-stream",
+				"cache-control": "no-cache"
+			}
+		});
+	}
+	/** The tracked path: live (or settled-suspended) in this process. */
+	async function resolveTracked(run, key, value) {
+		const section = run.queue.then(async () => {
+			if (run.done) return json(409, { error: {
+				code: "config",
+				message: `run '${run.runId}' already settled '${run.outcome?.status ?? "unknown"}'`
+			} });
+			const settledSuspended = run.outcome?.status === "suspended";
+			if (settledSuspended) {
+				const pendingKeys = run.outcome.pending.map((item) => item.key);
+				if (!pendingKeys.includes(key)) return json(404, { error: {
+					code: "invalid_resolution",
+					message: `no open suspension '${key}' (pending: ${pendingKeys.join(", ") || "none"})`
+				} });
+			}
+			const outcome = await run.handle.resolveExternal(key, value);
+			let resumed = false;
+			if (outcome.applied && settledSuspended) {
+				const workflow = workflows[run.workflowName];
+				if (workflow === void 0) return json(409, { error: {
+					code: "config",
+					message: `resolution applied, but workflow '${run.workflowName}' is no longer registered; resume it from a worker or a process with the registration`
+				} });
+				attach(run, engine.resume(run.runId, workflow, { args: run.args }));
+				resumed = true;
+			}
+			return json(200, {
+				...outcome,
+				resumed
+			});
+		});
+		run.queue = section.catch(() => void 0);
+		return section;
+	}
+	/**
+	* The offline path (docs/03, section 8): the run is not live in this
+	* process; append the resolution under a lease where the store is
+	* leasable and leave the resume to a queue worker.
+	*/
+	async function resolveOffline(runId, key, value) {
+		if (await metaOf(runId) === void 0) return json(404, { error: {
+			code: "config",
+			message: `run '${runId}' not found`
+		} });
+		let lease;
+		if (isLeasable(journal)) lease = await journal.acquire(runId, `rulvar-server:${process.pid}`);
+		try {
+			const entries = (await journal.load(runId)).map((raw) => normalizeEntry(raw));
+			const replayer = new Replayer({
+				runId,
+				store: journal,
+				now: wallClock,
+				priorEntries: entries
+			});
+			const target = entries.find((entry) => suspensionKeyOf(entry) === key);
+			if (target === void 0) return json(404, { error: {
+				code: "invalid_resolution",
+				message: `no suspension with key '${key}'`
+			} });
+			const state = replayer.suspensionState(target.seq);
+			if (state.state !== "suspended") return json(200, {
+				applied: false,
+				seq: target.seq,
+				supersededBy: state.by,
+				reason: state.state === "resolved" ? "already_resolved" : "target_abandoned",
+				resumed: false
+			});
+			if (target.kind === "approval") {
+				const decision = value?.decision;
+				if (decision !== "allow" && decision !== "deny") throw new InvalidResolutionError(`approval '${key}' resolves with { decision: 'allow' | 'deny', reason? }`);
+			}
+			const pinnedSchema = target.value?.schema;
+			if (pinnedSchema !== void 0) {
+				const validation = await validateSchemaSpec(pinnedSchema, value);
+				if (!validation.valid) throw new InvalidResolutionError(`resolution for '${key}' does not validate against the pinned schema: ` + validation.issues.map((issue) => issue.message).join("; "));
+			}
+			return json(200, {
+				...await replayer.resolveSuspended(target.seq, {
+					by: "external",
+					value
+				}),
+				resumed: false
+			});
+		} finally {
+			if (lease !== void 0 && isLeasable(journal)) await journal.release(lease).catch(() => void 0);
+		}
+	}
+	async function resolveRun(runId, key, req) {
+		let value;
+		try {
+			value = await req.json();
+		} catch {
+			return json(400, { error: {
+				code: "config",
+				message: "request body is not valid JSON"
+			} });
+		}
+		const run = runs.get(runId);
+		if (run !== void 0) return resolveTracked(run, key, value);
+		return resolveOffline(runId, key, value);
+	}
+	async function runCost(runId) {
+		const run = runs.get(runId);
+		if (run?.outcome !== void 0) return json(200, run.outcome.cost);
+		const meta = run === void 0 ? await metaOf(runId) : void 0;
+		if (run === void 0 && meta === void 0) return json(404, { error: {
+			code: "config",
+			message: `run '${runId}' not found`
+		} });
+		return json(200, costReportFromJournal((await journal.load(runId)).map((raw) => normalizeEntry(raw)), options.priceUsd ?? (() => void 0)));
+	}
+	async function route(req) {
+		const path = new URL(req.url).pathname;
+		if (path === "/runs") {
+			if (req.method !== "POST") return json(405, { error: {
+				code: "config",
+				message: "POST /runs"
+			} });
+			return startRun(req);
+		}
+		const events = /^\/runs\/([^/]+)\/events$/.exec(path);
+		if (events !== null) {
+			if (req.method !== "GET") return json(405, { error: {
+				code: "config",
+				message: "GET /runs/:id/events"
+			} });
+			return runEvents(decodeURIComponent(events[1]), req);
+		}
+		const external = /^\/runs\/([^/]+)\/external\/(.+)$/.exec(path);
+		if (external !== null) {
+			if (req.method !== "POST") return json(405, { error: {
+				code: "config",
+				message: "POST /runs/:id/external/:key"
+			} });
+			return resolveRun(decodeURIComponent(external[1]), decodeURIComponent(external[2]), req);
+		}
+		const cost = /^\/runs\/([^/]+)\/cost$/.exec(path);
+		if (cost !== null) {
+			if (req.method !== "GET") return json(405, { error: {
+				code: "config",
+				message: "GET /runs/:id/cost"
+			} });
+			return runCost(decodeURIComponent(cost[1]));
+		}
+		const status = /^\/runs\/([^/]+)$/.exec(path);
+		if (status !== null) {
+			if (req.method !== "GET") return json(405, { error: {
+				code: "config",
+				message: "GET /runs/:id"
+			} });
+			return runStatus(decodeURIComponent(status[1]));
+		}
+		return json(404, { error: {
+			code: "config",
+			message: `no route ${req.method} ${path}`
+		} });
+	}
+	return { fetch: async (req) => {
+		try {
+			return await route(req);
+		} catch (thrown) {
+			return errorResponse(thrown);
+		}
+	} };
+}
+//#endregion
+//#region src/worker.ts
+/**
+* createWorker (M8-T02): the queue shell over the public engine API
+* (docs/02, section 8.3; FR-703). Canonical signature
+* `createWorker(engine, { store: LeasableStore, concurrency? })`.
+*
+* The worker leases resumable ('running' meta: a crashed or currently
+* owned run) and suspended runs via acquire/renew/release with the
+* fencing epoch; acquire on a held lease rejects with LeaseHeldError and
+* the worker simply moves on. Stateless workers call engine.resume,
+* passing the lease via ResumeOptions.lease so EVERY engine append of
+* the resumed run is fenced (docs/03, section 12.3, M8 entry amendment):
+* lease theft is impossible because a stale writer's appends are
+* rejected by the store and never become visible, whether or not the
+* stale worker noticed it lost the lease.
+*
+* DEF-6 at acquire: the journal's hashVersion window is re-checked
+* immediately after every acquire, strictly before any append; a
+* JournalCompatibilityError releases the lease and poisons the run for
+* this worker (an older library never writes into a newer journal).
+*
+* Queue semantics are honestly at-least-once with deduplication by the
+* journal (docs/03, section 13.1): re-leasing a settled or unchanged
+* run replays to the same outcome with zero live calls. Workflows
+* resolve through the engine's defaults.workflows registry plus the
+* persisted CompiledWorkflow sources, never through a worker parameter
+* (docs/06, section 10.4); original in-process run arguments are not
+* journaled in v1, so the host MAY re-supply them per run via `argsFor`
+* (docs/14, OQ-21).
+*
+* Appendix A (committed at M8 entry): concurrency defaults to 1 (one
+* leased run per worker process; hosts scale out by adding workers,
+* which the fencing epoch makes safe by construction); the renew
+* cadence is ttl/3 with the reference ttl of 60000 ms. There is no
+* distributed cross-process rate limiter in v1 (EXC-14; docs/14,
+* OQ-17): divide provider quota per worker or front an external
+* gateway.
+*/
+/** Appendix A: the committed reference lease ttl (docs/06). */
+const DEFAULT_WORKER_TTL_MS = 6e4;
+const CANDIDATE_STATUSES = /* @__PURE__ */ new Set(["running", "suspended"]);
+let workerOrdinal = 0;
+function workerIdentity() {
+	workerOrdinal += 1;
+	return `rulvar-worker:${process.pid}:${workerOrdinal}`;
+}
+function createWorker(engine, options) {
+	const store = options.store;
+	if (!(typeof store.acquire === "function" && typeof store.renew === "function" && typeof store.release === "function")) throw new ConfigError("createWorker requires a LeasableStore (acquire/renew/release with fencing epochs); the supplied store has no lease capability (docs/03, section 12.3). Use @rulvar/store-sqlite or another conformant LeasableStore.");
+	if (engine.stores.journal !== store) throw new ConfigError("createWorker must lease the SAME journal store the engine writes (engine.stores.journal); leasing a different store would fence nothing (docs/02, section 8.3; docs/06, 10.2)");
+	const concurrency = options.concurrency ?? 1;
+	if (!Number.isInteger(concurrency) || concurrency < 1) throw new ConfigError(`createWorker concurrency must be a positive integer, got ${concurrency}`);
+	const owner = options.owner ?? workerIdentity();
+	const ttlMs = options.ttlMs ?? 6e4;
+	const renewMs = Math.max(1, Math.floor(ttlMs / 3));
+	const pollMs = options.pollMs ?? 1e3;
+	const registry = buildDeriverRegistry(options.extraDerivers);
+	const active = /* @__PURE__ */ new Map();
+	/** Runs this worker must not retry (DEF-6 violations, binding errors). */
+	const poisoned = /* @__PURE__ */ new Set();
+	/**
+	* Journal length at our last release of a still-suspended run: nothing
+	* new to consume until it grows (an offline resolution appends).
+	*/
+	const suspendedAt = /* @__PURE__ */ new Map();
+	let pollTimer;
+	let stopping = false;
+	function reportError(runId, error) {
+		try {
+			options.onError?.(runId, error);
+		} catch {}
+	}
+	async function releaseQuietly(lease) {
+		try {
+			await store.release(lease);
+		} catch {}
+	}
+	/** Drives one leased run to its next settle. */
+	async function drive(runId, meta, lease) {
+		const handle = engine.resume(runId, void 0, {
+			lease,
+			...options.argsFor === void 0 ? {} : { args: options.argsFor(meta) }
+		});
+		const renewTimer = setInterval(() => {
+			store.renew(lease).catch((thrown) => {
+				reportError(runId, thrown);
+				handle.cancel("lease lost: fencing epoch superseded");
+				clearInterval(renewTimer);
+				active.delete(runId);
+			});
+		}, renewMs);
+		const settled = handle.result.then(async (outcome) => {
+			if (outcome.status === "suspended") {
+				const entries = await store.load(runId);
+				suspendedAt.set(runId, entries.length);
+			} else suspendedAt.delete(runId);
+		}).catch((thrown) => {
+			if (thrown instanceof ConfigError || thrown instanceof JournalCompatibilityError) poisoned.add(runId);
+			reportError(runId, thrown);
+		}).finally(async () => {
+			clearInterval(renewTimer);
+			await releaseQuietly(lease);
+			active.delete(runId);
+		});
+		active.set(runId, {
+			lease,
+			renewTimer,
+			cancel: async (reason) => {
+				await handle.cancel(reason);
+			},
+			settled: settled.then(() => void 0)
+		});
+		await settled;
+	}
+	/** Opt-in retention over settled runs (docs/02, 8.3; M8-T04). */
+	async function applyRetention(meta) {
+		if (options.retention?.(meta) !== true) return;
+		let lease;
+		try {
+			lease = await store.acquire(meta.runId, owner);
+		} catch (thrown) {
+			if (thrown instanceof LeaseHeldError) return;
+			throw thrown;
+		}
+		try {
+			await engine.deleteRun(meta.runId);
+			suspendedAt.delete(meta.runId);
+			poisoned.delete(meta.runId);
+		} finally {
+			await releaseQuietly(lease);
+		}
+	}
+	async function sweep() {
+		if (stopping) return 0;
+		let picked = 0;
+		const metas = await store.listRuns();
+		for (const meta of metas) {
+			if (active.size >= concurrency) break;
+			if (!CANDIDATE_STATUSES.has(meta.status)) {
+				if (options.retention !== void 0 && !active.has(meta.runId)) await applyRetention(meta).catch((thrown) => {
+					reportError(meta.runId, thrown);
+				});
+				continue;
+			}
+			if (active.has(meta.runId) || poisoned.has(meta.runId)) continue;
+			let lease;
+			try {
+				lease = await store.acquire(meta.runId, owner);
+			} catch (thrown) {
+				if (thrown instanceof LeaseHeldError) continue;
+				throw thrown;
+			}
+			try {
+				const entries = (await store.load(meta.runId)).map((raw) => normalizeEntry(raw));
+				scanJournalCompatibility(meta.runId, entries, registry);
+				if (meta.status === "suspended" && suspendedAt.get(meta.runId) === entries.length) {
+					await releaseQuietly(lease);
+					continue;
+				}
+				picked += 1;
+				drive(meta.runId, meta, lease);
+			} catch (thrown) {
+				await releaseQuietly(lease);
+				if (thrown instanceof JournalCompatibilityError || thrown instanceof ConfigError) {
+					poisoned.add(meta.runId);
+					reportError(meta.runId, thrown);
+					continue;
+				}
+				reportError(meta.runId, thrown);
+			}
+		}
+		return picked;
+	}
+	return {
+		start: () => {
+			if (pollTimer !== void 0 || stopping) return;
+			pollTimer = setInterval(() => {
+				sweep().catch(() => void 0);
+			}, pollMs);
+			sweep().catch(() => void 0);
+		},
+		sweep,
+		stop: async () => {
+			stopping = true;
+			if (pollTimer !== void 0) {
+				clearInterval(pollTimer);
+				pollTimer = void 0;
+			}
+			const held = [...active.values()];
+			await Promise.all(held.map(async (run) => {
+				await run.cancel("worker stopping");
+				await run.settled;
+			}));
+		},
+		active: () => [...active.keys()]
+	};
+}
+//#endregion
+//#region src/otel.ts
+/**
+* OpenTelemetry exporter (M5-T08; docs/09, section 3). `toOtel(run,
+* tracer)` maps the spanId tree of a run 1:1 onto OTel spans: one span
+* per rulvar span, parented per the docs/09 1.2 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.
+*
+* `@opentelemetry/api` ^1.9 is an OPTIONAL peer: the CLI has no OTel
+* dependency, and the exporter is typed against a minimal structural
+* `TracerLike` so an absent peer never breaks the CLI. Attribute content
+* policy: prompts, completions, and tool payloads are NEVER exported;
+* only identifiers, statuses, usage counters, and cost figures ride
+* `rulvar.*` and `gen_ai.*` attributes. Replayed events do not create
+* duplicate spans; the single span is marked `rulvar.replayed = true`.
+*/
+const SPAN_OPENERS = /* @__PURE__ */ new Set([
+	"run:start",
+	"phase:start",
+	"agent:start",
+	"tool:start",
+	"child:start"
+]);
+function msOf(ts) {
+	return Date.parse(ts);
+}
+/** The OTel status codes (UNSET 0, OK 1, ERROR 2); inlined to avoid the peer. */
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+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 "tool:start": return `tool ${event.toolName}`;
+		case "child:start": return `workflow ${event.workflow}`;
+		default: return event.type;
+	}
+}
+function openAttributes(event, runId) {
+	const attrs = {
+		"rulvar.run_id": runId,
+		"rulvar.entry_seq": event.seq
+	};
+	const scope = event.scope;
+	if (typeof scope === "string") attrs["rulvar.scope"] = scope;
+	if (event.replayed === true) attrs["rulvar.replayed"] = true;
+	if (event.type === "agent:start") {
+		attrs["rulvar.agent_type"] = event.agentType;
+		attrs["gen_ai.request.model"] = event.model;
+		attrs["gen_ai.operation.name"] = event.role;
+	}
+	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;
+}
+/**
+* Exports one settled run's event stream onto a tracer. The run's
+* events are consumed in seq order; span openers start spans, the
+* matching closers end them, and payload-only events attach as span
+* events on the innermost open span. Returns the number of spans
+* created.
+*/
+async function toOtel(run, tracer, options = {}) {
+	const openBySpanId = /* @__PURE__ */ new Map();
+	const stack = [];
+	let created = 0;
+	const startSpan = (event) => {
+		if (event.replayed === true && openBySpanId.has(event.spanId)) {
+			openBySpanId.get(event.spanId)?.span.setAttribute("rulvar.replayed", true);
+			return;
+		}
+		const span = tracer.startSpan(spanName(event), {
+			startTime: msOf(event.ts),
+			attributes: openAttributes(event, run.runId)
+		});
+		created += 1;
+		const open = {
+			span,
+			spanId: event.spanId,
+			...event.parentSpanId === void 0 ? {} : { parentSpanId: event.parentSpanId }
+		};
+		openBySpanId.set(event.spanId, open);
+		stack.push(open);
+	};
+	const endSpan = (spanId, ts, status, message) => {
+		const open = openBySpanId.get(spanId);
+		if (open === void 0) return;
+		if (status !== void 0) open.span.setAttribute("rulvar.status", status);
+		open.span.setStatus(status !== void 0 && status !== "ok" && status !== "skipped" ? {
+			code: STATUS_ERROR,
+			...message === void 0 ? {} : { message }
+		} : { code: STATUS_OK });
+		open.span.end(msOf(ts));
+		openBySpanId.delete(spanId);
+		const idx = stack.lastIndexOf(open);
+		if (idx !== -1) stack.splice(idx, 1);
+	};
+	for await (const event of run.events) {
+		if (SPAN_OPENERS.has(event.type)) {
+			startSpan(event);
+			continue;
+		}
+		switch (event.type) {
+			case "run:end":
+				endSpan(event.spanId, event.ts, event.status);
+				break;
+			case "agent:end":
+				endSpan(event.spanId, event.ts, event.status);
+				break;
+			case "tool:end":
+				endSpan(event.spanId, event.ts, event.outcome);
+				break;
+			case "child:end":
+				endSpan(event.spanId, event.ts, event.status);
+				break;
+			default: (openBySpanId.get(event.spanId) ?? stack[stack.length - 1])?.span.addEvent(event.type, { "rulvar.entry_seq": event.seq });
+		}
+	}
+	const outcome = await run.result;
+	for (const open of [...openBySpanId.values()]) {
+		open.span.setStatus({ code: outcome.status === "ok" ? STATUS_OK : STATUS_ERROR });
+		open.span.end();
+		openBySpanId.delete(open.spanId);
+	}
+	return created;
+}
+//#endregion
+export { DEFAULT_STORE_DIR, DEFAULT_WORKER_TTL_MS, HELP, assembleEngine, attachProgress, createServer, createWorker, driveRun, inspectCommand, loadCliConfig, loadWorkflowModule, looksLikeFile, processIo, renderEventLine, reportOutcome, resumeCommand, runCli, runCommand, runsLsCommand, toOtel };