@rulvar/core 1.92.0 → 1.93.0

package/dist/index.d.ts

@@ -4110,6 +4110,24 @@ interface UsageLimits {
     costs?: Record<string, number>;
   };
   /**
+  * The mid-batch checkpoint boundary (RV408, the eighth-experiment
+  * review): checkpoints normally write once per COMPLETED tool turn,
+  * so a kill inside one large parallel batch re-pays every executed
+  * call of that batch on resume; with the whole executed-call budget
+  * fitting into a single batch (the `tool-cap-before-checkpoint`
+  * preflight warning), the re-paid window is the entire budget. Set to
+  * K to bound it: after every K EXECUTED calls within a batch the loop
+  * durably writes the same pending state the ask suspension already
+  * checkpoints (the executed prefix verbatim, the next call, the
+  * remaining tail), so a resume reuses the prefix and re-runs at most
+  * the calls since the last boundary. Denied and skipped calls do not
+  * advance the cadence, and the batch tail writes no extra boundary
+  * (the turn checkpoint follows immediately). Off by default: the
+  * boundary writes extra transcript blobs, and enabling it changes no
+  * journal bytes and no model requests, only the checkpoint cadence.
+  */
+  checkpointEveryToolCalls?: 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
@@ -4191,6 +4209,8 @@ interface EffectiveUsageLimits {
     max: number;
     costs?: Record<string, number>;
   };
+  /** RV408 mid-batch checkpoint cadence; absent = per-turn only. */
+  checkpointEveryToolCalls?: number;
   finalizationReserve?: {
     maxOutputTokens?: number;
   };

package/dist/index.js

@@ -9122,6 +9122,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 checkpointEveryToolCalls = pick("checkpointEveryToolCalls");
+	if (checkpointEveryToolCalls !== void 0) merged.checkpointEveryToolCalls = checkpointEveryToolCalls;
 	const finalizationReserve = pick("finalizationReserve");
 	if (finalizationReserve !== void 0) merged.finalizationReserve = finalizationReserve;
 	const toolBudgetExtension = pick("toolBudgetExtension");
@@ -9167,6 +9169,7 @@ function validateUsageLimits(limits, site) {
 			for (const [name, cost] of Object.entries(costs)) requireNonNegativeInteger(cost, `${site}.toolUnits.costs['${name}']`);
 		}
 	}
+	if (limits.checkpointEveryToolCalls !== void 0) requirePositiveInteger(limits.checkpointEveryToolCalls, `${site}.checkpointEveryToolCalls`);
 	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? }`);
@@ -11068,6 +11071,7 @@ async function runAgent(options) {
 			}));
 		};
 		let terminalAdmitted = false;
+		let executedSinceBoundary = 0;
 		for (const [index, call] of calls.entries()) {
 			const expiryOf = () => {
 				const cap = effectiveMaxToolCalls();
@@ -11319,6 +11323,21 @@ async function runAgent(options) {
 					guardTrip: true
 				};
 			}
+			executedSinceBoundary += 1;
+			const boundaryCadence = limits.checkpointEveryToolCalls;
+			const next = calls[index + 1];
+			if (boundaryCadence !== void 0 && executedSinceBoundary >= boundaryCadence && next !== void 0) {
+				executedSinceBoundary = 0;
+				await saveBoundary({
+					executed: toPendingRecords(parts),
+					awaiting: {
+						id: next.id,
+						name: next.name,
+						args: next.args
+					},
+					remaining: calls.slice(index + 2)
+				});
+			}
 		}
 		maybeMarkWindowEntry();
 		return {
@@ -18767,10 +18786,10 @@ function preflightEstimate(input) {
 				spawn: label
 			});
 		}
-		if (executedToolCallCeiling !== null && executedToolCallCeiling > 0 && caps?.supportsParallelTools === true) say({
+		if (executedToolCallCeiling !== null && executedToolCallCeiling > 0 && caps?.supportsParallelTools === true && (limits.checkpointEveryToolCalls === void 0 || limits.checkpointEveryToolCalls >= executedToolCallCeiling)) say({
 			severity: "warning",
 			code: "tool-cap-before-checkpoint",
-			message: `spawn '${label}': the whole executed-call budget (${String(executedToolCallCeiling)} calls) fits into one parallel tool batch, and checkpoints write once per completed tool turn: the cap can be reached before any checkpoint exists, and a kill mid-batch re-pays every executed call on resume`,
+			message: `spawn '${label}': the whole executed-call budget (${String(executedToolCallCeiling)} calls) fits into one parallel tool batch, and checkpoints write once per completed tool turn: the cap can be reached before any checkpoint exists, and a kill mid-batch re-pays every executed call on resume; bound the window with limits.checkpointEveryToolCalls (RV408)`,
 			spawn: label
 		});
 		if (limits.toolBudgetExtension !== void 0) if (limits.maxToolCalls === void 0) say({

package/package.json

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