Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.37.x — unified BudgetTracker for every gateway-routed LLM call.
*
* Replaces the per-command budget code (brainstorm orchestrator inline
* BudgetExhausted, cycle/budget-meter, eval-contradictions cost-prompt +
* cost-tracker). One class, one error type, one audit JSONL schema.
*
* Compose via `withBudgetTracker(tracker, fn)` from `src/core/ai/gateway.ts`
* (Phase 2 / TX5). Once inside the scope, every `gateway.chat / embed /
* rerank` call auto-records cost via AsyncLocalStorage — no per-call
* injection seam needed.
*
* Contracts (locked by /plan-eng-review):
* - TX1: `record()` THROWS BudgetExhausted(reason:'cost') when cumulative
* spend > maxCostUsd. The cap is a real ceiling, not a suggestion.
* - TX2: When a USER cap is set (`capSource: 'user'`, the default for an
* explicit `maxCostUsd`) AND the model is not in the pricing maps,
* `reserve()` HARD-FAILS with BudgetExhausted(reason:'no_pricing') whose
* `fix` registers the rate. A `derived` or `default` cap (A4) warns once
* and runs the model unmetered; so does an unset cap (legacy warn-once).
* - A4: exhausting a `derived` cap logs `derived_cap_exhausted` to the
* agent-contract log; callers report it with consent.ts's
* derivedCapExhaustedError (checkpoint + resume command, exit 1).
* - A3 amended: `record()` is best called from try/finally on every
* gateway site. When the call threw without usage, callers feed
* `extractUsageFromError(err, fallback)` — fallback is the pessimistic
* ceiling (`maxOutputTokens` worth of output), not the optimistic
* pre-call estimate. Better to overcount on failure than undercount.
*
* Audit JSONL lives at `~/.gbrain/audit/budget-YYYY-Www.jsonl` (ISO-week
* rotation, same shape as shell-audit / phantom-audit). Every line carries
* `schema_version: 1` so consumers can detect future renames. Writes are
* best-effort: a disk-full audit never gates the run.
*/
import { mkdirSync, appendFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { gbrainPath } from '../config.ts';
import { ANTHROPIC_PRICING } from '../anthropic-pricing.ts';
import { EMBEDDING_PRICING } from '../embedding-pricing.ts';
import { isoWeekFilename, resolveAuditDir } from '../audit-week-file.ts';
import {
canonicalPricingKey,
isAllowedPricingOverrideKey,
reservationCostUsd,
usageCostUsd,
type BudgetKind,
type PricingOverrides,
} from './reservation-cost.ts';
import { ModelLedger, type ModelUsageRow } from './models-used.ts';
import { noPricingFix, noPricingGuidance, noPricingMessage, pricingSetCommand, type NoPricingGuidance } from './no-pricing.ts';
import { recordAgentContractEvent } from '../agent-contract-log.ts';
import type { Action, Transport } from '../agent-output.ts';
import type { CapSource } from '../consent.ts';
export { isModelPriceable } from './reservation-cost.ts';
export type { BudgetKind, PricingOverrides, NoPricingGuidance };
export type BudgetReason = 'cost' | 'runtime' | 'no_pricing';
export interface BudgetEstimate {
modelId: string;
estimatedInputTokens: number;
maxOutputTokens: number;
kind: BudgetKind;
/** Optional label for telemetry (e.g. 'brainstorm.cross', 'dream.synthesize'). */
label?: string;
}
/**
* Opaque handle for one admitted reservation. `reserve()` returns it when it
* holds a projection against the cap; the caller hands it back to `record()`
* (settles it with the real usage) or `release()` (frees it when the call
* never reached the provider). Settlement is by identity, never by model.
*/
export type BudgetReservation = string & { readonly __budgetReservation: unique symbol };
export interface BudgetActualUsage {
modelId: string;
/** The reservation this usage settles, as returned by `reserve()`. */
reservation?: BudgetReservation;
inputTokens: number;
outputTokens?: number;
/** For embeddings: dimension count, surfaces in audit only. */
embeddingDims?: number;
/** Optional label echo for the audit row. */
label?: string;
/** Model string the caller asked for, before alias/default resolution. Defaults to the served model. */
requestedModelId?: string;
/** Caller-declared purpose (`skillopt.optimizer`, …); engine-internal calls leave it unset. */
purpose?: string;
/** The call failed. A `.failed` label implies it. */
failed?: boolean;
/** False for an extra attempt inside one gateway operation (structured-output fallback). Default true. */
countsAsCall?: boolean;
/** Token counts are a heuristic (char estimate or pessimistic failure fallback), not provider-reported. */
estimated?: boolean;
/**
* PR 4 (Wave B incremental derivation, transcripts): for a failed call, the tokens the provider may have billed
* across its attempts (failedCallUsage): zero only when it definitively refused every attempt before generating.
*/
billed?: { inputTokens: number; outputTokens: number };
}
export interface BudgetSnapshot {
cumulativeCostUsd: number;
startedAt: number;
elapsedMs: number;
maxCostUsd?: number;
maxRuntimeMs?: number;
callsRecorded: number;
/** Per-model ledger of every recorded call (see models-used.ts). */
models: ModelUsageRow[];
}
export interface BudgetTrackerOpts {
/** USD cap. When undefined, cost gate disabled; pricing misses warn-once. */
maxCostUsd?: number;
/** Wall-clock cap in milliseconds. When undefined, runtime gate disabled. */
maxRuntimeMs?: number;
/** Phase/command label used in audit rows. */
label: string;
/** Override the audit file path (tests + custom installers). */
auditPath?: string;
/**
* #4312 — operator config-plane price overrides (`pricing.overrides`),
* normalized via parsePricingOverrides. Consulted BEFORE the shipped
* pricing tables in every cost computation, so an operator routing through
* a proxy (LiteLLM fronting a paid provider — chat AND embed) can declare
* their real rate instead of TX2 no_pricing hard-failing under --max-cost.
* Models with neither a table row nor an override stay fail-closed.
*/
pricingOverrides?: PricingOverrides;
/**
* PR 4 (Wave B incremental derivation, transcripts): the provider SDK's own retries for each call made under this
* tracker (chat's maxRetries); unset keeps the SDK default. A metered page step sets 0, so every attempt is a call
* it reserved for and sees.
*/
providerRetries?: number;
/**
* A4: where `maxCostUsd` came from. `user` (an explicit flag or configured
* cap; the default whenever `maxCostUsd` is set) hard-fails an unpriced
* model; `derived` (estimate x1.5 under `--yes`) and `default` warn and run.
*/
capSource?: CapSource;
/** Caller's transport, for the no_pricing fix's actor (default `cli`). */
transport?: Transport;
}
/**
* Parse the raw `pricing.overrides` config value (JSON string or object) into
* a normalized PricingOverrides map. Invalid entries are DROPPED (the model
* stays unpriced → the TX2 fail-closed contract still applies to it); a
* provider wildcard on a per-token provider and a bare `*` are invalid keys
* (isAllowedPricingOverrideKey). A wholly-unparseable value yields undefined.
* Never throws.
*/
export function parsePricingOverrides(raw: unknown): PricingOverrides | undefined {
let value: unknown = raw;
if (value == null) return undefined;
if (typeof value === 'string') {
const s = value.trim();
if (!s) return undefined;
try {
value = JSON.parse(s);
} catch {
return undefined;
}
}
if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
const isRate = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0;
const out: PricingOverrides = {};
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
const key = k.trim().toLowerCase();
if (!isAllowedPricingOverrideKey(key)) continue;
if (isRate(v)) {
out[key] = { input: v, output: v };
continue;
}
if (v && typeof v === 'object' && !Array.isArray(v)) {
const obj = v as { input?: unknown; output?: unknown; pricePerMTok?: unknown };
const input = obj.input ?? obj.pricePerMTok;
if (isRate(input) && (obj.output === undefined || isRate(obj.output))) {
out[key] = { input, output: (obj.output as number | undefined) ?? input };
}
}
}
// An override keyed by the alias the operator configured
// (`nvidia:nemotron-3-super`) must also price the id the gateway records
// for it (`nvidia:nvidia/nemotron-3-super-120b-a12b`): overrideFor
// canonicalizes the looked-up id, so the stored key needs its canonical
// twin. An explicit row for the canonical id wins. (From #5959.)
for (const [key, rate] of Object.entries(out)) {
const canonical = canonicalPricingKey(key).toLowerCase();
if (!(canonical in out)) out[canonical] = rate;
}
return Object.keys(out).length > 0 ? out : undefined;
}
/**
* Load + parse operator price overrides from the DB config plane
* (`pricing.overrides`). Fail-open to undefined — a config read failure must
* never block a run; the affected models simply keep the fail-closed
* no-pricing behavior.
*/
export async function loadPricingOverrides(
engine: { getConfig(key: string): Promise<string | null> },
): Promise<PricingOverrides | undefined> {
try {
return parsePricingOverrides(await engine.getConfig('pricing.overrides'));
} catch {
return undefined;
}
}
export class BudgetExhausted extends Error {
readonly tag = 'BUDGET_EXHAUSTED' as const;
reason: BudgetReason;
spent: number;
cap: number;
modelId?: string;
/** Set when reason is 'no_pricing': the lookup-and-register guidance (no-pricing.ts). */
pricing?: NoPricingGuidance;
/** A4: the exhausted cap's source (cost and no_pricing reasons). */
capSource?: CapSource;
/** Agent contract v1: the next step (no_pricing: register the rate). */
fix?: Action;
constructor(
message: string,
opts: { reason: BudgetReason; spent: number; cap: number; modelId?: string; pricing?: NoPricingGuidance; capSource?: CapSource; fix?: Action },
) {
super(message);
this.name = 'BudgetExhausted';
this.reason = opts.reason;
this.spent = opts.spent;
this.cap = opts.cap;
this.modelId = opts.modelId;
if (opts.pricing) this.pricing = opts.pricing;
if (opts.capSource) this.capSource = opts.capSource;
if (opts.fix) this.fix = opts.fix;
}
}
/** One-process memo: warn-once on missing pricing per (modelId, kind). */
const _unpricedWarnings = new Set<string>();
/** Test seam: reset warn-once memo so unit tests can re-trigger the path. */
export function _resetBudgetTrackerWarningsForTest(): void {
_unpricedWarnings.clear();
}
/**
* Best-effort JSONL audit append. Failure never gates the run; matches the
* shell-audit / phantom-audit posture.
*/
function appendAuditLine(path: string, entry: object): void {
try {
mkdirSync(dirname(path), { recursive: true });
appendFileSync(path, JSON.stringify(entry) + '\n');
} catch {
// swallow — audit failures must not block the LLM call
}
}
function defaultAuditPath(): string {
const dir = resolveAuditDir();
return `${dir}/${isoWeekFilename('budget')}`;
}
export class BudgetTracker {
private cumulativeUsd = 0;
/**
* #4365 — sum of projections reserved but not yet record()ed. Concurrent
* callers (e.g. skillopt's validation gate, concurrency 4) all pass
* admission against cumulativeUsd alone, breaching the cap by up to
* (N-1)×per-call cost. Admission checks cumulative + outstanding instead.
*/
private outstandingUsd = 0;
/** Unsettled projections by reservation id (eng I6: settle by identity, not FIFO-by-model). */
private readonly outstanding = new Map<BudgetReservation, number>();
private nextReservation = 0;
private callsRecorded = 0;
private readonly ledger = new ModelLedger();
private readonly startedAt: number;
private readonly auditPath: string;
private readonly onExhaustedCbs: Array<() => void> = [];
private exhaustedFired = false;
constructor(private readonly opts: BudgetTrackerOpts) {
this.startedAt = Date.now();
this.auditPath = opts.auditPath ?? defaultAuditPath();
}
/** The SDK retries each call under this tracker may make (BudgetTrackerOpts.providerRetries). */
get providerRetries(): number | undefined {
return this.opts.providerRetries;
}
/** Public read access. */
get totalSpent(): number {
return this.cumulativeUsd;
}
/**
* The configured cost ceiling (USD), or undefined when uncapped. Read-only.
* Lets callers detect a post-hoc overage when a final-call BudgetExhausted is
* swallowed by the gateway ("surfaced via next reserve") and there is no next
* reserve — `totalSpent > cap` with no throw. See enrich's runEnrichCore.
*/
get cap(): number | undefined {
return this.opts.maxCostUsd;
}
/** A4: the cap's source; an explicit cap with no declared source is a user cap (pre-A4 behaviour). */
get capSource(): CapSource | undefined {
if (this.opts.maxCostUsd === undefined) return undefined;
return this.opts.capSource ?? 'user';
}
/**
* Register a synchronous callback to fire the first time the tracker
* throws BudgetExhausted (from reserve OR record). Fires once. Useful for
* persisting checkpoint state before the throw propagates. The callback
* MUST be synchronous; async work (fs writes are fine via writeFileSync)
* goes inside the callback body.
*/
onExhausted(cb: () => void): void {
this.onExhaustedCbs.push(cb);
}
/**
* Project a planned LLM call against the cap. Throws BudgetExhausted
* BEFORE any provider call when:
* - cumulative + projected > maxCostUsd (reason: 'cost')
* - wall-clock > maxRuntimeMs (reason: 'runtime')
* - maxCostUsd set AND pricing missing (reason: 'no_pricing') -- TX2
*
* When maxCostUsd is unset, missing pricing warns-once but does not throw
* (legacy behavior preserved for non-priced providers).
*
* Returns the reservation id when the projection is held against the cap
* (a cap is set and the model is priced); undefined when nothing is held.
* The caller settles it with `record({ reservation })` or `release()`.
*/
reserve(estimate: BudgetEstimate): BudgetReservation | undefined {
this.assertRuntime(estimate.modelId);
const projected = reservationCostUsd(
estimate.modelId,
estimate.kind,
estimate.estimatedInputTokens,
estimate.maxOutputTokens,
this.opts.pricingOverrides,
);
if (projected === null) {
if (this.opts.maxCostUsd !== undefined && this.capSource === 'user') {
// TX2: hard-fail when a cap is set but pricing is missing — without
// pricing we can't enforce the cap, and silently ignoring it would
// void the contract. The refusal tells the agent to look the rate up
// and register it (`gbrain pricing set`), then retry.
const pricing = noPricingGuidance(estimate.modelId, estimate.kind);
const pricingFile = estimate.kind === 'chat' ? 'model-pricing.ts' : 'embedding-pricing.ts';
const msg = `${noPricingMessage(pricing, { label: this.opts.label, capUsd: this.opts.maxCostUsd })} ` +
`(To ship the rate with gbrain itself, add it to src/core/${pricingFile}.)`;
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'reserve_no_pricing',
label: this.opts.label,
kind: estimate.kind,
model: estimate.modelId,
sub_label: estimate.label,
estimated_input_tokens: estimate.estimatedInputTokens,
max_output_tokens: estimate.maxOutputTokens,
cumulative_cost_usd: this.cumulativeUsd,
max_cost_usd: this.opts.maxCostUsd,
reason: 'no_pricing',
});
this.fireExhausted();
throw new BudgetExhausted(msg, {
reason: 'no_pricing',
spent: this.cumulativeUsd,
cap: this.opts.maxCostUsd,
modelId: estimate.modelId,
pricing,
capSource: 'user',
fix: noPricingFix(pricing, this.opts.transport),
});
}
// Warn-once path — cap unset, or a derived/default cap (A4: new models must run).
const memoKey = `${estimate.modelId}:${estimate.kind}`;
if (!_unpricedWarnings.has(memoKey)) {
_unpricedWarnings.add(memoKey);
const gate = this.opts.maxCostUsd === undefined
? 'Running it without a cost gate'
: `The ${this.capSource} $${this.opts.maxCostUsd.toFixed(2)} cap can't meter it, so it runs unmetered`;
process.stderr.write(
`[budget] BUDGET_TRACKER_NO_PRICING: model "${estimate.modelId}" (kind=${estimate.kind}) not in pricing maps. ` +
`${gate}; to meter it, register its rate: ${pricingSetCommand(estimate.modelId, estimate.kind)}\n`,
);
}
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'reserve_unpriced',
label: this.opts.label,
kind: estimate.kind,
model: estimate.modelId,
sub_label: estimate.label,
estimated_input_tokens: estimate.estimatedInputTokens,
max_output_tokens: estimate.maxOutputTokens,
});
return undefined;
}
if (this.opts.maxCostUsd !== undefined) {
const after = this.cumulativeUsd + this.outstandingUsd + projected;
if (after > this.opts.maxCostUsd) {
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'reserve_denied',
label: this.opts.label,
kind: estimate.kind,
model: estimate.modelId,
sub_label: estimate.label,
projected_cost_usd: projected,
cumulative_cost_usd: this.cumulativeUsd,
outstanding_usd: this.outstandingUsd,
max_cost_usd: this.opts.maxCostUsd,
});
throw this.costExhausted(
`${this.opts.label}: projected cost $${after.toFixed(4)} exceeds --max-cost $${this.opts.maxCostUsd.toFixed(2)} ` +
`(cumulative $${this.cumulativeUsd.toFixed(4)} + outstanding $${this.outstandingUsd.toFixed(4)} + this call $${projected.toFixed(4)})`,
this.opts.maxCostUsd, estimate.modelId,
);
}
}
// Admission passed — hold the projection until record() or release()
// settles this id, so parallel reserve() calls can't all admit against the
// same cumulative, and a small call settling first can't free a large
// in-flight call's hold.
const reservation = this.opts.maxCostUsd !== undefined
? `r${++this.nextReservation}` as BudgetReservation
: undefined;
if (reservation) {
this.outstanding.set(reservation, projected);
this.outstandingUsd += projected;
}
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'reserve',
label: this.opts.label,
kind: estimate.kind,
model: estimate.modelId,
sub_label: estimate.label,
reservation: reservation ?? null,
projected_cost_usd: projected,
cumulative_cost_usd: this.cumulativeUsd,
max_cost_usd: this.opts.maxCostUsd ?? null,
});
return reservation;
}
/**
* Free a reservation whose call never reached the provider (provider
* resolution failed, an invocation policy refused it, a preflight threw).
* A no-op for an id `record()` already settled, or for undefined, so a
* caller can release unconditionally in a `finally`.
*/
release(reservation: BudgetReservation | undefined): void {
if (!reservation || !this.settleReservation(reservation)) return;
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'release',
label: this.opts.label,
reservation,
outstanding_usd: this.outstandingUsd,
});
}
/**
* Record the actual usage after the provider returned (or threw). Updates
* cumulative spend. Throws BudgetExhausted(reason:'cost') AFTER the update
* when cumulative > maxCostUsd (TX1): a single underestimated call can
* blow past the cap and the cap must remain a real ceiling.
*
* `outputTokens` defaults to 0 (embed/rerank). `embeddingDims` is audit-
* only metadata.
*/
record(actual: BudgetActualUsage & { kind?: BudgetKind }): void {
this.callsRecorded++;
const kind: BudgetKind = actual.kind ?? 'chat';
const cost = usageCostUsd(
actual.modelId,
actual.inputTokens,
actual.outputTokens ?? 0,
kind,
this.opts.pricingOverrides,
);
// The ledger sees every record — before the unpriced return and the TX1
// throw below — so an over-cap or unpriced call is never invisible.
const servedModel = canonicalPricingKey(actual.modelId);
this.ledger.add({
requestedModel: actual.requestedModelId ?? servedModel,
model: servedModel,
label: actual.label,
purpose: actual.purpose,
failed: actual.failed === true || (actual.label?.endsWith('.failed') ?? false),
countsAsCall: actual.countsAsCall !== false,
estimated: actual.estimated === true,
inputTokens: actual.inputTokens,
outputTokens: actual.outputTokens ?? 0,
costUsd: cost,
});
if (cost === null) {
// Unpriced served model: no per-token math. A user cap
// already rejected this call at reserve(); a record() here means the
// unpriced warn-once path let it through (cap unset or default/derived).
// A served model can be unpriced while the requested one held a priced
// projection (a fallback hop, a renamed id): the real cost is unknown,
// so the held ceiling becomes spend and the cap stays a real ceiling.
const held = actual.reservation ? this.outstanding.get(actual.reservation) : undefined;
if (held !== undefined) {
this.settleReservation(actual.reservation!);
this.cumulativeUsd += held;
}
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'record_unpriced',
label: this.opts.label,
kind,
model: actual.modelId,
sub_label: actual.label,
input_tokens: actual.inputTokens,
output_tokens: actual.outputTokens ?? 0,
embedding_dims: actual.embeddingDims ?? null,
charged_reservation_usd: held ?? null,
});
return;
}
if (actual.reservation) this.settleReservation(actual.reservation);
this.cumulativeUsd += cost;
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'record',
label: this.opts.label,
kind,
model: actual.modelId,
requested_model: actual.requestedModelId ?? null,
reservation: actual.reservation ?? null,
sub_label: actual.label,
input_tokens: actual.inputTokens,
output_tokens: actual.outputTokens ?? 0,
embedding_dims: actual.embeddingDims ?? null,
actual_cost_usd: cost,
cumulative_cost_usd: this.cumulativeUsd,
max_cost_usd: this.opts.maxCostUsd ?? null,
});
if (this.opts.maxCostUsd !== undefined && this.cumulativeUsd > this.opts.maxCostUsd) {
// TX1: hard-throw — a single under-estimated call exceeded the cap.
throw this.costExhausted(
`${this.opts.label}: cumulative cost $${this.cumulativeUsd.toFixed(4)} exceeded --max-cost $${this.opts.maxCostUsd.toFixed(2)} after recording ${kind} call to ${actual.modelId}`,
this.opts.maxCostUsd, actual.modelId,
);
}
}
snapshot(): BudgetSnapshot {
return {
cumulativeCostUsd: this.cumulativeUsd,
startedAt: this.startedAt,
elapsedMs: Date.now() - this.startedAt,
maxCostUsd: this.opts.maxCostUsd,
maxRuntimeMs: this.opts.maxRuntimeMs,
callsRecorded: this.callsRecorded,
models: this.ledger.rows(),
};
}
/**
* Drop one reservation's hold. Settlement is by id: the gateway reserves
* with the pre-resolution model string and records the served id, and two
* same-model calls of different sizes settle in any order, so a model key
* cannot say which hold a record belongs to. Records with no reservation
* (expand/OCR spend sites) settle nothing. Returns false for an id that was
* already settled.
*/
private settleReservation(reservation: BudgetReservation): boolean {
const amount = this.outstanding.get(reservation);
if (amount === undefined) return false;
this.outstanding.delete(reservation);
this.outstandingUsd = Math.max(0, this.outstandingUsd - amount);
return true;
}
/** Internal helper: throw BudgetExhausted(reason:'runtime') when the wall-clock cap fires. */
private assertRuntime(modelId: string): void {
if (this.opts.maxRuntimeMs === undefined) return;
const elapsed = Date.now() - this.startedAt;
if (elapsed > this.opts.maxRuntimeMs) {
appendAuditLine(this.auditPath, {
schema_version: 1,
ts: new Date().toISOString(),
event: 'runtime_denied',
label: this.opts.label,
elapsed_ms: elapsed,
max_runtime_ms: this.opts.maxRuntimeMs,
model: modelId,
});
this.fireExhausted();
throw new BudgetExhausted(
`${this.opts.label}: wall-clock ${(elapsed / 1000).toFixed(1)}s exceeded --max-runtime ${(this.opts.maxRuntimeMs / 1000).toFixed(1)}s`,
{ reason: 'runtime', spent: elapsed, cap: this.opts.maxRuntimeMs, modelId },
);
}
}
/** The cost-cap BudgetExhausted; a derived cap's exhaustion is logged to E11 (A4). */
private costExhausted(message: string, cap: number, modelId: string): BudgetExhausted {
this.fireExhausted();
if (this.capSource === 'derived') {
recordAgentContractEvent({ command: this.opts.label, transport: this.opts.transport ?? 'cli', code: 'derived_cap_exhausted', effects: ['paid'], outcome: 'stopped' });
}
return new BudgetExhausted(message, { reason: 'cost', spent: this.cumulativeUsd, cap, modelId, capSource: this.capSource });
}
private fireExhausted(): void {
if (this.exhaustedFired) return;
this.exhaustedFired = true;
for (const cb of this.onExhaustedCbs) {
try {
cb();
} catch (err) {
process.stderr.write(`[budget] onExhausted callback threw: ${String(err)}\n`);
}
}
}
}
/**
* Pull usage out of an SDK error envelope. Common providers attach `usage`
* either at the top level (Anthropic) or under `response.usage` (OpenAI).
* Returns the fallback (pessimistic ceiling) when no usage can be found —
* NOT the conservative pre-call estimate (A3 amended). Callers should pass
* `{ inputTokens: estimate.estimatedInputTokens, outputTokens: estimate.maxOutputTokens }`
* so the worst-case budget is consumed on failure.
*/
export function extractUsageFromError(
err: unknown,
fallback: { inputTokens: number; outputTokens: number },
): { inputTokens: number; outputTokens: number } {
const found = usageFromError(err);
return {
inputTokens: found?.inputTokens ?? fallback.inputTokens,
outputTokens: found?.outputTokens ?? fallback.outputTokens,
};
}
/**
* The usage an SDK error envelope reports, or null when it reports none.
* Either side may be null when the provider reported only the other.
*/
export function usageFromError(err: unknown): { inputTokens: number | null; outputTokens: number | null } | null {
if (!err || typeof err !== 'object') return null;
const top = (err as { usage?: unknown }).usage;
const nested = (err as { response?: { usage?: unknown } }).response?.usage;
const candidate = (top && typeof top === 'object' ? top : nested && typeof nested === 'object' ? nested : null) as
| { input_tokens?: number; output_tokens?: number; inputTokens?: number; outputTokens?: number }
| null;
if (!candidate) return null;
const inputTokens = numericOrNull(candidate.input_tokens ?? candidate.inputTokens);
const outputTokens = numericOrNull(candidate.output_tokens ?? candidate.outputTokens);
return inputTokens !== null || outputTokens !== null ? { inputTokens, outputTokens } : null;
}
function numericOrNull(v: unknown): number | null {
return typeof v === 'number' && Number.isFinite(v) ? v : null;
}
/** Re-export the pricing maps for introspection / test setup. */
export { ANTHROPIC_PRICING, EMBEDDING_PRICING };