Ingest-Time Cost Semantics#
Overview#
Decant computes session cost at ingest time and writes it to the estimated_cost_usd column on the session row. Ingest does not price a session from its aggregate totals at a single model. It derives per-request model and price-tier usage from the stored messages, writes it to the session_model_usage table, and prices the session from that split. Where per-request usage is unavailable (for example, Antigravity), or does not add up to the session totals, the session is priced from its totals at the session's model unless the source supplies per-model totals. Copilot CLI instead retains per-model totals in session metadata and writes that split to session_model_usage at the standard tier. Usage receipts supply the totals when they cover every model's cumulative snapshot; otherwise cumulative per-model snapshots supply them. An unnamed usage row with no source-reported cost uses the known session model for pricing (model attribution, Copilot usage). Every sync reconciles stored session and activity costs with current pricing.
Costs reflect the pricing table in effect when sync runs. Repricing happens for all sessions, including unchanged and archived ones, without requiring source files. Stale session costs and activity cost components update together in one transaction. When an ingest pipeline revision advances (for example, to apply a parser correction like the Claude usage deduplication), the next sync re-ingests sources with an older pipeline revision once, replacing stored token totals along with corrected cost estimates while preserving session IDs and local archive state. This requires the source files to remain available.
Claude Code replies copied by /branch or claude --resume <id> --fork-session are billed in only one archived session per message.id; the other transcripts retain the reply without usage. The original session keeps the usage regardless of ingest order. If the original is absent, one archived copy stays billed. When every original is archived, branch totals and cost cover only turns made after branching. result totals are reduced only when they cover every reply the transcript billed; totals for the new run alone are kept as recorded (billing semantics).
Cross-session billing deduplication uses the model-usage format backfill rather than a pipeline-revision re-ingest: sync corrects stored Claude Code sessions from archived rows, including those whose source files are gone. If the billing session is deleted or re-read without a shared reply, a remaining copy regains usage, totals, cost, and its reasoning estimate from stored rows (archive lifecycle).
Copilot Chat in VS Code reports partial per-turn usage: output sums every model call in the turn, but input records only the last call's prompt, including cache reads without a cache split. Earlier prompts in tool-heavy turns go uncounted, and the cached portion of the recorded prompt is priced at the full input rate, so costs are rough list-price estimates rather than Copilot credits or premium-request charges. Sessions from older builds that record no usage show cost as unavailable, not free (usage semantics).
Imported ATIF trajectories use per-step metrics for session usage, skipping steps marked is_copied_context. Session totals normally sum those steps, since final_metrics may include subagents or earlier continuations. A trajectory without per-step metrics or embedded subagents uses final_metrics; Decant exports use final_metrics, or its extra.session_metrics share when totals include subagents. Models with known rates are priced by Decant; otherwise, recorded step metrics.cost_usd is retained as reported cost. A cost-only step still contributes. If no step records cost, an unpriceable model can use final_metrics.total_cost_usd only without embedded subagents or file references, or the trajectory's own Decant session_metrics.total_cost_usd (ATIF usage and cost).
Hermes Agent supplies session-level and per-model usage, not per-message usage. Decant prices each model's share at its API rates, assigns session usage not covered by the per-model rows to the session's model, and uses the per-model totals when they exceed the session row. Hermes input is already net of cache reads and writes. Decant does not use Hermes's estimated cost or provider-reported cost. A session with no recorded API call, no per-model usage row, and no tokens reports usage and cost as unavailable (Hermes usage).
Pi records per-message usage with per-model attribution. Its input excludes cache reads and writes, reasoning is included in output, and cacheWrite1h identifies the one-hour share of cache writes. Tool-result usage with no model is charged to the session's model; compaction and branch summaries use the model selected when Pi wrote them. Decant uses Pi's recorded usage.cost.total only when it has no rate for the model; a recorded zero is not used. Forks retain copied history in the transcript without billing its usage again, even if the original was never archived (Pi usage and cost).
How Cost Is Calculated#
The entry point is estimateCost(model, usage, pricing) in src/cost.ts. It delegates to estimateCostParts, which applies per-million-token rates across four billing dimensions:
| Dimension | Rate field |
|---|---|
| Input tokens | inputPerMtok |
| Output tokens | outputPerMtok |
| Cache read tokens | cacheReadPerMtok |
| Cache creation tokens (5-min TTL) | cacheWritePerMtok |
| Cache creation tokens (1-hour TTL) | cacheWrite1hPerMtok |
For Claude models, cache-read is typically 10% of input rate, though Fable 5.1, Mythos 5.1, Fable 5.2, and Mythos 5.2 use 2.5%, and cache-write is 1.25Ć (5-min) or 2Ć (1-hour) of input rate. For OpenAI models prior to GPT-5.6, cache writes carry no additional fee; GPT-5.6 and the GPT-6, GPT-6.1, and GPT-6.2 families bill cache writes at 1.25Ć the uncached input rate. Z.ai GLM and Meta Muse models charge no separate cache-write fee, so cache writes bill at the input rate (see docs/pricing.md). Most other exact-ID models use the same convention. Kimi K3.1 Pro uses flat per-million-token rates across its full context window: $2.00 input, $10.00 output, $0.20 cache reads, and $2.00 / $4.00 cache writes for 5-minute / 1-hour TTLs (see docs/pricing.md). MiMo cache writes bill at zero under Xiaomi's limited-time free-write pricing; Qwen3.8 explicit-cache writes bill at 1.25Ć input, while Qwen3.5 and Qwen3.6 models without caching bill any reported cache reads at the input rate. Qwen4-Max cache reads bill at $0.075 per million tokens, and explicit cache writes bill at $1.875 / $3.00 for 5-minute / 1-hour TTLs.
If the model slug is unrecognized or explicitly unpriceable (e.g., codex-auto-review, gpt-5.3-codex-spark), estimateCostParts returns all-zero parts rather than guessing a neighboring model's rate.
Where Pricing Comes From#
defaultPricing() returns a memoized, shared ReadonlyMap<string, Price> covering supported models from Claude, OpenAI, Gemini, Z.ai GLM, Meta Muse, DeepSeek, Moonshot Kimi, MiniMax, Xiaomi MiMo, Alibaba Qwen, StepFun, Tencent Hy, xAI Grok, and Reflection Beam. The function builds the pricing table once and returns the same immutable instance to all callers, ensuring the default pricing table cannot be accidentally modified. Claude Fable 5.2 and Mythos 5.2 rates, including fast-mode rates, were verified on November 9, 2026, Claude Haiku 5.5 rates on October 7, 2026, other Anthropic rates on September 28, 2026, and current OpenAI coding-agent rates (including GPT-6.1 Sol) on September 29, 2026, against official sources. Legacy OpenAI rates retain their September 2, 2026 verification, Gemini 4 Argon rates were checked November 5, 2026, and other Gemini rates September 28, 2026 (see docs/pricing.md). GPT-6.1 Terra and the supported GLM, Muse, DeepSeek, Kimi (except K3.1 Pro), MiniMax, MiMo, Qwen, StepFun, Hy, and Beam rates were checked against first-party sources on October 26, 2026. Kimi K3.1 Pro rates are recorded as verified on October 25, 2026 (see docs/pricing.md). Anthropic, OpenAI, Gemini, Z.ai, Meta, DeepSeek, MiniMax, MiMo, Qwen, StepFun, Tencent, and Reflection rates were rechecked on November 16, 2026; rates for Gemini 4 Carbon and Hydrogen, GPT-6 Cyber, GPT-5.5 Cyber Preview, Qwen4-Max, Muse Ember, MiniMax-M3.1-Flash, Hy4, Step 3.7 Flash, and xAI Grok were added on that date (see docs/pricing.md). GPT-6.2 Astra and Sol rates were verified on November 17, 2026 (see docs/pricing.md). Gemini 4 Neon rates were verified on November 18, 2026: $3.00 input, $0.15 cache reads, and $15.00 output per million tokens (see docs/pricing.md). Artificial Analysis selects which open-weight models to price, not their rates. The rates do not apply Batch, Flex, OpenAI Fast or Ultrafast, regional-processing, or partner-cloud modifiers. DeepSeek uses peak rates for every request, an upper-bound estimate; MiniMax-M3 uses its permanent discounted standard rate without the over-512K prompt or Priority multipliers, so those requests are underestimated. Qwen uses international (Singapore) list rates. Hy4 and Hy4 flash use list rates rather than Tencent's half-price promotions, so estimates during those promotions are twice the billed cost. Muse Ember uses the shorter-prompt rate without the 3Ć surcharge above 200,000 prompt tokens. Grok uses rates without xAI's 2Ć surcharge at 200,000 prompt tokens or its 1.1Ć US regional modifier, so requests subject to those modifiers are underestimated (see docs/pricing.md). Claude Haiku 5.5 bills every rate at five times the listed price when a request's prompt exceeds 100,000 tokens, and fast mode on Fable 5.2, Mythos 5.2, Opus 5.5, Opus 5, and Opus 4.8 bills at 2Ć. Because the cost is priced per request, these requests use the long_prompt and fast price tiers instead of the standard rates. Other Claude 4.6 and later models include their full context window at the standard rate. Haiku 5.5 sessions with no logged context window are inferred as 1M.
For Gemini models with explicit caching, the geminiPrice() helper function maps token-hour cache-storage billing to the approximate equivalent of the input rate per token for typical session-length holds. Gemini 4 Neon uses implicit caching; any separately reported cache writes are priced at the input rate with no storage surcharge. Model slug normalization is handled by canonicalModel(), which strips provider prefixes, lowercases, and maps version-specific suffixes to a canonical pricing key (e.g., claude-opus-4.5 ā claude-opus). canonicalModel() also normalizes Gemini slug variants (e.g., distinguishing flash-lite sub-versions by their major version number). Gemini 4 Argon, Carbon, Hydrogen, and Neon accept routed and versioned IDs. Neon's low, medium, high, and xhigh reasoning-level IDs use the same standard API rates, while unannounced variants such as gemini-4-carbon-lite, gemini-4-neon-lite, and gemini-4-neon-max stay unpriced. GPT-6 Cyber and GPT-5.5 Cyber Preview use their own pricing keys rather than a base model's rate (see docs/pricing.md). GPT-6.2 Astra and Sol match the exact IDs gpt-6.2-astra and gpt-6.2-sol, including OpenAI provider prefixes; dated and variant suffixes stay unpriced. It also recognizes supported GLM, Muse, DeepSeek, Kimi, MiniMax, MiMo, Qwen, StepFun, Hy, Grok, and Beam IDs, including router prefixes such as z-ai/, meta/, moonshotai/, and x-ai/, so sessions such as Claude Code pointed at a supported Anthropic-compatible endpoint are priced instead of showing $0. Exact-ID family detection reads only the last path segment, so kimi-proxy/claude-opus-5-5 still reaches Claude rates. Hosted routing suffixes such as :cloud and :nitro reach list rates, while local build tags such as qwen3.8:27b stay unpriced. OpenRouter's deepseek-v4.1-flash-1017 and deepseek-v4.1-flash alias to deepseek-flash, and deepseek-v4-pro-0813 aliases to deepseek-v4-pro. Matching uses the whole normalized ID rather than a prefix, so near-miss IDs such as glm-5.3-highspeed or muse-wonder-full stay unpriced. qwen4-max-preview and the retired grok-code-fast-1 and its aliases also stay unpriced because no per-token rate is documented for those IDs (see docs/pricing.md). GLM-4.7-Flash, GLM-4.5-Flash, and Reflection's Beam-1.0-501B-A23B beta are published as free and priced at zero, rather than treated as unknown prices.
Where Cost Is Stored#
writeSession() in src/ingest.ts inserts the session row with a placeholder cost of 0. Once the session's messages are stored, it calls materializeModelUsage() to write the per-model, per-tier split to session_model_usage, then updates estimated_cost_usd with the cost priced from that split (sessionCostParts() in src/model-usage.ts). The value lands in estimated_cost_usd REAL NOT NULL DEFAULT 0 on the session table.
Each session_model_usage row holds one session's usage for one model and price tier (standard, fast, or long_prompt). Sync backfills missing rows from the archive, including for sessions whose source files are gone. Cost is written as part of the same database transaction as the rest of the session row.
Implications for Pricing Changes#
- Every sync reconciles costs with
defaultPricing(). Updating the pricing table causes storedestimated_cost_usdvalues to refresh on the next sync for all sessions where the model's rate or calculation logic changed. This happens without re-ingesting source files. - Session and activity costs update atomically.
refreshSessionCosts()checks both the session-row total and the persisted activity cost components (input_cost, output_cost), updating stale values in one transaction. Matching costs are left untouched. - Server invalidates caches and notifies clients after repricing, even when no transcript was ingested. Recommendations refresh to reflect repriced economics.
- Pipeline revision advances also refresh costs. When
INGEST_PIPELINE_REVISIONis incremented (e.g., to fix a parser bug like the Claude usage deduplication), the next sync reprocesses available sources from older revisions once, applying the current pricing table along with corrected token counts. Session IDs and archive state are generally preserved, though some revisions may intentionally correct session identity (e.g., separating forked Codex subagents from their parent sessions) and clean up previously misfiled records. Such corrections can change session totals and attribution but do not affect the cost-calculation rules themselves. Pricing GLM and Muse models bumped the revision (to 11), so archived sessions with those model IDs are repriced on the next sync. Adding the other lab rates advances the revision from 12 to 13: newly priceable Kimi and MiniMax IDs can change the primary model selected for Claude Code sessions, which also prices usage without per-request attribution and residual tokens. The next sync re-ingests available older-revision sources once to apply that attribution. - New sources that report neither token usage nor cost must surface cost as unavailable, not zero, per the add-source guide. The presentation tier is wired deliberately based on the source's capability report.
Key Files#
| File | Role |
|---|---|
src/cost.ts | estimateCost, estimateCostParts, defaultPricing, canonicalModel |
src/ingest.ts | Writes the per-model usage split and stores the resulting cost on the session row |
src/model-usage.ts | Derives and stores session_model_usage rows; sessionCostParts prices a session from them, falling back to session totals |
src/token-economics.ts | refreshSessionCosts reconciles stored costs with current pricing on sync |
src/schema.sql | estimated_cost_usd column definition |
docs/pricing.md | Human-readable rate tables and source verification notes |