Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

feat(tokens): show a list-price cost estimate beside reported cost

Claude3c30f281491d
diff --git a/CLAUDE.md b/CLAUDE.md
index 16f754ee..40d2f187 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -64,7 +64,7 @@ Supported runtime surfaces today:
- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.
- Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.
- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log.
-- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon token-usage` report command for local and CI logs.
+- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon token-usage` report command for local and CI logs. Every report row carries three costs (`cli/beacon/internal/tokens/cost.go`): `cost_usd` (runtime-reported, unchanged), `estimated_cost_usd` (list price of every priced token, from `internal/pricing`, computed after dedup and cumulative resolution) and `effective_cost_usd` with `cost_source` (per endpoint/harness/session scope, reported cost wins wholesale when the scope has any; otherwise the estimate; session-less events per event), plus `unpriced_events`/`unpriced_tokens` and a report-level `pricing` block (catalog provenance, per-model key, match, base rates, bands applied, fallbacks, unpriced models). Long-context bands apply only to events `requestScoped` classifies as one model request; it defaults to aggregate, so a new capture path is priced at base rates until it is added there with a test. Lens data (`LensDataV1`) carries no estimate.
- Local threat detection via `beacon scan`, which runs the open Threat Rules format (`spec/threat-rules`; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (`pkg/asymptoteobserve/threatrules`) ships in the binary; the rule corpus is external data loaded from a local store (`~/.beacon/endpoint/rules`) managed by `beacon rules`, so the corpus can grow without enlarging the binary. `scan` is read-only and offline; only the explicit, user-initiated `beacon rules pull <url>` reaches the network. A small frozen baseline is embedded so `scan` works before any rules are installed.
- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx` and `docs/concepts/session-handoff.mdx`). Every runtime is one entry in the registry in `cli/beacon/internal/handoff/runtimes.go`: its session source, the names it answers to, and the commands that reopen it or start it from a brief; `TestRegistryIsConsistent` checks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of `--agent`. `resume` reopens a session natively with its runtime's own command when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets `--auto-approve false`, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (`COPILOT_ALLOW_ALL`, `COPILOT_PLAN_THEN_AUTOPILOT`, `HERMES_YOLO_MODE`, `GOOSE_MODE`); `--print` shows them under `env`. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook and plugin prompt paths and the session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.
- Commit-to-session links via `beacon git setup|status|remove|link|notes` (`cli/beacon/internal/gitlink`, `cli/beacon/cmd/git*.go`; docs in `docs/cli/git.mdx`). A link is a `beacon:<harness>/<session-id>` line in a git note under `refs/notes/beacon`; it carries identifiers only, never content, because notes can be pushed. Which sessions to link is inferred from the local runtime log: a session is linked when, between the parent commit and the commit (at least two hours, at most 24), it wrote a file the commit changes (for a merge, only files that differ from every parent, so a clean merge or pull links nothing). Evidence is file write events, write-type `file.operation`s, plainly readable shell targets, and `apply_patch` envelopes; reads never count. Note updates are a compare-and-swap on the notes ref through a private `refs/notes/beacon-tx/` working ref, and every existing note line, a teammate's or a person's, is kept verbatim. `setup` installs post-commit (links HEAD in the foreground with a 3 s budget, silent, never fails the commit, skips rebase/cherry-pick/revert) and post-rewrite (normalizes the note git concatenates on amend) as standalone `beacon-<hook>` scripts called from a marked block inserted after the shebang of the repository's own hook; only shell hooks are edited, `core.hooksPath` is refused without `--hooks-path`, and `notes.rewriteRef` carries links through amend and rebase. `BEACON_GIT_HOOKS=0` disables the hooks for one command. Every link a run adds is also written to the runtime log as one `session.commit_linked` event in the linked session's timeline (`event.fidelity=inferred`, no collection method), with commit id, branch and credential-stripped remote in the OTel-shaped `vcs` block and overlap counts in `vcs.attribution`; the event deliberately carries no file, command or tool fields so it can never become attribution evidence. Sharing is opt-in (`setup --share-notes`, off by default): a non-destructive fetch refspec `+refs/notes/beacon:refs/notes/beacon-remotes/<remote>` so git's own fetch brings teammates' links into a read-only tracking ref that `beacon git notes` unions with the local one (never force-fetch into `refs/notes/beacon`: it would destroy unpushed links), and a pre-push hook that fetches, merges with `cat_sort_uniq` through the same CAS, and pushes only the notes ref with `--no-verify`, within a 10 s budget and never failing the push. That pre-push hook is the only Beacon git hook that touches the network, and only during a push the person started; `beacon git notes push|fetch` do the same by hand.
diff --git a/agent-skills/skills/beacon-lens-create/SKILL.md b/agent-skills/skills/beacon-lens-create/SKILL.md
index 7d2fe929..4ddd0678 100644
--- a/agent-skills/skills/beacon-lens-create/SKILL.md
+++ b/agent-skills/skills/beacon-lens-create/SKILL.md
@@ -114,7 +114,8 @@ Things that are easy to get wrong:
- **Do not sum `usage` across events for a total.** Some runtimes report the same tokens on two
channels or as cumulative counters. `token_usage.totals` is the deduplicated count; if you
also show per-event figures, say they can add up to more. `cost_usd` is only ever what the
- runtime reported; Beacon never estimates cost, and neither should a lens.
+ runtime reported. Lens data carries no estimate (Beacon's list-price estimates live in
+ `beacon token-usage` and the Tokens page), and a lens must not compute one.
- **`fidelity: "inferred"`** marks an action Beacon derived rather than observed (for example an
approval built from a pre-tool notification). Show the difference when it matters.
- **Pair calls with results on `tool_call_id`**, not on adjacency, and order by `number` or
diff --git a/cli/beacon/cmd/token_usage_cost_test.go b/cli/beacon/cmd/token_usage_cost_test.go
new file mode 100644
index 00000000..2e25c963
--- /dev/null
+++ b/cli/beacon/cmd/token_usage_cost_test.go
@@ -0,0 +1,71 @@
+package cmd
+
+import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+// A runtime that reports no cost must still get a cost in the report: a list-price estimate,
+// labeled as one, beside the runtime-reported figure rather than in place of it.
+func TestTokenUsageJSONCarriesListPriceEstimates(t *testing.T) {
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ lines := []string{
+ // Claude Code token metrics plus its own cost metric: the reported cost is authoritative.
+ `{"timestamp":"2026-06-11T10:00:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"hostname":"mac","os":"darwin"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"claude-1"},"model":"claude-sonnet-4-5","gen_ai":{"usage":{"input_tokens":100}},"message":"claude_code.token.usage","raw":{"metric_name":"claude_code.token.usage","metric_temporality":"Delta"}}`,
+ `{"timestamp":"2026-06-11T10:00:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"hostname":"mac","os":"darwin"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"claude-1"},"model":"claude-sonnet-4-5","gen_ai":{"usage":{"output_tokens":40}},"message":"claude_code.token.usage","raw":{"metric_name":"claude_code.token.usage","metric_temporality":"Delta"}}`,
+ `{"timestamp":"2026-06-11T10:00:05Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"cost.usage","category":"metric"},"severity":"info","endpoint":{"hostname":"mac","os":"darwin"},"harness":{"name":"claude_code","collection_method":"otlp"},"session":{"id":"claude-1"},"model":"claude-sonnet-4-5","gen_ai":{"usage":{"cost_usd":0.5}},"message":"claude_code.cost.usage","raw":{"metric_name":"claude_code.cost.usage","metric_temporality":"Delta"}}`,
+ // A Codex turn span: Codex reports no cost at all.
+ `{"timestamp":"2026-06-11T10:01:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"hostname":"mac","os":"darwin"},"harness":{"name":"codex_cli","collection_method":"otlp"},"session":{"id":"codex-1"},"model":"gpt-5","gen_ai":{"usage":{"input_tokens":1000,"output_tokens":200,"cache_read":{"input_tokens":4000}}},"message":"codex.turn.token_usage","raw":{"source":"codex_turn_span","turn_id":"turn-1"}}`,
+ }
+ if err := os.WriteFile(logPath, []byte(strings.Join(lines, "\n")+"\n"), 0o644); err != nil {
+ t.Fatalf("write fixture log: %v", err)
+ }
+ output := runTokenUsageCommand(t, "--log-path", logPath, "--json")
+ var report map[string]interface{}
+ if err := json.Unmarshal([]byte(output), &report); err != nil {
+ t.Fatalf("unmarshal JSON report: %v\n%s", err, output)
+ }
+ totals, _ := report["totals"].(map[string]interface{})
+ // Claude: 100 x $3 + 40 x $15 per MTok = $0.0009. Codex gpt-5: 1000 x $1.25 + 4000 x
+ // $0.125 + 200 x $10 per MTok = $0.00375. The estimate covers both: $0.00465.
+ if got, ok := totals["estimated_cost_usd"].(float64); !ok || got != 0.00465 {
+ t.Fatalf("totals.estimated_cost_usd = %#v, want 0.00465\n%s", totals["estimated_cost_usd"], output)
+ }
+ // Effective: Claude's reported $0.5 replaces its estimate; Codex contributes its estimate.
+ if got, ok := totals["effective_cost_usd"].(float64); !ok || got != 0.50375 {
+ t.Fatalf("totals.effective_cost_usd = %#v, want 0.50375", totals["effective_cost_usd"])
+ }
+ if got := totals["cost_source"]; got != "mixed" {
+ t.Fatalf("totals.cost_source = %#v, want mixed", got)
+ }
+ // cost_usd keeps its meaning: what runtimes reported, nothing else.
+ if got := totals["cost_usd"]; got != 0.5 {
+ t.Fatalf("totals.cost_usd = %#v, want the reported 0.5 only", got)
+ }
+ pricingBlock, _ := report["pricing"].(map[string]interface{})
+ catalog, _ := pricingBlock["catalog"].(map[string]interface{})
+ if commit, _ := catalog["commit"].(string); commit == "" || catalog["generated_at"] == nil {
+ t.Fatalf("pricing.catalog lacks provenance: %#v", pricingBlock)
+ }
+}
+
+func TestTokenUsageTextLabelsReportedAndEstimatedCost(t *testing.T) {
+ logPath := writeTokensFixtureLog(t)
+ output := runTokenUsageCommand(t, "--log-path", logPath)
+ for _, want := range []string{
+ "COST USD",
+ "EST COST USD",
+ "COST USD is what the runtimes reported",
+ "list price",
+ "1h cache writes are priced at the 5m rate",
+ // 100 input + 40 output tokens of claude-sonnet-4-5 at $3/$15 per MTok.
+ "0.0009",
+ } {
+ if !strings.Contains(output, want) {
+ t.Fatalf("text report missing %q:\n%s", want, output)
+ }
+ }
+}
diff --git a/cli/beacon/internal/endpoint/dashboard/lenses/token-usage.lens.html b/cli/beacon/internal/endpoint/dashboard/lenses/token-usage.lens.html
index 8ad11bde..14e947d5 100644
--- a/cli/beacon/internal/endpoint/dashboard/lenses/token-usage.lens.html
+++ b/cli/beacon/internal/endpoint/dashboard/lenses/token-usage.lens.html
@@ -219,7 +219,7 @@
};
}), { cells: [el("td"), el("td"), el("td", "Reported by events"), el("td")], usage: reported }));
if (data.truncated) root.appendChild(el("p", "This trace was truncated; later line items are missing.", "muted"));
- if (n(totals, "cost_usd")) root.appendChild(el("p", "Costs are what the runtime reported. Beacon never estimates cost.", "muted"));
+ if (n(totals, "cost_usd")) root.appendChild(el("p", "Costs are what the runtime reported. List-price estimates are on the Tokens page, not in lens data.", "muted"));
finish();
}
diff --git a/cli/beacon/internal/endpoint/dashboard/server_test.go b/cli/beacon/internal/endpoint/dashboard/server_test.go
index 8e66afce..fea85373 100644
--- a/cli/beacon/internal/endpoint/dashboard/server_test.go
+++ b/cli/beacon/internal/endpoint/dashboard/server_test.go
@@ -2,6 +2,7 @@ package dashboard
import (
"encoding/json"
+ "math"
"net/http"
"net/http/httptest"
"os"
@@ -267,6 +268,16 @@ func TestTokensEndpointAggregatesUsage(t *testing.T) {
if report.Totals.InputTokens != 160 || report.Totals.OutputTokens != 60 || report.Totals.CostUSD != 0.5 {
t.Fatalf("totals = %#v", report.Totals)
}
+ // The list-price estimate rides beside the reported cost: claude-sonnet-4-5 100 x $3 + 40 x
+ // $15 per MTok, plus gpt-4o-mini 60 x $0.15 + 20 x $0.60 = $0.000921. The Claude session
+ // reported its cost, so its effective cost is that; the cloud session's is its estimate.
+ if report.Totals.EstimatedCostUSD != 0.000921 || report.Totals.CostSource != tokens.CostSourceMixed ||
+ math.Abs(report.Totals.EffectiveCostUSD-0.500021) > 1e-12 {
+ t.Fatalf("cost fields = %#v", report.Totals)
+ }
+ if report.Pricing == nil || report.Pricing.Catalog.Commit == "" || len(report.Pricing.Models) != 2 {
+ t.Fatalf("pricing = %#v", report.Pricing)
+ }
if len(report.ByModel) != 2 || report.ByModel[0].Key != "claude-sonnet-4-5" {
t.Fatalf("by_model = %#v", report.ByModel)
}
diff --git a/cli/beacon/internal/endpoint/dashboard/static/app.js b/cli/beacon/internal/endpoint/dashboard/static/app.js
index 1d711b4f..71659041 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/app.js
+++ b/cli/beacon/internal/endpoint/dashboard/static/app.js
@@ -1990,7 +1990,7 @@ function renderSessionMetadata(session, events) {
},
{ label: "Model", value: models.length ? escapeHTML(models.join(", ")) : `<span class="muted">-</span>`, className: "mono" },
{ label: "Tokens", value: usage.tokens ? escapeHTML(formatCompactTokens(usage.tokens)) : `<span class="muted">-</span>` },
- { label: "Est. Cost", value: usage.cost ? `$${escapeHTML(usage.cost.toFixed(4))}` : `<span class="muted">-</span>` },
+ { label: "Reported Cost", value: usage.cost ? `$${escapeHTML(usage.cost.toFixed(4))}` : `<span class="muted">-</span>` },
{ label: "Repository", value: session.repository ? escapeHTML(repositoryOptionLabel(session.repository)) : `<span class="muted">-</span>`, className: "mono" },
{ label: "Branch", value: session.branch ? escapeHTML(session.branch) : `<span class="muted">-</span>`, className: "mono" },
];
@@ -2570,7 +2570,7 @@ async function loadTokens() {
function renderTokensPage(report, session) {
setText("#log-path", state.status?.log_path || "Runtime log unavailable");
setText("#token-meta", `${report.events_with_usage} of ${report.total_events} events carry usage`);
- renderTokenCards(report.totals || {});
+ renderTokenCards(report.totals || {}, report.pricing);
renderTokenThroughput(report.series || []);
renderTokenSplit(report.totals || {});
renderTokenBreakdowns(report);
@@ -2591,7 +2591,22 @@ function usageTotal(usage = {}) {
(usage.reasoning_output_tokens || 0);
}
-function renderTokenCards(totals) {
+// The estimate is labeled wherever it appears: it is a list price from the embedded catalog,
+// not what anyone was billed, and it sits beside the runtime-reported cost rather than in it.
+function estimateHint(totals, pricing) {
+ const parts = ["list price"];
+ const catalog = pricing?.catalog;
+ if (catalog?.generated_at) parts.push(`catalog ${catalog.generated_at}`);
+ if (totals.unpriced_events) parts.push(`${totals.unpriced_events} unpriced events excluded`);
+ return parts.join(" · ");
+}
+
+function formatEstimatedCost(usage = {}) {
+ if (usage.estimated_cost_usd) return `~${usage.estimated_cost_usd.toFixed(4)}`;
+ return usage.unpriced_events ? "?" : "-";
+}
+
+function renderTokenCards(totals, pricing) {
if (!$("#token-cards")) return;
const totalTokens = usageTotal(totals);
const cards = [
@@ -2600,7 +2615,8 @@ function renderTokenCards(totals) {
{ label: "Output Tokens", value: formatTokens((totals.output_tokens || 0) + (totals.reasoning_output_tokens || 0)), hint: "completion + reasoning" },
{ label: "Cached Tokens", value: formatTokens((totals.cache_read_input_tokens || 0) + (totals.cache_creation_input_tokens || 0)) },
{ label: "Reasoning", value: formatTokens(totals.reasoning_output_tokens) },
- { label: "Cost (USD)", value: totals.cost_usd ? totals.cost_usd.toFixed(4) : "-", hint: "runtime-reported only" },
+ { label: "Reported cost (USD)", value: totals.cost_usd ? totals.cost_usd.toFixed(4) : "-", hint: "runtime-reported only" },
+ { label: "Est. cost (USD)", value: formatEstimatedCost(totals), hint: estimateHint(totals, pricing) },
];
$("#token-cards").innerHTML = cards
.map((card) => `
@@ -2811,7 +2827,7 @@ function renderUsageGroupRows(selector, groups, filterKey) {
const tbody = $(selector);
if (!tbody) return;
if (!groups.length) {
- tbody.innerHTML = `<tr><td colspan="8" class="muted">No usage captured yet.</td></tr>`;
+ tbody.innerHTML = `<tr><td colspan="9" class="muted">No usage captured yet.</td></tr>`;
return;
}
tbody.innerHTML = groups
@@ -2857,7 +2873,7 @@ function renderSessionDetail(detail, session) {
walk(detail.steps, 0);
$("#token-session-detail").innerHTML = rows.length
? rows.join("")
- : `<tr><td colspan="8" class="muted">No usage-bearing steps in this session.</td></tr>`;
+ : `<tr><td colspan="9" class="muted">No usage-bearing steps in this session.</td></tr>`;
}
function usageCells(usage = {}, { events = true } = {}) {
@@ -2868,6 +2884,7 @@ function usageCells(usage = {}, { events = true } = {}) {
formatTokens(usage.cache_creation_input_tokens),
formatTokens(usage.reasoning_output_tokens),
usage.cost_usd ? usage.cost_usd.toFixed(4) : "-",
+ formatEstimatedCost(usage),
];
if (events) cells.push(String(usage.events ?? 0));
return cells.map((value) => `<td>${escapeHTML(value)}</td>`).join("");
diff --git a/cli/beacon/internal/endpoint/dashboard/static/tokens.html b/cli/beacon/internal/endpoint/dashboard/static/tokens.html
index 2d667756..d8c933c7 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/tokens.html
+++ b/cli/beacon/internal/endpoint/dashboard/static/tokens.html
@@ -40,7 +40,7 @@
<section class="dashboard-hero analytics-hero">
<div>
<h2>Token usage analytics</h2>
- <p class="muted">Token consumption, runtime-reported cost, cache usage, and context-window pressure across local AI agents.</p>
+ <p class="muted">Token consumption, runtime-reported and list-price estimated cost, cache usage, and context-window pressure across local AI agents.</p>
</div>
<div class="range-pills" aria-label="Local token analytics range">
<span class="active">Local log</span>
@@ -59,7 +59,7 @@
<div class="section-head overview-head">
<div>
<h2>Token Totals</h2>
- <p class="muted">Prompt, completion, cache, reasoning, and runtime-reported cost across all captured telemetry.</p>
+ <p class="muted">Prompt, completion, cache, reasoning, runtime-reported cost and a list-price estimate across all captured telemetry.</p>
</div>
<div id="token-meta" class="muted"></div>
</div>
@@ -108,7 +108,7 @@
<h2>By Model</h2>
<table>
<thead>
- <tr><th>Model</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th><th>Events</th></tr>
+ <tr><th>Model</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th><th>Events</th></tr>
</thead>
<tbody id="token-models"></tbody>
</table>
@@ -119,7 +119,7 @@
<p class="muted">Select a session to inspect per-step usage.</p>
<table>
<thead>
- <tr><th>Session</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th><th>Events</th></tr>
+ <tr><th>Session</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th><th>Events</th></tr>
</thead>
<tbody id="token-sessions"></tbody>
</table>
@@ -129,7 +129,7 @@
<h2>By User</h2>
<table>
<thead>
- <tr><th>User</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th><th>Events</th></tr>
+ <tr><th>User</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th><th>Events</th></tr>
</thead>
<tbody id="token-users"></tbody>
</table>
@@ -139,7 +139,7 @@
<h2 id="token-session-title">Session Detail</h2>
<table>
<thead>
- <tr><th>Step</th><th>Model</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th></tr>
+ <tr><th>Step</th><th>Model</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th></tr>
</thead>
<tbody id="token-session-detail"></tbody>
</table>
@@ -149,7 +149,7 @@
<h2>By CI Run</h2>
<table>
<thead>
- <tr><th>Run</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th><th>Events</th></tr>
+ <tr><th>Run</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th><th>Events</th></tr>
</thead>
<tbody id="token-runs"></tbody>
</table>
@@ -159,7 +159,7 @@
<h2>By Harness</h2>
<table>
<thead>
- <tr><th>Harness</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th>Cost USD</th><th>Events</th></tr>
+ <tr><th>Harness</th><th>Input</th><th>Output</th><th>Cache Read</th><th>Cache Create</th><th>Reasoning</th><th title="What the runtime reported">Reported USD</th><th title="List-price estimate from the embedded catalog">Est. USD</th><th>Events</th></tr>
</thead>
<tbody id="token-harnesses"></tbody>
</table>
diff --git a/cli/beacon/internal/endpoint/dashboard/testdata/lens-e2e/tests/builtin-token-usage.spec.ts b/cli/beacon/internal/endpoint/dashboard/testdata/lens-e2e/tests/builtin-token-usage.spec.ts
index 66a7c7a0..a9a97344 100644
--- a/cli/beacon/internal/endpoint/dashboard/testdata/lens-e2e/tests/builtin-token-usage.spec.ts
+++ b/cli/beacon/internal/endpoint/dashboard/testdata/lens-e2e/tests/builtin-token-usage.spec.ts
@@ -25,7 +25,7 @@ test('token usage: counted totals, by model, by turn and line items', async ({ p
const items = tables.nth(3);
await expect(items.locator('tbody tr')).toHaveCount(2);
await expect(items.locator('tfoot')).toContainText('Reported by events');
- await expect(frame.locator('#root')).toContainText('Beacon never estimates cost.');
+ await expect(frame.locator('#root')).toContainText('Costs are what the runtime reported. List-price estimates are on the Tokens page, not in lens data.');
});
test('token usage: a runtime that should report usage but did not is flagged', async ({ page }) => {
diff --git a/cli/beacon/internal/tokens/cost.go b/cli/beacon/internal/tokens/cost.go
new file mode 100644
index 00000000..87888259
--- /dev/null
+++ b/cli/beacon/internal/tokens/cost.go
@@ -0,0 +1,390 @@
+package tokens
+
+import (
+ "sort"
+ "strings"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+ "github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
+)
+
+// Cost provenance.
+//
+// A report carries a runtime-reported cost (cost_usd), a list-price estimate
+// (estimated_cost_usd) and an effective cost made of one or the other. The estimate exists so
+// that runtimes which never report a price -- Codex, DeepSeek Harness, OpenClaw, Factory, Gemini
+// CLI and Copilot before it reported AI credits among them -- do not read as free. It is
+// report-time arithmetic over the final per-event deltas and is never written back into an
+// event: gen_ai.usage.cost_usd stays what the runtime said.
+//
+// The effective cost follows one rule. Within one (endpoint, harness, session) scope, if any
+// event reported a cost, the scope's cost is what the runtime reported and the estimate takes no
+// part in it: a runtime's own figure knows its plan, its discounts and its routing, which a list
+// price cannot. That is also what keeps Claude Code correct, whose cost arrives on a separate
+// cost metric beside token events that carry none: the scope is reported, so its token events
+// add nothing on top. A scope with no reported cost contributes its estimate. Events without a
+// session have no scope and are judged one at a time.
+
+// Values of Usage.CostSource.
+const (
+ CostSourceReported = "reported"
+ CostSourceEstimated = "estimated"
+ CostSourceMixed = "mixed"
+)
+
+// PricingTier names the price list an estimate is drawn from. Batch, flex and priority tiers,
+// regional surcharges and subscription plans are not modelled: nothing in a usage record says a
+// call used them.
+const PricingTier = "standard"
+
+// priceCatalog is the catalog estimates are priced from; a variable so tests can substitute one.
+var priceCatalog = pricing.Default
+
+// PricingSummary is the report's account of its estimates.
+type PricingSummary struct {
+ Catalog PricingCatalog `json:"catalog"`
+ Tier string `json:"tier"`
+ // Models lists every model the estimate priced, sorted by model.
+ Models []ModelPricing `json:"models,omitempty"`
+ // Unpriced lists the models the estimate could not price, sorted by model. Their tokens are
+ // in every token total and in no estimate.
+ Unpriced []UnpricedModel `json:"unpriced,omitempty"`
+}
+
+// PricingCatalog is the provenance of the embedded price list.
+type PricingCatalog struct {
+ Name string `json:"name"`
+ License string `json:"license"`
+ URL string `json:"url"`
+ Commit string `json:"commit,omitempty"`
+ FetchedAt string `json:"fetched_at"`
+ GeneratedAt string `json:"generated_at"`
+}
+
+// RatesPerMTok is a rate set in US dollars per million tokens. A zero cache rate means the
+// provider publishes none, and the estimate priced those tokens by the fallback the model's
+// Fallbacks name.
+type RatesPerMTok struct {
+ Input float64 `json:"input"`
+ Output float64 `json:"output"`
+ CacheRead float64 `json:"cache_read,omitempty"`
+ CacheWrite float64 `json:"cache_write,omitempty"`
+ CacheWrite1h float64 `json:"cache_write_1h,omitempty"`
+}
+
+// BandUse counts the requests a long-context band priced.
+type BandUse struct {
+ AboveTokens int64 `json:"above_tokens"`
+ Requests int `json:"requests"`
+}
+
+// ModelPricing is how one reported model was priced.
+type ModelPricing struct {
+ // Model is the model as the report groups it; Key is the catalog entry that priced it.
+ Model string `json:"model"`
+ Key string `json:"key"`
+ Provider string `json:"provider"`
+ Match string `json:"match"`
+ Stripped []string `json:"stripped,omitempty"`
+ // Rates are the base rates. A request priced in a long-context band used that band's rates
+ // instead, and is counted in BandsApplied.
+ Rates RatesPerMTok `json:"rates_usd_per_mtok"`
+ // Events is the number of priced usage events; RequestScopedEvents those known to be one
+ // model request, the only ones a band can apply to.
+ Events int `json:"events"`
+ RequestScopedEvents int `json:"request_scoped_events"`
+ BandsApplied []BandUse `json:"bands_applied,omitempty"`
+ // Fallbacks names each missing-rate fallback that priced a non-zero count:
+ // cache_read_at_input_rate, cache_write_at_input_rate, reasoning_at_output_rate.
+ Fallbacks []string `json:"fallbacks,omitempty"`
+ EstimatedCostUSD float64 `json:"estimated_cost_usd"`
+
+ estimated pricing.Microdollars
+ bands map[int64]int
+ fallbacks map[string]bool
+}
+
+// UnpricedModel is a model the estimate could not price. Model is empty for usage that named no
+// model at all; Candidates is set when several catalog entries matched with different prices.
+type UnpricedModel struct {
+ Model string `json:"model"`
+ Events int `json:"events"`
+ Tokens int64 `json:"tokens"`
+ Candidates []string `json:"candidates,omitempty"`
+}
+
+// settle derives the exported cost fields from the exact internal sums.
+func (u *Usage) settle() {
+ u.EstimatedCostUSD = u.estimated.USD()
+ u.EffectiveCostUSD = u.effectiveReported + u.effectiveEstimated.USD()
+ switch {
+ case u.reportedEvents > 0 && u.estimatedEvents > 0:
+ u.CostSource = CostSourceMixed
+ case u.reportedEvents > 0:
+ u.CostSource = CostSourceReported
+ case u.estimatedEvents > 0:
+ u.CostSource = CostSourceEstimated
+ default:
+ u.CostSource = ""
+ }
+}
+
+// pricedTokens is the token count an estimate covers: the disjoint total, plus reasoning when
+// it is the only output reported (pricing bills it as output then; otherwise it is inside output).
+func pricedTokens(u Usage) int64 {
+ n := u.TotalTokens()
+ if u.OutputTokens == 0 {
+ n += u.ReasoningOutputTokens
+ }
+ return n
+}
+
+// Harness names whose usage events requestScoped knows the granularity of.
+var (
+ piFamilyHarnesses = map[string]bool{"pi_cli": true, "omp": true, "prime_agent": true, "omo_senpi": true}
+ claudeOTelHarness = map[string]bool{"claude_code": true, "claude_cowork": true}
+)
+
+// requestScoped reports whether an event's usage is exactly one model request, which is the
+// only case a long-context band can be applied to (see pricing.Cost). It is decided per capture
+// path from what that path is known to record, and defaults to false: pricing a sum of requests
+// at base rates can understate a session that sent long prompts, while banding a sum would
+// overstate every session that merely sent many short ones.
+//
+// Request-scoped:
+// - Claude Code and Claude Cowork claude_code.api_request log records (one per API request),
+// and Claude Code session-file usage, which is the usage block of one assistant API response.
+// - Codex session-file token_count records: last_token_usage is one completion, and the
+// fallback difference between consecutive cumulative totals spans the one completion
+// between them.
+// - Pi-family message_end usage (Pi, Oh My Pi, Prime Agent, Senpi) and their session-file
+// usage: one finalized assistant message is one model call.
+// - OpenCode usage: each assistant message is one LLM step, and its tokens are that step's.
+// - OpenClaw session-file usage, recorded per assistant message.
+// - DeepSeek Harness usage from one assistant message.
+//
+// Aggregate, priced at base rates: every metric datapoint (an interval sum, cumulative ones
+// already differenced), Codex turn spans and token_usage_record turn totals, OpenClaw's
+// llm_output hook (one report per turn, across the turn's tool loop), Cline task totals,
+// Copilot shutdown deltas and assistant output counts, Hermes, Factory and fx cumulative or
+// per-turn deltas, Cursor Admin API usage, and any OTLP span of unknown granularity.
+func requestScoped(ue *usageEvent) bool {
+ if ue.metricName != "" || ue.cumulative {
+ return false
+ }
+ harness := asymptoteobserve.NormalizeHarnessName(ue.harness)
+ poll := strings.EqualFold(ue.collectionMethod, schema.CollectionMethodPoll)
+ switch {
+ case claudeOTelHarness[harness]:
+ if harness == "claude_code" && poll {
+ return true
+ }
+ name := strings.ToLower(strings.TrimSpace(ue.name))
+ return name == "claude_code.api_request" || name == "api_request"
+ case harness == "codex_cli" || harness == "codex_desktop":
+ return ue.codexSessionSource == "codex_session_token_count"
+ case piFamilyHarnesses[harness]:
+ // The hook path also attaches usage to a tool result when a build sends one there; that
+ // one is not known to be a single request.
+ return ue.action == "token.usage" || poll
+ case harness == "opencode":
+ return true
+ case harness == "openclaw_gateway":
+ return poll
+ case harness == "deepseek_harness":
+ return ue.tokenSource == "assistant_message"
+ }
+ return false
+}
+
+type costScopeKey struct {
+ endpoint string
+ harness string
+ session string
+}
+
+func costScope(ue *usageEvent) (costScopeKey, bool) {
+ session := strings.ToLower(strings.TrimSpace(ue.session))
+ if session == "" {
+ return costScopeKey{}, false
+ }
+ return costScopeKey{
+ endpoint: strings.ToLower(strings.TrimSpace(ue.endpoint)),
+ harness: asymptoteobserve.NormalizeHarnessName(ue.harness),
+ session: session,
+ }, true
+}
+
+type resolvedModel struct {
+ res pricing.Resolution
+ priced bool
+}
+
+// priceUsageEvents sets every usage event's estimated and effective cost and returns the
+// report's pricing summary. Context-only events are not spend and are skipped.
+func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSummary {
+ source := catalog.Source()
+ summary := &PricingSummary{
+ Catalog: PricingCatalog{
+ Name: source.Name,
+ License: source.License,
+ URL: source.URL,
+ Commit: source.Commit,
+ FetchedAt: source.FetchedAt,
+ GeneratedAt: catalog.GeneratedAt(),
+ },
+ Tier: PricingTier,
+ }
+
+ reportedScopes := map[costScopeKey]bool{}
+ for _, ue := range events {
+ if ue.contextOnly || ue.usage.CostUSD <= 0 {
+ continue
+ }
+ if key, ok := costScope(ue); ok {
+ reportedScopes[key] = true
+ }
+ }
+
+ lookups := map[string]resolvedModel{}
+ models := map[string]*ModelPricing{}
+ unpriced := map[string]*UnpricedModel{}
+ for _, ue := range events {
+ if ue.contextOnly {
+ continue
+ }
+ u := &ue.usage
+ tokens := pricedTokens(*u)
+ priced := false
+ if tokens > 0 {
+ resolved, seen := lookups[ue.model]
+ if !seen {
+ resolved.res, resolved.priced = catalog.Lookup(ue.model)
+ lookups[ue.model] = resolved
+ }
+ if resolved.priced {
+ scoped := requestScoped(ue)
+ est := pricing.Cost(resolved.res.Rates, pricing.Tokens{
+ Input: u.InputTokens,
+ Output: u.OutputTokens,
+ CacheRead: u.CacheReadInputTokens,
+ CacheCreation: u.CacheCreationInputTokens,
+ // gen_ai.usage does not carry the one-hour cache-write split yet, so every
+ // write is priced at the five-minute rate.
+ CacheCreation1h: 0,
+ Reasoning: u.ReasoningOutputTokens,
+ }, scoped)
+ // A saturated estimate means the counts are corrupt; it is not a price.
+ if !est.Saturated {
+ priced = true
+ u.estimated = est.Cost
+ models[ue.model] = recordModelPricing(models[ue.model], ue.model, resolved.res, scoped, est)
+ }
+ }
+ if !priced {
+ u.UnpricedEvents = 1
+ u.UnpricedTokens = tokens
+ entry := unpriced[ue.model]
+ if entry == nil {
+ entry = &UnpricedModel{Model: ue.model, Candidates: resolved.res.Candidates}
+ unpriced[ue.model] = entry
+ }
+ entry.Events++
+ entry.Tokens += tokens
+ }
+ }
+
+ reported := u.CostUSD > 0
+ if key, ok := costScope(ue); ok {
+ reported = reportedScopes[key]
+ }
+ switch {
+ case reported:
+ u.effectiveReported = u.CostUSD
+ u.reportedEvents = 1
+ case priced:
+ u.effectiveEstimated = u.estimated
+ u.estimatedEvents = 1
+ }
+ u.settle()
+ }
+
+ for _, model := range sortedKeys(models) {
+ m := models[model]
+ m.EstimatedCostUSD = m.estimated.USD()
+ for _, above := range sortedInt64Keys(m.bands) {
+ m.BandsApplied = append(m.BandsApplied, BandUse{AboveTokens: above, Requests: m.bands[above]})
+ }
+ for _, name := range sortedKeys(m.fallbacks) {
+ m.Fallbacks = append(m.Fallbacks, name)
+ }
+ summary.Models = append(summary.Models, *m)
+ }
+ for _, model := range sortedKeys(unpriced) {
+ summary.Unpriced = append(summary.Unpriced, *unpriced[model])
+ }
+ return summary
+}
+
+func recordModelPricing(m *ModelPricing, model string, res pricing.Resolution, scoped bool, est pricing.Estimate) *ModelPricing {
+ if m == nil {
+ m = &ModelPricing{
+ Model: model,
+ Key: res.Key,
+ Provider: res.Rates.Provider,
+ Match: string(res.Match),
+ Stripped: append([]string(nil), res.Stripped...),
+ Rates: ratesPerMTok(res.Rates.RateSet),
+ bands: map[int64]int{},
+ fallbacks: map[string]bool{},
+ }
+ }
+ m.Events++
+ if scoped {
+ m.RequestScopedEvents++
+ }
+ if est.BandAboveTokens > 0 {
+ m.bands[est.BandAboveTokens]++
+ }
+ if est.CacheReadAtInputRate {
+ m.fallbacks["cache_read_at_input_rate"] = true
+ }
+ if est.CacheWriteAtInputRate {
+ m.fallbacks["cache_write_at_input_rate"] = true
+ }
+ if est.ReasoningAtOutputRate {
+ m.fallbacks["reasoning_at_output_rate"] = true
+ }
+ m.estimated += est.Cost
+ return m
+}
+
+func ratesPerMTok(set pricing.RateSet) RatesPerMTok {
+ usd := func(v int64) float64 { return pricing.Microdollars(v).USD() }
+ return RatesPerMTok{
+ Input: usd(set.Input),
+ Output: usd(set.Output),
+ CacheRead: usd(set.CacheRead),
+ CacheWrite: usd(set.CacheWrite),
+ CacheWrite1h: usd(set.CacheWrite1h),
+ }
+}
+
+func sortedKeys[V any](m map[string]V) []string {
+ keys := make([]string, 0, len(m))
+ for k := range m {
+ keys = append(keys, k)
+ }
+ sort.Strings(keys)
+ return keys
+}
+
+func sortedInt64Keys(m map[int64]int) []int64 {
+ keys := make([]int64, 0, len(m))
+ for k := range m {
+ keys = append(keys, k)
+ }
+ sort.Slice(keys, func(i, j int) bool { return keys[i] < keys[j] })
+ return keys
+}
diff --git a/cli/beacon/internal/tokens/cost_test.go b/cli/beacon/internal/tokens/cost_test.go
new file mode 100644
index 00000000..aa8c76e0
--- /dev/null
+++ b/cli/beacon/internal/tokens/cost_test.go
@@ -0,0 +1,497 @@
+package tokens
+
+import (
+ "encoding/json"
+ "math"
+ "reflect"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+)
+
+// The expected figures below are worked by hand from the embedded catalog's rates, which are
+// quoted in each case (USD per million tokens). A catalog regeneration that moves one of these
+// rates is a reviewable change to this file.
+
+func withUsage(input, output, cacheRead, cacheCreation, reasoning int64, cost float64) func(*schema.Event) {
+ return func(e *schema.Event) {
+ u := e.GenAI.Usage
+ if input != 0 {
+ u.InputTokens = int64Ptr(input)
+ }
+ if output != 0 {
+ u.OutputTokens = int64Ptr(output)
+ }
+ if cacheRead != 0 {
+ u.CacheRead = &schema.GenAIUsageCacheReadInfo{InputTokens: int64Ptr(cacheRead)}
+ }
+ if cacheCreation != 0 {
+ u.CacheCreation = &schema.GenAIUsageCacheCreationInfo{InputTokens: int64Ptr(cacheCreation)}
+ }
+ if reasoning != 0 {
+ u.Reasoning = &schema.GenAIUsageReasoningInfo{OutputTokens: int64Ptr(reasoning)}
+ }
+ if cost != 0 {
+ u.CostUSD = float64Ptr(cost)
+ }
+ }
+}
+
+func chain(mutators ...func(*schema.Event)) func(*schema.Event) {
+ return func(e *schema.Event) {
+ for _, m := range mutators {
+ m(e)
+ }
+ }
+}
+
+func metricRaw(name, temporality string) func(*schema.Event) {
+ return func(e *schema.Event) {
+ e.Raw = map[string]interface{}{"metric_name": name, "metric_temporality": temporality}
+ }
+}
+
+func collected(method string) func(*schema.Event) {
+ return func(e *schema.Event) { e.Harness.CollectionMethod = method }
+}
+
+func usd(micro int64) float64 { return pricing.Microdollars(micro).USD() }
+
+func approxEqual(a, b float64) bool { return math.Abs(a-b) < 1e-9 }
+
+func TestAggregateCostEstimatesPerRuntimeShape(t *testing.T) {
+ type want struct {
+ estimated int64 // microdollars
+ effective float64
+ reported float64
+ source string
+ unpricedEvent int
+ unpricedTok int64
+ // model -> requests priced in a band
+ bands map[string][]BandUse
+ // model -> request-scoped event count
+ scoped map[string]int
+ }
+ cases := []struct {
+ name string
+ events []schema.Event
+ want want
+ }{
+ {
+ // claude_code.api_request carries the tokens (one request), the token metric repeats
+ // them (deduplicated away), and claude_code.cost.usage carries the cost. claude-opus-4-6:
+ // $5 in, $25 out, $0.50 cache read, $6.25 cache write, no band.
+ // 11x5 + 826x25 + 119393x0.5 + 15751x6.25 = 178845.25 -> 178845 microdollars.
+ name: "claude code api_request log plus cost metric",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-opus-4-6", chain(
+ withUsage(11, 826, 119393, 15751, 0, 0), collected("otlp"),
+ func(e *schema.Event) { e.Event.Action = "tool.invoked"; e.Message = "claude_code.api_request" })),
+ usageEventFixture("2026-06-11T10:00:05Z", "claude_code", "s1", "claude-opus-4-6[1m]", chain(
+ withUsage(11, 0, 0, 0, 0, 0), collected("otlp"), metricRaw("claude_code.token.usage", "Delta"))),
+ usageEventFixture("2026-06-11T10:00:05Z", "claude_code", "s1", "claude-opus-4-6[1m]", chain(
+ withUsage(0, 0, 0, 0, 0, 0.1788), collected("otlp"), metricRaw("claude_code.cost.usage", "Delta"))),
+ },
+ want: want{estimated: 178845, effective: 0.1788, reported: 0.1788, source: CostSourceReported,
+ scoped: map[string]int{"claude-opus-4-6": 1}},
+ },
+ {
+ // Metrics only: the tokens arrive as per-type datapoints, which are interval sums and
+ // priced at base rates. claude-sonnet-4-5: $3 in, $15 out.
+ // 250000x3 + 2000x15 = 780000 microdollars -- no band despite 250k, as the metric is not
+ // one request. The reported cost still wins the effective figure.
+ name: "claude code metric-only path",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(250000, 0, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Delta"))),
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(0, 2000, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Delta"))),
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(0, 0, 0, 0, 0, 0.9), metricRaw("claude_code.cost.usage", "Delta"))),
+ },
+ want: want{estimated: 780000, effective: 0.9, reported: 0.9, source: CostSourceReported,
+ scoped: map[string]int{"claude-sonnet-4-5": 0}},
+ },
+ {
+ // A Codex turn span sums the turn's requests, so even a 300k-token turn is priced at
+ // base rates. gpt-5.5: $5 in, $30 out, $0.50 cache read (band above 272k: $10/$45/$1).
+ // 100000x5 + 200000x0.5 + 1000x30 = 630000 microdollars.
+ name: "codex turn span is aggregate",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "codex_cli", "c1", "gpt-5.5", chain(
+ withUsage(100000, 1000, 200000, 0, 400, 0), collected("otlp"),
+ func(e *schema.Event) {
+ e.Message = "codex.turn.token_usage"
+ e.Raw = map[string]interface{}{"source": "codex_turn_span", "turn_id": "t1"}
+ })),
+ },
+ want: want{estimated: 630000, effective: 0.63, source: CostSourceEstimated,
+ scoped: map[string]int{"gpt-5.5": 0}},
+ },
+ {
+ // The same tokens from a Codex session-file token_count are one completion, so the
+ // 300k prompt is billed in the long-context band for every token:
+ // 100000x10 + 200000x1 + 1000x45 = 1245000 microdollars. Reasoning (400) is inside
+ // output and not billed again.
+ name: "codex session token_count is one request and banded",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "codex_cli", "c1", "gpt-5.5", chain(
+ withUsage(100000, 1000, 200000, 0, 400, 0), collected("poll"),
+ func(e *schema.Event) {
+ e.Raw = map[string]interface{}{"codex_session": map[string]interface{}{"source": "codex_session_token_count"}}
+ })),
+ },
+ want: want{estimated: 1245000, effective: 1.245, source: CostSourceEstimated,
+ bands: map[string][]BandUse{"gpt-5.5": {{AboveTokens: 272000, Requests: 1}}},
+ scoped: map[string]int{"gpt-5.5": 1}},
+ },
+ {
+ // Copilot's shutdown record is a session-total delta: base rates even above 272k.
+ // gpt-5.4: $2.50 in, $15 out, $0.25 cache read. 280000x2.5 + 5000x15 = 775000.
+ name: "copilot shutdown aggregate stays at base rates",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "copilot_cli", "p1", "gpt-5.4", chain(
+ withUsage(280000, 5000, 0, 0, 0, 0), collected("poll"),
+ func(e *schema.Event) {
+ e.Raw = map[string]interface{}{"token_source": "session_shutdown_model_metrics_delta"}
+ })),
+ },
+ want: want{estimated: 775000, effective: 0.775, source: CostSourceEstimated,
+ scoped: map[string]int{"gpt-5.4": 0}},
+ },
+ {
+ // A Pi message_end is one request and reports its own cost. The estimate is still
+ // computed (in the 200k band for claude-sonnet-4-5: $6 in, $22.50 out):
+ // 250000x6 + 1000x22.5 = 1522500; the effective figure is the reported $1.20.
+ name: "pi request with reported cost",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "pi_cli", "pi-1", "claude-sonnet-4-5", chain(
+ withUsage(250000, 1000, 0, 0, 0, 1.2), collected("plugin"))),
+ },
+ want: want{estimated: 1522500, effective: 1.2, reported: 1.2, source: CostSourceReported,
+ bands: map[string][]BandUse{"claude-sonnet-4-5": {{AboveTokens: 200000, Requests: 1}}},
+ scoped: map[string]int{"claude-sonnet-4-5": 1}},
+ },
+ {
+ // A model the catalog does not price is counted as missing, never as free.
+ name: "unpriced model",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "gemini_cli", "g1", "acme-internal-7b", withUsage(400, 100, 0, 0, 0, 0)),
+ },
+ want: want{estimated: 0, effective: 0, source: "", unpricedEvent: 1, unpricedTok: 500},
+ },
+ {
+ // Session-less events are judged one at a time: the first reported a cost and
+ // contributes it; the second did not and contributes its estimate (gpt-5: $1.25 in,
+ // $10 out: 1000x1.25 + 100x10 = 2250). Its own estimate counts in estimated too
+ // (claude-sonnet-4-5: 1000x3 + 100x15 = 4500).
+ name: "session-less events mix reported and estimated",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "", "claude-sonnet-4-5", withUsage(1000, 100, 0, 0, 0, 0.2)),
+ usageEventFixture("2026-06-11T10:00:01Z", "codex_cli", "", "gpt-5", withUsage(1000, 100, 0, 0, 0, 0)),
+ },
+ want: want{estimated: 6750, effective: 0.2 + 0.00225, reported: 0.2, source: CostSourceMixed},
+ },
+ {
+ // Cumulative datapoints are differenced before pricing: 1000 then 3000 is 3000
+ // tokens, not 4000. claude-sonnet-4-5 $3 in: 3000x3 = 9000.
+ name: "cumulative metric deltas are priced after resolution",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(1000, 0, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Cumulative"))),
+ usageEventFixture("2026-06-11T10:01:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(3000, 0, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Cumulative"))),
+ },
+ want: want{estimated: 9000, effective: 0.009, source: CostSourceEstimated,
+ scoped: map[string]int{"claude-sonnet-4-5": 0}},
+ },
+ {
+ // A request below the threshold is not banded even when request-scoped.
+ // claude-sonnet-4-5 via the Claude Code session file: 150000x3 + 50000x0.3 +
+ // 1000x15 = 480000.
+ name: "band needs the threshold",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(150000, 1000, 50000, 0, 0, 0), collected("poll"))),
+ },
+ want: want{estimated: 480000, effective: 0.48, source: CostSourceEstimated,
+ scoped: map[string]int{"claude-sonnet-4-5": 1}},
+ },
+ {
+ // DeepSeek publishes no cache-write price, so writes are priced as input.
+ // deepseek-chat: $0.28 in, $0.42 out, $0.028 cache read.
+ // 1000x0.28 + 2000x0.28 (write) + 10000x0.028 + 500x0.42 = 280+560+280+210 = 1330.
+ name: "deepseek per response with cache write fallback",
+ events: []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "deepseek_harness", "d1", "deepseek-chat", chain(
+ withUsage(1000, 500, 10000, 2000, 0, 0), collected("poll"),
+ func(e *schema.Event) { e.Raw = map[string]interface{}{"token_source": "assistant_message"} })),
+ },
+ want: want{estimated: 1330, effective: 0.00133, source: CostSourceEstimated,
+ scoped: map[string]int{"deepseek-chat": 1}},
+ },
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ report := Aggregate(tc.events, Options{BucketSize: 3600e9})
+ got := report.Totals
+ if got.estimated != pricing.Microdollars(tc.want.estimated) || got.EstimatedCostUSD != usd(tc.want.estimated) {
+ t.Fatalf("estimated = %d (%v), want %d", got.estimated, got.EstimatedCostUSD, tc.want.estimated)
+ }
+ if !approxEqual(got.EffectiveCostUSD, tc.want.effective) {
+ t.Fatalf("effective = %v, want %v", got.EffectiveCostUSD, tc.want.effective)
+ }
+ if !approxEqual(got.CostUSD, tc.want.reported) {
+ t.Fatalf("cost_usd = %v, want the reported %v only", got.CostUSD, tc.want.reported)
+ }
+ if got.CostSource != tc.want.source {
+ t.Fatalf("cost_source = %q, want %q", got.CostSource, tc.want.source)
+ }
+ if got.UnpricedEvents != tc.want.unpricedEvent || got.UnpricedTokens != tc.want.unpricedTok {
+ t.Fatalf("unpriced = %d events / %d tokens, want %d / %d", got.UnpricedEvents, got.UnpricedTokens, tc.want.unpricedEvent, tc.want.unpricedTok)
+ }
+ models := map[string]ModelPricing{}
+ for _, m := range report.Pricing.Models {
+ models[m.Model] = m
+ }
+ for model, scoped := range tc.want.scoped {
+ if models[model].RequestScopedEvents != scoped {
+ t.Fatalf("%s request_scoped_events = %d, want %d (%+v)", model, models[model].RequestScopedEvents, scoped, models[model])
+ }
+ }
+ for model := range models {
+ if !reflect.DeepEqual(models[model].BandsApplied, tc.want.bands[model]) {
+ t.Fatalf("%s bands_applied = %+v, want %+v", model, models[model].BandsApplied, tc.want.bands[model])
+ }
+ }
+ assertGroupsSumToTotals(t, report)
+ })
+ }
+}
+
+// Every rollup partitions the same events, so its estimates must add up to the total exactly.
+func assertGroupsSumToTotals(t *testing.T, report Report) {
+ t.Helper()
+ check := func(name string, usages []Usage) {
+ var est, effEst pricing.Microdollars
+ var effRep float64
+ unpriced := 0
+ for _, u := range usages {
+ est += u.estimated
+ effEst += u.effectiveEstimated
+ effRep += u.effectiveReported
+ unpriced += u.UnpricedEvents
+ }
+ if len(usages) == 0 {
+ return
+ }
+ if est != report.Totals.estimated || effEst != report.Totals.effectiveEstimated ||
+ !approxEqual(effRep, report.Totals.effectiveReported) || unpriced != report.Totals.UnpricedEvents {
+ t.Fatalf("%s sums (est %d, eff %d+%v, unpriced %d) differ from totals %+v", name, est, effEst, effRep, unpriced, report.Totals)
+ }
+ }
+ groupUsages := func(groups []Group) []Usage {
+ out := make([]Usage, 0, len(groups))
+ for _, g := range groups {
+ out = append(out, g.Usage)
+ }
+ return out
+ }
+ check("by_model", groupUsages(report.ByModel))
+ check("by_harness", groupUsages(report.ByHarness))
+ series := make([]Usage, 0, len(report.Series))
+ for _, b := range report.Series {
+ series = append(series, b.Usage)
+ }
+ check("series", series)
+ var modelEst pricing.Microdollars
+ for _, m := range report.Pricing.Models {
+ modelEst += m.estimated
+ }
+ if modelEst != report.Totals.estimated {
+ t.Fatalf("pricing.models estimates %d differ from totals %d", modelEst, report.Totals.estimated)
+ }
+}
+
+func TestRequestScopedClassifier(t *testing.T) {
+ cases := []struct {
+ name string
+ ue usageEvent
+ want bool
+ }{
+ {"claude api_request log", usageEvent{harness: "claude_code", name: "claude_code.api_request", collectionMethod: "otlp"}, true},
+ {"claude api_request by event.name", usageEvent{harness: "claude_code", name: "api_request", collectionMethod: "otlp"}, true},
+ {"cowork api_request log", usageEvent{harness: "claude_cowork", name: "claude_code.api_request"}, true},
+ {"claude token metric", usageEvent{harness: "claude_code", name: "claude_code.token.usage", metricName: "claude_code.token.usage"}, false},
+ {"claude session file", usageEvent{harness: "claude_code", action: "token.usage", collectionMethod: "poll"}, true},
+ {"claude other log", usageEvent{harness: "claude_code", name: "claude_code.tool_result", collectionMethod: "otlp"}, false},
+ {"codex token_count", usageEvent{harness: "codex_cli", codexSessionSource: "codex_session_token_count"}, true},
+ {"codex token_usage_record turn", usageEvent{harness: "codex_cli", codexSessionSource: "codex_session_token_usage_record"}, false},
+ {"codex turn span", usageEvent{harness: "codex_cli", rawSource: "codex_turn_span"}, false},
+ {"codex legacy metric", usageEvent{harness: "codex", metricName: "codex.turn.token_usage"}, false},
+ {"pi message_end", usageEvent{harness: "pi", action: "token.usage", collectionMethod: "plugin"}, true},
+ {"pi tool result usage", usageEvent{harness: "pi_cli", action: "tool.completed", collectionMethod: "plugin"}, false},
+ {"pi session file", usageEvent{harness: "pi_cli", action: "agent.message", collectionMethod: "poll"}, true},
+ {"omp message_end", usageEvent{harness: "omp", action: "token.usage", collectionMethod: "plugin"}, true},
+ {"prime message_end", usageEvent{harness: "prime_agent", action: "token.usage"}, true},
+ {"senpi message_end", usageEvent{harness: "omo_senpi", action: "token.usage"}, true},
+ {"opencode plugin", usageEvent{harness: "opencode", action: "agent.message", collectionMethod: "plugin"}, true},
+ {"opencode poll", usageEvent{harness: "opencode", action: "token.usage", collectionMethod: "poll"}, true},
+ {"openclaw llm_output turn", usageEvent{harness: "openclaw_gateway", action: "token.usage", collectionMethod: "plugin"}, false},
+ {"openclaw session file", usageEvent{harness: "openclaw_gateway", action: "token.usage", collectionMethod: "poll"}, true},
+ {"deepseek assistant message", usageEvent{harness: "deepseek_harness", tokenSource: "assistant_message"}, true},
+ {"cline task total", usageEvent{harness: "cline", action: "task.completed", collectionMethod: "plugin"}, false},
+ {"copilot shutdown", usageEvent{harness: "copilot_cli", tokenSource: "session_shutdown_model_metrics_delta", collectionMethod: "poll"}, false},
+ {"hermes cumulative delta", usageEvent{harness: "hermes", collectionMethod: "poll"}, false},
+ {"factory settings", usageEvent{harness: "factory", rawSource: "factory_settings", collectionMethod: "poll"}, false},
+ {"fx turn", usageEvent{harness: "vercel_fx", collectionMethod: "poll"}, false},
+ {"cursor admin api", usageEvent{harness: "cursor", collectionMethod: "poll"}, false},
+ {"gemini generic span", usageEvent{harness: "gemini_cli", collectionMethod: "otlp"}, false},
+ {"opencode cumulative metric", usageEvent{harness: "opencode", cumulative: true, metricName: "x"}, false},
+ }
+ for _, tc := range cases {
+ ue := tc.ue
+ if got := requestScoped(&ue); got != tc.want {
+ t.Errorf("%s: requestScoped = %v, want %v", tc.name, got, tc.want)
+ }
+ }
+}
+
+// A scope with a reported cost is reported through and through: its token events do not add
+// their estimate to the effective figure, on any grouping.
+func TestEffectiveCostUsesReportedScopeOnEveryGrouping(t *testing.T) {
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", chain(
+ withUsage(1000, 0, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Delta"))),
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5[1m]", chain(
+ withUsage(0, 0, 0, 0, 0, 0.01), metricRaw("claude_code.cost.usage", "Delta"))),
+ // Another session of the same runtime without any reported cost is estimated.
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s2", "claude-sonnet-4-5", chain(
+ withUsage(1000, 0, 0, 0, 0, 0), metricRaw("claude_code.token.usage", "Delta"))),
+ }
+ report := Aggregate(events, Options{SessionID: "s1"})
+ bySession := map[string]Usage{}
+ for _, g := range report.BySession {
+ bySession[g.Key] = g.Usage
+ }
+ if s1 := bySession["s1"]; !approxEqual(s1.EffectiveCostUSD, 0.01) || s1.CostSource != CostSourceReported || s1.EstimatedCostUSD != 0.003 {
+ t.Fatalf("s1 = %+v, want reported 0.01 effective with a 0.003 estimate alongside", s1)
+ }
+ if s2 := bySession["s2"]; s2.EffectiveCostUSD != 0.003 || s2.CostSource != CostSourceEstimated {
+ t.Fatalf("s2 = %+v, want its estimate as effective", s2)
+ }
+ if got := report.SessionDetail.Usage; !approxEqual(got.EffectiveCostUSD, 0.01) || got.CostSource != CostSourceReported {
+ t.Fatalf("session detail = %+v", got)
+ }
+ for _, step := range report.SessionDetail.Steps {
+ if step.Usage.CostSource != CostSourceReported {
+ t.Fatalf("step %+v should be reported-sourced", step.Usage)
+ }
+ }
+ if report.Totals.CostSource != CostSourceMixed {
+ t.Fatalf("totals cost_source = %q, want mixed", report.Totals.CostSource)
+ }
+}
+
+// Context-only events are not spend: no estimate, no unpriced count.
+func TestContextOnlyEventsAreNotPriced(t *testing.T) {
+ event := usageEventFixture("2026-06-11T10:00:00Z", "qwen_code", "q1", "acme-unknown", func(e *schema.Event) {
+ e.GenAI.Usage = nil
+ e.GenAI.Context = &schema.GenAIContextInfo{UsedTokens: int64Ptr(5000), LimitTokens: int64Ptr(100000)}
+ })
+ report := Aggregate([]schema.Event{event}, Options{})
+ if report.Totals.UnpricedEvents != 0 || len(report.Pricing.Unpriced) != 0 || report.Totals.EstimatedCostUSD != 0 {
+ t.Fatalf("context-only event was priced: %+v %+v", report.Totals, report.Pricing)
+ }
+}
+
+func TestPricingSummaryIsDeterministicAndComplete(t *testing.T) {
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "opencode", "o1", "gpt-5.5", withUsage(300000, 10, 0, 0, 0, 0)),
+ usageEventFixture("2026-06-11T10:00:01Z", "deepseek_harness", "d1", "deepseek-chat", chain(withUsage(10, 10, 0, 100, 0, 0),
+ func(e *schema.Event) { e.Raw = map[string]interface{}{"token_source": "assistant_message"} })),
+ usageEventFixture("2026-06-11T10:00:02Z", "gemini_cli", "g1", "zeta-unpriced", withUsage(5, 5, 0, 0, 0, 0)),
+ usageEventFixture("2026-06-11T10:00:03Z", "gemini_cli", "g1", "", withUsage(7, 0, 0, 0, 0, 0)),
+ usageEventFixture("2026-06-11T10:00:04Z", "copilot_cli", "c1", "claude-sonnet-4.6", withUsage(10, 10, 0, 0, 0, 0)),
+ }
+ first, _ := json.Marshal(Aggregate(events, Options{}).Pricing)
+ reversed := make([]schema.Event, len(events))
+ for i := range events {
+ reversed[len(events)-1-i] = events[i]
+ }
+ second, _ := json.Marshal(Aggregate(reversed, Options{}).Pricing)
+ if string(first) != string(second) {
+ t.Fatalf("pricing summary depends on event order:\n%s\n%s", first, second)
+ }
+ summary := Aggregate(events, Options{}).Pricing
+ var names []string
+ for _, m := range summary.Models {
+ names = append(names, m.Model)
+ }
+ if !reflect.DeepEqual(names, []string{"claude-sonnet-4.6", "deepseek-chat", "gpt-5.5"}) {
+ t.Fatalf("models = %v, want sorted", names)
+ }
+ for _, m := range summary.Models {
+ switch m.Model {
+ case "claude-sonnet-4.6":
+ if m.Key != "claude-sonnet-4-6" || m.Match != string(pricing.MatchDottedVersion) || m.Rates.Input != 3 || m.Rates.Output != 15 {
+ t.Fatalf("copilot model pricing = %+v", m)
+ }
+ case "gpt-5.5":
+ if len(m.BandsApplied) != 1 || m.BandsApplied[0].AboveTokens != 272000 || m.RequestScopedEvents != 1 {
+ t.Fatalf("opencode request above 272k should be banded: %+v", m)
+ }
+ case "deepseek-chat":
+ if !reflect.DeepEqual(m.Fallbacks, []string{"cache_write_at_input_rate"}) {
+ t.Fatalf("deepseek fallbacks = %v", m.Fallbacks)
+ }
+ }
+ }
+ if len(summary.Unpriced) != 2 || summary.Unpriced[0].Model != "" || summary.Unpriced[0].Tokens != 7 ||
+ summary.Unpriced[1].Model != "zeta-unpriced" || summary.Unpriced[1].Tokens != 10 {
+ t.Fatalf("unpriced = %+v", summary.Unpriced)
+ }
+ if summary.Catalog.Commit == "" || summary.Catalog.GeneratedAt == "" || summary.Tier != "standard" {
+ t.Fatalf("catalog provenance = %+v", summary.Catalog)
+ }
+}
+
+func TestUsageJSONCarriesCostFields(t *testing.T) {
+ report := Aggregate([]schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "codex_cli", "c1", "gpt-5", withUsage(1000, 100, 0, 0, 0, 0)),
+ }, Options{SessionID: "c1"})
+ encoded, err := json.Marshal(report)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var decoded struct {
+ Totals map[string]interface{} `json:"totals"`
+ SessionDetail struct {
+ Steps []struct {
+ Usage map[string]interface{} `json:"usage"`
+ } `json:"steps"`
+ } `json:"session_detail"`
+ Pricing map[string]interface{} `json:"pricing"`
+ }
+ if err := json.Unmarshal(encoded, &decoded); err != nil {
+ t.Fatal(err)
+ }
+ for _, key := range []string{"cost_usd", "estimated_cost_usd", "effective_cost_usd", "cost_source"} {
+ if _, ok := decoded.Totals[key]; !ok {
+ t.Fatalf("totals missing %q: %s", key, encoded)
+ }
+ if _, ok := decoded.SessionDetail.Steps[0].Usage[key]; !ok {
+ t.Fatalf("step usage missing %q: %s", key, encoded)
+ }
+ }
+ for _, key := range []string{"catalog", "tier", "models"} {
+ if _, ok := decoded.Pricing[key]; !ok {
+ t.Fatalf("pricing missing %q: %s", key, encoded)
+ }
+ }
+ // 1000 x $1.25 + 100 x $10 per MTok.
+ if decoded.Totals["estimated_cost_usd"] != 0.00225 || decoded.Totals["cost_source"] != CostSourceEstimated {
+ t.Fatalf("totals = %v", decoded.Totals)
+ }
+}
diff --git a/cli/beacon/internal/tokens/report.go b/cli/beacon/internal/tokens/report.go
index b2325f99..0a7c427a 100644
--- a/cli/beacon/internal/tokens/report.go
+++ b/cli/beacon/internal/tokens/report.go
@@ -11,7 +11,7 @@ import (
func RenderText(w io.Writer, report Report) {
fmt.Fprintf(w, "Token usage report (%d of %d events carry usage)\n\n", report.EventsWithUsage, report.TotalEvents)
tw := tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
- fmt.Fprintln(tw, "TOTALS\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEVENTS")
+ fmt.Fprintln(tw, "TOTALS\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEST COST USD\tEVENTS")
writeUsageRow(tw, "", report.Totals)
tw.Flush()
@@ -42,7 +42,7 @@ func RenderText(w io.Writer, report Report) {
if len(report.Series) > 0 {
fmt.Fprintln(w)
tw = tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
- fmt.Fprintln(tw, "BUCKET\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEVENTS")
+ fmt.Fprintln(tw, "BUCKET\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEST COST USD\tEVENTS")
for _, bucket := range report.Series {
writeUsageRow(tw, bucket.Start, bucket.Usage)
}
@@ -52,12 +52,14 @@ func RenderText(w io.Writer, report Report) {
if report.SessionDetail != nil {
fmt.Fprintf(w, "\nSESSION %s\n", report.SessionDetail.SessionID)
tw = tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
- fmt.Fprintln(tw, "STEP\tMODEL\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD")
+ fmt.Fprintln(tw, "STEP\tMODEL\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEST COST USD")
for _, step := range report.SessionDetail.Steps {
writeStepRows(tw, step, 0)
}
tw.Flush()
}
+
+ writePricingFooter(w, report)
}
func writeGroups(w io.Writer, title string, groups []Group) {
@@ -66,7 +68,7 @@ func writeGroups(w io.Writer, title string, groups []Group) {
}
fmt.Fprintln(w)
tw := tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
- fmt.Fprintf(tw, "%s\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEVENTS\n", title)
+ fmt.Fprintf(tw, "%s\tINPUT\tOUTPUT\tCACHE READ\tCACHE CREATE\tREASONING\tCOST USD\tEST COST USD\tEVENTS\n", title)
for _, group := range groups {
writeUsageRow(tw, group.Key, group.Usage)
}
@@ -77,7 +79,7 @@ func writeUsageRow(w io.Writer, key string, usage Usage) {
if key == "" {
key = "total"
}
- fmt.Fprintf(w, "%s\t%d\t%d\t%d\t%d\t%d\t%s\t%d\n",
+ fmt.Fprintf(w, "%s\t%d\t%d\t%d\t%d\t%d\t%s\t%s\t%d\n",
key,
usage.InputTokens,
usage.OutputTokens,
@@ -85,6 +87,7 @@ func writeUsageRow(w io.Writer, key string, usage Usage) {
usage.CacheCreationInputTokens,
usage.ReasoningOutputTokens,
formatCost(usage.CostUSD),
+ formatEstimate(usage),
usage.Events,
)
}
@@ -97,7 +100,7 @@ func writeStepRows(w io.Writer, step *Step, depth int) {
if label == "" {
label = step.SpanID
}
- fmt.Fprintf(w, "%s%s\t%s\t%d\t%d\t%d\t%d\t%d\t%s\n",
+ fmt.Fprintf(w, "%s%s\t%s\t%d\t%d\t%d\t%d\t%d\t%s\t%s\n",
strings.Repeat(" ", depth),
label,
step.Model,
@@ -107,6 +110,7 @@ func writeStepRows(w io.Writer, step *Step, depth int) {
step.Usage.CacheCreationInputTokens,
step.Usage.ReasoningOutputTokens,
formatCost(step.Usage.CostUSD),
+ formatEstimate(step.Usage),
)
for _, child := range step.Children {
writeStepRows(w, child, depth+1)
@@ -120,6 +124,70 @@ func formatCost(cost float64) string {
return fmt.Sprintf("%.4f", cost)
}
+// formatEstimate prints the list-price estimate from its exact microdollar sum when the usage
+// came from the aggregator, so a printed figure never carries float drift. A row whose tokens
+// were all unpriced prints "?" rather than "-": its cost is unknown, not zero.
+func formatEstimate(usage Usage) string {
+ if usage.estimated > 0 {
+ return usage.estimated.Format(4)
+ }
+ if usage.EstimatedCostUSD > 0 {
+ return fmt.Sprintf("%.4f", usage.EstimatedCostUSD)
+ }
+ if usage.UnpricedEvents > 0 {
+ return "?"
+ }
+ return "-"
+}
+
+// writePricingFooter says which cost column is which, where the estimate came from, and what it
+// leaves out. It is printed whenever there is usage, because a reader who sees two cost columns
+// must be able to tell them apart without the docs.
+func writePricingFooter(w io.Writer, report Report) {
+ if report.EventsWithUsage == 0 || report.Pricing == nil {
+ return
+ }
+ catalog := report.Pricing.Catalog
+ provenance := "generated " + catalog.GeneratedAt
+ if commit := catalog.Commit; commit != "" {
+ if len(commit) > 12 {
+ commit = commit[:12]
+ }
+ provenance = "commit " + commit + ", " + provenance
+ }
+ fmt.Fprintln(w)
+ fmt.Fprintln(w, "COST USD is what the runtimes reported. EST COST USD is an estimate at list price:")
+ fmt.Fprintf(w, " prices from %s (%s);\n", catalog.Name, provenance)
+ fmt.Fprintf(w, " %s tier, no batch, priority or subscription discounts;\n", report.Pricing.Tier)
+ fmt.Fprintln(w, " 1h cache writes are priced at the 5m rate until Beacon captures the split.")
+ totals := report.Totals
+ fmt.Fprintf(w, "Effective cost (reported where the runtime reported one, the estimate elsewhere): %s USD",
+ effectiveString(totals))
+ if totals.CostSource != "" {
+ fmt.Fprintf(w, " [%s]", totals.CostSource)
+ }
+ fmt.Fprintln(w)
+ if unpriced := report.Pricing.Unpriced; len(unpriced) > 0 {
+ names := make([]string, 0, len(unpriced))
+ for _, model := range unpriced {
+ name := model.Model
+ if name == "" {
+ name = "(no model)"
+ }
+ names = append(names, name)
+ }
+ fmt.Fprintf(w, "Not in EST COST USD: %d event(s), %d tokens from models the catalog does not price: %s\n",
+ totals.UnpricedEvents, totals.UnpricedTokens, strings.Join(names, ", "))
+ }
+}
+
+func effectiveString(usage Usage) string {
+ if usage.effectiveReported == 0 {
+ return usage.effectiveEstimated.Format(4)
+ }
+ return fmt.Sprintf("%.4f", usage.EffectiveCostUSD)
+}
+
// RenderCoverageText writes the token coverage report: which runtimes contributed token telemetry
// in the window and which did not.
//
diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.go
index b995d6fd..26dd5517 100644
--- a/cli/beacon/internal/tokens/tokens.go
+++ b/cli/beacon/internal/tokens/tokens.go
@@ -10,6 +10,7 @@ import (
"time"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
@@ -17,6 +18,19 @@ const defaultNearLimitRatio = 0.8
// Usage sums the canonical gen_ai.usage fields across events. Field names
// match the event schema so report consumers see one vocabulary.
+//
+// It carries three different costs, and they must not be confused (see cost.go):
+//
+// - CostUSD is what runtimes reported, summed. It has exactly the meaning of
+// gen_ai.usage.cost_usd and Beacon never fills it in.
+// - EstimatedCostUSD is a list-price estimate of every token the catalog could price,
+// whether or not the runtime also reported a cost: what the same tokens would cost at the
+// provider's published API price.
+// - EffectiveCostUSD is the best single figure: the reported cost wherever a runtime
+// reported one, the estimate everywhere else. CostSource says which it is made of.
+//
+// UnpricedEvents and UnpricedTokens count what the estimate is missing: usage whose model the
+// catalog does not price.
type Usage struct {
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
@@ -24,7 +38,21 @@ type Usage struct {
CacheCreationInputTokens int64 `json:"cache_creation_input_tokens"`
ReasoningOutputTokens int64 `json:"reasoning_output_tokens"`
CostUSD float64 `json:"cost_usd"`
+ EstimatedCostUSD float64 `json:"estimated_cost_usd"`
+ EffectiveCostUSD float64 `json:"effective_cost_usd"`
+ CostSource string `json:"cost_source,omitempty"`
+ UnpricedEvents int `json:"unpriced_events,omitempty"`
+ UnpricedTokens int64 `json:"unpriced_tokens,omitempty"`
Events int `json:"events"`
+
+ // The exported cost fields above are derived from these by settle, so sums stay exact:
+ // estimates are summed in integer microdollars and converted once, and the effective cost
+ // keeps its reported and estimated parts apart until it is printed.
+ estimated pricing.Microdollars
+ effectiveReported float64
+ effectiveEstimated pricing.Microdollars
+ reportedEvents int
+ estimatedEvents int
}
func (u Usage) TotalTokens() int64 {
@@ -38,7 +66,15 @@ func (u *Usage) add(delta Usage) {
u.CacheCreationInputTokens += delta.CacheCreationInputTokens
u.ReasoningOutputTokens += delta.ReasoningOutputTokens
u.CostUSD += delta.CostUSD
+ u.UnpricedEvents += delta.UnpricedEvents
+ u.UnpricedTokens += delta.UnpricedTokens
u.Events += delta.Events
+ u.estimated += delta.estimated
+ u.effectiveReported += delta.effectiveReported
+ u.effectiveEstimated += delta.effectiveEstimated
+ u.reportedEvents += delta.reportedEvents
+ u.estimatedEvents += delta.estimatedEvents
+ u.settle()
}
type Group struct {
@@ -111,6 +147,9 @@ type Report struct {
SessionDetail *SessionDetail `json:"session_detail,omitempty"`
EventsWithUsage int `json:"events_with_usage"`
TotalEvents int `json:"total_events"`
+ // Pricing says where every estimate in the report came from: the catalog, the rates each
+ // model was priced at, and the models it could not price.
+ Pricing *PricingSummary `json:"pricing,omitempty"`
}
// usageEvent is one usage-bearing event with its usage normalized to a delta
@@ -140,9 +179,14 @@ type usageEvent struct {
cumulative bool
metricName string
rawSource string
- sourceStart time.Time
- seriesField string
- seriesValue float64
+ // collectionMethod, codexSessionSource and tokenSource are what requestScoped (cost.go)
+ // reads to tell one model request from a sum of several.
+ collectionMethod string
+ codexSessionSource string
+ tokenSource string
+ sourceStart time.Time
+ seriesField string
+ seriesValue float64
}
// Aggregate builds a token usage report from endpoint events. Events from
@@ -169,6 +213,10 @@ func aggregate(events []schema.Event, opts Options, sessionUsers sessionUserInde
usageEvents = preferCodexTurnSpans(usageEvents)
usageEvents = dedupeOverlappingChannels(usageEvents)
resolveCumulativeSeries(usageEvents)
+ // Last, on the final per-event deltas: an estimate made before the passes above would price
+ // tokens they are about to remove as duplicates, and price a cumulative counter's running
+ // total instead of its interval delta.
+ report.Pricing = priceUsageEvents(usageEvents, priceCatalog())
byModel := map[string]*Usage{}
bySession := map[string]*Usage{}
@@ -439,6 +487,8 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []
model: asymptoteobserve.NormalizeModelName(event.Model),
repository: event.Repository,
usage: Usage{Events: 1},
+
+ collectionMethod: event.Harness.CollectionMethod,
}
if ts, err := schema.ParseTimestamp(event.Timestamp); err == nil {
ue.ts = ts
@@ -522,6 +572,10 @@ func collectUsageEvents(events []schema.Event, sessionUsers sessionUserIndex) []
}
ue.metricName, _ = event.Raw["metric_name"].(string)
ue.rawSource, _ = event.Raw["source"].(string)
+ ue.tokenSource, _ = event.Raw["token_source"].(string)
+ if codex, ok := event.Raw["codex_session"].(map[string]interface{}); ok {
+ ue.codexSessionSource, _ = codex["source"].(string)
+ }
if rawStart, _ := event.Raw["turn_start_timestamp"].(string); rawStart != "" {
ue.sourceStart, _ = schema.ParseTimestamp(rawStart)
}
diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdx
index bf2e42b2..1b7e2410 100644
--- a/docs/cli/token-usage.mdx
+++ b/docs/cli/token-usage.mdx
@@ -24,7 +24,7 @@ Beacon normalizes token telemetry from every runtime into one canonical [`gen_ai
A few rules shape how the numbers read:
- **Counts are kept disjoint.** `input_tokens`, `output_tokens`, `cache_read`, and `cache_creation` do not overlap, so a total is `input + output + cache_read + cache_creation` without double-counting. Codex reports input inclusive of both cache reads and cache writes, so Beacon subtracts both before storing uncached input.
-- **Cost is runtime-reported only.** `cost_usd` reflects what the runtime emits. Beacon never derives cost from local pricing tables, so cost appears only for runtimes that report it.
+- **Reported and estimated cost are kept apart.** `cost_usd` is what the runtime reported and nothing else. Beside it, every report carries a list-price estimate (`estimated_cost_usd`) for every runtime, including the ones that report no cost, and an effective cost that picks one of the two. See [Cost: reported, estimated, effective](#cost-reported-estimated-effective). Events never carry an estimate; it is computed when the report is built.
- **Attribution depends on the metadata a runtime attaches.** Model, harness, repository, and run grouping work whenever those fields are present. Per-session grouping (`--session`, the session step tree) requires a session or conversation id on the usage signal. Per-user grouping uses the event user directly or a matching session context event from a local hook.
- **Duplicate channels are de-duplicated.** When a runtime emits the same usage on more than one signal (Claude Code reports it on both logs and metrics), Beacon counts it once.
@@ -101,9 +101,34 @@ A runtime that reports occupancy and no spend still shows as `not_instrumented`
Legacy metric-only Codex rows written before the turn trace existed remain visible in historical totals, but cannot be assigned to a session or user. See the [Codex CLI](/runtimes/codex-cli#token-usage-and-cost) and [Claude Code](/runtimes/claude-code) runtime pages for details.
-### Cost estimates are separate
+The **Cost** column says what the runtime itself reports. Every runtime that reports tokens also gets a list-price estimate in the report, so "Not reported" no longer means the report shows no cost; see the next section.
-Beacon does not turn Codex token counts into `cost_usd`. A future report may show a separately labeled estimate with the pricing source, effective date, model, and service tier. Unknown models must remain unknown rather than reading as zero cost, and reasoning tokens must not be charged a second time because they are already included in output.
+## Cost: reported, estimated, effective
+
+Each usage row in the report (totals, every grouping, time buckets, the session step tree) carries three costs:
+
+| Field | Meaning |
+|-------|---------|
+| `cost_usd` | What the runtime reported, summed. Unchanged: Beacon never fills it in, and events never carry anything else in `gen_ai.usage.cost_usd` |
+| `estimated_cost_usd` | What the same tokens cost at the provider's published API list price, for every token whose model the catalog prices, whether or not the runtime also reported a cost. It is the API-equivalent cost, useful for comparing runtimes and for runtimes on a subscription |
+| `effective_cost_usd` | The best single figure. Within one endpoint, runtime and session, if the runtime reported any cost, the session's cost is what it reported and the estimate takes no part. Otherwise the session contributes its estimate. Events without a session are judged one at a time. `cost_source` says what it is made of: `reported`, `estimated`, `mixed`, or empty when there was nothing to price |
+
+A runtime's own figure wins because it knows the plan, the discounts and the routing that a list price cannot. The same rule keeps Claude Code right: its cost arrives on a separate `claude_code.cost.usage` metric beside token events that carry none, so its sessions are reported and its token events add no estimate on top.
+
+`unpriced_events` and `unpriced_tokens` count usage whose model the catalog does not price. Those tokens are in every token total and in no estimate: an unknown model stays unknown rather than reading as free.
+
+The text report prints `COST USD` (reported) and `EST COST USD` (estimate) side by side, a footer naming the catalog, and the effective total. A `?` in the estimate column marks a row whose tokens were all unpriced. The dashboard's token view shows both, the estimate marked `~` and labeled "Est.".
+
+### How the estimate is computed
+
+- **Catalog.** Rates come from a catalog embedded in the binary, generated from LiteLLM's published model price list. The report's `pricing.catalog` block names the source, its upstream commit and the generation date. Nothing is fetched at report time.
+- **Standard tier only.** No batch, flex or priority tiers, regional surcharges, or subscription and enterprise discounts: nothing in a usage record says a call used them.
+- **Model matching.** The model is matched to a catalog entry by exact name, then by canonical spelling (case, provider prefix), dotted versions (`claude-sonnet-4.6`), Bedrock route prefixes, and after stripping a context-window marker (`[1m]`), a snapshot date or an effort suffix. Never by similarity. `pricing.models` records, per model, the catalog key, how it matched, the base rates in USD per million tokens, and any rate fallback used.
+- **Missing rates.** A model with no published cache-read or cache-write price has those tokens priced at its input rate, and the fallback is named in `pricing.models[].fallbacks`.
+- **1h cache writes** are priced at the 5-minute write rate, because `gen_ai.usage` does not yet carry the split.
+- **Reasoning** is part of output and is not billed again. It is priced at the output rate only when a runtime reported reasoning and no output.
+- **Long-context bands.** Several providers bill every token of a request above a prompt size at a higher rate (Anthropic and Gemini above 200k tokens, OpenAI's newer models above 272k). A band can only apply to a single request, so it is applied only to usage Beacon knows is one request: Claude Code `claude_code.api_request` records and session files, Codex session `token_count` records, Pi-family `message_end` and session files, OpenCode assistant messages, OpenClaw session files and DeepSeek Harness assistant messages. Metric datapoints, Codex turn spans, OpenClaw `llm_output` (one per turn), Cline task totals, Copilot shutdown totals and the Hermes, Factory and fx deltas sum several requests and are priced at base rates, which can understate a session that sent long prompts. `pricing.models[].bands_applied` counts the banded requests.
+- **After deduplication.** The estimate prices the final per-event counts, after duplicate channels are removed and cumulative counters are differenced, so it covers exactly the tokens the totals count.
## Checking coverage
diff --git a/docs/runtimes/cline.mdx b/docs/runtimes/cline.mdx
index 70279b8b..6a2fa31c 100644
--- a/docs/runtimes/cline.mdx
+++ b/docs/runtimes/cline.mdx
@@ -72,7 +72,7 @@ A cancelled task ends rather than fails. Cline fires its cancel hook for the cle
Cancels and failures reach Beacon two ways: the file-based hooks name them in the hook itself, and the plugin reports them as a status on its run-completion handler. Both are read, so the distinction holds on the surface Beacon installs. A run that reports no recognized outcome is recorded as a completion.
-Token usage is recorded at task end only. Beacon's token rollups sum `gen_ai.usage` across events, so reporting the same tokens at a per-model-call boundary would double every Cline task's totals. Cost is recorded only as Cline reports it. Beacon never derives cost from a local price table.
+Token usage is recorded at task end only. Beacon's token rollups sum `gen_ai.usage` across events, so reporting the same tokens at a per-model-call boundary would double every Cline task's totals. Cost is recorded only as Cline reports it. Beacon never writes a derived cost into an event; token reports keep their list-price estimate separate from the reported figure.
The session sync path reads what Cline has already committed to disk. It can recover prompts, assistant messages, agent reasoning, tool calls/results, command/file/MCP-shaped tool activity, model ids, and token counts where the stored history carries them. It cannot hold or deny tool calls, and it does not imply that Beacon observed the event at runtime.
diff --git a/docs/runtimes/goose.mdx b/docs/runtimes/goose.mdx
index 9e225db4..5693d909 100644
--- a/docs/runtimes/goose.mdx
+++ b/docs/runtimes/goose.mdx
@@ -256,7 +256,7 @@ The OTLP path carries message content only when `OTEL_INSTRUMENTATION_GENAI_CAPT
- **No tool output of any kind.** goose's hook context has a `tool_output` field and **no emission site in the runtime populates it**. So there are no command exit codes, no command output, no file-read contents and no MCP results anywhere on the hook path. A command is recorded as executed, with its command line, and nothing about how it went. This is the largest gap on this runtime, and closing it needs a change in goose.
- **No approval decisions.** goose exposes no approval event, and Beacon does not synthesize one from `PreToolUse`. Approval rules and dashboards will show nothing for this runtime.
-- **No reported cost.** goose reports token counts and not a price, so `gen_ai.usage.cost_usd` is empty. Beacon does not derive cost from local pricing tables for any runtime.
+- **No reported cost.** goose reports token counts and not a price, so `gen_ai.usage.cost_usd` is empty. Beacon never writes a derived cost into an event; `beacon token-usage` and the dashboard show a separately labeled list-price estimate instead (see [Cost: reported, estimated, effective](/cli/token-usage#cost-reported-estimated-effective)).
- **Token usage needs the OTLP path.** Usage arrives on `chat` spans, so a hooks-only install reports none. That is expected rather than a fault, and `beacon token-usage` classifies goose accordingly.
- **No working directory on three events.** goose omits it on `SessionStart` and `SessionEnd` when they come from the agent rather than the CLI session loop, and on a `UserPromptSubmit` raised by steering mid-turn. Those events carry no `session.working_directory` and no repository. Beacon deliberately does **not** fall back to the hook process's own directory: goose runs hooks with `sh -c` inheriting its own cwd, which is the application bundle under the desktop app — a path that looks like a repository and resolves to nothing. Every tool event does carry it.
- **No duplicate shell and file events.** `BeforeShellExecution`, `AfterShellExecution`, `BeforeReadFile` and `AfterFileEdit` are deliberately not subscribed to. Each fires alongside `PreToolUse` or `PostToolUse` for the **same call**, with the same tool name and arguments and — the part that makes them worse than redundant — **no tool call id at all**. Subscribing would record every shell command and file edit twice, with the second copy uncorrelatable.
diff --git a/docs/telemetry-schema/normalization.mdx b/docs/telemetry-schema/normalization.mdx
index b8396915..86842de6 100644
--- a/docs/telemetry-schema/normalization.mdx
+++ b/docs/telemetry-schema/normalization.mdx
@@ -185,7 +185,7 @@ Beacon preserves OpenTelemetry GenAI semantic convention fields under the nested
| `gen_ai.usage.reasoning.output_tokens` | `gen_ai.usage.reasoning.output_tokens` |
| `gen_ai.usage.cost`, runtime `*.cost.usage` metric datapoints | `gen_ai.usage.cost_usd` |
-Usage also arrives as metric datapoints, not just span and log attributes. Claude Code's `claude_code.token.usage` and `claude_code.cost.usage` are expanded per datapoint. Codex's live source is its completed turn span, whose input, cache-read, cache-write, output, and reasoning attributes map into the same `gen_ai.usage` fields with `thread.id` promoted to `session.id`. Legacy `codex.turn.token_usage` metric rows remain supported for older logs. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never derived from a local pricing table. See [How token attribution works](/cli/token-usage#how-token-attribution-works) for how these normalized fields aggregate into local reports.
+Usage also arrives as metric datapoints, not just span and log attributes. Claude Code's `claude_code.token.usage` and `claude_code.cost.usage` are expanded per datapoint. Codex's live source is its completed turn span, whose input, cache-read, cache-write, output, and reasoning attributes map into the same `gen_ai.usage` fields with `thread.id` promoted to `session.id`. Legacy `codex.turn.token_usage` metric rows remain supported for older logs. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never derived from a local pricing table. Token reports add a separately labeled list-price estimate at report time; it is never written into an event (see [Cost: reported, estimated, effective](/cli/token-usage#cost-reported-estimated-effective)). See [How token attribution works](/cli/token-usage#how-token-attribution-works) for how these normalized fields aggregate into local reports.
## Prompt and content handling