Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
3.5 KB
Raw Blame
/**
 * Token-budget types (Phase P1). Mirrors the control-api
 * `POST /api/v1/internal/budgets/check` contract.
 *
 * Kept free of any `queue`/`agent` imports so `queue/types.ts` can import
 * `BudgetVerdict` (to persist it on a Task for the P2 per-task brake) without a
 * circular dependency.
 */

/** Source dimension reported to control-api. Same union as `UsageContext.source_kind`. */
export type BudgetSourceKind =
  | 'channel'
  | 'desktop'
  | 'workflow'
  | 'cron'
  | 'unknown'
  | 'plugin_workload_sdk'

/**
 * Request body for `POST /api/v1/internal/budgets/check`. Identity fields that
 * mcp-host cannot resolve (team/user UUIDs on channel tasks) are sent absent —
 * control-api resolves them via `context_ref`.
 */
export interface BudgetCheckRequest {
  host_ref: string
  context_ref: string | null
  team_id?: string | null
  user_id?: string | null
  provider: string
  model: string
  llm_secret_name?: string | null
  source_kind: BudgetSourceKind
  recipe_name?: string | null
  cron_job_id?: string | null
  /**
   * P2b (§5.4) — stable task correlation. control-api attaches any danger-zone
   * reservation it creates to this `task_ref` so mcp-host can release it early
   * on task termination (instead of waiting for the reservation TTL).
   */
  task_ref?: string | null
}

/**
 * Active price of one `(provider, model)`, per 1,000,000 tokens. Returned so the
 * P2 per-task cost brake can convert tokens→currency locally without a network
 * round-trip.
 */
export interface BudgetPrice {
  input: number
  output: number
  cacheRead: number
  cacheWrite: number
  currency: string
}

/**
 * Parsed verdict from the budget check. `maxTaskTokens`/`maxTaskCost`/`price`
 * feed the P2 per-task emergency brake; P1 only persists them on the Task.
 */
export interface BudgetVerdict {
  allowed: boolean
  reason?: string
  maxTaskTokens?: number | null
  maxTaskCost?: number | null
  price?: BudgetPrice | null
  /**
   * P2b (§5.4) — ids of the danger-zone reservations control-api created for
   * this check. Empty/absent when no budget was in the danger zone (the common,
   * far-from-limit case → nothing to release). Non-empty means mcp-host should
   * release the reservation early when the task reaches a terminal state.
   */
  reservationIds?: string[]
  /**
   * Informational (does NOT affect allow/deny). The `(provider, model)` pairs
   * with usage in the current period but no active price — cost budgets
   * sub-count these as $0. mcp-host logs them for ops visibility so a missing
   * price row is caught before it silently understates spend. Mirrors the
   * control-api `UnpricedModel` shape.
   */
  unpriced?: { provider: string; model: string }[]
}

/**
 * Request body for `POST /api/v1/internal/budgets/release` (P2b §5.4). At least
 * one of the two correlation keys must be present. Releasing by `task_ref`
 * drops ALL reservations for that task in one call. Idempotent on control-api.
 *
 * `host_ref` is REQUIRED by control-api: it binds the release to the caller's
 * JWT `claims.hostRefs[0]` and scopes the drop to reservations whose stored
 * `host_ref` matches. It MUST be the SAME `host_ref` sent on the matching
 * `/check` for this task (otherwise the reservation is not found and nothing is
 * released — a benign no-op given the fail-open/TTL semantics).
 */
export interface BudgetReleaseRequest {
  host_ref: string
  reservationId?: string | null
  task_ref?: string | null
}

/** Parsed result of a release call. `released` = number of reservations dropped. */
export interface BudgetReleaseResult {
  released: number
}