@rulvar/core 1.59.4 → 1.60.0

package/dist/index.d.ts

@@ -3876,6 +3876,24 @@ interface UsageLimits {
     max: number;
     costs?: Record<string, number>;
   };
+  /**
+  * The guaranteed finalization turn (the experiment-review P1.1): when
+  * a TOOL budget limiter (maxToolCalls or toolUnits) expires, the
+  * runtime closes the current batch's remaining calls with explicit
+  * skipped-call error results instead of dropping them silently, then
+  * grants the model exactly ONE summary turn with tools withheld
+  * before the invocation settles as status 'limit' with the exact
+  * limiter named in the terminal error. The summary text becomes the
+  * limit result's output for schema-less calls; a ridden schema
+  * validates into typed output when the summary parses (one attempt,
+  * no re-prompt). `maxOutputTokens` bounds the summary turn only;
+  * absent, the ordinary per-turn output policy applies. Off by
+  * default: the skip results and the summary instruction enter the
+  * conversation, so enabling it changes recorded model requests.
+  */
+  finalizationReserve?: {
+    maxOutputTokens?: number;
+  };
 }
 declare const DEFAULT_MAX_TURNS = 32;
 declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 12e4;
@@ -3896,6 +3914,9 @@ interface EffectiveUsageLimits {
     max: number;
     costs?: Record<string, number>;
   };
+  finalizationReserve?: {
+    maxOutputTokens?: number;
+  };
 }
 /**
 * Limits merge per spawn: AgentOpts.limits over profile limits over engine

package/dist/index.js

@@ -9328,6 +9328,8 @@ function mergeUsageLimits(call, profile, engine) {
 	if (maxCallsPerTool !== void 0) merged.maxCallsPerTool = maxCallsPerTool;
 	const toolUnits = pick("toolUnits");
 	if (toolUnits !== void 0) merged.toolUnits = toolUnits;
+	const finalizationReserve = pick("finalizationReserve");
+	if (finalizationReserve !== void 0) merged.finalizationReserve = finalizationReserve;
 	return merged;
 }
 /**
@@ -9367,6 +9369,12 @@ function validateUsageLimits(limits, site) {
 			for (const [name, cost] of Object.entries(costs)) requireNonNegativeInteger(cost, `${site}.toolUnits.costs['${name}']`);
 		}
 	}
+	if (limits.finalizationReserve !== void 0) {
+		const reserve = limits.finalizationReserve;
+		if (typeof reserve !== "object" || reserve === null || Array.isArray(reserve)) throw new ConfigError(`${site}.finalizationReserve must be { maxOutputTokens? }`);
+		const { maxOutputTokens } = reserve;
+		if (maxOutputTokens !== void 0) requirePositiveInteger(maxOutputTokens, `${site}.finalizationReserve.maxOutputTokens`);
+	}
 }
 //#endregion
 //#region src/runtime/model-retry.ts
@@ -10530,8 +10538,27 @@ async function runAgent(options) {
 	let toolCallsUsed = 0;
 	let escalationRequest;
 	let abortClass;
+	/**
+	* Set at a tool-budget expiry when limits.finalizationReserve is
+	* configured (P1.1); the reserve turn itself runs at ONE site after
+	* the loop ends (the pending-turn path trips before the dispatch
+	* machinery below is even defined), inside the still-open loop phase.
+	*/
+	let reserveRequest;
 	const noProgress = new NoProgressDetector(limits.noProgressTurns);
 	const guard = explorationTrackingEnabled(limits) ? new ExplorationGuard(limits) : void 0;
+	/**
+	* The exact limiter behind a tool-budget expiry, with its counts: the
+	* wording rides the finalization-reserve instruction and the 'limit'
+	* terminal's errorMessage (P1.1 criterion: the terminal names the
+	* limiter, never a bare status).
+	*/
+	const toolBudgetDetail = (limiter) => {
+		if (limiter === "maxToolCalls") return `maxToolCalls (${String(toolCallsUsed)}/${String(limits.maxToolCalls ?? 0)})`;
+		const max = limits.toolUnits?.max ?? 0;
+		const used = guard === void 0 ? max : guard.summary(toolCallsUsed).toolUnitsUsed ?? max;
+		return `toolUnits (${String(used)}/${String(max)})`;
+	};
 	if (limits.toolBudgetNotices === true && limits.maxToolCalls === void 0) events?.emit({
 		type: "log",
 		level: "warn",
@@ -10653,15 +10680,42 @@ async function runAgent(options) {
 			part.isError = true;
 			return part;
 		};
+		/**
+		* Closes the batch tail at a tool-budget expiry (P1.1): with the
+		* finalization reserve configured every not-admitted call gets a
+		* typed skipped-call error result naming the limiter, so the model
+		* (and the transcript) sees exactly which calls never executed and
+		* the summary turn's history stays well formed (providers reject
+		* tool calls without matching results). Without the reserve the
+		* tail stays unanswered, byte-identical to before.
+		*/
+		const closeSkippedTail = (skippedCalls, limiter) => {
+			if (limits.finalizationReserve === void 0) return;
+			for (const call of skippedCalls) parts.push(errorPart(call, {
+				error: "skipped: the tool budget is exhausted; the call was not executed",
+				limiter,
+				skipped: true
+			}));
+		};
 		for (const [index, call] of calls.entries()) {
-			if (limits.maxToolCalls !== void 0 && toolCallsUsed >= limits.maxToolCalls) return {
-				parts,
-				limitHit: true
-			};
-			if (guard !== void 0 && guard.unitsExhausted()) return {
-				parts,
-				limitHit: true
-			};
+			if (limits.maxToolCalls !== void 0 && toolCallsUsed >= limits.maxToolCalls) {
+				closeSkippedTail(calls.slice(index), "maxToolCalls");
+				return {
+					parts,
+					limitHit: true,
+					limiter: "maxToolCalls",
+					skipped: calls.length - index
+				};
+			}
+			if (guard !== void 0 && guard.unitsExhausted()) {
+				closeSkippedTail(calls.slice(index), "toolUnits");
+				return {
+					parts,
+					limitHit: true,
+					limiter: "toolUnits",
+					skipped: calls.length - index
+				};
+			}
 			const def = runtime.defs.find((candidate) => candidate.name === call.name);
 			events?.emit({
 				type: "tool:start",
@@ -10863,7 +10917,7 @@ async function runAgent(options) {
 			if (record.isError === true) part.isError = true;
 			return part;
 		});
-		const { parts, limitHit, escalated, finished, guardTrip } = await runToolCalls([restored.pending.awaiting, ...restored.pending.remaining], priorParts);
+		const { parts, limitHit, escalated, finished, guardTrip, limiter, skipped } = await runToolCalls([restored.pending.awaiting, ...restored.pending.remaining], priorParts);
 		if (parts.length > 0) messages.push({
 			role: "tool",
 			parts
@@ -10884,6 +10938,16 @@ async function runAgent(options) {
 					retryable: false
 				};
 				errorMessage = guard.describeTrip();
+			} else if (limiter !== void 0 && limits.finalizationReserve !== void 0) {
+				agentError = {
+					kind: "terminal",
+					retryable: false
+				};
+				errorMessage = `tool budget exhausted: ${toolBudgetDetail(limiter)}; skipped tool calls: ${String(skipped ?? 0)}`;
+				reserveRequest = {
+					limiter,
+					skipped: skipped ?? 0
+				};
 			}
 		} else {
 			maybePushBudgetNotice();
@@ -11285,7 +11349,7 @@ async function runAgent(options) {
 		}
 		if (options.tools !== void 0 && outcome.turn.toolCalls.length > 0) {
 			noProgress.recordTurn({ toolCalls: outcome.turn.toolCalls.length });
-			const { parts, limitHit, escalated, finished, guardTrip } = await runToolCalls(outcome.turn.toolCalls, []);
+			const { parts, limitHit, escalated, finished, guardTrip, limiter, skipped } = await runToolCalls(outcome.turn.toolCalls, []);
 			if (parts.length > 0) messages.push({
 				role: "tool",
 				parts
@@ -11310,6 +11374,16 @@ async function runAgent(options) {
 						retryable: false
 					};
 					errorMessage = guard.describeTrip();
+				} else if (limiter !== void 0 && limits.finalizationReserve !== void 0) {
+					agentError = {
+						kind: "terminal",
+						retryable: false
+					};
+					errorMessage = `tool budget exhausted: ${toolBudgetDetail(limiter)}; skipped tool calls: ${String(skipped ?? 0)}`;
+					reserveRequest = {
+						limiter,
+						skipped: skipped ?? 0
+					};
 				}
 				break;
 			}
@@ -11495,6 +11569,110 @@ async function runAgent(options) {
 		await saveBoundary();
 		continue loop;
 	}
+	if (status === "limit" && reserveRequest !== void 0) {
+		const { limiter, skipped } = reserveRequest;
+		let proceed = true;
+		try {
+			options.budget?.beforeTurn();
+		} catch {
+			events?.emit({
+				type: "log",
+				level: "warn",
+				msg: "the finalization reserve turn was skipped: the budget blocks further turns"
+			});
+			proceed = false;
+		}
+		if (proceed) {
+			turns += 1;
+			const reserveMessages = [...messages, {
+				role: "user",
+				parts: [{
+					type: "text",
+					text: `The tool budget is exhausted (${toolBudgetDetail(limiter)}). Skipped tool calls: ${String(skipped)}; no further tool calls will execute. This is the final turn: produce your best final answer from the evidence already collected.`
+				}]
+			}];
+			let reserveDispatch;
+			try {
+				reserveDispatch = await dispatchPhase({
+					role: primaryRole,
+					chain: loopChain,
+					cursor: loopCursor,
+					requestFor: (target) => {
+						let req = buildRequest(target.resolved, projectHistory(reserveMessages, providerOf(target.adapter)), limits, options.tools?.contracts);
+						if (options.schema !== void 0 && options.canonicalSchema !== void 0 && !separateExtract) req = applyStructuredOutputTier(req, rideTierFor(target), options.canonicalSchema);
+						if (req.tools !== void 0) req = {
+							...req,
+							toolChoice: "none"
+						};
+						const reserveMax = limits.finalizationReserve?.maxOutputTokens;
+						if (reserveMax !== void 0) req = {
+							...req,
+							maxOutputTokens: Math.min(req.maxOutputTokens ?? reserveMax, reserveMax)
+						};
+						return applyOutputBudget(req, target, options.budget);
+					},
+					streamOptionsFor: (target) => {
+						const reserveStreamOptions = {
+							idleTimeoutMs: limits.streamIdleTimeoutMs,
+							signals: options.signal === void 0 ? [] : [options.signal],
+							onUsage: (delta) => options.budget?.onUsage(delta, target.resolved.ref)
+						};
+						if (options.budget?.signal !== void 0) reserveStreamOptions.budgetSignal = options.budget.signal;
+						if (options.stream === true) reserveStreamOptions.onDelta = (delta) => events?.emit({
+							type: "agent:stream",
+							delta
+						});
+						return reserveStreamOptions;
+					}
+				});
+			} catch (thrown) {
+				if (!(thrown instanceof BudgetExhaustedError)) throw thrown;
+				events?.emit({
+					type: "log",
+					level: "warn",
+					msg: `the finalization reserve turn was skipped: ${thrown.message}`
+				});
+			}
+			if (reserveDispatch !== void 0) {
+				const { outcome, target: reserveTarget } = reserveDispatch;
+				servedBy = reserveTarget.resolved.ref;
+				usageApprox = usageApprox || outcome.usageApprox;
+				messages.push(assistantMsg(outcome.turn, liftRetainedParts(outcome.providerMetadata, reserveTarget.adapter)));
+				if (invariantViolation !== void 0) {
+					status = "error";
+					agentError = {
+						kind: "transport",
+						retryable: false
+					};
+					errorMessage = invariantViolation;
+				} else if (outcome.aborted === "external") status = "cancelled";
+				else if (outcome.aborted === "budget") {
+					status = "cancelled";
+					agentError = {
+						kind: "budget",
+						retryable: false
+					};
+				} else {
+					await saveBoundary();
+					if (outcome.wireError !== void 0 || outcome.aborted === "idle") events?.emit({
+						type: "log",
+						level: "warn",
+						msg: "the finalization reserve turn failed; the limit terminal stands" + (outcome.wireError === void 0 ? " (stream idle timeout)" : ` (${outcome.wireError.message})`)
+					});
+					else if (options.schema === void 0) {
+						const summary = outcome.turn.text;
+						if (summary.trim() !== "") output = summary;
+					} else if (!separateExtract && options.canonicalSchema !== void 0) {
+						const candidate = extractCandidate(outcome.turn, rideTierFor(reserveTarget));
+						if (candidate !== void 0) {
+							const validation = await validateSchemaSpec(options.schema, candidate.raw);
+							if (validation.valid) output = validation.value;
+						}
+					}
+				}
+			}
+		}
+	}
 	endPhase(loopPhase, phaseOutcome(), servedBy);
 	if (status === "ok" && !finishedViaTool && options.finalize !== void 0) {
 		const finalizeResolved = options.finalize.resolved;
@@ -14209,7 +14387,7 @@ function createCtx(internals, rootWorkflow) {
 			transcriptRef: result.transcriptRef
 		};
 		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.output !== null && (result.status === "ok" || result.status === "limit")) terminalPatch.value = result.output;
 		if (result.error !== void 0) terminalPatch.error = agentErrorToWire(result.error, result.errorMessage ?? `agent terminated with status ${result.status}`);
 		const resultUsageApprox = result.usageApprox === true;
 		if (resultUsageApprox) terminalPatch.usageApprox = true;

package/package.json

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