@rulvar/core 1.222.0 → 1.224.0

package/dist/index.d.ts

@@ -7623,8 +7623,10 @@ interface RunOptions {
   * used to be per-invocation and unrecorded, so a resumed segment
   * silently ran without the bound the original invocation declared
   * (the seventeenth comparison benchmark's top FinOps gap). A run
-  * started without the cap stays uncapped for its whole life, and
-  * ResumeOptions deliberately has no field to override it.
+  * started without the cap stays uncapped for its whole life unless
+  * a host changes the posture through the explicit, validated,
+  * journaled ResumeOptions.run override (RV2208); nothing changes it
+  * silently.
   */
   maxInFlightExposureUsd?: number;
   /**
@@ -7637,7 +7639,9 @@ interface RunOptions {
   * and `allowUnpriced` (exact model refs the host KNOWS are free,
   * the explicit exception). Recorded in RunMeta at genesis and
   * restored on every resume, the exposure cap's rule (RV1504): a
-  * FinOps posture a resumed segment silently drops is not a posture.
+  * FinOps posture a resumed segment silently drops is not a posture
+  * (and unlike the two ceilings, ResumeOptions.run has no field for
+  * this gate: pricing hygiene is not a per-segment decision).
   * Absent by default: dispatch behavior stays byte identical, and an
   * unpriced model keeps debiting nothing, the documented ceiling
   * hole this mode exists to close.
@@ -7711,6 +7715,27 @@ interface ResumeOptions {
   * meta/blob surfaces remain advisory (the fenced run state RFC).
   */
   lease?: Lease;
+  /**
+  * Ceiling overrides for the resumed segment and the run's remaining
+  * life (RV2208). The RV1504 rule stands: the RunMeta-recorded
+  * posture is what a bare resume restores; this field is the ONE
+  * explicit way to change that posture after genesis. Each supplied
+  * value is validated exactly like its RunOptions counterpart,
+  * applied to this segment's budget, written back by the segment's
+  * first meta write (a LATER bare resume restores the overridden
+  * posture, not the genesis one), and journaled as a
+  * `run_budget_override` decision naming the recorded and applied
+  * values and the settled spend it was judged against. A `budgetUsd`
+  * below the journal's settled spend refuses typed before ownership,
+  * meta, or any append: such a ceiling would exhaust the segment
+  * before its first turn and read like a fresh money death. Absent
+  * fields keep the recorded values; an absent object keeps the
+  * historical behavior byte for byte.
+  */
+  run?: {
+    budgetUsd?: number;
+    maxInFlightExposureUsd?: number;
+  };
 }
 interface ResumeHandle<R> extends RunHandle<R> {
   /** Resolves at settle with the replay accounting. */
@@ -7726,7 +7751,9 @@ interface Engine {
   * A compiled run resumes WITHOUT wf: the engine rehydrates the
   * persisted source pinned by workflowHash; supplying a compiled wf
   * whose source hash differs from the recorded one is a typed
-  * ConfigError (M6-T02).
+  * ConfigError (M6-T02). ResumeOptions.run (RV2208) overrides the
+  * recorded budget ceilings for the run's remaining life, with a
+  * journaled decision and a typed floor at the settled spend.
   */
   resume<A, R>(runId: string, wf?: Workflow<A, R> | CompiledWorkflow, options?: ResumeOptions): ResumeHandle<R>;
   /**

package/dist/index.js

@@ -12719,7 +12719,8 @@ async function runAgent(options) {
 				kind: "budget",
 				retryable: false
 			};
-			errorMessage = thrown instanceof Error ? thrown.message : String(thrown);
+			const lastMessage = messages[messages.length - 1];
+			errorMessage = (grantedRepairTurns > 0 && lastMessage !== void 0 && lastMessage.parts.some((part) => part.type === "tool-result" && part.name === options.terminalTool?.name && part.isError === true) ? "the granted repair turn could not be funded: " : "") + (thrown instanceof Error ? thrown.message : String(thrown));
 			break;
 		}
 		turns += 1;
@@ -24228,8 +24229,32 @@ function makeOrchestratorWorkflow(goal, opts) {
 		try {
 			result = await runtime.runInScope(orchestratorState, () => ctx.agent(orchestratorPrompt(goal, opts?.maxSpawns, promptLines.length === 0 ? void 0 : promptLines), agentOpts));
 		} catch (thrown) {
+			if (thrown instanceof BudgetExhaustedError) {
+				const repairEntryRef = thrown.data?.entryRef;
+				const repairTerminal = typeof repairEntryRef === "number" ? internals.replayer.snapshot().find((entry) => entry.seq === repairEntryRef) : void 0;
+				const repairMessage = repairTerminal?.error?.message ?? "";
+				if (repairMessage.includes("the granted repair turn could not be funded: ")) {
+					const repairDeclineKey = deriverV2.deriveKey({ kind: "orchestrator-repair-grant-declined" });
+					if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === repairDeclineKey)) await internals.replayer.appendSinglePhase({
+						scope: callingState.scope,
+						key: repairDeclineKey,
+						kind: "decision",
+						status: "ok",
+						spanId: internals.spans.mint(callingState.spanId),
+						site: "orchestrator-budget",
+						value: {
+							decisionType: "orchestrator_repair_grant_declined",
+							reason: repairMessage.slice(0, 300),
+							terminalRef: repairTerminal?.seq ?? null,
+							remainingUsd: internals.budget.remainingUsd() ?? null
+						}
+					});
+					throw new FailRunError(`the orchestrator finish could not complete its granted repair: ${repairMessage}`, { data: { source: "orchestrator_finish_validation" } });
+				}
+			}
 			const budgetReason = thrown instanceof BudgetExhaustedError ? thrown.data?.reason : void 0;
-			if (budgetReason !== "in-flight-exposure" && budgetReason !== "output-floor") throw thrown;
+			const crossed = thrown instanceof BudgetExhaustedError ? thrown.data : void 0;
+			if (budgetReason !== "in-flight-exposure" && budgetReason !== "output-floor" && crossed?.source !== "root" && crossed?.account !== "run") throw thrown;
 			const exposureKey = deriverV2.deriveKey({ kind: "orchestrator-exposure-fallback" });
 			if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === exposureKey)) await internals.replayer.appendSinglePhase({
 				scope: callingState.scope,
@@ -24240,7 +24265,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 				site: "orchestrator-budget",
 				value: {
 					decisionType: "orchestrator_finalize_fallback",
-					reason: budgetReason === "output-floor" ? "budget-floor" : "exposure-abort",
+					reason: budgetReason === "output-floor" ? "budget-floor" : budgetReason === "in-flight-exposure" ? "exposure-abort" : "budget-ceiling",
 					turnsUsed: 0,
 					foldParams: {
 						planHash: "",
@@ -26516,8 +26541,8 @@ function createEngine(options) {
 		});
 		const rootSpanId = spans.mint();
 		let budgetSeed;
-		const ceilingUsd = opts?.budgetUsd ?? resumeCtx?.budgetUsd;
-		const exposureCapUsd = opts?.maxInFlightExposureUsd ?? resumeCtx?.maxInFlightExposureUsd;
+		const ceilingUsd = opts?.budgetUsd ?? resumeCtx?.budgetOverride?.budgetUsd ?? resumeCtx?.budgetUsd;
+		const exposureCapUsd = opts?.maxInFlightExposureUsd ?? resumeCtx?.budgetOverride?.maxInFlightExposureUsd ?? resumeCtx?.maxInFlightExposureUsd;
 		const strictPricing = opts?.strictPricing === void 0 ? resumeCtx?.strictPricing : opts.strictPricing === true ? {} : opts.strictPricing === false ? void 0 : {
 			...opts.strictPricing.maxRatesAgeDays === void 0 ? {} : { maxRatesAgeDays: opts.strictPricing.maxRatesAgeDays },
 			...opts.strictPricing.allowUnpriced === void 0 ? {} : { allowUnpriced: [...opts.strictPricing.allowUnpriced] }
@@ -26565,6 +26590,8 @@ function createEngine(options) {
 				agentsSpawned: prior.agentsSpawned,
 				accounts: accountSpendFromJournal(replayer.snapshot(), priorPriceUsd)
 			};
+			const overrideCeilingUsd = resumeCtx.budgetOverride?.budgetUsd;
+			if (overrideCeilingUsd !== void 0 && budgetSeed.usd > overrideCeilingUsd) throw new ConfigError(`ResumeOptions.run.budgetUsd ${String(overrideCeilingUsd)} is below the ${budgetSeed.usd.toFixed(4)} USD the journal already records as settled spend; a ceiling below spent exhausts the resumed segment before its first turn. Pass a value at or above the recorded spend, or resume without the override`);
 		}
 		const controller = new AbortController();
 		let cancelReason;
@@ -26760,6 +26787,34 @@ function createEngine(options) {
 			let wireError;
 			let pending = [];
 			if (compiled !== void 0 && resumeCtx?.strict !== true) await transcripts.put(workflowSourceRef(runId), new TextEncoder().encode(compiled.source), segmentLease.current);
+			if (resumeCtx?.budgetOverride !== void 0 && resumeCtx.strict !== true) {
+				const override = resumeCtx.budgetOverride;
+				await replayer.appendSinglePhase({
+					scope: "",
+					key: deriverV2.deriveKey({
+						kind: "run-budget-override",
+						segment: segmentsBefore + 1
+					}),
+					kind: "decision",
+					status: "ok",
+					spanId: rootSpanId,
+					site: "run-budget-override",
+					value: {
+						decisionType: "run_budget_override",
+						source: "resume-options",
+						segment: segmentsBefore + 1,
+						...override.budgetUsd === void 0 ? {} : { budgetUsd: {
+							recorded: resumeCtx.budgetUsd ?? null,
+							applied: override.budgetUsd
+						} },
+						...override.maxInFlightExposureUsd === void 0 ? {} : { maxInFlightExposureUsd: {
+							recorded: resumeCtx.maxInFlightExposureUsd ?? null,
+							applied: override.maxInFlightExposureUsd
+						} },
+						...budgetSeed === void 0 ? {} : { settledSpendUsd: budgetSeed.usd }
+					}
+				});
+			}
 			await putMeta("running");
 			bus.emit({
 				type: "run:start",
@@ -27004,6 +27059,8 @@ function createEngine(options) {
 			previewResolve = resolve;
 		});
 		const handlePromise = (async () => {
+			if (resumeOptions?.run?.budgetUsd !== void 0) requireNonNegativeNumber(resumeOptions.run.budgetUsd, "ResumeOptions.run.budgetUsd");
+			if (resumeOptions?.run?.maxInFlightExposureUsd !== void 0) requireNonNegativeNumber(resumeOptions.run.maxInFlightExposureUsd, "ResumeOptions.run.maxInFlightExposureUsd");
 			const meta = await readRunMeta(journal, runId);
 			let supplied = wf;
 			if (supplied === void 0 && meta?.workflowSourceRef === void 0) {
@@ -27045,12 +27102,18 @@ function createEngine(options) {
 				code: "RULVAR_LEGACY_CACHE_SEMANTICS",
 				type: "RulvarWarning"
 			});
+			const runOverride = resumeOptions?.run;
+			const budgetOverride = runOverride === void 0 || runOverride.budgetUsd === void 0 && runOverride.maxInFlightExposureUsd === void 0 ? void 0 : {
+				...runOverride.budgetUsd === void 0 ? {} : { budgetUsd: runOverride.budgetUsd },
+				...runOverride.maxInFlightExposureUsd === void 0 ? {} : { maxInFlightExposureUsd: runOverride.maxInFlightExposureUsd }
+			};
 			return run(bound, resumeOptions?.args, void 0, {
 				runId,
 				priorEntries,
 				strict: resumeOptions?.dryRun ?? false,
 				invalidate: resumeOptions?.invalidate ?? [],
 				...resumeOptions?.lease === void 0 ? {} : { lease: resumeOptions.lease },
+				...budgetOverride === void 0 ? {} : { budgetOverride },
 				...typeof meta?.budgetUsd === "number" ? { budgetUsd: meta.budgetUsd } : {},
 				...typeof meta?.maxInFlightExposureUsd === "number" ? { maxInFlightExposureUsd: meta.maxInFlightExposureUsd } : {},
 				...typeof meta?.strictPricing === "object" && meta.strictPricing !== null ? { strictPricing: meta.strictPricing } : {},

package/package.json

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