@rulvar/core 1.220.0 → 1.221.0

package/dist/index.js

@@ -12604,6 +12604,102 @@ async function runAgent(options) {
 		resolved: options.resolved
 	}, ...options.fallbacks ?? []];
 	const loopCursor = { index: 0 };
+	/**
+	* The drained-finalization grant (RV2204, the third parity rerun).
+	* The exposure drain is terminal mid-work: spend only grows, so a
+	* seat refused with no live holder left can never dispatch an
+	* ordinary turn again. The third parity rerun killed three workers
+	* ~30 turns into research with evidence pools of 17 and 22 under a
+	* floor of 24 and a CONFIGURED finalization window: the drain came
+	* before the window, and the window's play needs the very wire the
+	* drain refuses. With `limits.finalizationReserve.maxOutputTokens`
+	* declared, a drained seat that already did work now spends ONE
+	* clamped finalization turn before its typed terminal: the output
+	* clamp shrinks the turn's exposure estimate (the full estimate was
+	* refused; the clamped one prices the summary allowance instead of
+	* the whole per-turn cap), the finalization-window allowlist rides
+	* as the turn's only tools so outstanding record_evidence calls can
+	* land in parallel, and the executed calls persist through the
+	* ordinary tool machinery. Best effort, exactly like the tool-budget
+	* reserve turn: a refusal of even the clamped estimate warns and
+	* keeps the typed drained terminal; a seat with NO completed turns
+	* keeps dying free (the RV2002 zero-cost doctrine: nothing to
+	* summarize, nothing paid).
+	*/
+	let drainFinalizationRan = false;
+	const runDrainFinalization = async (refusal) => {
+		const allow = limits.finalizationWindow?.allow;
+		const allowedTools = allow === void 0 ? void 0 : options.tools?.contracts.filter((contract) => allow.includes(contract.name));
+		const toolsRide = allowedTools !== void 0 && allowedTools.length > 0;
+		const drainMessages = [...messages, {
+			role: "user",
+			parts: [{
+				type: "text",
+				text: `The run's in-flight exposure pool is drained; no further ordinary turns can dispatch (${refusal}). This is your single finalization turn` + (toolsRide ? ": record any outstanding evidence with the allowed tools IN THIS turn (parallel calls), then close" : `: close`) + ` with your best final summary of the work already done.`
+			}]
+		}];
+		let grant;
+		try {
+			grant = await dispatchPhase({
+				role: primaryRole,
+				chain: loopChain,
+				cursor: loopCursor,
+				requestFor: (target) => {
+					let req = buildRequest(target.resolved, projectHistory(drainMessages, providerOf(target.adapter)), limits, toolsRide ? allowedTools : void 0);
+					const reserveMax = limits.finalizationReserve?.maxOutputTokens;
+					if (reserveMax !== void 0) req = {
+						...req,
+						maxOutputTokens: Math.min(req.maxOutputTokens ?? reserveMax, reserveMax)
+					};
+					req = applyCachePolicy(req, target, options.cache);
+					return applyOutputBudget(req, target, options.budget);
+				},
+				streamOptionsFor: (target) => {
+					const drainStreamOptions = {
+						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) drainStreamOptions.budgetSignal = options.budget.signal;
+					if (options.stream === true) drainStreamOptions.onDelta = (delta) => events?.emit({
+						type: "agent:stream",
+						delta
+					});
+					return drainStreamOptions;
+				}
+			});
+		} catch (grantThrown) {
+			if (!(grantThrown instanceof BudgetExhaustedError)) throw grantThrown;
+			events?.emit({
+				type: "log",
+				level: "warn",
+				msg: `the drained-finalization turn was skipped: ${grantThrown.message}`
+			});
+			return;
+		}
+		const { outcome: grantOutcome, target: grantTarget } = grant;
+		servedBy = grantTarget.resolved.ref;
+		usageApprox = usageApprox || grantOutcome.usageApprox;
+		messages.push(assistantMsg(grantOutcome.turn, liftRetainedParts(grantOutcome.providerMetadata, grantTarget.adapter)));
+		if (toolsRide && grantOutcome.turn.toolCalls.length > 0) try {
+			await runToolCalls(grantOutcome.turn.toolCalls, []);
+		} catch (toolThrown) {
+			events?.emit({
+				type: "log",
+				level: "warn",
+				msg: `a drained-finalization tool call failed: ${toolThrown instanceof Error ? toolThrown.message : String(toolThrown)}`
+			});
+		}
+		events?.emit({
+			type: "log",
+			level: "info",
+			msg: "the drained seat spent its finalization turn",
+			data: {
+				toolCalls: grantOutcome.turn.toolCalls.length,
+				outputTokens: grantOutcome.usage.outputTokens
+			}
+		});
+	};
 	loop: while (status === "ok" && !finishedViaTool) {
 		if (limits.timeoutMs !== void 0 && now() - startedAt >= limits.timeoutMs) {
 			status = "limit";
@@ -12657,8 +12753,12 @@ async function runAgent(options) {
 			});
 		} catch (thrown) {
 			if (!(thrown instanceof BudgetExhaustedError)) throw thrown;
-			status = "error";
 			const typedReason = thrown.data?.reason;
+			if (typedReason === "exposure-drained" && limits.finalizationReserve !== void 0 && turns > 1 && !drainFinalizationRan) {
+				drainFinalizationRan = true;
+				await runDrainFinalization(thrown.message);
+			}
+			status = "error";
 			agentError = {
 				kind: "budget",
 				retryable: false,
@@ -24792,10 +24892,16 @@ function preflightEstimate(input) {
 				spawn: label
 			});
 		}
-		if (limits.finalizationReserve !== void 0 && limits.maxToolCalls === void 0 && limits.toolUnits === void 0) say({
+		if (limits.finalizationReserve !== void 0 && limits.maxToolCalls === void 0 && limits.toolUnits === void 0 && input.run?.maxInFlightExposureUsd === void 0) say({
 			severity: "warning",
 			code: "inert-finalization-reserve",
-			message: `spawn '${label}' sets finalizationReserve without maxToolCalls or toolUnits: no tool budget limiter exists for it to fire on`,
+			message: `spawn '${label}' sets finalizationReserve without maxToolCalls or toolUnits: no tool budget limiter exists for it to fire on, and no in-flight exposure cap is declared for the drained-finalization grant (RV2204) to spend it at`,
+			spawn: label
+		});
+		if (limits.finalizationWindow !== void 0 && limits.finalizationReserve?.maxOutputTokens === void 0 && input.run?.maxInFlightExposureUsd !== void 0) say({
+			severity: "info",
+			code: "drained-finalization-unfunded",
+			message: `spawn '${label}' declares finalizationWindow under an in-flight exposure cap but no finalizationReserve.maxOutputTokens: a mid-work exposure drain refuses the wire the window needs, and without the reserve's clamped turn the seat dies with its window unplayed (RV2204); declare the reserve to fund one drained-finalization turn`,
 			spawn: label
 		});
 		if (limits.toolBudgetNotices === true && limits.maxToolCalls === void 0) say({

package/package.json

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