The doctrine in one line: unknown stays unknown. A cost Nika cannot prove is never rendered as$0.00, a local model is unpriced — your compute, your electricity — never « free », and an estimate always says which side of the truth it sits on: a floor (≥) or a ceiling (≤).
The vocabulary
Every cost surface speaks the same four words:UNBOUNDED — no max_tokens declared· the task has no output limit. You can fix this one: declaremax_tokens:and, on a priced model, the report becomes a hard ceiling (the check prints that exact hint).UNBOUNDED — no catalog price (local model; spend not metered)· the task is bounded but the model has no price row. Local models stay here by design — pricing your own hardware would be invention. A cloud model missing from the catalog reads(cloud provider; spend unpriced)instead.UNBOUNDED — for_each over an expression (unknown count)· a fan-out whose item count is known only at run time.
Before a token: the COST rung
nika check audits cost statically, next to the plan and the permits —
the same ladder, every time. On weekly-update.nika, a cloud workflow
whose one task declares no max_tokens, the COST rung and its hint
read:
max_tokens: 4096 on that task and the same rung reads:
$15 per million output tokens × 4096, at the catalog
price of the snapshot the rung names; the prompt’s input tokens,
exec: and MCP calls are outside it. nika explain <file> narrates the
same numbers in beginner words —
≤ $0.0614 worst case · ≥ $0.0614 cheapest path, and for a local model
local models: your compute · tokens unpriced — not « free » — and
nika run --dry-run carries them onto the plan.
The budget gate: refusal, not remorse
Priced before the first token, refused before the run. nika check finds no max_tokens on the update task and marks it UNBOUNDED. One line, max_tokens: 4096, gives it a worst-case output ceiling of $0.0614: $15 per million output tokens × 4096. With --max-cost-usd 0.05, nika run refuses to start (NIKA-1709, exit 2): no model is called and no run is recorded. Every terminal line and number is captured from the real CLI on nika 0.121.0, offline and with no API key. Prices are catalog estimates; the receipt, the meter and the stamp are illustration.
--max-cost-usd is a block-before-spend gate, not a post-hoc alarm:
-
If the static floor already exceeds the budget, the run refuses to
start (exit 2, before any provider is touched):
-
The pre-start refusal prices the effective model —
--modeloverride included. - If unbounded work rides along, the gate says so loudly on stderr — a budget over work with no ceiling is a promise it names, not one it fakes.
-
Mid-run, the ledger stops the workflow the moment metered spend
crosses the budget (
NIKA-1704) — settled tasks stay settled, the trace records what was spent. -
The flag itself is guarded: a non-finite value (
NaN,inf) is rejected at parse time — a budget that cannot compare is not a budget.
Repeated runs on an unpriced API route
A server operator can authorize bounded runs without a fresh cost review each time, usingnika serve --cost-policy. The rule names an exact
unpriced API route and limits requests, output, request time and runs per
window. Unknown prices remain unknown. With operator-declared prices,
the declared worst case must fit every binding ceiling; without them,
every USD ceiling must be absent. Read
Standing cost rules for startup
syntax, supported routes, admission evidence and recovery.
Paid media: priced, refused or unpriced
An image or speech builtin bills its provider the way a model call does, so the same doctrine holds: a media call is priced from a dated table, or it is unpriced, never$0.00.
The media price table
The engine carries a price table for paid media, kept apart from the model catalog. Each row names a provider, a model, a unit, a rate in US dollars and the provider’s public price page, read on the date the row carries. Every row in 0.124 is dated 2026-10-27 (standard tier, paid usage):gemini-3.1-flash-image 0.50 / 60 / 3, gemini-3-pro-image
2 / 120 / 12, gemini-2.5-flash-image 0.30 / 30 / 2.50,
gemini-3.1-flash-lite-image 0.25 / 30 / 1.50 and gemini-nano-banana-2.1
1.50 / 30 / 7.50. The ElevenLabs families follow its
models page. xAI images keep
the $0.02 floor per image they already had in 0.123.2, and their bill is the
exact spend xAI reports.
A request is priced the way its provider bills it. A Gemini size class is
provider_options.image_size, else the class of an exact size: by its
longer edge, else 1K. The floor of quality: auto is the cheapest price
listed for its size, and the floor of an unlisted size the cheapest at its
quality. An image whose response reports no usage is billed at the dearest
row the request leaves open: quality: auto with no size: bills $0.211 on
gpt-image-2, never $0.005. Name the size and quality you mean.
What a capped run does
Under a cap (--max-cost-usd, a project ceiling:, or a beat’s plafond:,
which every beat has):
- At launch, a priced call with literal arguments adds its floor to the
run’s cost floor: its price per image times
n:, or its rate per character times its text. A paid call the table cannot price is refused withNIKA-1709before the run starts, and no request is sent: OpenAI’s default voicegpt-4o-mini-tts(OpenAI prices it per token, and its speech response reports no usage),gpt-image-1.5andgpt-image-1-mini(which OpenAI shuts down on 2026-12-01), and any model id the table does not list, in the workflow itself or in a child or grandchild workflow it calls. - Billed from usage only.
gpt-image-2.5-sunburstandgpt-image-2.5-flarepublish no price per image, and speech whose text only the run renders has no length before the run.nika checkmarks bothMETERED: they run under a cap, and only a zero cap refuses them at launch. - Before every request, the rendered call is judged against what the cap
leaves, less the floors of the paid media calls still in flight. A provider,
model,
quality:,size:,n:ortext:that only the run decides is judged here: the call is refused withNIKA-1704, never retried, when the table cannot price it or its floor exceeds what is left. An admitted call holds its floor until it returns, so the items of a cappedfor_each, parallel or not, cannot launch past the cap together. - An
agent:judges each media call its tools make the same way, against what its task’s remainder leaves after the loop’s own model turns and the floors of its concurrent calls. A refused call goes back to the model, and nothing is sent.
cost_usd, with
cost_basis saying how (catalog_rate_x_usage: the token rates times the
usage the provider reported; catalog_price_x_images: the price per image,
when no response reports usage; catalog_rate_x_characters: the rate per
character times the characters sent; provider_reported: xAI’s own figure)
and cost_as_of, the date of the rates. Each response of a Gemini n: batch
is billed on its own. A call that fails after its provider billed keeps that
spend: a batch whose later request fails keeps the bill of the images already
rendered, and a render that fails after its answer keeps its bill. The run
ledger debits it as it debits a model’s, per attempt: a capped run stops
mid-run (NIKA-1704) once media spend crosses the cap, and a retry is judged
against what is left. The run’s prologue records the table (media_pricing),
and the cost replay of nika trace verify refuses a journal that recorded
other rates.
Without a cap, an unpriced paid call runs and is counted in
spend.unpriced_calls: the total reads unpriced, or partially_priced
beside priced spend, and a child workflow’s unpriced calls reach its parent’s
total. A capped run counts some calls unpriced too: a request that broke after
it left (the provider may have billed it), a call dropped in flight (a
fail_fast sibling, a timeout:, a Stop; its floor stays consumed) and a
GPT Image 2.5 response that reports no usage. Once a paid call has billed
without a figure, the capped run refuses any later call billed only from its
usage.
local and mock media, and the keyless provider: system voice, bill no
provider. The system voice runs under any cap and reports its cost as unpriced
local work (cost_unpriced: local_model), like a local model. nika:image_fx,
nika:chart and nika:image_compose are local pixel work, not paid media.
On the COST rung
nika check gives each paid media call a row: its floor, the rate and unit
that set it and the table’s date, or METERED, UNPRICED, or
DECIDED AT RUN when a template or an agent’s tools choose the provider or
the model. A composed child’s calls get rows too. A workflow that renders a
cover with gpt-image-2 at quality: low and a poster with
gpt-image-2.5-flare, then speaks one line with tts-1 and the same line
with OpenAI’s default voice, reads:
from figure is the least the call can cost. Under any cap, the same
workflow is refused before the run starts, and the refusal names every model
the table prices:
nika check --json lists the same rows under cost.media, and the refusals
a cap would raise under failure_plan: unpriced_media_cap for a call the
table cannot price, priced_image_over_cap and priced_speech_over_cap for a
priced floor that a smaller cap refuses, each with its task and a message
naming the call.
A beat always runs under its plafond:, and a project ceiling: caps a
plain nika run that passes no --max-cost-usd, so both refuse unpriced paid
media: nika arm shows such a beat UNREADY with NIKA-1709
(Arming a project). A beat cannot drop its cap. Switch the
call instead: model: tts-1 or tts-1-hd, a priced ElevenLabs model or the
system voice for speech, gpt-image-2 or a GPT Image 2.5 model for images,
or local / mock.
After the run: the totals stay honest
Every run ends with a totals line that never turns an unknown price into$0.00. nika run hello.nika on the introduction’s mock/echo
workflow ends:
unmetered.
When priced and unpriced calls share a run, the total reads
≥ $… (N unpriced): the ≥ is
printed because an unpriced call rode the run. Per-task spend rides
the trace itself (cost_usd on the terminal events), so
nika trace show and the run report read the recorded ledger — never a
summary’s opinion.
Where prices come from — and when they rot
Prices are a catalog fact with provenance, not a constant:nika check --json carries the pricing snapshot (source · date ·
hash · derived counts) so a cost claim is traceable to the table that
produced it, and nika doctor warns when the snapshot is stale enough
to distrust — an old price table silently undercounts, which is the
one direction honesty cannot tolerate. Cache-aware accounting follows
the OpenTelemetry GenAI convention (input includes cache reads), so
exported traces mean the same thing your dashboards expect.
The workflow-side controls
max_tokens:per task · turns UNBOUNDED into a ceiling on a priced model (a local model stays unpriced).agent:budgets (max_turns· token budgets) bound the loop the same way — exhaustion is a named failure, never a silent overrun.nika checkbeforenika run, always: the cost story is part of the same pre-flight as permits and secrets.
ollama/…,
llamacpp/… or vllm/… reports unpriced (N calls), not a dollar
total — Nika never converts « I don’t know the price » into
« it’s free ». That distinction is the whole doctrine.