@rulvar/core 1.101.0 → 1.102.0

package/dist/index.d.ts

@@ -4719,26 +4719,47 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   * already promised the raised cap), never re-admitted or re-announced,
   * and a restored window entry keeps the summary's
   * finalizationWindowEntered truthful even when a later grant moved the
-  * counts back out of the window. The hooks are fire-and-forget from
-  * the loop's view; pressure notices stay events and are never
-  * journaled. Absent, the loop is byte-identical to before.
+  * counts back out of the window.
+  *
+  * Both hooks are AWAITED before the thing they authorize becomes
+  * observable (RV601): a grant lifts no expiry and queues no notice
+  * until its decision is durable, and the window regime binds no call
+  * until its entry is. A rejected append therefore leaves the grant
+  * unissued and the entry unrecorded, and the rejection propagates
+  * exactly like a failed boundary checkpoint rather than being
+  * swallowed. Pressure notices stay events and are never journaled.
+  * Absent, the loop is byte-identical to before.
   */
   toolBudgetDurability?: {
     restored?: {
       extensionsGranted: number;
       finalizationWindowEntered: boolean;
+      /**
+      * The effective cap the journaled grant announced (RV602). It
+      * anchors the resumed ceiling, because the live `maxToolCalls`
+      * and `increment` are not part of the dispatch identity and may
+      * legitimately drift between segments: without the anchor the two
+      * recovery paths (pure replay, which reads the journal, and live
+      * resume, which recomputed) disagreed, and a promise already made
+      * to the model could be silently revoked. Validated as a
+      * persistent inlet: a non-integer, or one below the base cap, is
+      * ignored with a warning, leaving the count derivation as the
+      * floor. Grants taken AFTER the restore point still measure the
+      * current increment from this anchor.
+      */
+      cap?: number;
     };
     onExtensionGrant?: (grant: {
       grant: number;
       maxExtensions: number;
       toolCallsUsed: number;
       cap: number;
-    }) => void;
+    }) => Promise<void>;
     onWindowEntry?: (entry: {
       remaining: number;
       reserveCalls: number;
       budget: FinalizationWindowBudget;
-    }) => void;
+    }) => Promise<void>;
   };
   /** Emits agent:stream deltas when true (telemetry only). */
   stream?: boolean;

package/dist/index.js

@@ -10927,7 +10927,17 @@ async function runAgent(options) {
 	let extensionGrants = 0;
 	let extensionEvidenceAtLastGrant = 0;
 	const pendingExtensionNotices = [];
-	const effectiveMaxToolCalls = () => limits.maxToolCalls === void 0 ? void 0 : extension === void 0 ? limits.maxToolCalls : limits.maxToolCalls + extensionGrants * extension.increment;
+	/**
+	* The ceiling the effective cap is measured from (RV602). The base cap
+	* normally, so a fresh loop is byte-identical arithmetic; the journaled
+	* cap of the restored grant when a resume carried one, so drifting live
+	* limits cannot revoke a raise the journal already recorded. Grants
+	* taken after the restore point count from here at the CURRENT
+	* increment, which is the live policy doing what it should.
+	*/
+	let capBase = limits.maxToolCalls;
+	let grantsOverCapBase = 0;
+	const effectiveMaxToolCalls = () => capBase === void 0 ? void 0 : extension === void 0 ? capBase : capBase + grantsOverCapBase * extension.increment;
 	/** The limiter that ended the loop; rides the RV304 pressure snapshot. */
 	let limitLimiter;
 	/** True once the finalization reserve summary turn actually ran. */
@@ -10979,7 +10989,7 @@ async function runAgent(options) {
 	* join the history.
 	*/
 	const tryToolBudgetGrant = () => {
-		if (extension === void 0 || limits.maxToolCalls === void 0) return false;
+		if (extension === void 0 || limits.maxToolCalls === void 0 || capBase === void 0) return false;
 		if (extensionGrants >= extension.maxExtensions) return false;
 		if (extension.requireNewEvidence !== false) {
 			if ((guard?.evidenceCount() ?? 0) <= extensionEvidenceAtLastGrant) return false;
@@ -10989,22 +10999,28 @@ async function runAgent(options) {
 			const floor = extension.minHeadroomUsd ?? 0;
 			if (floor > 0 ? remaining < floor : remaining <= 0) return false;
 		}
-		extensionGrants += 1;
-		extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
-		const cap = limits.maxToolCalls + extensionGrants * extension.increment;
-		options.toolBudgetDurability?.onExtensionGrant?.({
-			grant: extensionGrants,
+		const grant = extensionGrants + 1;
+		const cap = capBase + (grantsOverCapBase + 1) * extension.increment;
+		const commit = () => {
+			extensionGrants = grant;
+			grantsOverCapBase += 1;
+			extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
+			pendingExtensionNotices.push(toolBudgetExtensionNoticeText(grant, extension.maxExtensions, toolCallsUsed, cap));
+			events?.emit({
+				type: "log",
+				level: "info",
+				msg: `tool budget extended (grant ${String(grant)}/${String(extension.maxExtensions)}): maxToolCalls now ${String(cap)}`
+			});
+			return true;
+		};
+		const durable = options.toolBudgetDurability?.onExtensionGrant;
+		if (durable === void 0) return commit();
+		return durable({
+			grant,
 			maxExtensions: extension.maxExtensions,
 			toolCallsUsed,
 			cap
-		});
-		pendingExtensionNotices.push(toolBudgetExtensionNoticeText(extensionGrants, extension.maxExtensions, toolCallsUsed, cap));
-		events?.emit({
-			type: "log",
-			level: "info",
-			msg: `tool budget extended (grant ${String(extensionGrants)}/${String(extension.maxExtensions)}): maxToolCalls now ${String(cap)}`
-		});
-		return true;
+		}).then(commit);
 	};
 	const flushExtensionNotices = () => {
 		for (const text of pendingExtensionNotices.splice(0)) messages.push({
@@ -11058,19 +11074,26 @@ async function runAgent(options) {
 		if (finalizationWindow === void 0 || windowNoticeFired) return;
 		const state = windowActive();
 		if (state === void 0) return;
-		windowEntered = true;
-		windowNoticeFired = true;
-		options.toolBudgetDurability?.onWindowEntry?.({
+		const commit = () => {
+			windowEntered = true;
+			windowNoticeFired = true;
+			pendingWindowNotices.push(finalizationWindowNoticeText(state.remaining, finalizationWindow.reserveCalls, state.budget));
+			events?.emit({
+				type: "log",
+				level: "info",
+				msg: `finalization window entered: ${String(state.remaining)} of the reserved final ${String(finalizationWindow.reserveCalls)} ${state.budget} remain`
+			});
+		};
+		const durable = options.toolBudgetDurability?.onWindowEntry;
+		if (durable === void 0) {
+			commit();
+			return;
+		}
+		return durable({
 			remaining: state.remaining,
 			reserveCalls: finalizationWindow.reserveCalls,
 			budget: state.budget
-		});
-		pendingWindowNotices.push(finalizationWindowNoticeText(state.remaining, finalizationWindow.reserveCalls, state.budget));
-		events?.emit({
-			type: "log",
-			level: "info",
-			msg: `finalization window entered: ${String(state.remaining)} of the reserved final ${String(finalizationWindow.reserveCalls)} ${state.budget} remain`
-		});
+		}).then(commit);
 	};
 	const flushWindowNotices = () => {
 		for (const text of pendingWindowNotices.splice(0)) messages.push({
@@ -11127,6 +11150,7 @@ async function runAgent(options) {
 			extensionGrants = Math.min(extension.maxExtensions, Math.ceil((toolCallsUsed - limits.maxToolCalls) / extension.increment));
 			extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
 		}
+		const derivedCap = limits.maxToolCalls === void 0 || extension === void 0 ? void 0 : limits.maxToolCalls + extensionGrants * extension.increment;
 		const durableRestored = options.toolBudgetDurability?.restored;
 		if (extension !== void 0 && durableRestored !== void 0) {
 			const journaled = Math.min(extension.maxExtensions, durableRestored.extensionsGranted);
@@ -11135,6 +11159,16 @@ async function runAgent(options) {
 				extensionEvidenceAtLastGrant = guard?.evidenceCount() ?? 0;
 			}
 		}
+		grantsOverCapBase = extensionGrants;
+		const journaledCap = durableRestored?.cap;
+		if (journaledCap !== void 0 && limits.maxToolCalls !== void 0 && derivedCap !== void 0) if (Number.isSafeInteger(journaledCap) && journaledCap >= limits.maxToolCalls) {
+			capBase = Math.max(journaledCap, derivedCap);
+			grantsOverCapBase = 0;
+		} else events?.emit({
+			type: "log",
+			level: "warn",
+			msg: `restored tool budget cap ${String(journaledCap)} is not an integer at or above the base cap ${String(limits.maxToolCalls)}; ignoring it and deriving from the counts`
+		});
 		if (windowActive() !== void 0 || finalizationWindow !== void 0 && durableRestored?.finalizationWindowEntered === true) {
 			windowEntered = true;
 			windowNoticeFired = true;
@@ -11231,7 +11265,10 @@ async function runAgent(options) {
 				return cap !== void 0 && toolCallsUsed >= cap ? "maxToolCalls" : guard !== void 0 && guard.unitsExhausted() ? "toolUnits" : void 0;
 			};
 			let expiredLimiter = expiryOf();
-			if (expiredLimiter === "maxToolCalls" && call.name !== options.terminalTool?.name && tryToolBudgetGrant()) expiredLimiter = expiryOf();
+			if (expiredLimiter === "maxToolCalls" && call.name !== options.terminalTool?.name) {
+				const attempt = tryToolBudgetGrant();
+				if (typeof attempt === "boolean" ? attempt : await attempt) expiredLimiter = expiryOf();
+			}
 			if (expiredLimiter !== void 0) {
 				const tail = calls.slice(index);
 				const terminalName = options.terminalTool?.name;
@@ -11419,10 +11456,14 @@ async function runAgent(options) {
 				};
 			}
 			if (finalizationWindow !== void 0) {
-				maybeMarkWindowEntry();
+				const entry = maybeMarkWindowEntry();
+				if (entry !== void 0) await entry;
 				let windowState = windowActive();
 				if (windowState !== void 0 && !windowAllows(gatedCall.name)) {
-					if (windowState.budget === "tool calls" && extension !== void 0 && windowState.remaining + extension.increment > finalizationWindow.reserveCalls && tryToolBudgetGrant()) windowState = windowActive();
+					if (windowState.budget === "tool calls" && extension !== void 0 && windowState.remaining + extension.increment > finalizationWindow.reserveCalls) {
+						const attempt = tryToolBudgetGrant();
+						if (typeof attempt === "boolean" ? attempt : await attempt) windowState = windowActive();
+					}
 					if (windowState !== void 0 && !windowAllows(gatedCall.name)) {
 						events?.emit({
 							type: "tool:end",
@@ -11492,7 +11533,8 @@ async function runAgent(options) {
 				});
 			}
 		}
-		maybeMarkWindowEntry();
+		const lastEntry = maybeMarkWindowEntry();
+		if (lastEntry !== void 0) await lastEntry;
 		return {
 			parts,
 			limitHit: false
@@ -14847,10 +14889,11 @@ function createCtx(internals, rootWorkflow) {
 			runAgentOptions.toolBudgetDurability = {
 				...durableRestored === void 0 ? {} : { restored: {
 					extensionsGranted: durableRestored.extensionsGranted,
-					finalizationWindowEntered: durableRestored.finalizationWindowEntered
+					finalizationWindowEntered: durableRestored.finalizationWindowEntered,
+					...durableRestored.cap === void 0 ? {} : { cap: durableRestored.cap }
 				} },
-				onExtensionGrant: (grant) => {
-					internals.replayer.appendSinglePhase({
+				onExtensionGrant: async (grant) => {
+					await internals.replayer.appendSinglePhase({
 						scope: state.scope,
 						key: "",
 						kind: "decision",
@@ -14863,8 +14906,8 @@ function createCtx(internals, rootWorkflow) {
 						}
 					});
 				},
-				onWindowEntry: (entry) => {
-					internals.replayer.appendSinglePhase({
+				onWindowEntry: async (entry) => {
+					await internals.replayer.appendSinglePhase({
 						scope: state.scope,
 						key: "",
 						kind: "decision",
@@ -18431,13 +18474,30 @@ function makeOrchestratorWorkflow(goal, opts) {
 						}
 					}, callingState.spanId);
 				};
-				const prior = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === skipKey);
-				if (prior !== void 0) {
+				const draftValue = draft ?? null;
+				const draftHash = createHash("sha256").update(jcsSerialize(draftValue), "utf8").digest("hex");
+				const validatorNames = validationSpec.validators.map((validator) => validator.name);
+				/**
+				* A journaled skip is the authority only for the generation and
+				* the draft it judged (RV603). The documented remedy for a
+				* broken contract is to fix it and resume, and a verdict that
+				* outlives its contract defeats exactly that: the run would
+				* settle ok carrying output the CURRENT contract rejects.
+				* Bound by three facts, in descending strength: the contract
+				* identity (the same `contractGenerationCurrent` test the
+				* finish-validation decisions already use), the draft the
+				* verdict actually judged, and the validator names that
+				* rendered it. Entries written before this field existed carry
+				* no draftHash and stay reusable, so journals in flight roll
+				* forward byte for byte.
+				*/
+				const applies = (value) => contractGenerationCurrent(value) && (value.draftHash === void 0 || value.draftHash === draftHash) && (!Array.isArray(value.validators) || JSON.stringify(value.validators) === JSON.stringify(validatorNames));
+				const prior = internals.replayer.snapshot().filter((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === skipKey).at(-1);
+				if (prior !== void 0 && applies(prior.value)) {
 					synthesisSkippedByValidDraft = true;
 					announceSkip(prior.seq);
 					return draft;
 				}
-				const draftValue = draft ?? null;
 				const input = {
 					result: draftValue,
 					text: typeof draftValue === "string" ? draftValue : JSON.stringify(draftValue),
@@ -18467,7 +18527,9 @@ function makeOrchestratorWorkflow(goal, opts) {
 						value: {
 							decisionType: "orchestrator_synthesis_skip",
 							reason: "synthesis_skipped_by_valid_draft",
-							validators: validationSpec.validators.map((validator) => validator.name)
+							validators: validatorNames,
+							...validationSpec.contract === void 0 ? {} : { contractHash: validationSpec.contract.hash },
+							draftHash
 						}
 					});
 					if (orchestratorAccount !== void 0 && (opts?.budget?.synthesisReserveUsd ?? 0) > 0) internals.budget.releaseSynthesisReserve(orchestratorAccount);

package/package.json

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