Graphorin API reference v0.8.0
Graphorin API reference / @graphorin/agent / / RunBudget
Interface: RunBudget
Defined in: packages/agent/src/types.ts:523
Run-level budget (C5 / W-084 residual, decision D-8). Enforced as a between-step precheck against the run's accumulated usage - the step that crosses a ceiling completes (in-flight overshoot is inherent to between-step enforcement, exactly like the consolidator's BudgetTracker), and the run stops before the next provider call. Sub-agent usage is included: handoff / toTool children fold their usage into the parent run's accounting (W-033).
The cost leg reads Usage.cost, which only exists when the provider chain reports it (wire withCostTracking from @graphorin/provider with a @graphorin/pricing snapshot). A cost ceiling without USD cost data is UNENFORCED and WARNs once per run - use maxTokens for a provider-independent ceiling.
Stable
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
maxCostUsd? | readonly | number | Maximum cumulative run cost in USD (sub-agents included). | packages/agent/src/types.ts:525 |
maxTokens? | readonly | number | Maximum cumulative run tokens (Usage.totalTokens, sub-agents included). Provider-independent - enforced even without pricing middleware. | packages/agent/src/types.ts:531 |
onExceed? | readonly | "stop" | "throw" | What to do when a ceiling is crossed. 'stop' (default) ends the run through the normal terminal path: the result resolves with status: 'failed' and error.code: 'budget-exceeded' (the stop-condition-cut precedent), so the resumable partial state stays on the result. 'throw' rejects the run with AgentBudgetExceededError after emitting agent.error - graceful finalization (final checkpoint, agent.end) is skipped. | packages/agent/src/types.ts:541 |