@rulvar/cli 1.3.0 → 1.3.2

package/README.md

@@ -0,0 +1,29 @@
+# @rulvar/cli
+
+The rulvar ops shell: the `rulvar` binary (`run`, `resume`, `runs`,
+`inspect`, `plan`, `kb`), TUI progress, the embeddable HTTP server with
+SSE events and external-input resolution (`createServer`), the queue
+worker over any leasable store (`createWorker`), and the OpenTelemetry
+exporter (`toOtel`).
+
+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:
+[docs.rulvar.com](https://docs.rulvar.com).
+
+## Install
+
+```bash
+pnpm add @rulvar/cli
+pnpm exec rulvar --help
+```
+
+## Documentation
+
+- [CLI](https://docs.rulvar.com/guide/cli)
+- [Observability](https://docs.rulvar.com/guide/observability)
+- [API reference](https://docs.rulvar.com/api/%40rulvar/cli/)
+
+## License
+
+[Apache-2.0](https://github.com/o-stepper/rulvar/blob/main/LICENSE)

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runCli, t as processIo } from "./io-DSpNsEKg.js";
+import { r as runCli, t as processIo } from "./io-nATg3Bhx.js";
 //#region src/cli.ts
 /**
 * The `rulvar` bin entry: thin wrapper over runCli with process io.

package/dist/{dist-Clz0iBp5.js → dist-DIqBj4U-.js}

@@ -60,7 +60,7 @@ function isTerminalPlanStatus(status) {
 * (never a silent brick).
 */
 function assertPlanTransition(node, to) {
-	if (isTerminalPlanStatus(node.status)) throw new PlanInvariantError(`plan node ${node.nodeId} is terminal '${node.status}' and cannot become '${to}' (docs/07, 3.1: the status machine is closed and 'done' is immutable)`, { data: {
+	if (isTerminalPlanStatus(node.status)) throw new PlanInvariantError(`plan node ${node.nodeId} is terminal '${node.status}' and cannot become '${to}' (the status machine is closed and 'done' is immutable)`, { data: {
 		nodeId: node.nodeId,
 		from: node.status,
 		to
@@ -70,7 +70,7 @@ function assertPlanTransition(node, to) {
 		from: node.status,
 		to
 	} });
-	if (to === "running" && node.status !== "ready") throw new PlanInvariantError(`plan node ${node.nodeId} cannot start running from '${node.status}' (the engine schedules ready nodes only; docs/07, 3.1)`, { data: {
+	if (to === "running" && node.status !== "ready") throw new PlanInvariantError(`plan node ${node.nodeId} cannot start running from '${node.status}' (the engine schedules ready nodes only)`, { data: {
 		nodeId: node.nodeId,
 		from: node.status,
 		to
@@ -327,7 +327,7 @@ function effectiveDroppedStreak(state) {
 }
 function verifyHash(entry, which, expected, plan, deriverFor) {
 	const actual = planHash(plan, deriverFor?.(entry.hashVersion) ?? deriverV2);
-	if (actual !== expected) throw new ReplayPlanHashMismatch(`plan fold ${which} mismatch at seq ${String(entry.seq)}: recomputed ${actual}, entry carries ${expected} (hashVersion ${String(entry.hashVersion)}); the resume is rejected without corrupting the journal (docs/07, 3.4)`, { data: {
+	if (actual !== expected) throw new ReplayPlanHashMismatch(`plan fold ${which} mismatch at seq ${String(entry.seq)}: recomputed ${actual}, entry carries ${expected} (hashVersion ${String(entry.hashVersion)}); the resume is rejected without corrupting the journal`, { data: {
 		entryRef: entry.seq,
 		expected,
 		actual,
@@ -1251,11 +1251,11 @@ function boundLedgerRender(view, budgetChars = LEDGER_RENDER_BUDGET_CHARS) {
 			bounded[section].shift();
 			droppedRows += 1;
 		}
-		if (droppedRows > 0) bounded.discrepancies.push(`renderBudget: dropped the ${String(droppedRows)} oldest ${section} rows (docs/06, Appendix A)`);
+		if (droppedRows > 0) bounded.discrepancies.push(`renderBudget: dropped the ${String(droppedRows)} oldest ${section} rows `);
 		if (size(bounded) <= budgetChars) return bounded;
 	}
 	if (bounded.brief !== void 0 && size(bounded) > budgetChars) {
-		bounded.discrepancies.push("renderBudget: the mission brief was sliced (docs/06, Appendix A)");
+		bounded.discrepancies.push("renderBudget: the mission brief was sliced");
 		const over = size(bounded) - budgetChars;
 		const keep = Math.max(0, bounded.brief.text.length - over);
 		bounded.brief = {
@@ -2115,7 +2115,7 @@ function planRunner(options) {
 				logicalTaskId,
 				isNew: false
 			});
-			if (!debited.ok) throw new ConfigError("termination_exhausted: maxTotalSpawns reached at a reuse link (docs/07, 11.3)");
+			if (!debited.ok) throw new ConfigError("termination_exhausted: maxTotalSpawns reached at a reuse link");
 			decision = {
 				verdict: {
 					kind: "reuse_full",
@@ -2312,7 +2312,7 @@ function planRunner(options) {
 	* against the per-engine registry BEFORE paying for the attempt.
 	*/
 	const ladderDispatchFields = (node, spec, ladder) => {
-		for (const gate of ladder.acceptance ?? []) if (gate.kind === "mechanical" && io.gates[gate.profile] === void 0) throw new ConfigError(`mechanical gate profile '${gate.profile}' is not registered under defaults.gates (docs/07, section 10)`);
+		for (const gate of ladder.acceptance ?? []) if (gate.kind === "mechanical" && io.gates[gate.profile] === void 0) throw new ConfigError(`mechanical gate profile '${gate.profile}' is not registered under defaults.gates `);
 		const rungIndex = executingRungOf(ladder, clampStartTier(ladder, spec.model_hint?.startTier), requireAccount().rungIndexOf(node.logicalTaskId));
 		const rung = ladder.rungs[rungIndex];
 		if (rung === void 0) throw new ConfigError(`ladder rung ${String(rungIndex)} is undeclared`);
@@ -3154,10 +3154,10 @@ function planRunner(options) {
 				ledgerScope: rootScope,
 				planScope
 			}), op);
-			if (violation !== void 0) throw new ConfigError(`ledger_append rejected: ${violation} (docs/06, Appendix A)`);
+			if (violation !== void 0) throw new ConfigError(`ledger_append rejected: ${violation}`);
 			if (op.op === "lesson_add") {
 				const stats = io.admission.lineage()?.statsOf(op.key.logicalTaskId);
-				if (!(stats !== void 0 && stats.attemptsUsed > 0 && stats.approaches.some((approach) => approach.approachSig === op.key.approachSig))) throw new ConfigError("lesson_add rejected: the key matches no journaled attempt of that logical task (docs/07, 9.2)");
+				if (!(stats !== void 0 && stats.attemptsUsed > 0 && stats.approaches.some((approach) => approach.approachSig === op.key.approachSig))) throw new ConfigError("lesson_add rejected: the key matches no journaled attempt of that logical task ");
 			}
 			const entry = await io.append({
 				scope: rootScope,

package/dist/{dist-Cdj5YBRG.js → dist-hv4J07hq.js}

@@ -86992,7 +86992,7 @@ var require_eslint_helpers = /* @__PURE__ */ __commonJSMin(((exports, module) =>
 	*/
 	async function globMatch({ basePath, pattern }) {
 		let found = false;
-		const { hfs } = await import("./src-BA7JP7vn.js");
+		const { hfs } = await import("./src-pbHnkjmy.js");
 		const patternToUse = normalizeToPosix(path$9.relative(basePath, pattern));
 		const matcher = new Minimatch(patternToUse, MINIMATCH_OPTIONS);
 		const walkSettings = {
@@ -87040,7 +87040,7 @@ var require_eslint_helpers = /* @__PURE__ */ __commonJSMin(((exports, module) =>
 			return new Minimatch(patternToUse, MINIMATCH_OPTIONS);
 		});
 		const unmatchedPatterns = /* @__PURE__ */ new Set([...relativeToPatterns.keys()]);
-		const { hfs } = await import("./src-BA7JP7vn.js");
+		const { hfs } = await import("./src-pbHnkjmy.js");
 		const walk = hfs.walk(basePath, {
 			async directoryFilter(entry) {
 				if (!matchers.some((matcher) => matcher.match(entry.path, true))) return false;
@@ -94921,7 +94921,7 @@ const duplicateIdenticalCall = {
 	meta: {
 		type: "suggestion",
 		docs: { description: "advisory: byte-identical ctx.agent/ctx.workflow calls in one function forward-match to ONE journal entry; pass opts.key to distinguish deliberate repeats" },
-		messages: { duplicateCall: "this call is byte-identical to an earlier one in the same function; identical calls share one journal entry via forward-matching, so a deliberate repeat needs a distinguishing opts.key (docs/03, section 7.3)" },
+		messages: { duplicateCall: "this call is byte-identical to an earlier one in the same function; identical calls share one journal entry via forward-matching, so a deliberate repeat needs a distinguishing opts.key" },
 		schema: []
 	},
 	create(context) {
@@ -95229,7 +95229,7 @@ var WorkerSandboxRunner = class {
 		this.workerUrl = options?.workerUrl ?? new URL("./sandbox-worker.js", import.meta.url);
 	}
 	async execute(wf, ctx, args) {
-		if (wf.kind !== "compiled-workflow") throw new ConfigError("WorkerSandboxRunner executes CompiledWorkflow values only; closures run in process (docs/06, section \"Script runners\")");
+		if (wf.kind !== "compiled-workflow") throw new ConfigError("WorkerSandboxRunner executes CompiledWorkflow values only; closures run in process ");
 		const argsJson = toJournalValue(args ?? null, "sandbox workflow args");
 		const channel = new MessageChannel();
 		const worker = new Worker(this.workerUrl, { resourceLimits: { maxOldGenerationSizeMb: this.memoryMb } });

package/dist/index.d.ts

@@ -16,7 +16,7 @@ interface CliIo {
 declare function processIo(): CliIo;
 //#endregion
 //#region src/cli-main.d.ts
-declare const HELP = "rulvar: durable multi-agent workflows (docs/06, section 10.5)\n\n  rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]\n  rulvar resume <runId>  [--store PATH]\n  rulvar runs ls         [--store PATH]\n  rulvar inspect <runId> [--store PATH]\n  rulvar plan \"<goal>\"   [--dry-run]\n  rulvar kb <list | inbox | sweep>\n\nEngine assembly: adapters, defaults, and the workflow registry come from\nrulvar.config.mjs in the working directory (default export\n{ engineOptions?, workflows? }) or from the workflow module's named\nexports. --store selects the JsonlFileStore directory (default .rulvar).\nplan asks the planner model (role plan) to write a workflow script,\nlints and self-repairs it, then runs it in the worker sandbox; --dry-run\nprints the accepted script without running. Requires @rulvar/planner\ninstalled. kb list shows the per-project claim store\n(./rulvar.models.json) with full provenance. kb sweep runs the\nfalsification matrix from the kbSweep section of rulvar.config.mjs\n(fixed pool UNIONED with every model carrying an active negative claim\nplus the re-measure queue; optional canary probes flip drifted claims\nstale first; requires @rulvar/evals installed). kb inbox arrives with\nModelKnowledge phase 3.";
+declare const HELP = "rulvar: durable multi-agent workflows (https://docs.rulvar.com)\n\n  rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]\n  rulvar resume <runId>  [--store PATH]\n  rulvar runs ls         [--store PATH]\n  rulvar inspect <runId> [--store PATH]\n  rulvar plan \"<goal>\"   [--dry-run]\n  rulvar kb <list | inbox | sweep>\n\nEngine assembly: adapters, defaults, and the workflow registry come from\nrulvar.config.mjs in the working directory (default export\n{ engineOptions?, workflows? }) or from the workflow module's named\nexports. --store selects the JsonlFileStore directory (default .rulvar).\nplan asks the planner model (role plan) to write a workflow script,\nlints and self-repairs it, then runs it in the worker sandbox; --dry-run\nprints the accepted script without running. Requires @rulvar/planner\ninstalled. kb list shows the per-project claim store\n(./rulvar.models.json) with full provenance. kb sweep runs the\nfalsification matrix from the kbSweep section of rulvar.config.mjs\n(fixed pool UNIONED with every model carrying an active negative claim\nplus the re-measure queue; optional canary probes flip drifted claims\nstale first; requires @rulvar/evals installed). kb inbox arrives with\nModelKnowledge phase 3.";
 declare function runCli(argv: string[], options: {
   cwd: string;
   io: CliIo;

package/dist/index.js

@@ -1,4 +1,4 @@
-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-DSpNsEKg.js";
+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-nATg3Bhx.js";
 import { ConfigError, InvalidResolutionError, JournalCompatibilityError, LeaseHeldError, Replayer, RulvarError, buildDeriverRegistry, costReportFromJournal, maskSecrets, normalizeEntry, scanJournalCompatibility, validateSchemaSpec } from "@rulvar/core";
 //#region src/server.ts
 /**
@@ -139,7 +139,7 @@ function createServer(options) {
 		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)`
+			message: `no workflow named '${name}' in the registry`
 		} });
 		const runOptions = {
 			...body.options?.runId === void 0 ? {} : { runId: body.options.runId },
@@ -477,8 +477,8 @@ function workerIdentity() {
 }
 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)");
+	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. 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");
 	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();

package/dist/{io-DSpNsEKg.js → io-nATg3Bhx.js}

@@ -373,7 +373,7 @@ async function resumeCommand(argv, context) {
 	if (meta === void 0) throw new ConfigError(`run '${runId}' not found in the store`);
 	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 resume (docs/06, section 10.2: resume requires the in-process workflow value)`);
+	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 resume (resume requires the in-process workflow value)`);
 	const first = assembled.engine.resume(runId, workflow, { args });
 	return reportOutcome(await driveRun({
 		engine: assembled.engine,
@@ -456,7 +456,7 @@ async function planCommand(argv, context) {
 	if (goal === void 0 || parsed.positionals.length > 1) throw new ConfigError("usage: rulvar plan \"<goal>\" [--dry-run]");
 	let plannerModule;
 	try {
-		plannerModule = await import("./dist-Cdj5YBRG.js");
+		plannerModule = await import("./dist-hv4J07hq.js");
 	} catch {
 		throw new ConfigError("rulvar plan requires @rulvar/planner (the plan agent, compileScript, and the worker sandbox live there); install it next to the CLI");
 	}
@@ -532,7 +532,7 @@ async function kbInboxCommand(argv, context) {
 	if (flags.positionals.length > 0) throw new ConfigError("usage: rulvar kb inbox [--store PATH]");
 	let plan;
 	try {
-		plan = await import("./dist-Clz0iBp5.js");
+		plan = await import("./dist-DIqBj4U-.js");
 	} catch {
 		throw new ConfigError("rulvar kb inbox requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
 	}
@@ -675,7 +675,7 @@ async function kbGateCommand(argv, context) {
 	].includes(confidence)) throw new ConfigError(`--confidence must be high, medium or low, got '${String(values.confidence)}'`);
 	let plan;
 	try {
-		plan = await import("./dist-Clz0iBp5.js");
+		plan = await import("./dist-DIqBj4U-.js");
 	} catch {
 		throw new ConfigError("rulvar kb gate requires @rulvar/plan (the RunLedger fold behind the LedgerExport seam)");
 	}
@@ -771,7 +771,7 @@ async function kbSweepCommand(argv, context) {
 	if (argv.length > 0) throw new ConfigError("usage: rulvar kb sweep (configuration lives in rulvar.config.mjs)");
 	const config = await loadCliConfig(context.cwd);
 	const sweep = config.kbSweep;
-	if (sweep === void 0) throw new ConfigError("rulvar kb sweep requires a kbSweep section in rulvar.config.mjs ({ committerId, models, cases }; docs/05, section 'Grounding and decay')");
+	if (sweep === void 0) throw new ConfigError("rulvar kb sweep requires a kbSweep section in rulvar.config.mjs ({ committerId, models, cases })");
 	let evals;
 	try {
 		evals = await import("./dist-M-vPRtBM.js");
@@ -850,7 +850,7 @@ async function kbSweepCommand(argv, context) {
 * Command dispatch for the canonical grammar (https://docs.rulvar.com/guide/cli):
 * no aliases in v1; unknown commands and flags fail loudly with usage.
 */
-const HELP = `rulvar: durable multi-agent workflows (docs/06, section 10.5)
+const HELP = `rulvar: durable multi-agent workflows (https://docs.rulvar.com)
 
   rulvar run <file|name> [--args JSON] [--store PATH] [--budget-usd N]
   rulvar resume <runId>  [--store PATH]

package/dist/{src-BA7JP7vn.js → src-pbHnkjmy.js}

@@ -1,4 +1,4 @@
-import { t as __esmMin } from "./dist-Cdj5YBRG.js";
+import { t as __esmMin } from "./dist-hv4J07hq.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import nativeFsp from "node:fs/promises";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/cli",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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.3.0"
+    "@rulvar/core": "1.3.2"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.3.0",
-    "@rulvar/store-sqlite": "1.3.0",
-    "@rulvar/planner": "1.3.0",
-    "@rulvar/plan": "1.3.0",
-    "@rulvar/evals": "1.3.0"
+    "@rulvar/testing": "1.3.2",
+    "@rulvar/planner": "1.3.2",
+    "@rulvar/plan": "1.3.2",
+    "@rulvar/evals": "1.3.2",
+    "@rulvar/store-sqlite": "1.3.2"
   },
   "bin": {
     "rulvar": "./dist/cli.js"