@rulvar/core 1.208.0 → 1.210.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
@@ -13131,6 +13171,24 @@ interface PreflightSpawnReport {
   * turn grows with the prompt, so this is a floor, never a cap.
   */
   turnFloorUsd?: number;
+  /**
+  * The loop's input floor over its projected turns, UNCACHED
+  * (RV2007): the declared prompt floor (`estInputTokens`) re-billed
+  * at the full input rate on every projected provider turn. A floor
+  * over the static prefix: real prompts grow. Present when the shape
+  * prices and projects more than one turn.
+  */
+  uncachedLoopInputFloorUsd?: number;
+  /**
+  * The same loop under the RV2006 cache policy: one cache write of
+  * the prompt floor plus a cache read on every later turn, priced by
+  * the row's cache rates. Present beside the uncached figure when
+  * the row carries cache rates. The parity worker shape (36k-token
+  * prompt floor, a long cycle) prices the difference at roughly
+  * three to four times, the gap between four seats fitting a $6
+  * envelope and three seats dying against it.
+  */
+  cachedLoopInputFloorUsd?: number;
   /** Executed-call ceiling across any tool mix; null = unlimited. */
   executedToolCallCeiling: number | null;
   /**

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;
@@ -24474,6 +24526,29 @@ function preflightEstimate(input) {
 		const toolCeilings = toolCeilingsOf(limits);
 		const executedToolCallCeiling = overallExecutedCeiling(limits, toolCeilings);
 		const projectedProviderTurns = projectedProviderTurnsOf(limits, executedToolCallCeiling);
+		let uncachedLoopInputFloorUsd;
+		let cachedLoopInputFloorUsd;
+		if (pricing !== void 0 && (spec.estInputTokens ?? 0) > 0 && Number.isFinite(projectedProviderTurns) && projectedProviderTurns > 1) {
+			const loopInputTokens = spec.estInputTokens ?? 0;
+			uncachedLoopInputFloorUsd = projectedProviderTurns * priceUsdOf(pricing, {
+				inputTokens: loopInputTokens,
+				outputTokens: 0,
+				cacheReadTokens: 0,
+				cacheWriteTokens: 0
+			});
+			if (pricing.cacheReadUsdPerMTok !== void 0 && pricing.cacheWriteUsdPerMTok !== void 0) cachedLoopInputFloorUsd = priceUsdOf(pricing, {
+				inputTokens: projectedProviderTurns * loopInputTokens,
+				outputTokens: 0,
+				cacheReadTokens: (projectedProviderTurns - 1) * loopInputTokens,
+				cacheWriteTokens: loopInputTokens
+			});
+		}
+		if (caps?.promptCaching === "explicit" && engine.defaults?.cache?.mode === "off" && uncachedLoopInputFloorUsd !== void 0 && cachedLoopInputFloorUsd !== void 0 && projectedProviderTurns >= 4) say({
+			severity: "warning",
+			code: "uncached-long-loop",
+			message: `spawn '${label}' projects ${String(projectedProviderTurns)} provider turns on the explicit-caching '${servedBy ?? ""}' with the cache policy OFF: the loop's input floor re-bills every turn (${uncachedLoopInputFloorUsd.toFixed(4)} USD uncached against ${cachedLoopInputFloorUsd.toFixed(4)} USD under the default policy); drop defaults.cache { mode: 'off' } or scope the opt-out to the profiles that need it`,
+			spawn: label
+		});
 		for (const row of toolCeilings) {
 			if (row.tool === ANY_TOOL) continue;
 			const cost = limits.toolUnits?.costs?.[row.tool];
@@ -24610,6 +24685,8 @@ function preflightEstimate(input) {
 			reserveSource,
 			...outputBound === void 0 ? {} : { maxOutputTokensPerTurn: outputBound },
 			...turnFloorUsd === void 0 ? {} : { turnFloorUsd },
+			...uncachedLoopInputFloorUsd === void 0 ? {} : { uncachedLoopInputFloorUsd },
+			...cachedLoopInputFloorUsd === void 0 ? {} : { cachedLoopInputFloorUsd },
 			executedToolCallCeiling,
 			projectedProviderTurns,
 			toolCeilings

package/package.json

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