The Credit Engine

The credit unit

Usage is metered in credits. Internally every run logs raw tokens — the ground truth for cost and margin — but customers see one normalized number. The conversion is defined once, in billing.ts, and read everywhere downstream:

// 1 credit = 1,000 tokens of the baseline (fast) model.
const TOKENS_PER_CREDIT = 1_000;

credits_charged = max(1, ceil( total_tokens / 1000 * model_multiplier ))

// Multipliers mirror real API price ratios vs the fast baseline:
fast    = 1×    // Gemini Flash, Claude Haiku
smart   = 12×   // Claude Sonnet, Gemini Pro
premium = 60×   // Claude Opus

Because the multiplier tracks the true price ratio, a credit maps to real cost no matter which model an agent uses. A premium run on the same token count costs 60× the credits of a fast run — which is exactly why model choice, escalation, and downshift matter to a budget. Every run is charged at least 1 credit.

Model multipliers & tier classification

The tier of a model is inferred from its id: anything with "opus" is premium; "sonnet" (or Gemini Pro) is smart; "haiku", "flash", or other Gemini models are fast. An unknown model is priced conservatively as smart so the meter never undercharges.

Metering & enforcement

The credit meter wraps every run as part of the harness, in three moves:

1. •

   Pre-run gate

   Before an agent runs, the meter checks the org's remaining credits for the billing period and — on plans that support them — the member's personal budget. If either is exhausted it is a hard stop: the run is blocked and routed to triage with a clear reason, never run on credit it doesn't have.
2. •

   Model downshift

   The meter returns the plan, so the harness can downshift the agent's model to the best tier the plan allows — the agent still runs, on a cheaper brain.
3. •

   Post-run reconcile

   After a successful run, actual tokens are converted to credits, a row is appended to the per-org credit_ledger (with agent, model, and run id), and the period counter is atomically incremented. Metering is best-effort — a metering failure is logged but never breaks a completed run.

Worked example: computing credits for a run

The five plan tiers

Five tiers govern included credits, which model tiers an agent may reach, whether the harness may escalate to Opus, seat counts, per-member budgets, API access, and audit retention. Every plan can use every agent — tiers differ only by which brains agents may run on and how many credits you get.