Tokenomics — the three cost levers

What this is

How Colibri keeps agent-token spend down. Cost isn’t one knob — it’s a trifecta of independent levers, each owned by a different part of the system. This page is the map; the actual rates and mechanics live in the linked pages (and in code), never here, so the numbers can’t drift.

The three levers, by the question each answers:

Lever	Question	Detail
Timing	When do we run?	deepseek-pricing
Caching	How much do we re-send?	cost-model
Budget	How big a context?	cost-model

1. Timing — run in the valley

DeepSeek prices tokens by the clock: cheaper in the off-peak valley window, more at peak. Scheduling heavy or batchable work into valley hours cuts the per-token price with no change to the work itself.

Authoritative rates + UTC windows: deepseek-pricing
The pricing table the runtime computes against: hermes-bsd:agent/usage_pricing.py

2. Caching — keep the prefix byte-stable

Cache-hit tokens are roughly two orders of magnitude cheaper than fresh ones. Colibri holds the system prefix byte-stable across requests so the provider serves it from cache instead of re-billing it. For a long-running session this is the largest lever.

Mechanics + cache-hit metering: cost-model
The spawn-time prefix-stability work: prefix-caching plan

3. Budget — size the context to the task

Three cost modes — fast / smart / max — cap how much context a turn may spend, and the runtime auto-escalates only when a cheaper mode can’t keep up. You pay for the headroom the task needs, not a flat maximum.

The modes + escalation: cost-model

How they compose

The levers are independent and multiply:

Timing lowers the price per token.
Caching lowers the count of billed tokens.
Budget lowers the tokens a turn is allowed to draw.

A valley-scheduled, cache-warm, fast-mode turn pays the floor on all three at once — none of them trades off against the others.