@rulvar/rulvar 1.22.0 → 1.24.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { sanitizeTerminalText } from "@rulvar/core";
+import { maskSecrets, sanitizeTerminalText } from "@rulvar/core";
 import { ANTHROPIC_MODELS, anthropic } from "@rulvar/anthropic";
 import { OPENAI_MODELS, openai } from "@rulvar/openai";
 export * from "@rulvar/core";
@@ -17,7 +17,24 @@ export * from "@rulvar/core";
 * P2-1).
 */
 function usd(amount) {
-	return `${amount.toFixed(4)} USD`;
+	return `${(typeof amount === "number" && Number.isFinite(amount) ? amount : 0).toFixed(4)} USD`;
+}
+/**
+* Defensive readers: the input is a raw iterable by contract, so a
+* recognized event with a missing or mistyped field degrades its own
+* line instead of throwing out of the render loop (v1.22.0 review
+* P2-3; same discipline as the live progress reducer).
+*/
+function str$1(value) {
+	return typeof value === "string" ? value : "";
+}
+function num$1(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function name(event) {
+	const agentType = str$1(event.agentType) || "anonymous";
+	const label = str$1(event.label);
+	return `${agentType}${label === "" ? "" : ` [${label}]`}`;
 }
 /**
 * Renders events until the stream ends (the run settled). Returns after
@@ -31,34 +48,34 @@ async function renderProgress(events, options) {
 	const logs = options?.logs ?? true;
 	for await (const event of events) switch (event.type) {
 		case "run:start":
-			write(`run ${event.runId} started: ${event.workflow}${event.resumed ? " (resumed)" : ""}`);
+			write(`run ${str$1(event.runId)} started: ${str$1(event.workflow)}${event.resumed === true ? " (resumed)" : ""}`);
 			break;
 		case "phase:start":
-			write(`phase: ${event.phase}`);
+			write(`phase: ${str$1(event.phase)}`);
 			break;
 		case "agent:queued":
-			write(`agent ${event.agentType || "anonymous"}${event.label ? ` [${event.label}]` : ""} queued`);
+			write(`agent ${name(event)} queued`);
 			break;
 		case "agent:start":
-			write(`agent ${event.agentType || "anonymous"}${event.label ? ` [${event.label}]` : ""} -> ${event.model} (${event.role})`);
+			write(`agent ${name(event)} -> ${str$1(event.model)} (${str$1(event.role)})`);
 			break;
 		case "agent:end":
-			write(`agent ${event.agentType || "anonymous"}${event.label ? ` [${event.label}]` : ""} ${event.status} (${usd(event.costUsd)}, ${event.usage.outputTokens} out tokens)`);
+			write(`agent ${name(event)} ${str$1(event.status)} (${usd(event.costUsd)}, ${String(num$1(event.usage?.outputTokens))} out tokens)`);
 			break;
 		case "agent:error":
-			write(`agent ${event.agentType || "anonymous"} error: ${event.error.message}${event.willRetry ? " (will retry)" : ""}`);
+			write(`agent ${str$1(event.agentType) || "anonymous"} error: ${str$1(event.error?.message)}${event.willRetry === true ? " (will retry)" : ""}`);
 			break;
 		case "agent:schema-retry":
-			write(`agent ${event.agentType || "anonymous"} schema retry ${event.attempt}/${event.maxAttempts}`);
+			write(`agent ${str$1(event.agentType) || "anonymous"} schema retry ${String(num$1(event.attempt))}/${String(num$1(event.maxAttempts))}`);
 			break;
 		case "budget:update":
-			write(`budget: spent ${usd(event.spentUsd)}` + (event.remainingUsd === null ? "" : `, remaining ${usd(event.remainingUsd)}`));
+			write(`budget: spent ${usd(event.spentUsd)}` + (typeof event.remainingUsd === "number" ? `, remaining ${usd(event.remainingUsd)}` : ""));
 			break;
 		case "log":
-			if (logs && event.level !== "debug") write(`[${event.level}] ${event.msg}`);
+			if (logs && event.level !== "debug") write(`[${str$1(event.level)}] ${str$1(event.msg)}`);
 			break;
 		case "run:end":
-			write(`run finished: ${event.status} (total ${usd(event.totalUsd)})`);
+			write(`run finished: ${str$1(event.status)} (total ${usd(event.totalUsd)})`);
 			break;
 		default: break;
 	}
@@ -94,9 +111,11 @@ async function renderProgress(events, options) {
 */
 /**
 * 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.
+* non-finite caller value falls back to the default and a below-minimum
+* value CLAMPS to the minimum (wording fixed in the v1.22.0 review
+* P4-2; the behavior always clamped), so no caller value can poison 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;
@@ -183,9 +202,44 @@ function nodeOf(state, event, kind, title) {
 * P2-1).
 */
 const scrub = sanitizeTerminalText;
+/**
+* Defensive readers for recognized event types arriving from a RAW
+* iterable: the engine's own bus always satisfies the types, but the
+* documented raw-iterable source can hand the reducer any shape, and a
+* missing or mistyped field must degrade the one row, never stop the
+* view or reach a template literal as an object whose coercion could
+* throw (v1.22.0 review P2-3).
+*/
+function str(value) {
+	return typeof value === "string" ? value : "";
+}
+function num(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function numOpt(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/**
+* One safe form for every error a catch path surfaces: the message is
+* secret-masked FIRST (the thrown value never went through the event
+* masking boundary) and terminal-sanitized second, so a rejected
+* source can neither leak a key-shaped fragment nor inject control
+* sequences or forged lines into the sink (v1.22.0 review P2-2).
+*/
+function errorNotice(thrown) {
+	let message;
+	try {
+		message = thrown instanceof Error ? thrown.message : String(thrown);
+	} catch {
+		message = "unprintable thrown value";
+	}
+	return scrub(maskSecrets(`error: ${message}`));
+}
 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)})`;
+	const agentType = str(event.agentType);
+	const label = str(event.label);
+	const base = agentType === "" ? "agent" : scrub(agentType);
+	return label === "" ? base : `${base} (${scrub(label)})`;
 }
 /** The tool event's span is the agent's own span or a child of it. */
 function toolTarget(state, event) {
@@ -198,11 +252,11 @@ function applyEvent(state, event, now) {
 			state.runId = event.runId;
 			state.resumed = event.resumed === true;
 			state.startedAt ??= now;
-			state.title ??= scrub(event.workflow);
+			state.title ??= scrub(str(event.workflow));
 			break;
 		case "run:end":
-			state.status = event.status;
-			state.totalUsd = event.totalUsd;
+			state.status = str(event.status) || "interrupted";
+			state.totalUsd = numOpt(event.totalUsd);
 			state.endedAt = now;
 			for (const node of state.nodes.values()) {
 				if (node.endedAt === void 0 && node.kind !== "phase") {
@@ -214,36 +268,36 @@ function applyEvent(state, event, now) {
 			}
 			break;
 		case "phase:start": {
-			const node = nodeOf(state, event, "phase", scrub(event.phase));
+			const node = nodeOf(state, event, "phase", scrub(str(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;
+			state.spentUsd = num(event.spentUsd);
+			state.ceilingUsd = typeof event.remainingUsd === "number" && Number.isFinite(event.remainingUsd) ? num(event.spentUsd) + event.remainingUsd : void 0;
 			break;
 		case "log":
 			if (event.level === "warn" || event.level === "error") {
-				state.notices.push(scrub(`${event.level}: ${event.msg}`));
+				state.notices.push(scrub(`${str(event.level)}: ${str(event.msg)}`));
 				if (state.notices.length > 2) state.notices.shift();
 			}
 			break;
 		case "external:waiting":
-			state.banner = scrub(`waiting on external: ${event.key}`);
+			state.banner = scrub(`waiting on external: ${str(event.key)}`);
 			break;
 		case "approval:pending":
-			state.banner = scrub(`approval pending: ${event.toolName}`);
+			state.banner = scrub(`approval pending: ${str(event.toolName)}`);
 			break;
 		case "child:start": {
-			const node = nodeOf(state, event, "child", scrub(`${event.workflow} (${event.scope})`));
+			const node = nodeOf(state, event, "child", scrub(`${str(event.workflow)} (${str(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.status = str(event.status) || "interrupted";
 				node.endedAt = now;
 			}
 			break;
@@ -259,41 +313,41 @@ function applyEvent(state, event, now) {
 			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);
+			node.model = scrub(str(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,
+				role: str(event.role),
 				startedAt: now
 			});
 			break;
 		}
 		case "agent:stream": {
 			const node = state.nodes.get(event.spanId);
-			if (node !== void 0) node.streamedChars += event.delta.length;
+			if (node !== void 0) node.streamedChars += str(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 ?? ""}`);
+			if (node !== void 0) node.badge = event.willRetry ? "retry" : scrub(`error: ${str(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)}`;
+			if (node !== void 0) node.badge = `schema ${String(num(event.attempt))}/${String(num(event.maxAttempts))}`;
 			break;
 		}
 		case "agent:end": {
 			state.banner = void 0;
 			const node = nodeOf(state, event, "agent", agentTitle(event));
-			node.status = event.status;
+			node.status = str(event.status) || "interrupted";
 			node.endedAt = now;
 			node.usage = {
-				input: event.usage?.inputTokens ?? 0,
-				output: event.usage?.outputTokens ?? 0
+				input: num(event.usage?.inputTokens),
+				output: num(event.usage?.outputTokens)
 			};
-			node.costUsd = event.costUsd;
+			node.costUsd = numOpt(event.costUsd);
 			if (event.replayed === true) node.replayed = true;
 			if (node.status === "ok") node.badge = void 0;
 			const open = node.roles.at(-1);
@@ -302,7 +356,7 @@ function applyEvent(state, event, now) {
 		}
 		case "tool:start": {
 			const node = toolTarget(state, event);
-			if (node !== void 0) node.toolActive = scrub(event.toolName);
+			if (node !== void 0) node.toolActive = scrub(str(event.toolName));
 			break;
 		}
 		case "tool:end": {
@@ -310,7 +364,7 @@ function applyEvent(state, event, now) {
 			if (node !== void 0) {
 				node.toolActive = void 0;
 				node.toolCount += 1;
-				if (event.outcome === "denied") node.badge = scrub(`tool ${event.toolName} denied`);
+				if (event.outcome === "denied") node.badge = scrub(`tool ${str(event.toolName)} denied`);
 			}
 			break;
 		}
@@ -322,7 +376,7 @@ function applyEvent(state, event, now) {
 			break;
 		case "spawn:rejected":
 			state.rejected += 1;
-			state.notices.push(`spawn rejected: ${event.code}`);
+			state.notices.push(scrub(`spawn rejected: ${str(event.code)}`));
 			if (state.notices.length > 2) state.notices.shift();
 			break;
 		default: break;
@@ -339,7 +393,7 @@ const GLYPHS = {
 	escalated: "!"
 };
 function paint(text, code, style) {
-	return style.color ? `[${code}m${text}` : text;
+	return style.color ? `\u001B[${code}m${text}\u001B[0m` : text;
 }
 function nodeRow(node, now, spinner, style) {
 	const running = node.endedAt === void 0 && node.status === "running";
@@ -524,44 +578,57 @@ function progress(source, options) {
 		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` : "";
+		const erase = paintedLines > 0 ? `\u001B[${String(paintedLines)}A\u001B[0J` : "";
 		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 "run:start": return `run ${str(event.runId)} started: ${str(event.workflow)}${event.resumed === true ? " (resumed)" : ""}`;
+			case "phase:start": return `phase: ${str(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]" : ""}`;
+				return `agent ${agentTitle(event)} -> ${str(event.model)} (${str(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)" : ""}`;
+				return `agent ${agentTitle(event)} ${str(event.status)}${elapsed}: in ${fmtTokens(num(event.usage?.inputTokens))} out ${fmtTokens(num(event.usage?.outputTokens))}, ${fmtUsd(num(event.costUsd))}${roles}${event.replayed === true ? " (replay)" : ""}`;
 			}
-			case "agent:error": return `agent ${agentTitle(event)} error: ${event.error?.message ?? ""}` + (event.willRetry ? " (will retry)" : "");
+			case "agent:error": return `agent ${agentTitle(event)} error: ${str(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)})`;
+				return `budget: ${fmtUsd(num(event.spentUsd))}` + (typeof event.remainingUsd === "number" && Number.isFinite(event.remainingUsd) ? ` of ${fmtUsd(num(event.spentUsd) + event.remainingUsd)}` : "");
+			case "log": return event.level === "warn" || event.level === "error" ? `[${str(event.level)}] ${str(event.msg)}` : void 0;
+			case "external:waiting": return `waiting on external: ${str(event.key)}`;
+			case "approval:pending": return `approval pending: ${str(event.toolName)}`;
+			case "run:end": return `run finished: ${str(event.status)} (total ${fmtUsd(num(event.totalUsd))})`;
 			default: return;
 		}
 	};
+	const pushNotice = (notice) => {
+		state.notices.push(notice);
+		if (state.notices.length > 2) state.notices.shift();
+		if (mode === "lines") sink.write(scrub(notice) + "\n");
+	};
+	let malformedNoticed = false;
 	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");
+		try {
+			applyEvent(state, event, now);
+			if (mode === "lines") {
+				const line = lineFor(event, now);
+				if (line !== void 0) sink.write(scrub(line) + "\n");
+			}
+		} catch {
+			if (!malformedNoticed) {
+				malformedNoticed = true;
+				pushNotice("progress: skipped malformed event(s); view may be incomplete");
+			}
 		}
 	};
 	const finishLines = () => {
@@ -615,7 +682,7 @@ function progress(source, options) {
 			state.totalUsd = outcome.cost.totalUsd;
 			state.endedAt ??= clock.now();
 		}).catch((thrown) => {
-			state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+			pushNotice(errorNotice(thrown));
 			state.endedAt ??= clock.now();
 		}).finally(() => {
 			handleApi.stop(true);
@@ -625,7 +692,7 @@ function progress(source, options) {
 	else if (typeof source.then === "function") source.then((handle) => {
 		attachHandle(handle);
 	}).catch((thrown) => {
-		state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+		pushNotice(errorNotice(thrown));
 		state.endedAt ??= clock.now();
 		handleApi.stop(true);
 	});
@@ -636,7 +703,7 @@ function progress(source, options) {
 				onEvent(event);
 			}
 		} catch (thrown) {
-			state.notices.push(`error: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+			pushNotice(errorNotice(thrown));
 		} finally {
 			state.endedAt ??= clock.now();
 			handleApi.stop(true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/rulvar",
-  "version": "1.22.0",
+  "version": "1.24.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.22.0",
-    "@rulvar/anthropic": "1.22.0",
-    "@rulvar/openai": "1.22.0"
+    "@rulvar/core": "1.24.0",
+    "@rulvar/anthropic": "1.24.0",
+    "@rulvar/openai": "1.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
     "zod": "^4.4.3",
-    "@rulvar/testing": "1.22.0"
+    "@rulvar/testing": "1.24.0"
   },
   "repository": {
     "type": "git",