Rulvar API reference / @rulvar/core / PreflightSpawnSpec
Interface: PreflightSpawnSpec
Defined in: packages/core/src/engine/preflight.ts:73
One intended spawn of the wave under estimation: the same layers the engine reads at ctx.agent time (call limits over profile limits over engine defaults; call estCost over profile estCost over the priced estimate over the flat default), plus the two stand-ins a static estimate needs: estInputTokens replaces the adapter countTokens the runtime would call over the real prompt, and count declares how many spawns of this shape the first wave holds.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
budgetUsd? | number | The spawn's explicit budget, exactly the spawn_agent budgetUsd param. Consumed by the layer-2 spawn-gate projection only (the shared dispatchProjectionReserveUsd clamp); a dynamic spawn's budget never becomes an account, so the layer-1 chain reserve is NOT clamped by it, exactly like the runtime. | packages/core/src/engine/preflight.ts:100 |
count? | number | How many spawns of this shape the wave declares; default 1. | packages/core/src/engine/preflight.ts:109 |
estCost? | number | The declared admission estimate. In a PLAIN wave this is AgentOpts.estCost verbatim. In an orchestrate wave (an orchestrator spec is present) a spawn tool has no per-call estCost channel, so declare the agentType PROFILE's estimate here: the layer-2 spawn gate evaluates exactly that (or the flat default), never the priced estimate. | packages/core/src/engine/preflight.ts:92 |
estInputTokens? | number | The prompt-size stand-in for the runtime's adapter countTokens: feeds the priced admission estimate and the per-turn and quota exposure floors. Absent, the reserve falls through to the flat default exactly like a runtime spawn whose adapter cannot count. | packages/core/src/engine/preflight.ts:107 |
evidenceContract? | EvidenceContract | The declared evidence contract this spawn must fill (RV303): wins over the registered profile's declaration. The estimator compares the call floor (minEntries * estCallsPerEntry + overheadCalls, defaults 3 and 8) against the spawn's effective executed-call ceiling and warns tool-cap-below-evidence-floor when the cap cannot fit the contract. | packages/core/src/engine/preflight.ts:118 |
label? | string | Display label; defaults to the role name. | packages/core/src/engine/preflight.ts:75 |
limits? | UsageLimits | The call-layer limits, merged exactly like AgentOpts.limits. | packages/core/src/engine/preflight.ts:83 |
model? | ModelSpec | Wins over the profile model over defaults.routing[role]. | packages/core/src/engine/preflight.ts:81 |
profile? | string | A registered AgentProfile name from defaults.profiles. | packages/core/src/engine/preflight.ts:79 |
role? | InvocationRole | Default 'loop', exactly like ctx.agent. | packages/core/src/engine/preflight.ts:77 |