@rulvar/core 1.203.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;

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;
@@ -16473,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. */
@@ -17852,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;
@@ -21470,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.203.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",