@rulvar/core 1.202.0 → 1.204.0

package/dist/index.d.ts

@@ -381,6 +381,14 @@ type AgentError = {
   retryable: boolean;
   retryAfterMs?: number;
   issues?: Issue$1[];
+  /**
+  * The typed refusal marker (RV2002): 'exposure-drained' names a
+  * spawned child refused pre-wire by the in-flight exposure cap with
+  * no live holder left to wait out. Zero provider attempts by
+  * construction, so the seat is cheap to re-spawn; an orchestrator
+  * treats it as a starved seat, never a crashed child.
+  */
+  reason?: "exposure-drained";
 };
 /**
 * Projects an AgentError to its WireError form: code 'agent', with kind,
@@ -2438,7 +2446,8 @@ type AgentEvents = {
 } | {
   type: "budget:exposure-wait";
   agentType: string;
-  label?: string; /** The refused model ref. */
+  label?: string; /** The waiting party: the orchestrate root or a spawned child. */
+  scope?: "root" | "child"; /** The refused model ref. */
   model?: string; /** The refusal arithmetic, verbatim from the typed refusal. */
   capUsd?: number;
   spentUsd?: number;
@@ -5489,12 +5498,19 @@ interface RunAgentOptions<S extends SchemaSpec = JsonSchema> {
   /**
   * The exposure-wait posture (RV1902): an in-flight exposure refusal
   * on this invocation parks until a live hold releases and retries
-  * pre-wire, instead of settling a budget error. Set only by the
-  * orchestrate-owned root dispatches (the coordination loop, the
-  * synthesis invocation, the forced-finish wake), whose settle would
-  * tear down the run its own admitted children are still funding.
-  */
-  exposureWait?: boolean;
+  * pre-wire, instead of settling a budget error. `true` is set only
+  * by the orchestrate-owned root dispatches (the coordination loop,
+  * the synthesis invocation, the forced-finish wake), whose settle
+  * would tear down the run its own admitted children are still
+  * funding. `'child'` (RV2002) rides on orchestrator-spawned
+  * children: the same park-and-retry, but the drained arm (no live
+  * holder left to wait out) dies as the typed cheap
+  * 'exposure-drained' refusal instead of the raw budget error, so
+  * the orchestrator can tell a starved seat apart from a crashed
+  * child and re-spawn it; the third parity rerun terminally killed
+  * three mid-research workers on exactly this path.
+  */
+  exposureWait?: boolean | "child";
   events?: RuntimeEventSink;
   transcript?: {
     mintRef(): string;
@@ -6199,6 +6215,25 @@ declare class RunBudget {
   /** Live dispatch estimates held by reserveTurnExposure (RV711). */
   private inFlightExposureUsd;
   /**
+  * The same live estimates attributed to their holders (RV2001): one
+  * entry per holder scope with a nonzero balance, kept in lockstep
+  * with the scalar above by every acquire and release. The holder is
+  * the agent invocation the dispatch belongs to, so a terminal can
+  * return whatever its agent still holds; entries at zero are removed,
+  * making the map size the live holder count.
+  */
+  private readonly exposureHolds;
+  /**
+  * Live holds taken without a holder attribution (a direct caller of
+  * reserveTurnExposure): counted so the zero-holders snap below knows
+  * when NOTHING is held. Subtraction leaves float residue (three 0.18
+  * releases leave 5.5e-17), and a residue above zero would park the
+  * exposure wait on money nobody holds, the epsilon-scale rebirth of
+  * the very deadlock RV2001 closes; when the last hold of any kind
+  * releases, the scalar snaps to exactly zero.
+  */
+  private unattributedHoldCount;
+  /**
   * Waiters parked on the next exposure release (RV1902): the
   * orchestrate root's dispatch waits out a transient refusal here
   * instead of settling a budget error. Notified (and self-removed)
@@ -6418,7 +6453,37 @@ declare class RunBudget {
   * (committedReserveUsd) stay out of the formula, because a child's
   * lifetime reserve and its own turn exposure would double-count.
   */
-  reserveTurnExposure(servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number): (() => void) | undefined;
+  reserveTurnExposure(servedBy: ModelRef, estimatedInputTokens: number, plannedOutputTokens: number, holderScope?: string): (() => void) | undefined;
+  /**
+  * The one release chokepoint of the exposure scalar (RV2001):
+  * subtracts, snaps to exactly zero when no hold of any kind remains
+  * (float subtraction leaves residue, and a residue would park the
+  * exposure wait on money nobody holds), and wakes the parked
+  * waiters. Spend never shrinks, so releases stay the only wake
+  * source that can turn a refusal into a fit.
+  */
+  private settleExposureRelease;
+  /**
+  * The terminal backstop of the exposure surface (RV2001, the third
+  * parity rerun's quiescence deadlock): EVERY terminal of an agent
+  * invocation (ok, error, exhausted, cancelled) returns whatever live
+  * dispatch estimates that holder still has to the exposure budget.
+  * The attempt settle owns the per-hold closure in a finally, so this
+  * usually finds nothing; the parity crash proved a dispatch path can
+  * die without its closure (three killed children left 0.478 USD of
+  * live estimates parked against the cap forever, and the root's
+  * exposure wait starved on money no live dispatch was holding). A
+  * real release wakes the parked waiters exactly like the closure
+  * does; a holder with nothing held is a free no-op. Returns the USD
+  * actually returned.
+  */
+  releaseExposureHolder(holderScope: string): number;
+  /**
+  * Live exposure holders: agents with a nonzero held balance (RV2001).
+  * Zero with live waiters means nothing can ever release, the drained
+  * signal the quiescence machinery keys on.
+  */
+  get liveExposureHolderCount(): number;
   /** Live in-flight exposure currently held by open dispatches (RV1902). */
   get liveExposureUsd(): number;
   /**

package/dist/index.js

@@ -413,6 +413,7 @@ var DeterminismError = class extends RulvarError {
 function agentErrorToWire(error, message) {
 	const data = { kind: error.kind };
 	if (error.retryAfterMs !== void 0) data.retryAfterMs = error.retryAfterMs;
+	if (error.reason !== void 0) data.reason = error.reason;
 	if (error.issues !== void 0) data.issues = error.issues.map((issue) => {
 		const out = { message: issue.message };
 		if (issue.path !== void 0) out.path = issue.path.map((segment) => {
@@ -12368,20 +12369,30 @@ async function runAgent(options) {
 					} catch (thrown) {
 						const refusalData = thrown instanceof BudgetExhaustedError ? thrown.data : void 0;
 						const awaitRelease = options.budget?.awaitExposureRelease;
-						if (options.exposureWait !== true || refusalData?.reason !== "in-flight-exposure" || awaitRelease === void 0) throw thrown;
+						if (options.exposureWait !== true && options.exposureWait !== "child" || refusalData?.reason !== "in-flight-exposure" || awaitRelease === void 0) throw thrown;
+						const waitScope = options.exposureWait === "child" ? "child" : "root";
 						const willWait = (options.budget?.liveExposureUsd?.() ?? 0) > 0;
 						events?.emit({
 							type: "budget:exposure-wait",
 							agentType,
 							label: options.label,
 							model: target.resolved.ref,
+							scope: waitScope,
 							...typeof refusalData.capUsd === "number" ? { capUsd: refusalData.capUsd } : {},
 							...typeof refusalData.spentUsd === "number" ? { spentUsd: refusalData.spentUsd } : {},
 							...typeof refusalData.inFlightUsd === "number" ? { inFlightUsd: refusalData.inFlightUsd } : {},
 							...typeof refusalData.estimateUsd === "number" ? { estimateUsd: refusalData.estimateUsd } : {},
 							willWait
 						});
-						if (!willWait) throw thrown;
+						if (!willWait) {
+							if (waitScope === "child") throw new BudgetExhaustedError(`exposure pool drained for the spawned child: ${thrown instanceof Error ? thrown.message : String(thrown)}`, { data: {
+								reason: "exposure-drained",
+								...typeof refusalData.capUsd === "number" ? { capUsd: refusalData.capUsd } : {},
+								...typeof refusalData.spentUsd === "number" ? { spentUsd: refusalData.spentUsd } : {},
+								...typeof refusalData.estimateUsd === "number" ? { estimateUsd: refusalData.estimateUsd } : {}
+							} });
+							throw thrown;
+						}
 						const waitSignals = [options.signal, options.budget?.signal].filter((candidate) => candidate !== void 0);
 						await awaitRelease(waitSignals.length === 0 ? void 0 : AbortSignal.any(waitSignals));
 						continue;
@@ -12604,7 +12615,8 @@ async function runAgent(options) {
 			status = "error";
 			agentError = {
 				kind: "budget",
-				retryable: false
+				retryable: false,
+				...thrown.data?.reason === "exposure-drained" ? { reason: "exposure-drained" } : {}
 			};
 			errorMessage = thrown.message;
 			break;
@@ -13523,6 +13535,25 @@ var RunBudget = class {
 	/** Live dispatch estimates held by reserveTurnExposure (RV711). */
 	inFlightExposureUsd = 0;
 	/**
+	* The same live estimates attributed to their holders (RV2001): one
+	* entry per holder scope with a nonzero balance, kept in lockstep
+	* with the scalar above by every acquire and release. The holder is
+	* the agent invocation the dispatch belongs to, so a terminal can
+	* return whatever its agent still holds; entries at zero are removed,
+	* making the map size the live holder count.
+	*/
+	exposureHolds = /* @__PURE__ */ new Map();
+	/**
+	* Live holds taken without a holder attribution (a direct caller of
+	* reserveTurnExposure): counted so the zero-holders snap below knows
+	* when NOTHING is held. Subtraction leaves float residue (three 0.18
+	* releases leave 5.5e-17), and a residue above zero would park the
+	* exposure wait on money nobody holds, the epsilon-scale rebirth of
+	* the very deadlock RV2001 closes; when the last hold of any kind
+	* releases, the scalar snaps to exactly zero.
+	*/
+	unattributedHoldCount = 0;
+	/**
 	* Waiters parked on the next exposure release (RV1902): the
 	* orchestrate root's dispatch waits out a transient refusal here
 	* instead of settling a budget error. Notified (and self-removed)
@@ -13920,7 +13951,7 @@ var RunBudget = class {
 	* (committedReserveUsd) stay out of the formula, because a child's
 	* lifetime reserve and its own turn exposure would double-count.
 	*/
-	reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens) {
+	reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens, holderScope) {
 		const cap = this.maxInFlightExposureUsd;
 		if (cap === void 0) return;
 		const pricing = this.pricingOf?.(servedBy);
@@ -13941,14 +13972,69 @@ var RunBudget = class {
 			estimateUsd
 		} });
 		this.inFlightExposureUsd += estimateUsd;
+		if (estimateUsd > 0) if (holderScope === void 0) this.unattributedHoldCount += 1;
+		else this.exposureHolds.set(holderScope, (this.exposureHolds.get(holderScope) ?? 0) + estimateUsd);
 		let released = false;
 		return () => {
 			if (released) return;
 			released = true;
-			this.inFlightExposureUsd = Math.max(0, this.inFlightExposureUsd - estimateUsd);
-			for (const waiter of [...this.exposureWaiters]) waiter();
+			let amount = estimateUsd;
+			if (estimateUsd > 0) if (holderScope === void 0) this.unattributedHoldCount = Math.max(0, this.unattributedHoldCount - 1);
+			else {
+				const held = this.exposureHolds.get(holderScope) ?? 0;
+				amount = Math.min(amount, held);
+				const next = held - amount;
+				if (next <= 0) this.exposureHolds.delete(holderScope);
+				else this.exposureHolds.set(holderScope, next);
+			}
+			this.settleExposureRelease(amount);
 		};
 	}
+	/**
+	* The one release chokepoint of the exposure scalar (RV2001):
+	* subtracts, snaps to exactly zero when no hold of any kind remains
+	* (float subtraction leaves residue, and a residue would park the
+	* exposure wait on money nobody holds), and wakes the parked
+	* waiters. Spend never shrinks, so releases stay the only wake
+	* source that can turn a refusal into a fit.
+	*/
+	settleExposureRelease(amountUsd) {
+		this.inFlightExposureUsd = Math.max(0, this.inFlightExposureUsd - amountUsd);
+		if (this.exposureHolds.size === 0 && this.unattributedHoldCount === 0) this.inFlightExposureUsd = 0;
+		for (const waiter of [...this.exposureWaiters]) waiter();
+	}
+	/**
+	* The terminal backstop of the exposure surface (RV2001, the third
+	* parity rerun's quiescence deadlock): EVERY terminal of an agent
+	* invocation (ok, error, exhausted, cancelled) returns whatever live
+	* dispatch estimates that holder still has to the exposure budget.
+	* The attempt settle owns the per-hold closure in a finally, so this
+	* usually finds nothing; the parity crash proved a dispatch path can
+	* die without its closure (three killed children left 0.478 USD of
+	* live estimates parked against the cap forever, and the root's
+	* exposure wait starved on money no live dispatch was holding). A
+	* real release wakes the parked waiters exactly like the closure
+	* does; a holder with nothing held is a free no-op. Returns the USD
+	* actually returned.
+	*/
+	releaseExposureHolder(holderScope) {
+		const held = this.exposureHolds.get(holderScope) ?? 0;
+		if (held <= 0) {
+			this.exposureHolds.delete(holderScope);
+			return 0;
+		}
+		this.exposureHolds.delete(holderScope);
+		this.settleExposureRelease(held);
+		return held;
+	}
+	/**
+	* Live exposure holders: agents with a nonzero held balance (RV2001).
+	* Zero with live waiters means nothing can ever release, the drained
+	* signal the quiescence machinery keys on.
+	*/
+	get liveExposureHolderCount() {
+		return this.exposureHolds.size;
+	}
 	/** Live in-flight exposure currently held by open dispatches (RV1902). */
 	get liveExposureUsd() {
 		return this.inFlightExposureUsd;
@@ -16399,9 +16485,16 @@ const kFinalizeReserve = Symbol("rulvar.finalizeReserve");
 * benchmark's recovery arm died exactly there: the refusal is transient
 * by contract (budgets guide), but the refused agent was the workflow's
 * coordinating root, so its settle tore down the whole run while four
-* admitted children were still finalizing. Never part of the public
-* AgentOpts surface; plain agents keep the documented settle-as-budget-
-* error behavior, because their caller can catch and decide.
+* admitted children were still finalizing. The 'child' flavor (RV2002)
+* rides on orchestrator-spawned children (spawn_agent and
+* parallel_agents): the same park-and-retry, but a DRAINED refusal
+* (no live holder left to wait out) dies as the typed cheap
+* 'exposure-drained' child refusal the orchestrator can tell apart
+* from a crash and re-spawn, instead of the root's forced-finish
+* partial; the third parity rerun killed three mid-research workers
+* on exactly this path. Never part of the public AgentOpts surface;
+* plain agents keep the documented settle-as-budget-error behavior,
+* because their caller can catch and decide.
 */
 const kExposureWait = Symbol("rulvar.exposureWait");
 /** Typed accessor used by the in-package consumers. */
@@ -17761,7 +17854,7 @@ function createCtx(internals, rootWorkflow) {
 				remainingUsd: () => internals.budget.remainingUsd(budgetAccount),
 				...internals.budget.strictPricing === void 0 ? {} : { assertPricedDispatch: (servedBy) => internals.budget.assertPricedDispatch(servedBy) },
 				...internals.budget.maxInFlightExposureUsd === void 0 ? {} : {
-					admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens),
+					admitTurnExposure: (servedBy, estimatedInputTokens, plannedOutputTokens) => internals.budget.reserveTurnExposure(servedBy, estimatedInputTokens, plannedOutputTokens, `agent:${running.seq}`),
 					awaitExposureRelease: (signal) => internals.budget.awaitExposureRelease(signal),
 					liveExposureUsd: () => internals.budget.liveExposureUsd
 				},
@@ -17778,7 +17871,10 @@ function createCtx(internals, rootWorkflow) {
 		if (escalation !== void 0) runAgentOptions.escalation = { minSpendUsd: escalation.minSpendUsd ?? 0 };
 		const terminalTool = opts[kTerminalTool];
 		if (terminalTool !== void 0) runAgentOptions.terminalTool = terminalTool;
-		if (opts[kExposureWait] === true) runAgentOptions.exposureWait = true;
+		{
+			const exposureWait = opts[kExposureWait];
+			if (exposureWait === true || exposureWait === "child") runAgentOptions.exposureWait = exposureWait;
+		}
 		runAgentOptions.checkpoint = checkpointPlumbing;
 		if (opts.schema !== void 0) runAgentOptions.schema = opts.schema;
 		if (canonicalSchema !== void 0) runAgentOptions.canonicalSchema = canonicalSchema;
@@ -17865,6 +17961,7 @@ function createCtx(internals, rootWorkflow) {
 			}, spanId), branchOrRunSignal);
 		} finally {
 			exitActivity?.();
+			internals.budget.releaseExposureHolder(`agent:${running.seq}`);
 		}
 		internals.budget.releaseReserve(reserve, budgetAccount);
 		const declaredRules = internals.quota?.declaredRules;
@@ -21395,7 +21492,8 @@ function makeOrchestratorWorkflow(goal, opts) {
 				agentType: spec.agentType,
 				result: "full",
 				...resolveDispatchOpts(spec, internals.defaults),
-				[kOnRunning]: (seq) => resolveHandle(seq)
+				[kOnRunning]: (seq) => resolveHandle(seq),
+				[kExposureWait]: "child"
 			};
 			const result = runtime.runInScope(childState, () => ctx.agent(spec.prompt, agentOpts));
 			const PRE_ROOT_FAILED = -1;

package/package.json

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