@rulvar/core 1.19.0 → 1.20.0

package/dist/index.d.ts

@@ -602,10 +602,20 @@ type AbandonPayload = {
   retainCheckpoint?: boolean; /** Default false; counts against the pin cap (DEF-5). */
   retainWorktree?: boolean;
 };
-/** One serving model's slice of a multi-model agent call's usage. */
+/**
+* One (invocation role, serving model) slice of an agent call's usage.
+* `role` is the phase that PAID the slice (v1.19.0 review P1-2: the
+* loop, extract, finalize, and summarize phases of one agent call must
+* land in their own CostReport.byRole buckets even when a single model
+* serves several of them). Absent on slices written before roles
+* shipped: readers fall back to the entry's primary
+* `costAttribution.role`, exactly like the other documented fallbacks.
+* Policy, never identity.
+*/
 interface UsageSlice {
   servedBy: ModelRef;
   usage: Usage;
+  role?: InvocationRole;
 }
 /**
 * Cost-attribution facts a live run knows at settlement and a pure
@@ -2760,11 +2770,13 @@ interface AgentResult<T> {
   */
   servedBy: ModelRef;
   /**
-  * Present only when the call spanned MORE THAN ONE serving model (the
-  * loop, extract, finalize, and summarize roles resolve independently):
-  * usage split per model, so `costUsd` and every cost bucket price each
-  * slice at its own rate. Absent for a single-model call, which
-  * (usage, servedBy) already describes exactly.
+  * Present only when the call spanned MORE THAN ONE (invocation role,
+  * serving model) pair (the loop, extract, finalize, and summarize
+  * roles resolve independently): usage split per (role, model), so
+  * `costUsd` and every cost bucket price each slice at its own rate
+  * and `CostReport.byRole` attributes each phase to its own bucket
+  * (v1.19.0 review P1-2). Absent for a single-phase single-model call,
+  * which (usage, servedBy) already describes exactly.
   */
   usageByModel?: UsageSlice[];
   transcriptRef: string;

package/dist/index.js

@@ -6386,7 +6386,8 @@ function costReportFromJournal(entries, priceUsd) {
 		byPhase[phase] = (byPhase[phase] ?? 0) + priced.usd;
 		const agentType = facts?.agentType ?? "unknown";
 		byAgentType[agentType] = (byAgentType[agentType] ?? 0) + priced.usd;
-		byRole[facts?.role ?? "loop"] += priced.usd;
+		const primaryRole = facts?.role ?? "loop";
+		for (const slice of priced.priced) byRole[slice.role ?? primaryRole] += slice.usd;
 		if (facts?.budgetAccount !== void 0 && isOrchestratorAccount(facts.budgetAccount)) {
 			orchestratorSpentUsd += priced.usd;
 			if (facts.finalizeReserve === true) reserveUsedUsd += priced.usd;
@@ -8058,7 +8059,17 @@ async function runAgent(options) {
 		}]
 	}];
 	let totalUsage = ZERO_USAGE$1;
-	const usageByModel = /* @__PURE__ */ new Map();
+	const primaryRole = options.role ?? "loop";
+	const usageByPhaseModel = /* @__PURE__ */ new Map();
+	const addPhaseUsage = (role, ref, usage) => {
+		const key = `${role}${ref}`;
+		const prior = usageByPhaseModel.get(key);
+		usageByPhaseModel.set(key, {
+			role,
+			servedBy: ref,
+			usage: addUsage(prior?.usage ?? ZERO_USAGE$1, usage)
+		});
+	};
 	let turns = 0;
 	let schemaAttempts = 0;
 	let output = null;
@@ -8093,13 +8104,14 @@ async function runAgent(options) {
 			usage: restored.usage
 		}];
 		for (const slice of restoredSlices) {
-			usageByModel.set(slice.servedBy, addUsage(usageByModel.get(slice.servedBy) ?? ZERO_USAGE$1, slice.usage));
+			addPhaseUsage(slice.role ?? primaryRole, slice.servedBy, slice.usage);
 			options.budget?.onUsage(slice.usage, slice.servedBy);
 		}
 	}
-	const usageSlices = () => [...usageByModel].map(([sliceServedBy, usage]) => ({
+	const usageSlices = () => [...usageByPhaseModel.values()].map(({ role, servedBy: sliceServedBy, usage }) => ({
 		servedBy: sliceServedBy,
-		usage
+		usage,
+		role
 	}));
 	/**
 	* Every slice priced at ITS OWN model's rate. An unpriced model
@@ -8110,7 +8122,7 @@ async function runAgent(options) {
 		const price = options.priceUsd;
 		if (price === void 0) return 0;
 		let usd = 0;
-		for (const [sliceServedBy, usage] of usageByModel) usd += price(sliceServedBy, usage) ?? 0;
+		for (const slice of usageByPhaseModel.values()) usd += price(slice.servedBy, slice.usage) ?? 0;
 		return usd;
 	};
 	const saveBoundary = async (pending) => {
@@ -8343,17 +8355,17 @@ async function runAgent(options) {
 		agentType,
 		label: options.label,
 		model: servedBy,
-		role: options.role ?? "loop"
+		role: primaryRole
 	});
 	let invariantViolation;
-	const recordUsage = (usage, reported, adapterId, ref) => {
+	const recordUsage = (usage, reported, adapterId, ref, role) => {
 		try {
 			assertUsageInvariant(usage, adapterId);
 		} catch (thrown) {
 			invariantViolation = thrown instanceof Error ? thrown.message : String(thrown);
 		}
 		totalUsage = addUsage(totalUsage, usage);
-		usageByModel.set(ref, addUsage(usageByModel.get(ref) ?? ZERO_USAGE$1, usage));
+		addPhaseUsage(role, ref, usage);
 		const remainder = {
 			inputTokens: Math.max(0, usage.inputTokens - reported.inputTokens),
 			outputTokens: Math.max(0, usage.outputTokens - reported.outputTokens),
@@ -8375,7 +8387,7 @@ async function runAgent(options) {
 			inner: for (;;) {
 				const dispatch = () => streamTurn(target.adapter, site.requestFor(target), site.streamOptionsFor(target));
 				const outcome = await (options.providerSlot === void 0 ? dispatch() : options.providerSlot(target.adapter.id, dispatch));
-				recordUsage(outcome.usage, outcome.reported, target.adapter.id, target.resolved.ref);
+				recordUsage(outcome.usage, outcome.reported, target.adapter.id, target.resolved.ref, site.role);
 				tries += 1;
 				const retryClass = outcome.aborted === "idle" ? "transport" : outcome.wireError === void 0 ? void 0 : retryClassOf(outcome.wireError);
 				if (retryClass === void 0) return {
@@ -8452,6 +8464,7 @@ async function runAgent(options) {
 		let loopDispatch;
 		try {
 			loopDispatch = await dispatchPhase({
+				role: primaryRole,
 				chain: loopChain,
 				cursor: loopCursor,
 				requestFor: (target) => {
@@ -8643,6 +8656,7 @@ async function runAgent(options) {
 				let summaryDispatch;
 				try {
 					summaryDispatch = await dispatchPhase({
+						role: "summarize",
 						chain: [{
 							adapter: options.summarize.adapter,
 							resolved: options.summarize.resolved
@@ -8822,6 +8836,7 @@ async function runAgent(options) {
 			let finalizeDispatch;
 			try {
 				finalizeDispatch = await dispatchPhase({
+					role: "finalize",
 					chain: [{
 						adapter: options.finalize.adapter,
 						resolved: options.finalize.resolved
@@ -8944,6 +8959,7 @@ async function runAgent(options) {
 			let extractDispatch;
 			try {
 				extractDispatch = await dispatchPhase({
+					role: "extract",
 					chain: extractChain,
 					cursor: extractCursor,
 					requestFor: (target) => {
@@ -9047,7 +9063,7 @@ async function runAgent(options) {
 		servedBy,
 		transcriptRef
 	};
-	if (usageByModel.size > 1) result.usageByModel = usageSlices();
+	if (usageByPhaseModel.size > 1) result.usageByModel = usageSlices();
 	if (agentError !== void 0) result.error = agentError;
 	if (escalationRequest !== void 0) result.escalationRequest = escalationRequest;
 	if (abortClass !== void 0) result.abortClass = abortClass;
@@ -11062,10 +11078,11 @@ function createCtx(internals, rootWorkflow) {
 			});
 		}
 		const usd = result.costUsd;
-		for (const slice of result.usageByModel ?? [{
+		const attributionSlices = result.usageByModel ?? [{
 			servedBy: result.servedBy,
 			usage: result.usage
-		}]) {
+		}];
+		for (const slice of attributionSlices) {
 			const priced = internals.priceUsd(slice.servedBy, slice.usage);
 			if (priced === void 0) {
 				internals.cost.unpriced.push({
@@ -11075,10 +11092,11 @@ function createCtx(internals, rootWorkflow) {
 				continue;
 			}
 			bump(internals.cost.byModel, slice.servedBy, priced);
+			const sliceRole = slice.role ?? primaryRole;
+			internals.cost.byRole.set(sliceRole, (internals.cost.byRole.get(sliceRole) ?? 0) + priced);
 		}
 		bump(internals.cost.byPhase, state.phase ?? "", usd);
 		bump(internals.cost.byAgentType, agentType, usd);
-		internals.cost.byRole.set(primaryRole, (internals.cost.byRole.get(primaryRole) ?? 0) + usd);
 		if (result.error?.kind === "budget" || internals.budget.exhausted && result.status !== "ok") {
 			const diagnostics = internals.budget.exhaustionDiagnostics(state.budgetScope ?? "run");
 			const crossed = diagnostics.crossed;

package/package.json

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