@rulvar/core 1.209.0 → 1.211.0

package/dist/index.d.ts

@@ -5551,6 +5551,20 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   * else. See applyCachePolicy for the exact shape.
   */
   cache?: CachePolicy;
+  /**
+  * The incremental billing seam (RV2008): called with every
+  * ProviderCallRecord the moment the wire call settles and the record
+  * is minted, so the caller can journal it while the invocation is
+  * still running. The parity rerun lost ~$0.99 of root dispatches
+  * because records rode ONLY the terminal entry and the process died
+  * before one existed; with the seam the crash window shrinks to the
+  * single in-flight turn. Restored records (a checkpoint reboot)
+  * never re-emit: they were journaled by the segment that minted
+  * them.
+  */
+  billing?: {
+    onProviderCall: (record: ProviderCallRecord) => void;
+  };
   events?: RuntimeEventSink;
   transcript?: {
     mintRef(): string;
@@ -12630,6 +12644,32 @@ interface InvoiceExport {
   usageApprox?: boolean;
   /** The rates provenance (RV407); present when the caller declared it. */
   pricing?: InvoicePricingProvenance;
+  /**
+  * The unsettled lane (RV2008): dispatches whose agent is still
+  * RUNNING at the journal's edge, recovered from the incremental
+  * provider-call rows the loop journals as each wire call settles.
+  * Deliberately OUTSIDE the settled totals above: run_settle stays
+  * the billing boundary, and this section prices what the crash
+  * window preserved anyway, the ~$0.99 of parity root dispatches
+  * that used to live only in process memory. Present only when such
+  * rows exist; a journal whose roster is closed never carries it.
+  */
+  unsettled?: {
+    usd: number;
+    wireRequests: number;
+    rows: Array<{
+      agentRef: number;
+      scope: string;
+      ordinal: number;
+      servedBy: ModelRef;
+      role: string;
+      attempt: number;
+      outcome: string;
+      usage: Usage;
+      usd?: number;
+      responseId?: string;
+    }>;
+  };
 }
 /**
 * The pure invoice fold. Pass the same entries and price table you

package/dist/index.js

@@ -12511,6 +12511,7 @@ async function runAgent(options) {
 					if (outcome.aborted !== void 0) record.aborted = outcome.aborted;
 					else if (outcome.wireError !== void 0) record.errorCode = outcome.wireError.code;
 					providerCalls.push(record);
+					options.billing?.onProviderCall(record);
 					addCallUsd(site.role, target.resolved.ref, accounted);
 					const limited = outcome.wireError?.data;
 					if (limited?.kind === "rate-limit" && typeof limited.reportedLimits === "object" && limited.reportedLimits !== null) rateLimitObservations.set(`${target.adapter.id}:${target.resolved.model}`, {
@@ -14809,6 +14810,35 @@ function invoiceFromJournal(entries, priceUsd, options) {
 		}
 	}
 	const unallocatedUsd = allocateRows(rows, entries, priceUsd, report.grossUsd);
+	const terminalRefs = new Set(entries.filter((entry) => entry.kind === "agent" && entry.status !== "running").map((entry) => entry.ref));
+	const runningBySeq = new Map(entries.filter((entry) => entry.kind === "agent" && entry.status === "running").map((entry) => [entry.seq, entry]));
+	const unsettledRows = [];
+	for (const entry of entries) {
+		if (entry.kind !== "decision") continue;
+		const value = entry.value;
+		if (value?.decisionType !== "provider-call" || typeof value.agentRef !== "number" || terminalRefs.has(value.agentRef)) continue;
+		const running = runningBySeq.get(value.agentRef);
+		const record = value.record;
+		if (running === void 0 || record?.usage === void 0 || typeof record.ordinal !== "number" || typeof record.servedBy !== "string") continue;
+		const usd = rowUsd(priceUsd, record.servedBy, record.usage, entry.seq);
+		unsettledRows.push({
+			agentRef: value.agentRef,
+			scope: running.scope,
+			ordinal: record.ordinal,
+			servedBy: record.servedBy,
+			role: typeof record.role === "string" ? record.role : "loop",
+			attempt: typeof record.attempt === "number" ? record.attempt : 1,
+			outcome: typeof record.outcome === "string" ? record.outcome : "ok",
+			usage: record.usage,
+			...usd === void 0 ? {} : { usd },
+			...typeof record.responseId === "string" ? { responseId: record.responseId } : {}
+		});
+	}
+	const unsettled = unsettledRows.length === 0 ? void 0 : {
+		usd: unsettledRows.reduce((sum, row) => sum + (row.usd ?? 0), 0),
+		wireRequests: unsettledRows.length,
+		rows: unsettledRows
+	};
 	const usageApprox = report.usageApprox === true || report.abandoned.usageApprox === true;
 	const invoice = {
 		rows,
@@ -14821,6 +14851,7 @@ function invoiceFromJournal(entries, priceUsd, options) {
 		unpriced: [...report.unpriced, ...report.abandoned.unpriced],
 		reconciliationFailures: rows.filter((row) => row.reconciliation !== "provider-id-present").length,
 		cardinality: cardinalityOf(rows),
+		...unsettled === void 0 ? {} : { unsettled },
 		...(() => {
 			const count = rows.filter((row) => row.usageUnknown === true).length;
 			return count === 0 ? {} : { usageUnknownRows: count };
@@ -18003,6 +18034,27 @@ function createCtx(internals, rootWorkflow) {
 			const cachePolicy = opts.cache ?? profile?.cache ?? internals.defaults.cache;
 			if (cachePolicy !== void 0) runAgentOptions.cache = cachePolicy;
 		}
+		runAgentOptions.billing = { onProviderCall: (record) => {
+			internals.replayer.appendSinglePhase({
+				scope: state.scope,
+				key: `pc:${String(running.seq)}:${String(record.ordinal)}`,
+				kind: "decision",
+				status: "ok",
+				spanId,
+				site: "provider-call",
+				value: {
+					decisionType: "provider-call",
+					agentRef: running.seq,
+					record
+				}
+			}).catch((thrown) => {
+				internals.events.emit({
+					type: "log",
+					level: "warn",
+					msg: `incremental billing row failed to append; the terminal entry remains the canonical record (${thrown instanceof Error ? thrown.message : String(thrown)})`
+				}, spanId);
+			});
+		} };
 		runAgentOptions.summarize = summarize;
 		if (profile?.compaction !== void 0) runAgentOptions.compaction = profile.compaction;
 		if (profile?.evidenceContract !== void 0) runAgentOptions.evidenceContract = profile.evidenceContract;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.209.0",
+  "version": "1.211.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",