Cost Receipts

Per-stage, per-agent, per-token tracking. Opt-in toggle, default off. Fuel burns are the default surface.

What it is

Every LLM call the framework makes is recorded with its agent role, stage, input tokens, output tokens, model, and estimated amount. These records aggregate into a Receipt.

The Receipt is an opt-in user-toggled surface — default off, available to all tiers.

Where it lives

File	Lines	Purpose
`cost/models.py`	58	The record shape
`cost/consumer.py`	—	Event-bus consumer that tracks events
`cost/analyzer.py`	—	Per-run aggregation

Why it's a toggle, not a default

Default product UI shows stages advancing, fuel accumulating, XP filling, and the feeding-the-bonfire animation playing. No raw numbers anywhere.

When you toggle receipts on, you see the stage-by-stage breakdown:

+-----------------------------------------------+
|  BONFIRE RECEIPT -- BON-17                     |
|  standard_build . 7 stages                     |
+-----------------------------------------------+
|  stage        agent     est.      tokens       |
|  01 observe   scout    $0.0600   8,412         |
|  02 contract  knight   $0.0800  11,204         |
|  03 execute   warrior  $0.1400  18,891         |
|  04 verify    prover    --        --           |
|  05 publish   bard      --        --           |
|  06 audit     wizard    --        --           |
|  07 announce  herald    --        --           |
|  TOTAL                 $0.2800  38,507         |
|  tokens: chars/4 heuristic +15% margin         |
|  wall clock: 54.7s . attempts: 2/3             |
+-----------------------------------------------+

The honesty label (chars/4 heuristic +15% margin) exposes the estimation accuracy limitation inside the receipt itself. The user who opts into seeing data also sees exactly how that data is estimated.

Caps

Agent calls accept max_budget_usd. When a pipeline exceeds this cap, the next stage refuses to dispatch. Cap enforcement runs regardless of the receipts toggle state — the difference is only whether the user sees the numbers.

What the default surface shows

The default product experience for all tiers:

Stages advance with agent-colored indicators
Fuel accumulates as a gamification substrate
XP fills toward the next tier
The feeding-the-bonfire animation plays on PR lifecycle events

No raw numbers. No nagging. The Receipt is there when you want it.