System Manual
The Credit Engine
How usage is metered: one credit per 1,000 tokens on a fast model, multipliers for heavier models, budgets per organization and per member, hard stops, and the model downshift on smaller plans.
The credit unit
Usage is metered in credits. Every run logs its raw tokens, and customers see one number: credits. The conversion is defined once, in billing.ts, and everything else reads it from there:
// 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 OpusThe multiplier follows the price ratio between models, so a credit means the same cost whichever model an agent uses. A premium run costs 60× the credits of a fast run for the same tokens, which is why model choice, escalation and downshift matter to a budget. Every run is charged at least 1 credit.
Tokens
Raw usage per run
Ground truth logged for cost & margin
÷ 1,000
Normalize
1 baseline credit = 1,000 fast-model tokens
× model multiplier
fast 1×
smart 12×
premium 60×
Credits
Metered vs. allowance
Counted against the monthly cap
Worked example
5,000 Sonnet (smart) tokens
= 5,000 ÷ 1,000 = 5
= 5 × 12 = 60 credits
Hard stop at the cap
When the org (or a member's budget) reaches the monthly allowance, the pre-run gate blocks the run and routes it to triage. Nothing runs on credit the org doesn't have.
Model multipliers and tiers
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 as smart, so the meter never undercharges.
| fast | 1×: Gemini Flash, Claude Haiku |
| smart | 12×: Claude Sonnet, Gemini Pro |
| premium | 60×: Claude Opus |
| unknown model | Priced as smart (12×) to avoid undercharging |
Metering & enforcement
The credit meter is part of the harness and acts at three points in a run:
- •
Pre-run gate
Before an agent runs, the meter checks the org's remaining credits for the billing period and, on plans that have them, the member's own budget. If either is used up, that is a hard stop: the run is blocked and routed to triage with the reason. - •
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 model. - •
Post-run reconcile
After a successful run, actual tokens are converted to credits, a row is appended to the per-orgcredit_ledger(with agent, model, and run id), and the period counter is atomically incremented. If metering itself fails, the failure is logged and the completed run stands.
blockedBy: "member", distinct from the org running out (blockedBy: "organization"), so the dashboard can show the right message. Top-ups cost $25 per 1,000 credits.Worked example: computing credits for a run
Example · A 9,200-token run on three different models
An agent run uses 9,200 tokens in total. The charge depends on the model tier it ran on:
- Fast (Haiku, 1×): ceil(9200 / 1000 × 1) = ceil(9.2) = 10 credits.
- Smart (Sonnet, 12×): ceil(9.2 × 12) = ceil(110.4) = 111 credits.
- Premium (Opus, 60×): ceil(9.2 × 60) = ceil(552) = 552 credits.
The same tokens cost about 55 times more on the most expensive model than on the cheapest. If this agent were on a Pro plan (fast and smart only) but defaulted to Opus, the meter would downshift it to Sonnet and charge 111 credits, not 552. On Starter (500 included credits), one Sonnet run of this size would use more than a fifth of the monthly allowance, which is why Starter is fast-tier only.
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 type. Plans differ in which models agents may run on and how many credits are included.
| Starter, $0/mo | 500 credits · fast only · no Opus escalation · 1 seat · no per-member budgets · no API · 7-day audit log |
| Pro, $25/mo | 3,000 credits · fast + smart · no Opus escalation · 1 seat · no per-member budgets · no API · 30-day audit log |
| Team, $99/mo | 12,000 credits · fast + smart · no Opus escalation · 3 seats · per-member budgets · no API · 60-day audit log |
| Growth, $299/mo | 40,000 credits · fast + smart + premium · Opus escalation · 10 seats · per-member budgets · rate-limited API · 90-day audit log |
| Enterprise, custom | Committed credits · all tiers · Opus escalation · unlimited seats · per-member budgets · unlimited API · 365-day audit log |