@rulvar/rulvar 1.21.0 → 1.22.0

package/dist/index.d.ts

@@ -33,7 +33,7 @@ type ProgressMode = "auto" | "tty" | "lines" | "off";
 interface ProgressOptions {
   /** Defaults to process.stderr so application stdout stays clean. */
   sink?: ProgressSink;
-  /** Defaults to Date.now plus setInterval. */
+  /** Defaults to a monotonic clock (performance.now) plus setInterval. */
   clock?: ProgressClock;
   /**
   * 'auto' (default) picks 'tty' when the sink reports a TTY and the

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":
@@ -50,7 +65,45 @@ 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`;
@@ -82,6 +135,7 @@ const SPINNER = [
 	"-",
 	"\\"
 ];
+const SGR_STRIP = /* @__PURE__ */ new RegExp("\\u001B\\[[0-9;]*m", "gu");
 function newState(title) {
 	return {
 		...title === void 0 ? {} : { title },
@@ -120,15 +174,15 @@ function nodeOf(state, event, kind, title) {
 	return node;
 }
 /**
-* Untrusted wire strings (model ids, tool names, error messages) may
-* carry control characters; a raw newline or escape sequence in a frame
-* would break the repaint arithmetic or leak terminal control. One
-* space per control run, SGR added only by paint() afterwards.
+* 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 CONTROL_CHARS = /[\u0000-\u001f\u007f]+/gu;
-function scrub(text) {
-	return text.replace(CONTROL_CHARS, " ");
-}
+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)})`;
@@ -222,7 +276,7 @@ function applyEvent(state, event, now) {
 		}
 		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: ${event.error?.message ?? ""}`);
 			break;
 		}
 		case "agent:schema-retry": {
@@ -236,8 +290,8 @@ function applyEvent(state, event, now) {
 			node.status = event.status;
 			node.endedAt = now;
 			node.usage = {
-				input: event.usage.inputTokens,
-				output: event.usage.outputTokens
+				input: event.usage?.inputTokens ?? 0,
+				output: event.usage?.outputTokens ?? 0
 			};
 			node.costUsd = event.costUsd;
 			if (event.replayed === true) node.replayed = true;
@@ -375,10 +429,11 @@ function composeFrame(state, now, tick, style, width, maxRows, maxHeight) {
 			...lines.slice(lines.length - keepTail)
 		];
 	}
+	const limit = Math.max(0, width - 1);
 	return clamped.map((line) => {
-		const plain = line.replace(/\[[0-9;]*m/gu, "");
-		if (plain.length <= width - 1) return line;
-		return plain.slice(0, Math.max(0, width - 4)) + "...";
+		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() {
@@ -440,10 +495,12 @@ function progress(source, options) {
 	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 width = options?.width ?? sink.columns ?? 80;
-	const maxRows = options?.maxRows ?? Math.max(6, Math.min(24, (sink.rows ?? 32) - 8));
-	const fps = Math.min(30, Math.max(1, options?.fps ?? 10));
-	const state = newState(options?.title);
+	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) => {
@@ -464,7 +521,8 @@ function progress(source, options) {
 	let paintedLines = 0;
 	let lastLinesBudgetAt;
 	const paintFrame = () => {
-		const maxHeight = sink.rows === void 0 ? void 0 : Math.max(3, sink.rows - 1);
+		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");
@@ -484,9 +542,9 @@ function progress(source, options) {
 				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)} out ${fmtTokens(event.usage.outputTokens)}, ${fmtUsd(event.costUsd)}${roles}${event.replayed === true ? " (replay)" : ""}`;
+				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 "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;
@@ -503,7 +561,7 @@ function progress(source, options) {
 		applyEvent(state, event, now);
 		if (mode === "lines") {
 			const line = lineFor(event, now);
-			if (line !== void 0) sink.write(line + "\n");
+			if (line !== void 0) sink.write(scrub(line) + "\n");
 		}
 	};
 	const finishLines = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/rulvar",
-  "version": "1.21.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.21.0",
-    "@rulvar/anthropic": "1.21.0",
-    "@rulvar/openai": "1.21.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.21.0"
+    "@rulvar/testing": "1.22.0"
   },
   "repository": {
     "type": "git",