Class SpendBudget

constructor

• new SpendBudget(options): SpendBudget

• Parameters

  • options: SpendBudgetOptions

    The budget's settings.

  Returns SpendBudget

  Throws

  When maxCostUSD, or a maxTotalTokens that is set, is not a number zero or more. maxCostUSD may be Number.POSITIVE_INFINITY (a budget with no dollar cap). Also when a budget in the parent chain keeps its spending on the given guard under the same id; the guard is left as it was.

spentUSD

• spentUSD(): number

• What the run has spent, in US dollars, as the guard holds it.

  Returns number

tokensUsed

• tokensUsed(): number

• The tokens this budget has counted.

  Returns number

remaining

• remaining(): {
      usd: number;
      tokens?: number;
  }

• What is left under this budget's own caps (a parent's are not counted): the dollars under maxCostUSD (Infinity for a budget with no dollar cap) and, when maxTotalTokens is set, the tokens under it. Never below zero: a record is never refused, so a run can pass a cap by its last call.

  Returns {
      usd: number;
      tokens?: number;
  }

  • usd: number

  • Optional tokens?: number

assertCanSpend

• assertCanSpend(estimateUSD, estimateTokens, what, model?): void

• Refuses (or warns about) a call that could cost up to estimateUSD and use up to estimateTokens, when it would pass what is left; estimateUSD undefined means the model has no price row, which unpriced: 'allow' checks as a call that costs nothing. model, the call's provider and model, is named in the refusal of a model with no price row. A budget with a parent has the parent check the call first, with the same estimate, so the refusal thrown can be the parent's, or that of a budget above it.

  Parameters

  • estimateUSD: undefined | number
  • estimateTokens: number
  • what: string
  • Optional model: {
        providerId: string;
        modelId: string;
    }

    • providerId: string

    • modelId: string

  Returns void

  Throws

  At a cap. Its capType, currentCost and limit are those of the cap that refused the call: the id's total for the session or the day and that cap, or, at the guard's single-operation cap, the call's estimate and that cap. The token cap has no cap type of its own, so its refusal carries session, the run's dollars and maxCostUSD, and a message that names the token cap and the token counts.

  Throws

  For a model with no price row, unless the budget allows one.

record

• record(costUSD, tokens, what): void

• Records a finished call: its cost (undefined for a model with no price row, counted as nothing) and its tokens. A token count the provider reported as NaN counts as none: added, it would make the count NaN, and a count of NaN never reaches maxTotalTokens, since every comparison with NaN is false. A budget with a parent records the call there too, after itself.

  Parameters

  • costUSD: undefined | number
  • tokens: number
  • what: string

  Returns void

recordExternal

• recordExternal(costUSD, kind): void

• Records a cost made outside AgentOS, such as speech-to-text minutes billed by the minute. A cost of zero or below records nothing. A budget with a parent records the cost there too, after itself.

  Parameters

  • costUSD: number
  • kind: string

  Returns void

  Throws

  When costUSD is not a number, NaN included: a cost that could not be counted would let the run spend past its cap.

Readonly id

Readonly options