@rulvar/core 1.38.0 → 1.40.0

package/dist/index.d.ts

@@ -4303,6 +4303,14 @@ type CoreEvents = {
   type: "run:end";
   status: "ok" | "error" | "cancelled" | "exhausted" | "suspended";
   totalUsd: number;
+  /**
+  * Present and true when any priced usage folded into totalUsd is
+  * approximate (a transport cut, a stream the ceiling severed, or an
+  * abort left a turn's usage estimated rather than reported by the
+  * provider), so totalUsd is a lower bound estimate, never an exact
+  * charge. Absent means every contributing turn reported exact usage.
+  */
+  usageApprox?: boolean;
 } | {
   type: "phase:start";
   phase: string;
@@ -4356,6 +4364,14 @@ type AgentEvents = {
   usage: Usage;
   costUsd: number;
   entryRef: number;
+  /**
+  * Present and true when this agent's usage is approximate rather
+  * than reported by the provider (the turn was cut by a transport
+  * failure, a ceiling that severed the stream, or an abort). Absent
+  * means the provider reported the usage exactly. Mirrors the
+  * terminal journal entry's usageApprox.
+  */
+  usageApprox?: boolean;
 } | {
   type: "agent:error";
   agentType: string;
@@ -4612,6 +4628,16 @@ interface CostReport {
     model: string;
     usage: Usage;
   }>;
+  /**
+  * Present and true when any terminal entry folded into totalUsd carried
+  * approximate usage (a transport cut, a stream the ceiling severed, or
+  * an abort estimated the turn instead of the provider reporting it), so
+  * totalUsd is a lower bound estimate, never an exact charge. Absent
+  * means every contributing entry reported exact usage. The field the
+  * v1.39.0 review asked the report to raise so approximate cost is never
+  * shown as though it were the provider invoice.
+  */
+  usageApprox?: boolean;
 }
 type RunOutcome<R> = {
   status: "ok" | "error" | "cancelled" | "exhausted" | "suspended";

package/dist/index.js

@@ -6799,6 +6799,7 @@ function costReportFromJournal(entries, priceUsd) {
 	const byRole = emptyByRole();
 	const unpriced = [];
 	let totalUsd = 0;
+	let usageApprox = false;
 	let orchestratorSpentUsd = 0;
 	let reserveUsedUsd = 0;
 	let wakes = 0;
@@ -6815,6 +6816,7 @@ function costReportFromJournal(entries, priceUsd) {
 		});
 		for (const slice of priced.priced) byModel[slice.servedBy] = (byModel[slice.servedBy] ?? 0) + slice.usd;
 		totalUsd += priced.usd;
+		if (entry.usageApprox === true) usageApprox = true;
 		const facts = entry.costAttribution;
 		const phase = facts?.phase ?? "";
 		byPhase[phase] = (byPhase[phase] ?? 0) + priced.usd;
@@ -6840,7 +6842,8 @@ function costReportFromJournal(entries, priceUsd) {
 			forcedFinish,
 			reserveUsedUsd
 		},
-		unpriced
+		unpriced,
+		...usageApprox ? { usageApprox: true } : {}
 	};
 }
 //#endregion
@@ -11411,7 +11414,8 @@ function createCtx(internals, rootWorkflow) {
 				status: result.status,
 				usage,
 				costUsd,
-				entryRef: terminal?.seq ?? matched.running.seq
+				entryRef: terminal?.seq ?? matched.running.seq,
+				...terminal?.usageApprox === true ? { usageApprox: true } : {}
 			}, spanId, true);
 			for (const slice of replayPriced?.priced ?? []) bump(internals.cost.byModel, slice.servedBy, slice.usd);
 			for (const slice of replayPriced?.unpriced ?? []) internals.cost.unpriced.push({
@@ -11866,7 +11870,8 @@ function createCtx(internals, rootWorkflow) {
 		if (result.status === "escalated" && result.escalation !== void 0) terminalPatch.escalation = result.escalation;
 		if (result.output !== null && result.status === "ok") terminalPatch.value = result.output;
 		if (result.error !== void 0) terminalPatch.error = agentErrorToWire(result.error, result.errorMessage ?? `agent terminated with status ${result.status}`);
-		if (result.usageApprox === true) terminalPatch.usageApprox = true;
+		const resultUsageApprox = result.usageApprox === true;
+		if (resultUsageApprox) terminalPatch.usageApprox = true;
 		if (result.artifacts !== void 0) terminalPatch.artifacts = result.artifacts;
 		if (result.abortClass !== void 0) {
 			terminalPatch.memoizeOutcome = true;
@@ -11891,7 +11896,8 @@ function createCtx(internals, rootWorkflow) {
 			status: result.status,
 			usage: result.usage,
 			costUsd: result.costUsd,
-			entryRef: terminal.seq
+			entryRef: terminal.seq,
+			...resultUsageApprox ? { usageApprox: true } : {}
 		}, spanId);
 		if (result.status === "escalated" && result.escalation !== void 0) {
 			let decision = flavorBDecision;
@@ -14110,7 +14116,8 @@ function createEngine(options) {
 			bus.emit({
 				type: "run:end",
 				status,
-				totalUsd: ledger.usd
+				totalUsd: ledger.usd,
+				...outcome.cost.usageApprox === true ? { usageApprox: true } : {}
 			}, rootSpanId);
 			bus.end();
 			resumeCtx?.previewResolve({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",