Skip to content

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

feat(pricing): local price overrides and a beacon pricing command group

Claude15d8ffd4aaa3
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7632ca9d..0c553520 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -258,6 +258,8 @@ jobs:
./beacon rules --help > /tmp/beacon-rules-help.txt
./beacon rules lint --help > /tmp/beacon-rules-lint-help.txt
./beacon lenses --help > /tmp/beacon-lenses-help.txt
+ ./beacon pricing --help > /tmp/beacon-pricing-help.txt
+ ./beacon pricing info > /tmp/beacon-pricing-info.txt
for forbidden in init update claude cursor dep-scan config; do
if grep -E "^[[:space:]]+$forbidden([[:space:]]|$)" /tmp/beacon-help.txt; then
echo "forbidden command exposed: $forbidden"
diff --git a/CLAUDE.md b/CLAUDE.md
index 40d2f187..d421caf9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -540,7 +540,7 @@ unpacked through Chrome's developer mode.
- Set the provenance markers on every new collection path. `harness.collection_method` (`hook`, `otlp`, `plugin`, `poll`) records the mechanism; `event.fidelity` (`observed`, `inferred`) records whether the source named the action or Beacon derived it. Both are defined in `pkg/asymptoteobserve/provenance.go` and are the only sanctioned way to express that difference — do not add per-runtime confidence fields, and do not leave a derived action unmarked. A new plugin-shaped runtime must be added to `CollectionMethodForPlatform`, whose default is `hook`. An action synthesized from an adjacent observation, such as an approval built from a pre-tool notification on a runtime with no approval hook, is `inferred`.
- Keep event identity derivable rather than asserted. `gen_ai.tool.call.id` carries the runtime's own name for one tool invocation, promoted on every capture path from the shared alias list in `pkg/asymptoteobserve.ToolCallIDKeys`; a new runtime adds its spelling there rather than in a mapper. `event.id` is a deterministic UUID derived by `EventIDForLine` from the event about to be written, so both capture paths name one action the same way. Its namespace constant and derivation are a contract: changing either renames every event ID Beacon has written, and a test pins the value.
- Keep `gen_ai.usage` as the single canonical token-usage representation: normalize all runtime token telemetry (span attributes, metric datapoints, legacy `llm.usage.*` aliases) into it, mirror OTel GenAI semconv JSON names exactly, and never add parallel or per-harness token fields. `gen_ai.usage.cost_usd` carries runtime-reported cost only and is never written from a price list; list-price estimates are computed only at report time from the embedded catalog (`cli/beacon/internal/pricing`), are always labeled as estimates, and are never stored in events.
-- `cli/beacon/internal/pricing` estimates list-price cost for reports: integer-microdollar math over the gen_ai.usage counts (disjoint input/output/cache read/cache write, a one-hour write subset, reasoning inside output), long-context bands only for a single request, and a strict model-name ladder (exact, canonical via `NormalizeModelName`, dotted version, Bedrock route prefix, then stripping a `[1m]` marker, snapshot date or effort suffix) that leaves a model unpriced rather than guess, including when two entries tie with different prices. Its `catalog.json` is embedded, offline and report-time only (hooks never import it); it is generated from LiteLLM's MIT-licensed `model_prices_and_context_window.json` and records the upstream URL, commit and fetch/generation dates. Regenerate with `cd cli/beacon && go run ./internal/pricing/internal/gen` (resolves LiteLLM's main with `git ls-remote` and fetches that commit; `-src`/`-commit` for a local copy) and review the one-model-per-line diff; the generator never runs in builds or tests.
+- `cli/beacon/internal/pricing` estimates list-price cost for reports: integer-microdollar math over the gen_ai.usage counts (disjoint input/output/cache read/cache write, a one-hour write subset, reasoning inside output), long-context bands only for a single request, and a strict model-name ladder (exact, canonical via `NormalizeModelName`, dotted version, Bedrock route prefix, then stripping a `[1m]` marker, snapshot date or effort suffix) that leaves a model unpriced rather than guess, including when two entries tie with different prices. Its `catalog.json` is embedded, offline and report-time only (hooks never import it); it is generated from LiteLLM's MIT-licensed `model_prices_and_context_window.json` and records the upstream URL, commit and fetch/generation dates. Regenerate with `cd cli/beacon && go run ./internal/pricing/internal/gen` (resolves LiteLLM's main with `git ls-remote` and fetches that commit; `-src`/`-commit` for a local copy) and review the one-model-per-line diff; the generator never runs in builds or tests. Operators price what the catalog cannot (internal models, new releases, gateway aliases, negotiated rates) in a local overrides file, `<BaseDir>/pricing/overrides.json` (`pricing.DefaultOverridesPath`, user or system mode; `--pricing-file` on `beacon token-usage` and `beacon pricing` names another), schema `beacon.pricing.overrides/v1`, documented in `docs/cli/pricing.mdx`. It is offline and Beacon never writes it: the CLI reads it per run, and the dashboard re-reads it per `/api/tokens` request, read-only, falling back to the catalog with `pricing.overrides.error` when it is invalid (the CLI fails instead). Rates are USD per MTok converted exactly to microdollars; zero, negative, quoted, sub-microdollar, absurd, unknown and duplicate keys are refused with the key named. `Pricer.Lookup` runs the same ladder over the file's names first and a row replaces the catalog row whole (omitted cache rates are unpublished, priced by the usual fallbacks); aliases map a reported name to an exact row or catalog key. Reports record `source` (`override`/`catalog`), `alias`, and the file's path and SHA-256. `beacon pricing show|list|info|validate` (`cli/beacon/cmd/pricing.go`) inspects resolution, the catalog, its provenance and the file.
- When adding a new signal, include stable identifiers/counts/hashes alongside any retained raw content, and route raw fields through redaction, sanitization, truncation, and event-size controls.
- Keep the dashboard read-only. It should inspect local status and JSONL events but must not mutate endpoint configuration or telemetry.
- The local trace history (`~/.beacon/endpoint/history.db`, `cli/beacon/internal/endpoint/dashboard/history_*.go`) is opt-in: only `beacon endpoint traces reindex`, a yes to the first-run prompt, or (later) `beacon mcp setup` creates it, and nothing non-interactive is ever prompted. Once it exists, `list`, `search` and `show` must return exactly what the JSONL scan returns for the same log (`TestHistoryAnswersExactlyLikeTheJSONLScan`), so it stores every event and projects it with the same code. A change to the trace projection bumps `historyDerivationVersion`, which rebuilds derived data from the stored lines. The stored lines keep only the raw keys in `historyRawKeys`, and a test fails if the dashboard reads one that is missing. The line dictionary (`historyLineDictionary`) must never change without a new codec.
diff --git a/cli/beacon/cmd/pricing.go b/cli/beacon/cmd/pricing.go
new file mode 100644
index 00000000..06372953
--- /dev/null
+++ b/cli/beacon/cmd/pricing.go
@@ -0,0 +1,525 @@
+package cmd
+
+import (
+ "fmt"
+ "io"
+ "strings"
+ "text/tabwriter"
+
+ "github.com/spf13/cobra"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
+)
+
+var pricingOpts struct {
+ userMode bool
+ systemMode bool
+ pricingFile string
+ provider string
+ json bool
+}
+
+func pricingUserMode() bool {
+ if pricingOpts.systemMode {
+ return false
+ }
+ return pricingOpts.userMode
+}
+
+var pricingCmd = &cobra.Command{
+ Use: "pricing",
+ Short: "Inspect the price list behind token cost estimates, and your overrides",
+ Long: `Inspect how 'beacon token-usage' and the dashboard price token usage.
+
+Estimates come from a list-price catalog embedded in Beacon and, where it names a model, from
+an overrides file you write: ~/.beacon/endpoint/pricing/overrides.json (or the system endpoint's
+pricing/overrides.json with --system), or the file named by --pricing-file. An override row
+replaces the catalog's price for that model; an alias sends a reported name to an existing
+entry. Every command here is offline and read-only: Beacon never writes the overrides file.`,
+}
+
+// pricingLoad returns the pricer for the selected overrides file. A missing default file is
+// not an error; a file named with --pricing-file must exist, and an invalid file is an error.
+func pricingLoad() (*pricing.Pricer, string, error) {
+ path, required := pricingOverridesPath()
+ p, err := pricing.LoadPricer(pricing.Default(), path, required)
+ return p, path, err
+}
+
+func pricingOverridesPath() (path string, required bool) {
+ if explicit := strings.TrimSpace(pricingOpts.pricingFile); explicit != "" {
+ return explicit, true
+ }
+ return pricing.DefaultOverridesPath(pricingUserMode()), false
+}
+
+// pricingBand is one long-context band in pricing output.
+type pricingBand struct {
+ AboveTokens int64 `json:"above_tokens"`
+ Rates tokens.RatesPerMTok `json:"rates_usd_per_mtok"`
+}
+
+// pricingShowResult is 'beacon pricing show --json'.
+type pricingShowResult struct {
+ Model string `json:"model"`
+ Priced bool `json:"priced"`
+ // Source is where the rates came from (catalog or override); Key the entry.
+ Source string `json:"source,omitempty"`
+ Key string `json:"key,omitempty"`
+ Alias string `json:"alias,omitempty"`
+ Provider string `json:"provider,omitempty"`
+ Match string `json:"match,omitempty"`
+ Stripped []string `json:"stripped,omitempty"`
+ Rates *tokens.RatesPerMTok `json:"rates_usd_per_mtok,omitempty"`
+ Bands []pricingBand `json:"bands,omitempty"`
+ // Fallbacks names each rate the entry does not publish and how its tokens are priced.
+ Fallbacks []string `json:"fallbacks,omitempty"`
+ Candidates []string `json:"candidates,omitempty"`
+ CandidatesSource string `json:"candidates_source,omitempty"`
+ Catalog tokens.PricingCatalog `json:"catalog"`
+ Overrides *tokens.PricingOverrides `json:"overrides,omitempty"`
+}
+
+var pricingShowCmd = &cobra.Command{
+ Use: "show <model>",
+ Short: "Show how a model name is priced",
+ Args: cobra.ExactArgs(1),
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ p, _, err := pricingLoad()
+ if err != nil {
+ return err
+ }
+ model := args[0]
+ res, ok := p.Lookup(model)
+ out := pricingShowResult{
+ Model: model,
+ Priced: ok,
+ Catalog: pricingCatalogInfo(p.Catalog()),
+ Overrides: pricingOverridesInfo(p),
+ }
+ if ok {
+ rates := tokens.RatesUSDPerMTok(res.Rates.RateSet)
+ out.Source, out.Key, out.Alias = res.Source, res.Key, res.Alias
+ out.Provider = res.Rates.Provider
+ out.Match = string(res.Match)
+ out.Stripped = res.Stripped
+ out.Rates = &rates
+ for _, b := range res.Rates.Bands {
+ out.Bands = append(out.Bands, pricingBand{AboveTokens: b.AboveTokens, Rates: tokens.RatesUSDPerMTok(b.RateSet)})
+ }
+ out.Fallbacks = pricingFallbacks(res.Rates.RateSet)
+ } else if len(res.Candidates) > 0 {
+ out.Source = res.Source
+ out.Match = string(res.Match)
+ out.Candidates = res.Candidates
+ out.CandidatesSource = res.Source
+ }
+ w := cmd.OutOrStdout()
+ if pricingOpts.json {
+ return writeIndentedJSON(w, out)
+ }
+ renderPricingShow(w, p, res, out)
+ return nil
+ },
+}
+
+func renderPricingShow(w io.Writer, p *pricing.Pricer, res pricing.Resolution, out pricingShowResult) {
+ fmt.Fprintf(w, "Model: %s\n", out.Model)
+ if !out.Priced {
+ if len(out.Candidates) > 0 {
+ fmt.Fprintf(w, "Not priced: %d %s entries match at the %s rung with different prices:\n", len(out.Candidates), out.CandidatesSource, out.Match)
+ for _, c := range out.Candidates {
+ fmt.Fprintf(w, " %s\n", c)
+ }
+ fmt.Fprintln(w, "Report the model under one of those names, or add it to the overrides file under its own name.")
+ } else {
+ fmt.Fprintln(w, "Not priced: no catalog key or override matches it at any rung.")
+ fmt.Fprintln(w, "Estimates leave its tokens out. Add it to the overrides file, or alias it to a catalog key.")
+ }
+ pricingFooter(w, p)
+ return
+ }
+ switch out.Source {
+ case pricing.SourceOverride:
+ fmt.Fprintf(w, "Priced by: override %q\n", out.Key)
+ if c := p.Overrides().ModelComment(out.Key); c != "" {
+ fmt.Fprintf(w, "Comment: %s\n", c)
+ }
+ if _, ok := p.Catalog().Rates(out.Key); ok {
+ fmt.Fprintf(w, " (replaces the catalog entry of the same name)\n")
+ }
+ default:
+ fmt.Fprintf(w, "Priced by: catalog key %q\n", out.Key)
+ }
+ if out.Alias != "" {
+ fmt.Fprintf(w, "Alias: %s -> %s (overrides file)\n", out.Alias, out.Key)
+ }
+ if out.Provider != "" {
+ fmt.Fprintf(w, "Provider: %s\n", out.Provider)
+ }
+ match := out.Match
+ if len(out.Stripped) > 0 {
+ match += " after stripping " + strings.Join(out.Stripped, ", ")
+ }
+ fmt.Fprintf(w, "Match: %s\n", match)
+ fmt.Fprintln(w, "Rates (USD per million tokens):")
+ tw := tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
+ set := res.Rates.RateSet
+ fmt.Fprintf(tw, " input\t%s\n", usdPerMTok(set.Input))
+ fmt.Fprintf(tw, " output\t%s\n", usdPerMTok(set.Output))
+ fmt.Fprintf(tw, " cache read\t%s\n", usdPerMTokOr(set.CacheRead, "unpublished: priced at the input rate"))
+ fmt.Fprintf(tw, " cache write (5m)\t%s\n", usdPerMTokOr(set.CacheWrite, "unpublished: priced at the input rate"))
+ fmt.Fprintf(tw, " cache write (1h)\t%s\n", usdPerMTokOr(set.CacheWrite1h, "unpublished: priced at the 5m write rate"))
+ tw.Flush()
+ if len(res.Rates.Bands) > 0 {
+ fmt.Fprintln(w, "Long-context bands (a single request whose prompt is above the threshold is billed at the band's rates for every token):")
+ for _, b := range res.Rates.Bands {
+ fmt.Fprintf(w, " above %d: input %s, output %s, cache read %s, cache write %s, cache write 1h %s\n",
+ b.AboveTokens, usdPerMTok(b.Input), usdPerMTok(b.Output), usdPerMTokOr(b.CacheRead, "-"),
+ usdPerMTokOr(b.CacheWrite, "-"), usdPerMTokOr(b.CacheWrite1h, "-"))
+ }
+ }
+ pricingFooter(w, p)
+}
+
+func pricingFooter(w io.Writer, p *pricing.Pricer) {
+ cat := pricingCatalogInfo(p.Catalog())
+ fmt.Fprintf(w, "\nCatalog: %s, generated %s\n", cat.Name, cat.GeneratedAt)
+ if o := p.Overrides(); o != nil {
+ fmt.Fprintf(w, "Overrides: %s (sha256 %s)\n", o.Path(), shortSHA(o.SHA256()))
+ }
+}
+
+// pricingFallbacks names, in the report's vocabulary, each rate an entry leaves unpublished.
+func pricingFallbacks(set pricing.RateSet) []string {
+ var out []string
+ if set.CacheRead <= 0 {
+ out = append(out, "cache_read_at_input_rate")
+ }
+ if set.CacheWrite <= 0 {
+ out = append(out, "cache_write_at_input_rate")
+ }
+ if set.CacheWrite1h <= 0 {
+ out = append(out, "cache_write_1h_at_write_rate")
+ }
+ return out
+}
+
+// usdPerMTok renders an exact rate with at least two decimal places and no trailing zeros
+// beyond them: 3000000 is "3.00", 375000 is "0.375", 1 is "0.000001".
+func usdPerMTok(micros int64) string {
+ s := pricing.Microdollars(micros).Format(6)
+ for strings.HasSuffix(s, "0") && len(s)-strings.IndexByte(s, '.') > 3 {
+ s = s[:len(s)-1]
+ }
+ return s
+}
+
+func usdPerMTokOr(micros int64, unpublished string) string {
+ if micros <= 0 {
+ return unpublished
+ }
+ return usdPerMTok(micros)
+}
+
+func pricingCatalogInfo(c *pricing.Catalog) tokens.PricingCatalog {
+ src := c.Source()
+ return tokens.PricingCatalog{
+ Name: src.Name,
+ License: src.License,
+ URL: src.URL,
+ Commit: src.Commit,
+ FetchedAt: src.FetchedAt,
+ GeneratedAt: c.GeneratedAt(),
+ }
+}
+
+func pricingOverridesInfo(p *pricing.Pricer) *tokens.PricingOverrides {
+ if o := p.Overrides(); o != nil {
+ return &tokens.PricingOverrides{Path: o.Path(), SHA256: o.SHA256(), Models: len(o.Models()), Aliases: len(o.Aliases())}
+ }
+ if path, err := p.OverridesError(); err != nil {
+ return &tokens.PricingOverrides{Path: path, Error: err.Error()}
+ }
+ return nil
+}
+
+// pricingListEntry is one priced entry in 'beacon pricing list --json'.
+type pricingListEntry struct {
+ Key string `json:"key"`
+ Source string `json:"source"`
+ Provider string `json:"provider,omitempty"`
+ Rates tokens.RatesPerMTok `json:"rates_usd_per_mtok"`
+ Bands []pricingBand `json:"bands,omitempty"`
+ // Overridden is set on a catalog entry that an override row of the same name replaces.
+ Overridden bool `json:"overridden,omitempty"`
+}
+
+type pricingAliasEntry struct {
+ Alias string `json:"alias"`
+ Target string `json:"target"`
+ TargetSource string `json:"target_source"`
+}
+
+var pricingListCmd = &cobra.Command{
+ Use: "list",
+ Short: "List catalog entries and overrides",
+ Args: cobra.NoArgs,
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ p, _, err := pricingLoad()
+ if err != nil {
+ return err
+ }
+ provider := strings.TrimSpace(pricingOpts.provider)
+ keep := func(r pricing.Rates) bool { return provider == "" || strings.EqualFold(r.Provider, provider) }
+ var entries []pricingListEntry
+ var aliases []pricingAliasEntry
+ o := p.Overrides()
+ if o != nil {
+ for _, name := range o.Models() {
+ r, _ := o.Rates(name)
+ if keep(r) {
+ entries = append(entries, pricingEntry(name, pricing.SourceOverride, r, false))
+ }
+ }
+ for _, alias := range o.Aliases() {
+ target, source, _ := o.AliasTarget(alias)
+ if provider != "" {
+ r, _ := p.Lookup(alias)
+ if !keep(r.Rates) {
+ continue
+ }
+ }
+ aliases = append(aliases, pricingAliasEntry{Alias: alias, Target: target, TargetSource: source})
+ }
+ }
+ for _, key := range p.Catalog().Keys() {
+ r, _ := p.Catalog().Rates(key)
+ if !keep(r) {
+ continue
+ }
+ overridden := false
+ if o != nil {
+ _, overridden = o.Rates(key)
+ }
+ entries = append(entries, pricingEntry(key, pricing.SourceCatalog, r, overridden))
+ }
+ w := cmd.OutOrStdout()
+ if pricingOpts.json {
+ return writeIndentedJSON(w, map[string]interface{}{
+ "models": nonNil(entries),
+ "aliases": nonNilAliases(aliases),
+ "catalog": pricingCatalogInfo(p.Catalog()),
+ "overrides": pricingOverridesInfo(p),
+ })
+ }
+ tw := tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
+ fmt.Fprintln(tw, "MODEL\tSOURCE\tPROVIDER\tINPUT\tOUTPUT\tCACHE READ\tCACHE WRITE\tBANDS")
+ for _, e := range entries {
+ source := e.Source
+ if e.Overridden {
+ source = "catalog*"
+ }
+ r := e.Rates
+ fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%d\n", e.Key, source, dashIfEmpty(e.Provider),
+ usdFloat(r.Input), usdFloat(r.Output), usdFloat(r.CacheRead), usdFloat(r.CacheWrite), len(e.Bands))
+ }
+ tw.Flush()
+ if len(aliases) > 0 {
+ fmt.Fprintln(w)
+ tw = tabwriter.NewWriter(w, 2, 4, 2, ' ', 0)
+ fmt.Fprintln(tw, "ALIAS\tTARGET\tTARGET SOURCE")
+ for _, a := range aliases {
+ fmt.Fprintf(tw, "%s\t%s\t%s\n", a.Alias, a.Target, a.TargetSource)
+ }
+ tw.Flush()
+ }
+ fmt.Fprintf(w, "\n%d entr(ies). Rates are USD per million tokens; - is unpublished.", len(entries))
+ if o != nil {
+ fmt.Fprintf(w, " catalog* is replaced by an override.\nOverrides: %s", o.Path())
+ }
+ fmt.Fprintln(w)
+ return nil
+ },
+}
+
+func pricingEntry(key, source string, r pricing.Rates, overridden bool) pricingListEntry {
+ e := pricingListEntry{Key: key, Source: source, Provider: r.Provider, Rates: tokens.RatesUSDPerMTok(r.RateSet), Overridden: overridden}
+ for _, b := range r.Bands {
+ e.Bands = append(e.Bands, pricingBand{AboveTokens: b.AboveTokens, Rates: tokens.RatesUSDPerMTok(b.RateSet)})
+ }
+ return e
+}
+
+func nonNil(e []pricingListEntry) []pricingListEntry {
+ if e == nil {
+ return []pricingListEntry{}
+ }
+ return e
+}
+
+func nonNilAliases(a []pricingAliasEntry) []pricingAliasEntry {
+ if a == nil {
+ return []pricingAliasEntry{}
+ }
+ return a
+}
+
+func usdFloat(v float64) string {
+ if v == 0 {
+ return "-"
+ }
+ return usdPerMTok(int64(v*1_000_000 + 0.5))
+}
+
+func dashIfEmpty(s string) string {
+ if s == "" {
+ return "-"
+ }
+ return s
+}
+
+// pricingInfoResult is 'beacon pricing info --json'.
+type pricingInfoResult struct {
+ Catalog tokens.PricingCatalog `json:"catalog"`
+ CatalogModels int `json:"catalog_models"`
+ Unit string `json:"unit"`
+ Tier string `json:"tier"`
+ // OverridesPath is the file the commands and reports read; OverridesFound says whether it
+ // exists, and Overrides describes it when it does.
+ OverridesPath string `json:"overrides_path"`
+ OverridesFound bool `json:"overrides_found"`
+ Overrides *tokens.PricingOverrides `json:"overrides,omitempty"`
+}
+
+var pricingInfoCmd = &cobra.Command{
+ Use: "info",
+ Short: "Show where the prices come from: the catalog's provenance and the overrides file",
+ Args: cobra.NoArgs,
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ path, _ := pricingOverridesPath()
+ // info reports an unusable file rather than failing on it: saying why is its job.
+ p, _ := pricing.LoadPricer(pricing.Default(), path, false)
+ info := pricingInfoResult{
+ Catalog: pricingCatalogInfo(p.Catalog()),
+ CatalogModels: len(p.Catalog().Keys()),
+ Unit: "USD per million tokens",
+ Tier: tokens.PricingTier,
+ OverridesPath: path,
+ Overrides: pricingOverridesInfo(p),
+ }
+ info.OverridesFound = info.Overrides != nil
+ w := cmd.OutOrStdout()
+ if pricingOpts.json {
+ return writeIndentedJSON(w, info)
+ }
+ c := info.Catalog
+ fmt.Fprintf(w, "Catalog: %s (%s license)\n", c.Name, c.License)
+ fmt.Fprintf(w, "Source: %s\n", c.URL)
+ if c.Commit != "" {
+ fmt.Fprintf(w, "Commit: %s\n", c.Commit)
+ }
+ fmt.Fprintf(w, "Fetched: %s\n", c.FetchedAt)
+ fmt.Fprintf(w, "Generated: %s\n", c.GeneratedAt)
+ fmt.Fprintf(w, "Models: %d\n", info.CatalogModels)
+ fmt.Fprintf(w, "Tier: %s (no batch, flex, priority or subscription pricing)\n", info.Tier)
+ fmt.Fprintf(w, "\nOverrides: %s\n", path)
+ switch o := info.Overrides; {
+ case o == nil:
+ fmt.Fprintln(w, " not present; estimates use the catalog alone")
+ case o.Error != "":
+ fmt.Fprintf(w, " NOT usable: %s\n", o.Error)
+ default:
+ fmt.Fprintf(w, " sha256 %s, %d model(s), %d alias(es)\n", o.SHA256, o.Models, o.Aliases)
+ }
+ return nil
+ },
+}
+
+// pricingValidateEntry is one name in 'beacon pricing validate --json'.
+type pricingValidateEntry struct {
+ Name string `json:"name"`
+ // Kind is "model" or "alias".
+ Kind string `json:"kind"`
+ // ReplacesCatalog is set on a model row whose name is also a catalog key.
+ ReplacesCatalog bool `json:"replaces_catalog,omitempty"`
+ Target string `json:"target,omitempty"`
+ TargetSource string `json:"target_source,omitempty"`
+ // Fallbacks names each rate the row leaves unpublished.
+ Fallbacks []string `json:"fallbacks,omitempty"`
+}
+
+var pricingValidateCmd = &cobra.Command{
+ Use: "validate",
+ Short: "Check a pricing overrides file",
+ Args: cobra.NoArgs,
+ SilenceUsage: true,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ path, _ := pricingOverridesPath()
+ // Validating a file that is not there is a failure, whichever path it is.
+ p, err := pricing.LoadPricer(pricing.Default(), path, true)
+ if err != nil {
+ return err
+ }
+ o := p.Overrides()
+ var entries []pricingValidateEntry
+ for _, name := range o.Models() {
+ r, _ := o.Rates(name)
+ _, replaces := p.Catalog().Rates(name)
+ entries = append(entries, pricingValidateEntry{Name: name, Kind: "model", ReplacesCatalog: replaces, Fallbacks: pricingFallbacks(r.RateSet)})
+ }
+ for _, alias := range o.Aliases() {
+ target, source, _ := o.AliasTarget(alias)
+ entries = append(entries, pricingValidateEntry{Name: alias, Kind: "alias", Target: target, TargetSource: source})
+ }
+ warnings := o.Warnings()
+ w := cmd.OutOrStdout()
+ if pricingOpts.json {
+ if warnings == nil {
+ warnings = []string{}
+ }
+ if entries == nil {
+ entries = []pricingValidateEntry{}
+ }
+ return writeIndentedJSON(w, map[string]interface{}{
+ "valid": true,
+ "path": o.Path(),
+ "sha256": o.SHA256(),
+ "entries": entries,
+ "warnings": warnings,
+ })
+ }
+ fmt.Fprintf(w, "ok: %s (sha256 %s): %d model(s), %d alias(es)\n", o.Path(), shortSHA(o.SHA256()), len(o.Models()), len(o.Aliases()))
+ for _, e := range entries {
+ switch {
+ case e.Kind == "alias":
+ fmt.Fprintf(w, " alias %s -> %s (%s)\n", e.Name, e.Target, e.TargetSource)
+ case e.ReplacesCatalog:
+ fmt.Fprintf(w, " model %s replaces the catalog entry of the same name\n", e.Name)
+ default:
+ fmt.Fprintf(w, " model %s\n", e.Name)
+ }
+ if len(e.Fallbacks) > 0 {
+ fmt.Fprintf(w, " unpublished, priced by fallback: %s\n", strings.Join(e.Fallbacks, ", "))
+ }
+ }
+ for _, warning := range warnings {
+ fmt.Fprintf(cmd.ErrOrStderr(), "warning: %s\n", warning)
+ }
+ return nil
+ },
+}
+
+func init() {
+ pricingCmd.PersistentFlags().BoolVar(&pricingOpts.userMode, "user", true, "Use per-user endpoint paths")
+ pricingCmd.PersistentFlags().BoolVar(&pricingOpts.systemMode, "system", false, "Use system endpoint paths")
+ pricingCmd.PersistentFlags().StringVar(&pricingOpts.pricingFile, "pricing-file", "", "Pricing overrides file to use instead of <endpoint>/pricing/overrides.json")
+ pricingCmd.PersistentFlags().BoolVar(&pricingOpts.json, "json", false, "Print JSON")
+ pricingListCmd.Flags().StringVar(&pricingOpts.provider, "provider", "", "Only list entries from this provider (for example anthropic, openai, gemini)")
+ pricingCmd.AddCommand(pricingShowCmd, pricingListCmd, pricingInfoCmd, pricingValidateCmd)
+ rootCmd.AddCommand(pricingCmd)
+}
diff --git a/cli/beacon/cmd/pricing_test.go b/cli/beacon/cmd/pricing_test.go
new file mode 100644
index 00000000..e19760e2
--- /dev/null
+++ b/cli/beacon/cmd/pricing_test.go
@@ -0,0 +1,422 @@
+package cmd
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/spf13/cobra"
+ "github.com/spf13/pflag"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// A file shaped like an organisation's own: a negotiated rate replacing a catalog row, an
+// internal model with a long-context band, and a gateway alias.
+const testOverridesDoc = `{
+ "schema": "beacon.pricing.overrides/v1",
+ "comment": "Acme enterprise agreement",
+ "models": {
+ "claude-sonnet-4-5": {
+ "provider": "anthropic",
+ "comment": "20% off list",
+ "input_usd_per_mtok": 2.4, "output_usd_per_mtok": 12, "cache_read_usd_per_mtok": 0.24,
+ "bands": [{"above_tokens": 200000, "input_usd_per_mtok": 4.8, "output_usd_per_mtok": 18}]
+ },
+ "acme-coder-2": {"provider": "acme", "input_usd_per_mtok": 1, "output_usd_per_mtok": 4}
+ },
+ "aliases": {"my-gateway-model": "gpt-5"}
+}`
+
+// runPricing executes `beacon pricing ...` through the root command with fresh flag values and
+// an isolated home, so no real overrides file can leak in.
+func runPricing(t *testing.T, args ...string) (stdout, stderr string, err error) {
+ t.Helper()
+ pricingOpts.userMode, pricingOpts.systemMode = true, false
+ pricingOpts.pricingFile, pricingOpts.provider, pricingOpts.json = "", "", false
+ var reset func(*cobra.Command)
+ reset = func(c *cobra.Command) {
+ for _, fs := range []*pflag.FlagSet{c.Flags(), c.PersistentFlags()} {
+ fs.VisitAll(func(f *pflag.Flag) {
+ _ = f.Value.Set(f.DefValue)
+ f.Changed = false
+ })
+ }
+ for _, sub := range c.Commands() {
+ reset(sub)
+ }
+ }
+ reset(pricingCmd)
+ var out, errOut bytes.Buffer
+ rootCmd.SetOut(&out)
+ rootCmd.SetErr(&errOut)
+ rootCmd.SetArgs(append([]string{"pricing"}, args...))
+ t.Cleanup(func() {
+ rootCmd.SetOut(nil)
+ rootCmd.SetErr(nil)
+ rootCmd.SetArgs(nil)
+ })
+ err = rootCmd.Execute()
+ return out.String(), errOut.String(), err
+}
+
+func writeOverrides(t *testing.T, doc string) string {
+ t.Helper()
+ path := filepath.Join(t.TempDir(), "overrides.json")
+ if err := os.WriteFile(path, []byte(doc), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ return path
+}
+
+func TestPricingCommandTree(t *testing.T) {
+ for _, sub := range []string{"show", "list", "info", "validate"} {
+ cmd, _, err := rootCmd.Find([]string{"pricing", sub})
+ if err != nil || cmd.Name() != sub {
+ t.Fatalf("pricing %s not registered: %v", sub, err)
+ }
+ for _, flag := range []string{"pricing-file", "json", "user", "system"} {
+ if cmd.Flags().Lookup(flag) == nil && cmd.InheritedFlags().Lookup(flag) == nil {
+ t.Fatalf("pricing %s missing --%s", sub, flag)
+ }
+ }
+ }
+ if cmd, _, _ := rootCmd.Find([]string{"token-usage"}); cmd.Flags().Lookup("pricing-file") == nil {
+ t.Fatal("token-usage missing --pricing-file")
+ }
+}
+
+func TestPricingShowCatalogModelText(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ out, _, err := runPricing(t, "show", "us.anthropic.claude-sonnet-4-5-20250929-v1:0[1m]")
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{
+ `Priced by: catalog key "us.anthropic.claude-sonnet-4-5-20250929-v1:0"`,
+ "Match: exact after stripping context_window",
+ "input 3.30",
+ "Catalog: LiteLLM",
+ } {
+ if !strings.Contains(out, want) {
+ t.Fatalf("show missing %q:\n%s", want, out)
+ }
+ }
+}
+
+func TestPricingShowOverrideJSON(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ path := writeOverrides(t, testOverridesDoc)
+ out, _, err := runPricing(t, "show", "claude-sonnet-4-5-20250929", "--pricing-file", path, "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got pricingShowResult
+ if err := json.Unmarshal([]byte(out), &got); err != nil {
+ t.Fatalf("%v\n%s", err, out)
+ }
+ // The catalog has an exact row for the dated snapshot; the override for the model wins.
+ if !got.Priced || got.Source != pricing.SourceOverride || got.Key != "claude-sonnet-4-5" || got.Match != "exact" ||
+ len(got.Stripped) != 1 || got.Stripped[0] != pricing.StrippedDateSnapshot {
+ t.Fatalf("resolution = %+v", got)
+ }
+ if got.Rates == nil || got.Rates.Input != 2.4 || got.Rates.CacheRead != 0.24 || got.Rates.CacheWrite != 0 {
+ t.Fatalf("rates = %+v", got.Rates)
+ }
+ // The band restates input and output and inherits the row's cache-read rate.
+ if len(got.Bands) != 1 || got.Bands[0].AboveTokens != 200_000 || got.Bands[0].Rates.Input != 4.8 || got.Bands[0].Rates.CacheRead != 0.24 {
+ t.Fatalf("bands = %+v", got.Bands)
+ }
+ if strings.Join(got.Fallbacks, ",") != "cache_write_at_input_rate,cache_write_1h_at_write_rate" {
+ t.Fatalf("fallbacks = %v", got.Fallbacks)
+ }
+ if got.Overrides == nil || got.Overrides.Path != path || len(got.Overrides.SHA256) != 64 {
+ t.Fatalf("overrides = %+v", got.Overrides)
+ }
+
+ // An alias through to a catalog key.
+ out, _, err = runPricing(t, "show", "My-Gateway-Model", "--pricing-file", path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{`Priced by: catalog key "gpt-5"`, "Alias: my-gateway-model -> gpt-5", "Match: canonical", "Overrides: " + path} {
+ if !strings.Contains(out, want) {
+ t.Fatalf("alias show missing %q:\n%s", want, out)
+ }
+ }
+ // An override row shows its comment and that it replaces a catalog entry.
+ out, _, _ = runPricing(t, "show", "claude-sonnet-4-5", "--pricing-file", path)
+ for _, want := range []string{`override "claude-sonnet-4-5"`, "Comment: 20% off list", "replaces the catalog entry of the same name"} {
+ if !strings.Contains(out, want) {
+ t.Fatalf("override show missing %q:\n%s", want, out)
+ }
+ }
+}
+
+func TestPricingShowUnpriced(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ path := writeOverrides(t, `{"schema":"beacon.pricing.overrides/v1","models":{
+ "gw-a/acme-x":{"input_usd_per_mtok":1,"output_usd_per_mtok":1},
+ "gw-b/acme-x":{"input_usd_per_mtok":2,"output_usd_per_mtok":2}}}`)
+ out, _, err := runPricing(t, "show", "acme-x", "--pricing-file", path, "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got pricingShowResult
+ if err := json.Unmarshal([]byte(out), &got); err != nil {
+ t.Fatal(err)
+ }
+ if got.Priced || got.CandidatesSource != pricing.SourceOverride || strings.Join(got.Candidates, ",") != "gw-a/acme-x,gw-b/acme-x" || got.Rates != nil {
+ t.Fatalf("tie = %+v", got)
+ }
+ out, _, _ = runPricing(t, "show", "nobody-prices-this")
+ if !strings.Contains(out, "Not priced: no catalog key or override matches it") {
+ t.Fatalf("unpriced text:\n%s", out)
+ }
+}
+
+func TestPricingListMarksOverrides(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ path := writeOverrides(t, testOverridesDoc)
+ out, _, err := runPricing(t, "list", "--provider", "anthropic", "--pricing-file", path, "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got struct {
+ Models []pricingListEntry `json:"models"`
+ Aliases []pricingAliasEntry `json:"aliases"`
+ }
+ if err := json.Unmarshal([]byte(out), &got); err != nil {
+ t.Fatal(err)
+ }
+ if len(got.Models) < 2 || got.Models[0].Key != "claude-sonnet-4-5" || got.Models[0].Source != pricing.SourceOverride {
+ t.Fatalf("first entry = %+v", got.Models[0])
+ }
+ var overridden, other bool
+ for _, m := range got.Models {
+ if m.Provider != "anthropic" {
+ t.Fatalf("provider filter let %+v through", m)
+ }
+ if m.Source == pricing.SourceCatalog && m.Key == "claude-sonnet-4-5" {
+ overridden = m.Overridden
+ }
+ if m.Key == "acme-coder-2" {
+ other = true
+ }
+ }
+ if !overridden || other {
+ t.Fatalf("overridden=%v acme listed=%v", overridden, other)
+ }
+ // The alias resolves to an openai entry, so the anthropic filter drops it.
+ if len(got.Aliases) != 0 {
+ t.Fatalf("aliases = %+v", got.Aliases)
+ }
+
+ out, _, err = runPricing(t, "list", "--provider", "acme", "--pricing-file", path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(out, "acme-coder-2") || !strings.Contains(out, "override") || strings.Contains(out, "claude-") {
+ t.Fatalf("acme list:\n%s", out)
+ }
+}
+
+func TestPricingInfo(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ out, _, err := runPricing(t, "info", "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var got pricingInfoResult
+ if err := json.Unmarshal([]byte(out), &got); err != nil {
+ t.Fatal(err)
+ }
+ if got.Catalog.Commit == "" || got.Catalog.URL == "" || got.CatalogModels < 100 || got.OverridesFound ||
+ got.OverridesPath != filepath.Join(home, ".beacon", "endpoint", "pricing", "overrides.json") {
+ t.Fatalf("info = %+v", got)
+ }
+ // info reports an unusable file instead of failing on it.
+ bad := writeOverrides(t, `{"schema":"nope"}`)
+ out, _, err = runPricing(t, "info", "--pricing-file", bad)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(out, "NOT usable") || !strings.Contains(out, `schema "nope"`) || !strings.Contains(out, "Commit:") {
+ t.Fatalf("info text:\n%s", out)
+ }
+}
+
+func TestPricingValidate(t *testing.T) {
+ testenv.SetHome(t, t.TempDir())
+ path := writeOverrides(t, testOverridesDoc)
+ out, _, err := runPricing(t, "validate", "--pricing-file", path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{
+ "ok: " + path,
+ "2 model(s), 1 alias(es)",
+ "model claude-sonnet-4-5 replaces the catalog entry of the same name",
+ "alias my-gateway-model -> gpt-5 (catalog)",
+ "unpublished, priced by fallback: cache_read_at_input_rate",
+ } {
+ if !strings.Contains(out, want) {
+ t.Fatalf("validate missing %q:\n%s", want, out)
+ }
+ }
+
+ bad := writeOverrides(t, `{"schema":"beacon.pricing.overrides/v1","models":{"acme":{"input_usd_per_mtok":3,"output_usd_per_mtok":0.0000001}}}`)
+ if _, _, err := runPricing(t, "validate", "--pricing-file", bad); err == nil || !strings.Contains(err.Error(), `models["acme"].output_usd_per_mtok`) {
+ t.Fatalf("invalid file: %v", err)
+ }
+ // There is nothing to validate at the default location.
+ if _, _, err := runPricing(t, "validate"); err == nil || !strings.Contains(err.Error(), "no pricing overrides file at") {
+ t.Fatalf("missing default: %v", err)
+ }
+ // Collisions are warnings on stderr, not failures.
+ tie := writeOverrides(t, `{"schema":"beacon.pricing.overrides/v1","models":{
+ "gw-a/acme-x":{"input_usd_per_mtok":1,"output_usd_per_mtok":1},
+ "gw-b/acme-x":{"input_usd_per_mtok":2,"output_usd_per_mtok":2}}}`)
+ _, stderr, err := runPricing(t, "validate", "--pricing-file", tie)
+ if err != nil || !strings.Contains(stderr, "warning:") {
+ t.Fatalf("tie: err=%v stderr=%q", err, stderr)
+ }
+}
+
+func TestPricingDefaultFileFollowsUserAndSystemMode(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ userPath := pricing.DefaultOverridesPath(true)
+ if err := os.MkdirAll(filepath.Dir(userPath), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(userPath, []byte(testOverridesDoc), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ out, _, err := runPricing(t, "show", "acme-coder-2", "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(out, `"source": "override"`) {
+ t.Fatalf("user default not read:\n%s", out)
+ }
+ out, _, err = runPricing(t, "info", "--system", "--json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ var info pricingInfoResult
+ if err := json.Unmarshal([]byte(out), &info); err != nil {
+ t.Fatal(err)
+ }
+ if info.OverridesPath != pricing.DefaultOverridesPath(false) || strings.HasPrefix(info.OverridesPath, home) {
+ t.Fatalf("system path = %q", info.OverridesPath)
+ }
+}
+
+// token-usage prices with the overrides file: --pricing-file names one, the default location is
+// read when present, a missing named file and an invalid file are errors.
+func TestTokenUsagePricesWithOverrides(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ lines := []string{
+ // A Codex turn span on a gateway alias for gpt-5 ($1.25 in, $10 out list).
+ `{"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":"my-gateway-model","gen_ai":{"usage":{"input_tokens":1000,"output_tokens":200}},"message":"codex.turn.token_usage","raw":{"source":"codex_turn_span","turn_id":"turn-1"}}`,
+ // An OpenCode step on an internal model.
+ `{"timestamp":"2026-06-11T10:02: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":"opencode","collection_method":"plugin"},"session":{"id":"oc-1"},"model":"acme-coder-2","gen_ai":{"usage":{"input_tokens":1000,"output_tokens":100}},"message":"opencode.step"}`,
+ }
+ if err := os.WriteFile(logPath, []byte(strings.Join(lines, "\n")+"\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+
+ // No file anywhere: both models are unpriced.
+ var report map[string]interface{}
+ if err := json.Unmarshal([]byte(runTokenUsageCommand(t, "--log-path", logPath, "--json")), &report); err != nil {
+ t.Fatal(err)
+ }
+ if totals := report["totals"].(map[string]interface{}); totals["unpriced_events"] != 2.0 {
+ t.Fatalf("no overrides: totals = %v", totals)
+ }
+
+ path := writeOverrides(t, testOverridesDoc)
+ output := runTokenUsageCommand(t, "--log-path", logPath, "--json", "--pricing-file", path)
+ if err := json.Unmarshal([]byte(output), &report); err != nil {
+ t.Fatal(err)
+ }
+ totals := report["totals"].(map[string]interface{})
+ // gpt-5 via the alias: 1000 x $1.25 + 200 x $10 = $0.00325; acme-coder-2: 1000 x $1 +
+ // 100 x $4 = $0.0014.
+ if totals["estimated_cost_usd"] != 0.00465 || totals["unpriced_events"] != nil {
+ t.Fatalf("with overrides: totals = %v", totals)
+ }
+ block := report["pricing"].(map[string]interface{})
+ overrides := block["overrides"].(map[string]interface{})
+ if overrides["path"] != path || len(overrides["sha256"].(string)) != 64 {
+ t.Fatalf("overrides block = %v", overrides)
+ }
+ sources := map[string]string{}
+ for _, m := range block["models"].([]interface{}) {
+ row := m.(map[string]interface{})
+ sources[row["model"].(string)] = row["source"].(string)
+ if row["model"] == "my-gateway-model" && (row["alias"] != "my-gateway-model" || row["key"] != "gpt-5") {
+ t.Fatalf("alias row = %v", row)
+ }
+ }
+ if sources["acme-coder-2"] != "override" || sources["my-gateway-model"] != "catalog" {
+ t.Fatalf("sources = %v", sources)
+ }
+
+ text := runTokenUsageCommand(t, "--log-path", logPath, "--pricing-file", path)
+ for _, want := range []string{"overrides from " + path, "priced by the overrides file: acme-coder-2, my-gateway-model"} {
+ if !strings.Contains(text, want) {
+ t.Fatalf("text missing %q:\n%s", want, text)
+ }
+ }
+
+ // The default location is read without the flag.
+ defaultPath := pricing.DefaultOverridesPath(true)
+ if err := os.MkdirAll(filepath.Dir(defaultPath), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(defaultPath, []byte(testOverridesDoc), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if out := runTokenUsageCommand(t, "--log-path", logPath, "--json"); !strings.Contains(out, defaultPath) {
+ t.Fatalf("default overrides file not used:\n%s", out)
+ }
+
+ // Errors: a named file that does not exist, and an invalid default file.
+ for _, tc := range []struct {
+ args []string
+ want string
+ }{
+ {[]string{"--pricing-file", filepath.Join(home, "missing.json")}, "no pricing overrides file at"},
+ } {
+ if err := tokenUsageError(t, append([]string{"--log-path", logPath}, tc.args...)...); err == nil || !strings.Contains(err.Error(), tc.want) {
+ t.Fatalf("%v: err = %v", tc.args, err)
+ }
+ }
+ if err := os.WriteFile(defaultPath, []byte(`{"schema":"beacon.pricing.overrides/v1","models":{"x":{"input_usd_per_mtok":"$3","output_usd_per_mtok":1}}}`), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if err := tokenUsageError(t, "--log-path", logPath); err == nil || !strings.Contains(err.Error(), `models["x"].input_usd_per_mtok`) {
+ t.Fatalf("invalid default: err = %v", err)
+ }
+}
+
+func tokenUsageError(t *testing.T, args ...string) error {
+ t.Helper()
+ tokenUsageOpts = tokenUsageOptions{userMode: true}
+ if err := tokenUsageCmd.Flags().Parse(args); err != nil {
+ t.Fatalf("parse flags: %v", err)
+ }
+ var out bytes.Buffer
+ tokenUsageCmd.SetOut(&out)
+ defer tokenUsageCmd.SetOut(nil)
+ return runTokenUsage(tokenUsageCmd, nil)
+}
diff --git a/cli/beacon/cmd/token_usage.go b/cli/beacon/cmd/token_usage.go
index d7de8ad0..745bc9fc 100644
--- a/cli/beacon/cmd/token_usage.go
+++ b/cli/beacon/cmd/token_usage.go
@@ -10,6 +10,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/dashboard"
endpointinventory "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
@@ -29,6 +30,8 @@ type tokenUsageOptions struct {
bucket string
top int
coverage bool
+ // pricingFile names an overrides file to price with instead of the default location.
+ pricingFile string
}
var tokenUsageOpts tokenUsageOptions
@@ -73,9 +76,14 @@ func runTokenUsage(cmd *cobra.Command, args []string) error {
if err != nil {
return err
}
+ pricer, err := tokenUsagePricer(userMode, tokenUsageOpts.pricingFile)
+ if err != nil {
+ return err
+ }
opts := tokens.Options{
SessionID: tokenUsageOpts.session,
TopLimit: tokenUsageOpts.top,
+ Pricer: pricer,
}
if bucket := strings.TrimSpace(tokenUsageOpts.bucket); bucket != "" {
parsed, err := time.ParseDuration(bucket)
@@ -95,6 +103,17 @@ func runTokenUsage(cmd *cobra.Command, args []string) error {
return nil
}
+// tokenUsagePricer loads the overrides file the estimate prices with. The default location may
+// hold nothing, which is fine; a file named with --pricing-file must exist. An invalid file is
+// an error in both cases, because a report that quietly fell back to list prices would read as
+// priced at the rates the file was written to set.
+func tokenUsagePricer(userMode bool, explicit string) (*pricing.Pricer, error) {
+ if path := strings.TrimSpace(explicit); path != "" {
+ return pricing.LoadPricer(pricing.Default(), path, true)
+ }
+ return pricing.LoadPricer(pricing.Default(), pricing.DefaultOverridesPath(userMode), false)
+}
+
// runTokenCoverage answers "is this total all of it", which the usage report itself cannot: a
// runtime whose telemetry never arrives is indistinguishable from one nobody used, since both are
// simply absent from every rollup.
@@ -185,5 +204,6 @@ func init() {
tokenUsageCmd.Flags().StringVar(&tokenUsageOpts.runID, "run-id", "", "Filter by CI run id")
tokenUsageCmd.Flags().StringVar(&tokenUsageOpts.bucket, "bucket", "", "Time-series bucket size (for example 1h or 15m)")
tokenUsageCmd.Flags().IntVar(&tokenUsageOpts.top, "top", 0, "Limit each grouping to the top N entries (0 keeps all)")
+ tokenUsageCmd.Flags().StringVar(&tokenUsageOpts.pricingFile, "pricing-file", "", "Pricing overrides file for the cost estimate (defaults to <endpoint>/pricing/overrides.json when present)")
tokenUsageCmd.Flags().BoolVar(&tokenUsageOpts.coverage, "coverage", false, "Report which runtimes contributed token telemetry instead of the usage totals")
}
diff --git a/cli/beacon/internal/endpoint/dashboard/server.go b/cli/beacon/internal/endpoint/dashboard/server.go
index 6a290f9c..bc857d16 100644
--- a/cli/beacon/internal/endpoint/dashboard/server.go
+++ b/cli/beacon/internal/endpoint/dashboard/server.go
@@ -18,6 +18,7 @@ import (
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/inventory"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lensstore"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/lifecycle"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
)
@@ -314,7 +315,13 @@ func Handler(opts Options) (http.Handler, error) {
writeError(w, http.StatusInternalServerError, err)
return
}
- writeJSON(w, tokens.AggregateScopedWithContexts(events, contexts, "", tokenOptions(r)))
+ tokenOpts := tokenOptions(r)
+ // The same overrides file `beacon token-usage` reads by default, re-read on every request
+ // so an edit shows on the next reload. The dashboard only reads it. An invalid file does
+ // not fail the view: the estimate falls back to list prices and the response's
+ // pricing.overrides.error says why.
+ tokenOpts.Pricer, _ = pricing.LoadPricer(pricing.Default(), pricing.DefaultOverridesPath(rulesUserMode), false)
+ writeJSON(w, tokens.AggregateScopedWithContexts(events, contexts, "", tokenOpts))
})
// Coverage answers a different question from the rollup above -- "is this all of it" rather
// than "what did it cost" -- so it gets its own route rather than a flag on /api/tokens. A
diff --git a/cli/beacon/internal/endpoint/dashboard/static/app.js b/cli/beacon/internal/endpoint/dashboard/static/app.js
index 71659041..11584318 100644
--- a/cli/beacon/internal/endpoint/dashboard/static/app.js
+++ b/cli/beacon/internal/endpoint/dashboard/static/app.js
@@ -2591,12 +2591,15 @@ function usageTotal(usage = {}) {
(usage.reasoning_output_tokens || 0);
}
-// 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.
+// The estimate is labeled wherever it appears: it is a list price from the embedded catalog
+// (or the operator's pricing overrides file), 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 overrides = pricing?.overrides;
+ const parts = [overrides && !overrides.error ? "list price + overrides" : "list price"];
const catalog = pricing?.catalog;
if (catalog?.generated_at) parts.push(`catalog ${catalog.generated_at}`);
+ if (overrides?.error) parts.push("overrides file invalid, not used");
if (totals.unpriced_events) parts.push(`${totals.unpriced_events} unpriced events excluded`);
return parts.join(" · ");
}
diff --git a/cli/beacon/internal/endpoint/dashboard/tokens_pricing_test.go b/cli/beacon/internal/endpoint/dashboard/tokens_pricing_test.go
new file mode 100644
index 00000000..2ae01028
--- /dev/null
+++ b/cli/beacon/internal/endpoint/dashboard/tokens_pricing_test.go
@@ -0,0 +1,123 @@
+package dashboard
+
+import (
+ "bytes"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/tokens"
+)
+
+// /api/tokens prices with the same overrides file `beacon token-usage` reads by default,
+// re-reads it per request, survives an invalid one, and never writes it.
+func TestTokensEndpointUsesThePricingOverridesFile(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ logPath := filepath.Join(t.TempDir(), "runtime.jsonl")
+ // A Codex turn span on gpt-5 ($1.25 in, $10 out list) and an OpenCode step on an internal
+ // model the catalog does not know.
+ lines := `{"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":{"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}},"message":"codex.turn.token_usage","raw":{"source":"codex_turn_span","turn_id":"turn-1"}}
+{"timestamp":"2026-06-11T10:02:00Z","vendor":"beacon","product":"endpoint-agent","schema_version":"1.0","event":{"kind":"agent_runtime","action":"token.usage","category":"metric"},"severity":"info","endpoint":{"os":"darwin"},"harness":{"name":"opencode","collection_method":"plugin"},"session":{"id":"oc-1"},"model":"acme-coder-2","gen_ai":{"usage":{"input_tokens":1000,"output_tokens":100}},"message":"opencode.step"}
+`
+ if err := os.WriteFile(logPath, []byte(lines), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ handler, err := Handler(Options{UserMode: true, LogPath: logPath})
+ if err != nil {
+ t.Fatal(err)
+ }
+ get := func() tokens.Report {
+ t.Helper()
+ rec := httptest.NewRecorder()
+ handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/tokens", nil))
+ if rec.Code != http.StatusOK {
+ t.Fatalf("status %d: %s", rec.Code, rec.Body.String())
+ }
+ var report tokens.Report
+ if err := json.Unmarshal(rec.Body.Bytes(), &report); err != nil {
+ t.Fatal(err)
+ }
+ return report
+ }
+
+ // No file: list prices, no overrides block, the internal model unpriced.
+ // gpt-5: 1000 x $1.25 + 200 x $10 = $0.00325.
+ report := get()
+ if report.Pricing.Overrides != nil || report.Totals.EstimatedCostUSD != 0.00325 || report.Totals.UnpricedEvents != 1 {
+ t.Fatalf("no file: totals %+v overrides %+v", report.Totals, report.Pricing.Overrides)
+ }
+
+ path := pricing.DefaultOverridesPath(true)
+ if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+ t.Fatal(err)
+ }
+ doc := []byte(`{"schema":"beacon.pricing.overrides/v1","models":{
+ "gpt-5":{"input_usd_per_mtok":1,"output_usd_per_mtok":8},
+ "acme-coder-2":{"input_usd_per_mtok":2,"output_usd_per_mtok":4}}}`)
+ if err := os.WriteFile(path, doc, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ before, err := os.Stat(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ // The file is picked up without restarting the dashboard. gpt-5: 1000 x $1 + 200 x $8 =
+ // $0.0026; acme-coder-2: 1000 x $2 + 100 x $4 = $0.0024.
+ report = get()
+ if o := report.Pricing.Overrides; o == nil || o.Path != path || o.Models != 2 || o.Error != "" {
+ t.Fatalf("overrides block = %+v", report.Pricing.Overrides)
+ }
+ if report.Totals.EstimatedCostUSD != 0.005 || report.Totals.UnpricedEvents != 0 {
+ t.Fatalf("with overrides: totals %+v", report.Totals)
+ }
+ for _, m := range report.Pricing.Models {
+ if m.Source != pricing.SourceOverride {
+ t.Fatalf("model %s source = %q, want override", m.Model, m.Source)
+ }
+ }
+
+ // An invalid file degrades to list prices and says why; the view still answers.
+ if err := os.WriteFile(path, []byte(`{"schema":"beacon.pricing.overrides/v1","models":{"gpt-5":{"input_usd_per_mtok":-1,"output_usd_per_mtok":8}}}`), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ report = get()
+ if o := report.Pricing.Overrides; o == nil || o.Error == "" || o.Path != path {
+ t.Fatalf("invalid file block = %+v", report.Pricing.Overrides)
+ }
+ if report.Totals.EstimatedCostUSD != 0.00325 {
+ t.Fatalf("invalid file: totals %+v", report.Totals)
+ }
+
+ // Read-only: restore the valid file and check that serving leaves it byte-identical.
+ if err := os.WriteFile(path, doc, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ get()
+ after, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !bytes.Equal(after, doc) {
+ t.Fatal("the dashboard changed the overrides file")
+ }
+ if testenv.HasPOSIXFileModes() {
+ info, err := os.Stat(path)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if info.Mode().Perm() != before.Mode().Perm() {
+ t.Fatalf("mode changed from %v to %v", before.Mode().Perm(), info.Mode().Perm())
+ }
+ }
+ entries, err := os.ReadDir(filepath.Dir(path))
+ if err != nil || len(entries) != 1 {
+ t.Fatalf("pricing dir holds %v (%v), want only the overrides file", entries, err)
+ }
+}
diff --git a/cli/beacon/internal/pricing/catalog.go b/cli/beacon/internal/pricing/catalog.go
index 10a479f0..c7193374 100644
--- a/cli/beacon/internal/pricing/catalog.go
+++ b/cli/beacon/internal/pricing/catalog.go
@@ -4,7 +4,6 @@ import (
_ "embed"
"encoding/json"
"fmt"
- "sort"
"sync"
)
@@ -44,9 +43,7 @@ type CatalogFile struct {
// Catalog is a loaded, validated price list with its lookup indexes.
type Catalog struct {
file CatalogFile
- keys []string
- // index[r] maps a key spelled at rung r to every catalog key with that spelling.
- index [numRungs]map[string][]string
+ *table
}
var (
@@ -67,7 +64,8 @@ func Default() *Catalog {
return defaultCatalog
}
-// Lookup resolves model against the embedded catalog. See Catalog.Lookup.
+// Lookup resolves model against the embedded catalog alone, without any overrides. See
+// Catalog.Lookup.
func Lookup(model string) (Resolution, bool) {
return Default().Lookup(model)
}
@@ -87,27 +85,12 @@ func LoadCatalog(data []byte) (*Catalog, error) {
if len(file.Models) == 0 {
return nil, fmt.Errorf("catalog has no models")
}
- c := &Catalog{file: file}
for key, rates := range file.Models {
if err := validateRates(rates); err != nil {
return nil, fmt.Errorf("model %q: %w", key, err)
}
- c.keys = append(c.keys, key)
}
- sort.Strings(c.keys)
- for r := range c.index {
- c.index[r] = make(map[string][]string, len(c.keys))
- }
- for _, key := range c.keys {
- for r := rung(0); r < numRungs; r++ {
- spelled := spell(r, key)
- if spelled == "" {
- continue
- }
- c.index[r][spelled] = append(c.index[r][spelled], key)
- }
- }
- return c, nil
+ return &Catalog{file: file, table: newTable(file.Models)}, nil
}
func validateRates(r Rates) error {
diff --git a/cli/beacon/internal/pricing/doc.go b/cli/beacon/internal/pricing/doc.go
index 52540152..6099285b 100644
--- a/cli/beacon/internal/pricing/doc.go
+++ b/cli/beacon/internal/pricing/doc.go
@@ -67,4 +67,20 @@
// Lookup turns what a runtime called the model into a catalog entry by a strict ladder and
// never by substring or prefix similarity; see Lookup for the rungs. Two catalog entries that
// match at the same rung with different rates leave the model unpriced rather than picking one.
+//
+// # Overrides
+//
+// An operator can price what the catalog cannot -- internal models, releases newer than the
+// catalog, gateway names -- and replace list prices with negotiated ones, in a local JSON file
+// (schema "beacon.pricing.overrides/v1", default <BaseDir>/pricing/overrides.json, see
+// DefaultOverridesPath and docs/cli/pricing.mdx). Beacon only reads that file: the CLI and the
+// dashboard load it per run or per request, and nothing in Beacon writes it. Its rates are
+// decimal US dollars per million tokens, converted exactly to integer microdollars; a value that
+// is negative, zero, finer than a microdollar, quoted, or above MaxOverrideUSDPerMTok is refused
+// with an error naming its key, and so is an unknown or repeated key. A row replaces the
+// catalog row of every name that reaches it: an omitted cache rate is unpublished, priced by the
+// fallbacks above, not inherited from the catalog. An alias sends a reported name to an exact
+// row of the file or catalog key. Pricer.Lookup runs the same ladder over the file's names
+// first, and the catalog sees only models no override name reaches. Resolution.Source and
+// Alias say which list decided.
package pricing
diff --git a/cli/beacon/internal/pricing/lookup.go b/cli/beacon/internal/pricing/lookup.go
index effca5c6..4c8310fb 100644
--- a/cli/beacon/internal/pricing/lookup.go
+++ b/cli/beacon/internal/pricing/lookup.go
@@ -3,6 +3,7 @@ package pricing
import (
"reflect"
"regexp"
+ "sort"
"strings"
"github.com/asymptote-labs/agent-beacon/pkg/asymptoteobserve"
@@ -42,22 +43,66 @@ const (
StrippedEffortSuffix = "effort_suffix"
)
+// Values of Resolution.Source: which price list the rates came from.
+const (
+ SourceCatalog = "catalog"
+ SourceOverride = "override"
+)
+
// Resolution is the outcome of Lookup.
type Resolution struct {
// Model is the string that was looked up.
Model string
- // Key is the catalog key that priced it, and Rates its entry. Empty when unpriced.
- Key string
- Rates Rates
+ // Key is the entry that priced it, and Rates its entry. Empty when unpriced. Source says
+ // whether Key is a catalog key (SourceCatalog) or a model in an overrides file
+ // (SourceOverride).
+ Key string
+ Rates Rates
+ Source string
+ // Alias is set when the model matched an alias in an overrides file rather than a priced
+ // entry; Key is then the alias's target. Match and Stripped describe how the model met the
+ // alias, since the alias-to-target step is always exact.
+ Alias string
// Match is the spelling rung that matched; Stripped lists the reductions that were
// needed first, in the order applied. Together they say how loose the match was.
Match Match
Stripped []string
- // Candidates is set when the model was left unpriced because several catalog keys
- // matched at the same rung with different rates.
+ // Candidates is set when the model was left unpriced because several entries matched at
+ // the same rung with different rates. When the overrides decided the tie, they are names
+ // from the overrides file.
Candidates []string
}
+// table is a set of priced names and the spelling indexes Lookup runs over. The catalog is one;
+// an overrides file is another.
+type table struct {
+ models map[string]Rates
+ keys []string
+ // index[r] maps a key spelled at rung r to every key with that spelling.
+ index [numRungs]map[string][]string
+}
+
+func newTable(models map[string]Rates) *table {
+ t := &table{models: models}
+ for key := range models {
+ t.keys = append(t.keys, key)
+ }
+ sort.Strings(t.keys)
+ for r := range t.index {
+ t.index[r] = make(map[string][]string, len(t.keys))
+ }
+ for _, key := range t.keys {
+ for r := rung(0); r < numRungs; r++ {
+ spelled := spell(r, key)
+ if spelled == "" {
+ continue
+ }
+ t.index[r][spelled] = append(t.index[r][spelled], key)
+ }
+ }
+ return t
+}
+
type rung int
const (
@@ -153,6 +198,14 @@ var reductions = []struct {
// Resolution.Candidates names the disagreeing keys. Lookup does not fall through to a looser
// rung after a tie, since a looser rung can only match more keys.
func (c *Catalog) Lookup(model string) (Resolution, bool) {
+ res, ok := c.table.lookup(model)
+ if ok || len(res.Candidates) > 0 {
+ res.Source = SourceCatalog
+ }
+ return res, ok
+}
+
+func (c *table) lookup(model string) (Resolution, bool) {
res := Resolution{Model: model}
query := strings.TrimSpace(model)
if query == "" {
@@ -186,23 +239,23 @@ func (c *Catalog) Lookup(model string) (Resolution, bool) {
// matchSpellings runs the spelling rungs for one query. decided reports that some rung
// matched; priced reports that its candidates agreed on a price.
-func (c *Catalog) matchSpellings(query string, res *Resolution) (priced, decided bool) {
+func (c *table) matchSpellings(query string, res *Resolution) (priced, decided bool) {
for r := rung(0); r < numRungs; r++ {
spelled := spell(r, query)
keys := c.index[r][spelled]
if len(keys) == 0 {
continue
}
- first := c.file.Models[keys[0]]
+ first := c.models[keys[0]]
for _, k := range keys[1:] {
- if !samePrice(first, c.file.Models[k]) {
+ if !samePrice(first, c.models[k]) {
res.Candidates = append([]string(nil), keys...)
res.Match = rungMatch[r]
return false, true
}
}
res.Key = preferredKey(keys, query)
- res.Rates = c.file.Models[res.Key]
+ res.Rates = c.models[res.Key]
res.Match = rungMatch[r]
return true, true
}
diff --git a/cli/beacon/internal/pricing/overrides.go b/cli/beacon/internal/pricing/overrides.go
new file mode 100644
index 00000000..a841b916
--- /dev/null
+++ b/cli/beacon/internal/pricing/overrides.go
@@ -0,0 +1,512 @@
+package pricing
+
+import (
+ "bytes"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "math/big"
+ "os"
+ "path/filepath"
+ "sort"
+ "strconv"
+ "strings"
+
+ endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"
+)
+
+// OverridesSchema is the schema string an overrides file must declare. A layout change gets a
+// new string, and a file declaring any other one is refused rather than half-read.
+const OverridesSchema = "beacon.pricing.overrides/v1"
+
+// OverridesFileName is the overrides file's name inside OverridesDir.
+const OverridesFileName = "overrides.json"
+
+// maxOverridesFileBytes bounds what ReadOverridesFile reads. A hand-written price list is a few
+// kilobytes; anything near this is not one.
+const maxOverridesFileBytes = 4 << 20
+
+// MaxOverrideUSDPerMTok is the largest rate an overrides file may set: $100,000 per million
+// tokens, ten cents a token. The most expensive published list price is two orders of magnitude
+// below it, so a larger value is a unit mistake (a per-token or per-thousand price written where
+// a per-million one belongs) and is refused rather than turned into a figure nobody paid.
+const MaxOverrideUSDPerMTok = 100_000
+
+// maxAboveTokens bounds a band threshold. No model has a context window near it.
+const maxAboveTokens = 1_000_000_000_000
+
+// OverridesDir is where the user or system endpoint keeps its pricing overrides.
+func OverridesDir(userMode bool) string {
+ return filepath.Join(endpointconfig.BaseDir(userMode), "pricing")
+}
+
+// DefaultOverridesPath is the overrides file `beacon token-usage`, `beacon pricing` and the
+// dashboard read when no other file is named. Beacon never writes it: the file is the
+// operator's, written by hand or by their own tooling.
+func DefaultOverridesPath(userMode bool) string {
+ return filepath.Join(OverridesDir(userMode), OverridesFileName)
+}
+
+// Overrides is a loaded, validated overrides file: price rows that replace or extend the
+// catalog, and aliases that send a reported name to an existing entry.
+type Overrides struct {
+ path string
+ digest string
+ comment string
+ // models are the file's own price rows; comments their optional notes.
+ models map[string]Rates
+ comments map[string]string
+ // aliases map an alias to its target; aliasSource says whether the target is one of
+ // models (SourceOverride) or a catalog key (SourceCatalog).
+ aliases map[string]string
+ aliasSource map[string]string
+ // table indexes models and aliases together, an alias carrying its target's rates, so one
+ // Lookup ladder decides between them exactly as it decides between catalog keys.
+ table *table
+}
+
+// Path is the file the overrides were read from ("" when loaded from bytes with no path).
+func (o *Overrides) Path() string { return o.path }
+
+// SHA256 is the hex SHA-256 of the file's bytes, so a report can say exactly which file priced
+// it.
+func (o *Overrides) SHA256() string { return o.digest }
+
+// Comment is the file's top-level comment.
+func (o *Overrides) Comment() string { return o.comment }
+
+// Models returns the names of the file's price rows, sorted.
+func (o *Overrides) Models() []string { return sortedNames(o.models) }
+
+// Rates returns the file's row for an exact model name.
+func (o *Overrides) Rates(name string) (Rates, bool) {
+ r, ok := o.models[name]
+ return r, ok
+}
+
+// ModelComment returns the optional comment on a price row.
+func (o *Overrides) ModelComment(name string) string { return o.comments[name] }
+
+// Aliases returns the alias names, sorted.
+func (o *Overrides) Aliases() []string { return sortedNames(o.aliases) }
+
+// AliasTarget returns the entry an alias points at and whether that entry is an override row
+// (SourceOverride) or a catalog key (SourceCatalog).
+func (o *Overrides) AliasTarget(alias string) (target, source string, ok bool) {
+ target, ok = o.aliases[alias]
+ return target, o.aliasSource[alias], ok
+}
+
+// Warnings lists names in the file that collide once spelled loosely: two entries that Lookup
+// would both match at one rung with different prices, which leaves a model that reaches them
+// only by that rung unpriced. An exact query for either name still prices it, so this is a
+// warning and not an error.
+func (o *Overrides) Warnings() []string {
+ var out []string
+ // A collision at one rung repeats at every looser one; it is reported once, at the first.
+ seen := map[string]bool{}
+ for r := rungCanonical; r < numRungs; r++ {
+ for _, spelled := range sortedNames(o.table.index[r]) {
+ keys := o.table.index[r][spelled]
+ id := spelled + "\x00" + strings.Join(keys, "\x00")
+ if len(keys) < 2 || seen[id] {
+ continue
+ }
+ seen[id] = true
+ first := o.table.models[keys[0]]
+ for _, k := range keys[1:] {
+ if !samePrice(first, o.table.models[k]) {
+ out = append(out, fmt.Sprintf("%s are the same name at the %s rung (%q) with different prices; a model reported as %q is left unpriced",
+ quoteList(keys), rungMatch[r], spelled, spelled))
+ break
+ }
+ }
+ }
+ }
+ return out
+}
+
+func quoteList(names []string) string {
+ quoted := make([]string, len(names))
+ for i, n := range names {
+ quoted[i] = fmt.Sprintf("%q", n)
+ }
+ return strings.Join(quoted, ", ")
+}
+
+func sortedNames[V any](m map[string]V) []string {
+ out := make([]string, 0, len(m))
+ for k := range m {
+ out = append(out, k)
+ }
+ sort.Strings(out)
+ return out
+}
+
+// The file layout. Rates are json.RawMessage so a value is converted from its decimal text
+// exactly, never through a float64, and so a quoted number can be refused.
+type overridesJSON struct {
+ Schema string `json:"schema"`
+ Comment string `json:"comment,omitempty"`
+ Models map[string]overrideRowJSON `json:"models"`
+ Aliases map[string]string `json:"aliases"`
+}
+
+type overrideRatesJSON struct {
+ Input json.RawMessage `json:"input_usd_per_mtok"`
+ Output json.RawMessage `json:"output_usd_per_mtok"`
+ CacheRead json.RawMessage `json:"cache_read_usd_per_mtok"`
+ CacheWrite json.RawMessage `json:"cache_write_usd_per_mtok"`
+ CacheWrite1h json.RawMessage `json:"cache_write_1h_usd_per_mtok"`
+}
+
+type overrideRowJSON struct {
+ Provider string `json:"provider,omitempty"`
+ Comment string `json:"comment,omitempty"`
+ overrideRatesJSON
+ Bands []overrideBandJSON `json:"bands,omitempty"`
+}
+
+type overrideBandJSON struct {
+ AboveTokens json.RawMessage `json:"above_tokens"`
+ overrideRatesJSON
+}
+
+// ReadOverridesFile reads and validates the overrides file at path. A missing file is returned
+// as an error satisfying errors.Is(err, os.ErrNotExist), so a caller reading the default path
+// can treat it as "no overrides" while one reading a path the user named can refuse it.
+func ReadOverridesFile(path string, catalog *Catalog) (*Overrides, error) {
+ f, err := os.Open(path)
+ if errors.Is(err, os.ErrNotExist) {
+ return nil, fmt.Errorf("no pricing overrides file at %s: %w", path, err)
+ }
+ if err != nil {
+ return nil, fmt.Errorf("read pricing overrides %s: %w", path, err)
+ }
+ defer f.Close()
+ data, err := io.ReadAll(io.LimitReader(f, maxOverridesFileBytes+1))
+ if err != nil {
+ return nil, fmt.Errorf("read pricing overrides %s: %w", path, err)
+ }
+ if len(data) > maxOverridesFileBytes {
+ return nil, fmt.Errorf("pricing overrides %s: larger than %d bytes", path, maxOverridesFileBytes)
+ }
+ o, err := LoadOverrides(data, catalog)
+ if err != nil {
+ return nil, fmt.Errorf("pricing overrides %s: %w", path, err)
+ }
+ o.path = path
+ return o, nil
+}
+
+// LoadOverrides parses and validates an overrides document against catalog, which alias
+// targets may name.
+//
+// Every error names the offending key as a path into the document (models["x"].bands[0]...),
+// because a file that is refused prices nothing from it and the reader has to find the line.
+func LoadOverrides(data []byte, catalog *Catalog) (*Overrides, error) {
+ if err := checkDuplicateKeys(data); err != nil {
+ return nil, err
+ }
+ dec := json.NewDecoder(bytes.NewReader(data))
+ // An unknown field is almost always a misspelled rate. Ignoring it would leave that rate
+ // unpublished and price its tokens by a fallback the author never asked for.
+ dec.DisallowUnknownFields()
+ var file overridesJSON
+ if err := dec.Decode(&file); err != nil {
+ return nil, fmt.Errorf("parse: %w", err)
+ }
+ if dec.More() {
+ return nil, fmt.Errorf("parse: trailing data after the document")
+ }
+ if file.Schema != OverridesSchema {
+ return nil, fmt.Errorf("schema %q, want %q", file.Schema, OverridesSchema)
+ }
+ sum := sha256.Sum256(data)
+ o := &Overrides{
+ digest: hex.EncodeToString(sum[:]),
+ comment: file.Comment,
+ models: map[string]Rates{},
+ comments: map[string]string{},
+ aliases: map[string]string{},
+ aliasSource: map[string]string{},
+ }
+ for _, name := range sortedNames(file.Models) {
+ where := fmt.Sprintf("models[%q]", name)
+ if err := checkName(where, name); err != nil {
+ return nil, err
+ }
+ rates, err := convertRow(where, file.Models[name])
+ if err != nil {
+ return nil, err
+ }
+ o.models[name] = rates
+ if c := file.Models[name].Comment; c != "" {
+ o.comments[name] = c
+ }
+ }
+ entries := make(map[string]Rates, len(o.models)+len(file.Aliases))
+ for name, rates := range o.models {
+ entries[name] = rates
+ }
+ for _, alias := range sortedNames(file.Aliases) {
+ where := fmt.Sprintf("aliases[%q]", alias)
+ if err := checkName(where, alias); err != nil {
+ return nil, err
+ }
+ if _, clash := o.models[alias]; clash {
+ return nil, fmt.Errorf("%s: %q is also a model in this file; a name is either priced or an alias", where, alias)
+ }
+ target := file.Aliases[alias]
+ if strings.TrimSpace(target) == "" {
+ return nil, fmt.Errorf("%s: target is empty", where)
+ }
+ // The target is an exact name: the file's own rows first, as they win everywhere else,
+ // then the catalog. Matching it loosely would let one typo price a different model.
+ if rates, ok := o.models[target]; ok {
+ o.aliasSource[alias] = SourceOverride
+ entries[alias] = rates
+ } else if rates, ok := catalog.Rates(target); ok {
+ o.aliasSource[alias] = SourceCatalog
+ entries[alias] = rates
+ } else {
+ return nil, fmt.Errorf("%s: target %q is neither a model in this file nor a catalog key (beacon pricing list prints the catalog keys)", where, target)
+ }
+ o.aliases[alias] = target
+ }
+ o.table = newTable(entries)
+ return o, nil
+}
+
+func checkName(where, name string) error {
+ if strings.TrimSpace(name) == "" {
+ return fmt.Errorf("%s: the name is empty", where)
+ }
+ if strings.TrimSpace(name) != name {
+ return fmt.Errorf("%s: the name has leading or trailing white space", where)
+ }
+ return nil
+}
+
+func convertRow(where string, row overrideRowJSON) (Rates, error) {
+ base, err := convertSet(where, row.overrideRatesJSON, nil)
+ if err != nil {
+ return Rates{}, err
+ }
+ if base.Input == 0 {
+ return Rates{}, fmt.Errorf("%s.input_usd_per_mtok: required", where)
+ }
+ if base.Output == 0 {
+ return Rates{}, fmt.Errorf("%s.output_usd_per_mtok: required", where)
+ }
+ rates := Rates{Provider: strings.TrimSpace(row.Provider), RateSet: base}
+ for i, b := range row.Bands {
+ bwhere := fmt.Sprintf("%s.bands[%d]", where, i)
+ above, err := convertAbove(bwhere+".above_tokens", b.AboveTokens)
+ if err != nil {
+ return Rates{}, err
+ }
+ set, err := convertSet(bwhere, b.overrideRatesJSON, &base)
+ if err != nil {
+ return Rates{}, err
+ }
+ rates.Bands = append(rates.Bands, Band{AboveTokens: above, RateSet: set})
+ }
+ // Cost walks bands in increasing order, so the file may list them in any order, but two
+ // bands at one threshold are two answers to one question.
+ sort.SliceStable(rates.Bands, func(i, j int) bool { return rates.Bands[i].AboveTokens < rates.Bands[j].AboveTokens })
+ for i := 1; i < len(rates.Bands); i++ {
+ if rates.Bands[i].AboveTokens == rates.Bands[i-1].AboveTokens {
+ return Rates{}, fmt.Errorf("%s.bands: two bands above %d tokens", where, rates.Bands[i].AboveTokens)
+ }
+ }
+ if err := validateRates(rates); err != nil {
+ return Rates{}, fmt.Errorf("%s: %w", where, err)
+ }
+ return rates, nil
+}
+
+// convertSet converts one rate set. A band (inherit != nil) takes every field it leaves out
+// from the row's base rates, so a band need only restate what changes above its threshold; a
+// field unpublished in the base stays unpublished in the band.
+func convertSet(where string, raw overrideRatesJSON, inherit *RateSet) (RateSet, error) {
+ var set RateSet
+ if inherit != nil {
+ set = *inherit
+ }
+ fields := []struct {
+ name string
+ raw json.RawMessage
+ dst *int64
+ }{
+ {"input_usd_per_mtok", raw.Input, &set.Input},
+ {"output_usd_per_mtok", raw.Output, &set.Output},
+ {"cache_read_usd_per_mtok", raw.CacheRead, &set.CacheRead},
+ {"cache_write_usd_per_mtok", raw.CacheWrite, &set.CacheWrite},
+ {"cache_write_1h_usd_per_mtok", raw.CacheWrite1h, &set.CacheWrite1h},
+ }
+ for _, f := range fields {
+ v, present, err := convertRate(where+"."+f.name, f.raw)
+ if err != nil {
+ return RateSet{}, err
+ }
+ if present {
+ *f.dst = v
+ }
+ }
+ return set, nil
+}
+
+var (
+ microsPerUSD = big.NewRat(microdollarsPerDollar, 1)
+ maxRateMicros = new(big.Rat).SetInt64(MaxOverrideUSDPerMTok * microdollarsPerDollar)
+ maxAboveTokRat = new(big.Rat).SetInt64(maxAboveTokens)
+)
+
+// convertRate turns a USD-per-MTok JSON number into integer microdollars per MTok exactly. The
+// decimal text is read as a rational, so 0.30 is 300000 with no float rounding; a value finer
+// than one microdollar per MTok cannot be represented exactly and is refused rather than
+// rounded.
+func convertRate(where string, raw json.RawMessage) (int64, bool, error) {
+ r, present, err := numberLiteral(where, raw)
+ if err != nil || !present {
+ return 0, present, err
+ }
+ switch r.Sign() {
+ case -1:
+ return 0, false, fmt.Errorf("%s: %s is negative", where, raw)
+ case 0:
+ // A zero in the catalog means "unpublished", never "free"; an override keeps that rule,
+ // so a zero cannot quietly drop tokens from an estimate.
+ return 0, false, fmt.Errorf("%s: 0 is not a price; leave the field out when the rate is unpublished", where)
+ }
+ micros := new(big.Rat).Mul(r, microsPerUSD)
+ if micros.Cmp(maxRateMicros) > 0 {
+ return 0, false, fmt.Errorf("%s: %s is above the %d USD per million tokens limit; rates are per million tokens", where, raw, MaxOverrideUSDPerMTok)
+ }
+ if !micros.IsInt() {
+ return 0, false, fmt.Errorf("%s: %s is finer than one microdollar per million tokens (6 decimal places)", where, raw)
+ }
+ return micros.Num().Int64(), true, nil
+}
+
+func convertAbove(where string, raw json.RawMessage) (int64, error) {
+ r, present, err := numberLiteral(where, raw)
+ if err != nil {
+ return 0, err
+ }
+ if !present {
+ return 0, fmt.Errorf("%s: required", where)
+ }
+ if !r.IsInt() || r.Sign() <= 0 {
+ return 0, fmt.Errorf("%s: %s is not a positive whole number of tokens", where, raw)
+ }
+ if r.Cmp(maxAboveTokRat) > 0 {
+ return 0, fmt.Errorf("%s: %s is above %d tokens", where, raw, int64(maxAboveTokens))
+ }
+ return r.Num().Int64(), nil
+}
+
+// numberLiteral reads a JSON number literal as an exact rational. An absent field or a null is
+// "not present". A quoted number is refused: the file is hand-written, and a string where a
+// number belongs is more often a pasted price with a currency sign than a deliberate choice.
+func numberLiteral(where string, raw json.RawMessage) (*big.Rat, bool, error) {
+ text := strings.TrimSpace(string(raw))
+ if text == "" || text == "null" {
+ return nil, false, nil
+ }
+ if c := text[0]; c != '-' && (c < '0' || c > '9') {
+ return nil, false, fmt.Errorf("%s: %s is not a JSON number", where, text)
+ }
+ // encoding/json has already checked this is one valid JSON value, and a value starting
+ // with a digit or '-' is a number, so big.Rat sees only decimal and exponent forms. An
+ // exponent is bounded first: big.Rat would otherwise build 1e999999999 in full before any
+ // range check could refuse it.
+ if i := strings.IndexAny(text, "eE"); i >= 0 {
+ exp, err := strconv.Atoi(strings.TrimPrefix(text[i+1:], "+"))
+ if err != nil || exp > 30 || exp < -30 {
+ return nil, false, fmt.Errorf("%s: %s is out of range", where, text)
+ }
+ }
+ r, ok := new(big.Rat).SetString(text)
+ if !ok {
+ return nil, false, fmt.Errorf("%s: %s is not a number", where, text)
+ }
+ return r, true, nil
+}
+
+// checkDuplicateKeys refuses an object that names one key twice. encoding/json keeps the last
+// silently, which in a price list means one of two rates the author wrote is ignored without a
+// word. Syntax errors are left to the real decode, which reports them with better context.
+func checkDuplicateKeys(data []byte) error {
+ type frame struct {
+ object bool
+ keys map[string]bool
+ path string
+ expectKey bool
+ key string
+ }
+ dec := json.NewDecoder(bytes.NewReader(data))
+ dec.UseNumber()
+ var stack []*frame
+ // valueDone records that a value inside the top frame ended, so an object's next token is
+ // a key again.
+ valueDone := func() {
+ if n := len(stack); n > 0 && stack[n-1].object {
+ stack[n-1].expectKey = true
+ }
+ }
+ for {
+ tok, err := dec.Token()
+ if err != nil {
+ return nil
+ }
+ var top *frame
+ if n := len(stack); n > 0 {
+ top = stack[n-1]
+ }
+ if top != nil && top.object && top.expectKey {
+ if tok == json.Delim('}') {
+ stack = stack[:len(stack)-1]
+ valueDone()
+ continue
+ }
+ key, _ := tok.(string)
+ if top.keys[key] {
+ where := top.path
+ if where == "" {
+ where = "document"
+ }
+ return fmt.Errorf("%s: key %q appears twice", where, key)
+ }
+ top.keys[key] = true
+ top.key = key
+ top.expectKey = false
+ continue
+ }
+ var path string
+ switch {
+ case top == nil:
+ case top.object && top.path == "":
+ path = top.key
+ case top.object:
+ path = fmt.Sprintf("%s[%q]", top.path, top.key)
+ default:
+ path = top.path + "[]"
+ }
+ switch tok {
+ case json.Delim('{'):
+ stack = append(stack, &frame{object: true, keys: map[string]bool{}, path: path, expectKey: true})
+ case json.Delim('['):
+ stack = append(stack, &frame{path: path})
+ case json.Delim(']'):
+ stack = stack[:len(stack)-1]
+ valueDone()
+ default:
+ valueDone()
+ }
+ }
+}
diff --git a/cli/beacon/internal/pricing/overrides_test.go b/cli/beacon/internal/pricing/overrides_test.go
new file mode 100644
index 00000000..b4a1c9ad
--- /dev/null
+++ b/cli/beacon/internal/pricing/overrides_test.go
@@ -0,0 +1,362 @@
+package pricing
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "errors"
+ "os"
+ "path/filepath"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"
+)
+
+// overridesCatalog is a small catalog with real list prices, so the override tests are
+// hand-checkable and independent of catalog regenerations.
+func overridesCatalog(t *testing.T) *Catalog {
+ t.Helper()
+ return testCatalog(t, map[string]Rates{
+ "claude-sonnet-4-5": {Provider: "anthropic",
+ RateSet: RateSet{Input: 3_000_000, Output: 15_000_000, CacheRead: 300_000, CacheWrite: 3_750_000, CacheWrite1h: 6_000_000},
+ Bands: []Band{{AboveTokens: 200_000, RateSet: RateSet{Input: 6_000_000, Output: 22_500_000, CacheRead: 600_000, CacheWrite: 7_500_000, CacheWrite1h: 12_000_000}}},
+ },
+ "claude-sonnet-4-5-20250929": {Provider: "anthropic",
+ RateSet: RateSet{Input: 3_000_000, Output: 15_000_000, CacheRead: 300_000, CacheWrite: 3_750_000},
+ },
+ "gpt-5": {Provider: "openai", RateSet: RateSet{Input: 1_250_000, Output: 10_000_000, CacheRead: 125_000}},
+ })
+}
+
+func mustOverrides(t *testing.T, c *Catalog, doc string) *Overrides {
+ t.Helper()
+ o, err := LoadOverrides([]byte(doc), c)
+ if err != nil {
+ t.Fatalf("LoadOverrides: %v", err)
+ }
+ return o
+}
+
+func TestOverridesConvertDecimalRatesExactly(t *testing.T) {
+ c := overridesCatalog(t)
+ // Values a float64 cannot hold exactly (0.3, 0.1+0.2-style sums) must still land on the
+ // exact microdollar, and the exponent form is accepted.
+ o := mustOverrides(t, c, `{
+ "schema": "beacon.pricing.overrides/v1",
+ "models": {
+ "acme-internal-1": {
+ "provider": "acme",
+ "input_usd_per_mtok": 0.3,
+ "output_usd_per_mtok": 2.4e0,
+ "cache_read_usd_per_mtok": 0.030000,
+ "cache_write_usd_per_mtok": 0.375,
+ "cache_write_1h_usd_per_mtok": 0.000001
+ }
+ }
+ }`)
+ got, ok := o.Rates("acme-internal-1")
+ if !ok {
+ t.Fatal("row missing")
+ }
+ want := Rates{Provider: "acme", RateSet: RateSet{Input: 300_000, Output: 2_400_000, CacheRead: 30_000, CacheWrite: 375_000, CacheWrite1h: 1}}
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("rates = %+v, want %+v", got, want)
+ }
+}
+
+func TestOverridesRejectBadValuesNamingTheKey(t *testing.T) {
+ c := overridesCatalog(t)
+ row := func(fields string) string {
+ return `{"schema":"beacon.pricing.overrides/v1","models":{"m":{` + fields + `}}}`
+ }
+ cases := []struct {
+ name, doc, want string
+ }{
+ {"negative", row(`"input_usd_per_mtok":-1,"output_usd_per_mtok":2`), `models["m"].input_usd_per_mtok: -1 is negative`},
+ {"zero", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"cache_read_usd_per_mtok":0`), `models["m"].cache_read_usd_per_mtok: 0 is not a price`},
+ {"too precise", row(`"input_usd_per_mtok":0.0000001,"output_usd_per_mtok":2`), `models["m"].input_usd_per_mtok: 0.0000001 is finer than one microdollar`},
+ {"absurd", row(`"input_usd_per_mtok":3,"output_usd_per_mtok":100000.000001`), `models["m"].output_usd_per_mtok: 100000.000001 is above the 100000 USD`},
+ {"huge exponent", row(`"input_usd_per_mtok":1e999999,"output_usd_per_mtok":2`), `models["m"].input_usd_per_mtok: 1e999999 is out of range`},
+ {"quoted", row(`"input_usd_per_mtok":"3.00","output_usd_per_mtok":2`), `models["m"].input_usd_per_mtok: "3.00" is not a JSON number`},
+ {"NaN string", row(`"input_usd_per_mtok":"NaN","output_usd_per_mtok":2`), `models["m"].input_usd_per_mtok: "NaN" is not a JSON number`},
+ {"bare NaN", row(`"input_usd_per_mtok":NaN,"output_usd_per_mtok":2`), `parse:`},
+ {"missing output", row(`"input_usd_per_mtok":1`), `models["m"].output_usd_per_mtok: required`},
+ {"misspelled field", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"cache_read_usd_per_mtk":1`), `unknown field "cache_read_usd_per_mtk"`},
+ {"duplicate key", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"input_usd_per_mtok":3`), `models["m"]: key "input_usd_per_mtok" appears twice`},
+ {"duplicate model", `{"schema":"beacon.pricing.overrides/v1","models":{"m":{"input_usd_per_mtok":1,"output_usd_per_mtok":2},"m":{"input_usd_per_mtok":3,"output_usd_per_mtok":4}}}`, `models: key "m" appears twice`},
+ {"band threshold", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"bands":[{"above_tokens":1.5,"input_usd_per_mtok":2}]`), `models["m"].bands[0].above_tokens: 1.5 is not a positive whole number`},
+ {"band missing threshold", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"bands":[{"input_usd_per_mtok":2}]`), `models["m"].bands[0].above_tokens: required`},
+ {"band duplicate", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"bands":[{"above_tokens":10,"input_usd_per_mtok":2},{"above_tokens":10,"input_usd_per_mtok":3}]`), `models["m"].bands: two bands above 10 tokens`},
+ {"band bad rate", row(`"input_usd_per_mtok":1,"output_usd_per_mtok":2,"bands":[{"above_tokens":10,"output_usd_per_mtok":-2}]`), `models["m"].bands[0].output_usd_per_mtok: -2 is negative`},
+ {"wrong schema", `{"schema":"beacon.pricing.overrides/v2","models":{}}`, `schema "beacon.pricing.overrides/v2"`},
+ {"no schema", `{"models":{}}`, `schema ""`},
+ {"blank name", `{"schema":"beacon.pricing.overrides/v1","models":{" ":{"input_usd_per_mtok":1,"output_usd_per_mtok":2}}}`, `models[" "]: the name is empty`},
+ {"padded name", `{"schema":"beacon.pricing.overrides/v1","models":{"m ":{"input_usd_per_mtok":1,"output_usd_per_mtok":2}}}`, `leading or trailing white space`},
+ {"alias to nothing", `{"schema":"beacon.pricing.overrides/v1","aliases":{"gw":"claude-sonnet-9"}}`, `aliases["gw"]: target "claude-sonnet-9" is neither a model in this file nor a catalog key`},
+ {"alias is a model", `{"schema":"beacon.pricing.overrides/v1","models":{"m":{"input_usd_per_mtok":1,"output_usd_per_mtok":2}},"aliases":{"m":"gpt-5"}}`, `aliases["m"]: "m" is also a model in this file`},
+ {"alias loose target", `{"schema":"beacon.pricing.overrides/v1","aliases":{"gw":"Claude-Sonnet-4-5"}}`, `target "Claude-Sonnet-4-5" is neither`},
+ {"trailing data", `{"schema":"beacon.pricing.overrides/v1"} {}`, `trailing data`},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ _, err := LoadOverrides([]byte(tc.doc), c)
+ if err == nil || !strings.Contains(err.Error(), tc.want) {
+ t.Fatalf("err = %v, want it to contain %q", err, tc.want)
+ }
+ })
+ }
+}
+
+func TestOverridesWinOverTheCatalogAtEveryRung(t *testing.T) {
+ c := overridesCatalog(t)
+ o := mustOverrides(t, c, `{
+ "schema": "beacon.pricing.overrides/v1",
+ "comment": "Acme enterprise agreement, 2026",
+ "models": {
+ "claude-sonnet-4-5": {"input_usd_per_mtok": 2.4, "output_usd_per_mtok": 12, "comment": "20% off list"}
+ }
+ }`)
+ p := NewPricer(c, o)
+ // The catalog has an exact row for the dated snapshot, but the negotiated rate for the
+ // model is what the organisation pays for its snapshots too.
+ for _, model := range []string{"claude-sonnet-4-5", "anthropic/claude-sonnet-4-5", "claude-sonnet-4.5", "claude-sonnet-4-5-20250929", "claude-sonnet-4-5[1m]"} {
+ res, ok := p.Lookup(model)
+ if !ok || res.Source != SourceOverride || res.Key != "claude-sonnet-4-5" || res.Rates.Input != 2_400_000 {
+ t.Fatalf("%s: %+v ok=%v, want the override", model, res, ok)
+ }
+ }
+ // The override row replaces the catalog row whole: its omitted cache rates are
+ // unpublished, not inherited, and its bands are its own (none here).
+ res, _ := p.Lookup("claude-sonnet-4-5")
+ if res.Rates.CacheRead != 0 || res.Rates.CacheWrite != 0 || len(res.Rates.Bands) != 0 {
+ t.Fatalf("override inherited catalog fields: %+v", res.Rates)
+ }
+ est := Cost(res.Rates, Tokens{Input: 1_000_000, CacheRead: 1_000_000, CacheCreation: 1_000_000, Output: 1_000_000}, true)
+ if est.Cost != 2_400_000*3+12_000_000 || !est.CacheReadAtInputRate || !est.CacheWriteAtInputRate || est.BandAboveTokens != 0 {
+ t.Fatalf("estimate = %+v", est)
+ }
+ // Models the file does not name still come from the catalog.
+ if res, ok := p.Lookup("gpt-5"); !ok || res.Source != SourceCatalog || res.Key != "gpt-5" {
+ t.Fatalf("gpt-5 = %+v ok=%v", res, ok)
+ }
+ if got := o.ModelComment("claude-sonnet-4-5"); got != "20% off list" {
+ t.Fatalf("comment = %q", got)
+ }
+ if o.Comment() != "Acme enterprise agreement, 2026" {
+ t.Fatalf("file comment = %q", o.Comment())
+ }
+}
+
+func TestOverridesPriceAModelTheCatalogDoesNotKnow(t *testing.T) {
+ c := overridesCatalog(t)
+ if _, ok := c.Lookup("acme-coder-2"); ok {
+ t.Fatal("fixture model is in the catalog")
+ }
+ p := NewPricer(c, mustOverrides(t, c, `{"schema":"beacon.pricing.overrides/v1","models":{"acme-coder-2":{"input_usd_per_mtok":1,"output_usd_per_mtok":4}}}`))
+ res, ok := p.Lookup("acme/acme-coder-2-20261001")
+ if !ok || res.Key != "acme-coder-2" || res.Source != SourceOverride || res.Match != MatchExact || !reflect.DeepEqual(res.Stripped, []string{StrippedDateSnapshot}) {
+ t.Fatalf("got %+v ok=%v", res, ok)
+ }
+}
+
+func TestOverridesAliases(t *testing.T) {
+ c := overridesCatalog(t)
+ o := mustOverrides(t, c, `{
+ "schema": "beacon.pricing.overrides/v1",
+ "models": {"acme-coder-2": {"input_usd_per_mtok": 1, "output_usd_per_mtok": 4}},
+ "aliases": {
+ "my-gateway-model": "claude-sonnet-4-5",
+ "acme-fast": "acme-coder-2",
+ "gpt-5": "acme-coder-2"
+ }
+ }`)
+ p := NewPricer(c, o)
+ cases := []struct {
+ model, key, source, alias string
+ input int64
+ match Match
+ }{
+ // An alias to a catalog key is priced by the catalog row, and says it went through the
+ // alias.
+ {"my-gateway-model", "claude-sonnet-4-5", SourceCatalog, "my-gateway-model", 3_000_000, MatchExact},
+ // The alias itself is matched with the full ladder.
+ {"litellm_proxy/My-Gateway-Model", "claude-sonnet-4-5", SourceCatalog, "my-gateway-model", 3_000_000, MatchCanonical},
+ {"acme-fast", "acme-coder-2", SourceOverride, "acme-fast", 1_000_000, MatchExact},
+ // An alias may claim a catalog name and send it elsewhere.
+ {"gpt-5", "acme-coder-2", SourceOverride, "gpt-5", 1_000_000, MatchExact},
+ }
+ for _, tc := range cases {
+ res, ok := p.Lookup(tc.model)
+ if !ok || res.Key != tc.key || res.Source != tc.source || res.Alias != tc.alias || res.Rates.Input != tc.input || res.Match != tc.match {
+ t.Fatalf("%s: got %+v ok=%v, want key %s source %s alias %s", tc.model, res, ok, tc.key, tc.source, tc.alias)
+ }
+ }
+ // A catalog alias carries the catalog's bands.
+ res, _ := p.Lookup("my-gateway-model")
+ if len(res.Rates.Bands) != 1 {
+ t.Fatalf("alias lost the catalog bands: %+v", res.Rates)
+ }
+ if target, source, ok := o.AliasTarget("my-gateway-model"); !ok || target != "claude-sonnet-4-5" || source != SourceCatalog {
+ t.Fatalf("AliasTarget = %q %q %v", target, source, ok)
+ }
+ if got, want := o.Aliases(), []string{"acme-fast", "gpt-5", "my-gateway-model"}; !reflect.DeepEqual(got, want) {
+ t.Fatalf("Aliases = %v", got)
+ }
+}
+
+func TestOverridesBands(t *testing.T) {
+ c := overridesCatalog(t)
+ // Bands may be listed in any order and need restate only what changes; the rest is the
+ // row's base rate.
+ o := mustOverrides(t, c, `{
+ "schema": "beacon.pricing.overrides/v1",
+ "models": {"acme-long": {
+ "input_usd_per_mtok": 1, "output_usd_per_mtok": 4, "cache_read_usd_per_mtok": 0.1,
+ "bands": [
+ {"above_tokens": 1e6, "input_usd_per_mtok": 4},
+ {"above_tokens": 200000, "input_usd_per_mtok": 2, "output_usd_per_mtok": 6}
+ ]
+ }}
+ }`)
+ got, _ := o.Rates("acme-long")
+ want := []Band{
+ {AboveTokens: 200_000, RateSet: RateSet{Input: 2_000_000, Output: 6_000_000, CacheRead: 100_000}},
+ {AboveTokens: 1_000_000, RateSet: RateSet{Input: 4_000_000, Output: 4_000_000, CacheRead: 100_000}},
+ }
+ if !reflect.DeepEqual(got.Bands, want) {
+ t.Fatalf("bands = %+v, want %+v", got.Bands, want)
+ }
+ p := NewPricer(c, o)
+ res, _ := p.Lookup("acme-long")
+ est := Cost(res.Rates, Tokens{Input: 300_000, Output: 1_000}, true)
+ if est.BandAboveTokens != 200_000 || est.Cost != 300_000*2+1_000*6 {
+ t.Fatalf("banded estimate = %+v", est)
+ }
+ if est := Cost(res.Rates, Tokens{Input: 300_000, Output: 1_000}, false); est.BandAboveTokens != 0 || est.Cost != 300_000+4_000 {
+ t.Fatalf("aggregate estimate = %+v", est)
+ }
+}
+
+func TestOverridesTieIsUnpricedAndDoesNotFallThrough(t *testing.T) {
+ c := overridesCatalog(t)
+ o := mustOverrides(t, c, `{
+ "schema": "beacon.pricing.overrides/v1",
+ "models": {
+ "gw-a/gpt-5": {"input_usd_per_mtok": 1, "output_usd_per_mtok": 2},
+ "gw-b/gpt-5": {"input_usd_per_mtok": 3, "output_usd_per_mtok": 4}
+ }
+ }`)
+ p := NewPricer(c, o)
+ res, ok := p.Lookup("gpt-5")
+ if ok || res.Source != SourceOverride || !reflect.DeepEqual(res.Candidates, []string{"gw-a/gpt-5", "gw-b/gpt-5"}) {
+ t.Fatalf("got %+v ok=%v, want an unpriced override tie", res, ok)
+ }
+ // The exact names still price.
+ if res, ok := p.Lookup("gw-b/gpt-5"); !ok || res.Rates.Input != 3_000_000 {
+ t.Fatalf("exact = %+v ok=%v", res, ok)
+ }
+ warnings := o.Warnings()
+ if len(warnings) != 1 || !strings.Contains(warnings[0], `"gw-a/gpt-5", "gw-b/gpt-5"`) || !strings.Contains(warnings[0], "canonical") {
+ t.Fatalf("warnings = %q", warnings)
+ }
+}
+
+func TestOverridesEmptyFileIsValid(t *testing.T) {
+ c := overridesCatalog(t)
+ o := mustOverrides(t, c, `{"schema":"beacon.pricing.overrides/v1"}`)
+ p := NewPricer(c, o)
+ if res, ok := p.Lookup("gpt-5"); !ok || res.Source != SourceCatalog {
+ t.Fatalf("got %+v ok=%v", res, ok)
+ }
+ if len(o.Models()) != 0 || len(o.Aliases()) != 0 || len(o.Warnings()) != 0 {
+ t.Fatalf("empty file has content")
+ }
+}
+
+func TestLoadPricerMissingAndInvalidFiles(t *testing.T) {
+ c := overridesCatalog(t)
+ dir := t.TempDir()
+ missing := filepath.Join(dir, "pricing", OverridesFileName)
+
+ // The default location usually holds nothing; that is not an error.
+ p, err := LoadPricer(c, missing, false)
+ if err != nil || p.Overrides() != nil {
+ t.Fatalf("missing default: %v %v", p.Overrides(), err)
+ }
+ if _, oerr := p.OverridesError(); oerr != nil {
+ t.Fatalf("missing default recorded an error: %v", oerr)
+ }
+ // A file the user named must exist.
+ if _, err := LoadPricer(c, missing, true); !errors.Is(err, os.ErrNotExist) {
+ t.Fatalf("missing required: %v", err)
+ }
+
+ bad := filepath.Join(dir, "bad.json")
+ if err := os.WriteFile(bad, []byte(`{"schema":"beacon.pricing.overrides/v1","models":{"m":{"input_usd_per_mtok":-1,"output_usd_per_mtok":1}}}`), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ p, err = LoadPricer(c, bad, false)
+ if err == nil || !strings.Contains(err.Error(), bad) || !strings.Contains(err.Error(), `models["m"].input_usd_per_mtok`) {
+ t.Fatalf("invalid: %v", err)
+ }
+ // The pricer still prices from the catalog and says why it is not using the file.
+ if path, oerr := p.OverridesError(); path != bad || oerr == nil {
+ t.Fatalf("OverridesError = %q %v", path, oerr)
+ }
+ if res, ok := p.Lookup("gpt-5"); !ok || res.Source != SourceCatalog {
+ t.Fatalf("fallback lookup = %+v", res)
+ }
+
+ good := filepath.Join(dir, "good.json")
+ doc := []byte(`{"schema":"beacon.pricing.overrides/v1","models":{"m":{"input_usd_per_mtok":1,"output_usd_per_mtok":1}}}`)
+ if err := os.WriteFile(good, doc, 0o600); err != nil {
+ t.Fatal(err)
+ }
+ p, err = LoadPricer(c, good, true)
+ if err != nil {
+ t.Fatal(err)
+ }
+ sum := sha256.Sum256(doc)
+ if o := p.Overrides(); o.Path() != good || o.SHA256() != hex.EncodeToString(sum[:]) {
+ t.Fatalf("path %q digest %q", o.Path(), o.SHA256())
+ }
+
+ big := filepath.Join(dir, "big.json")
+ if err := os.WriteFile(big, make([]byte, maxOverridesFileBytes+1), 0o600); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := LoadPricer(c, big, true); err == nil || !strings.Contains(err.Error(), "larger than") {
+ t.Fatalf("oversized: %v", err)
+ }
+}
+
+func TestDefaultOverridesPathIsUnderTheEndpointBaseDir(t *testing.T) {
+ home := t.TempDir()
+ testenv.SetHome(t, home)
+ if got, want := DefaultOverridesPath(true), filepath.Join(home, ".beacon", "endpoint", "pricing", "overrides.json"); got != want {
+ t.Fatalf("user path = %q, want %q", got, want)
+ }
+ if got := DefaultOverridesPath(false); !strings.HasSuffix(got, filepath.Join("pricing", "overrides.json")) || strings.HasPrefix(got, home) {
+ t.Fatalf("system path = %q", got)
+ }
+}
+
+// The digest and every resolution are a function of the file's bytes alone: loading the same
+// document twice resolves the same way, whatever map order Go picks.
+func TestOverridesAreDeterministic(t *testing.T) {
+ c := overridesCatalog(t)
+ doc := `{"schema":"beacon.pricing.overrides/v1","models":{"a/x":{"input_usd_per_mtok":1,"output_usd_per_mtok":1},"b/x":{"input_usd_per_mtok":1,"output_usd_per_mtok":1}},"aliases":{"y":"a/x","z":"gpt-5"}}`
+ first := mustOverrides(t, c, doc)
+ for i := 0; i < 20; i++ {
+ again := mustOverrides(t, c, doc)
+ if again.SHA256() != first.SHA256() {
+ t.Fatal("digest moved")
+ }
+ a, _ := NewPricer(c, first).Lookup("x")
+ b, _ := NewPricer(c, again).Lookup("x")
+ if !reflect.DeepEqual(a, b) || a.Key != "a/x" {
+ t.Fatalf("resolution moved: %+v vs %+v", a, b)
+ }
+ }
+}
diff --git a/cli/beacon/internal/pricing/pricer.go b/cli/beacon/internal/pricing/pricer.go
new file mode 100644
index 00000000..1d68bd3c
--- /dev/null
+++ b/cli/beacon/internal/pricing/pricer.go
@@ -0,0 +1,83 @@
+package pricing
+
+import (
+ "errors"
+ "os"
+)
+
+// Pricer resolves models against an overrides file first and the catalog second. It is what
+// every report prices through; a Pricer with no overrides is the catalog alone.
+type Pricer struct {
+ catalog *Catalog
+ overrides *Overrides
+ // overridesPath and overridesErr record an overrides file that was asked for and could not
+ // be used, so a report that carried on without it can say so.
+ overridesPath string
+ overridesErr error
+}
+
+// NewPricer combines a catalog with optional overrides (nil for none).
+func NewPricer(catalog *Catalog, overrides *Overrides) *Pricer {
+ return &Pricer{catalog: catalog, overrides: overrides}
+}
+
+// LoadPricer prices from catalog plus the overrides file at path.
+//
+// A missing file is not an error unless required: the default location usually holds nothing,
+// and a report should not fail for want of a file nobody wrote. A file named by the user
+// (required) must exist. An invalid file is always an error; the returned Pricer is still
+// usable, prices from the catalog alone, and reports the error through OverridesError, so a
+// reader that must not fail (the dashboard) can carry on and say why its figures are list
+// prices. An empty path means no overrides.
+func LoadPricer(catalog *Catalog, path string, required bool) (*Pricer, error) {
+ p := NewPricer(catalog, nil)
+ if path == "" {
+ return p, nil
+ }
+ o, err := ReadOverridesFile(path, catalog)
+ if err != nil {
+ if !required && errors.Is(err, os.ErrNotExist) {
+ return p, nil
+ }
+ p.overridesPath = path
+ p.overridesErr = err
+ return p, err
+ }
+ p.overrides = o
+ return p, nil
+}
+
+// Catalog is the catalog the Pricer falls back to.
+func (p *Pricer) Catalog() *Catalog { return p.catalog }
+
+// Overrides is the loaded overrides file, or nil.
+func (p *Pricer) Overrides() *Overrides { return p.overrides }
+
+// OverridesError is the reason an overrides file that was asked for is not in use, with the
+// path it was read from; nil when there is none.
+func (p *Pricer) OverridesError() (string, error) { return p.overridesPath, p.overridesErr }
+
+// Lookup resolves model to a price.
+//
+// The overrides file is tried first, with the same ladder Catalog.Lookup runs (exact, then the
+// looser spellings, then stripping trailing decorations), and if any of its names match, it
+// decides: a row there replaces the catalog's price for every spelling that reaches it, which
+// is what a negotiated rate for claude-sonnet-4-5 means for claude-sonnet-4-5-20250929 too. A
+// tie between differently priced names in the file leaves the model unpriced rather than
+// falling through to a list price the file was written to replace. Only a model no override
+// name reaches is looked up in the catalog.
+func (p *Pricer) Lookup(model string) (Resolution, bool) {
+ if o := p.overrides; o != nil {
+ res, ok := o.table.lookup(model)
+ if ok || len(res.Candidates) > 0 {
+ res.Source = SourceOverride
+ if target, isAlias := o.aliases[res.Key]; ok && isAlias {
+ res.Alias = res.Key
+ res.Key = target
+ res.Source = o.aliasSource[res.Alias]
+ }
+ return res, ok
+ }
+ }
+ return p.catalog.Lookup(model)
+}
diff --git a/cli/beacon/internal/tokens/cost.go b/cli/beacon/internal/tokens/cost.go
index 87888259..14e68749 100644
--- a/cli/beacon/internal/tokens/cost.go
+++ b/cli/beacon/internal/tokens/cost.go
@@ -38,13 +38,17 @@ const (
// call used them.
const PricingTier = "standard"
-// priceCatalog is the catalog estimates are priced from; a variable so tests can substitute one.
+// priceCatalog is the catalog estimates are priced from when Options.Pricer is nil; 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"`
+ // Overrides names the overrides file the estimate consulted, by path and digest, so an
+ // estimate drawn from it can be traced to the exact bytes. Nil when there was none.
+ Overrides *PricingOverrides `json:"overrides,omitempty"`
+ 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
@@ -62,6 +66,17 @@ type PricingCatalog struct {
GeneratedAt string `json:"generated_at"`
}
+// PricingOverrides is the overrides file behind a report. Error is set when a file was asked
+// for and could not be used; the estimate is then list price alone, and Models and Aliases are
+// zero.
+type PricingOverrides struct {
+ Path string `json:"path"`
+ SHA256 string `json:"sha256,omitempty"`
+ Models int `json:"models"`
+ Aliases int `json:"aliases"`
+ Error string `json:"error,omitempty"`
+}
+
// 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.
@@ -81,9 +96,14 @@ type BandUse struct {
// 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 is the model as the report groups it; Key is the entry that priced it, and Source
+ // says whether that is a catalog key ("catalog") or a row of the overrides file
+ // ("override"). Alias is set when the model reached Key through an alias in the overrides
+ // file.
Model string `json:"model"`
Key string `json:"key"`
+ Source string `json:"source"`
+ Alias string `json:"alias,omitempty"`
Provider string `json:"provider"`
Match string `json:"match"`
Stripped []string `json:"stripped,omitempty"`
@@ -106,12 +126,14 @@ type ModelPricing struct {
}
// 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.
+// model at all; Candidates is set when several entries matched with different prices, and
+// CandidatesSource says whether they are catalog keys or names in the overrides file.
type UnpricedModel struct {
- Model string `json:"model"`
- Events int `json:"events"`
- Tokens int64 `json:"tokens"`
- Candidates []string `json:"candidates,omitempty"`
+ Model string `json:"model"`
+ Events int `json:"events"`
+ Tokens int64 `json:"tokens"`
+ Candidates []string `json:"candidates,omitempty"`
+ CandidatesSource string `json:"candidates_source,omitempty"`
}
// settle derives the exported cost fields from the exact internal sums.
@@ -223,7 +245,8 @@ type resolvedModel struct {
// 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 {
+func priceUsageEvents(events []*usageEvent, pricer *pricing.Pricer) *PricingSummary {
+ catalog := pricer.Catalog()
source := catalog.Source()
summary := &PricingSummary{
Catalog: PricingCatalog{
@@ -234,7 +257,8 @@ func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSu
FetchedAt: source.FetchedAt,
GeneratedAt: catalog.GeneratedAt(),
},
- Tier: PricingTier,
+ Tier: PricingTier,
+ Overrides: overridesSummary(pricer),
}
reportedScopes := map[costScopeKey]bool{}
@@ -260,7 +284,7 @@ func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSu
if tokens > 0 {
resolved, seen := lookups[ue.model]
if !seen {
- resolved.res, resolved.priced = catalog.Lookup(ue.model)
+ resolved.res, resolved.priced = pricer.Lookup(ue.model)
lookups[ue.model] = resolved
}
if resolved.priced {
@@ -288,6 +312,9 @@ func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSu
entry := unpriced[ue.model]
if entry == nil {
entry = &UnpricedModel{Model: ue.model, Candidates: resolved.res.Candidates}
+ if len(entry.Candidates) > 0 {
+ entry.CandidatesSource = resolved.res.Source
+ }
unpriced[ue.model] = entry
}
entry.Events++
@@ -327,15 +354,27 @@ func priceUsageEvents(events []*usageEvent, catalog *pricing.Catalog) *PricingSu
return summary
}
+func overridesSummary(pricer *pricing.Pricer) *PricingOverrides {
+ if o := pricer.Overrides(); o != nil {
+ return &PricingOverrides{Path: o.Path(), SHA256: o.SHA256(), Models: len(o.Models()), Aliases: len(o.Aliases())}
+ }
+ if path, err := pricer.OverridesError(); err != nil {
+ return &PricingOverrides{Path: path, Error: err.Error()}
+ }
+ return nil
+}
+
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,
+ Source: res.Source,
+ Alias: res.Alias,
Provider: res.Rates.Provider,
Match: string(res.Match),
Stripped: append([]string(nil), res.Stripped...),
- Rates: ratesPerMTok(res.Rates.RateSet),
+ Rates: RatesUSDPerMTok(res.Rates.RateSet),
bands: map[int64]int{},
fallbacks: map[string]bool{},
}
@@ -360,7 +399,8 @@ func recordModelPricing(m *ModelPricing, model string, res pricing.Resolution, s
return m
}
-func ratesPerMTok(set pricing.RateSet) RatesPerMTok {
+// RatesUSDPerMTok converts a rate set to US dollars per million tokens for display.
+func RatesUSDPerMTok(set pricing.RateSet) RatesPerMTok {
usd := func(v int64) float64 { return pricing.Microdollars(v).USD() }
return RatesPerMTok{
Input: usd(set.Input),
diff --git a/cli/beacon/internal/tokens/cost_overrides_test.go b/cli/beacon/internal/tokens/cost_overrides_test.go
new file mode 100644
index 00000000..2027ac70
--- /dev/null
+++ b/cli/beacon/internal/tokens/cost_overrides_test.go
@@ -0,0 +1,149 @@
+package tokens
+
+import (
+ "bytes"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/schema"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
+)
+
+// An organisation's overrides file: a negotiated OpenAI rate that publishes no cache-read
+// price, an internal model the catalog cannot know with a long-context band, and a gateway
+// alias for a catalog model.
+const orgOverrides = `{
+ "schema": "beacon.pricing.overrides/v1",
+ "comment": "Acme 2026 agreement",
+ "models": {
+ "gpt-5": {"provider": "openai", "input_usd_per_mtok": 1, "output_usd_per_mtok": 8},
+ "acme-coder-2": {
+ "provider": "acme",
+ "input_usd_per_mtok": 1, "output_usd_per_mtok": 4,
+ "bands": [{"above_tokens": 200000, "input_usd_per_mtok": 2, "output_usd_per_mtok": 6}]
+ }
+ },
+ "aliases": {"my-gateway-model": "claude-sonnet-4-5"}
+}`
+
+func overridesFixtureEvents() []schema.Event {
+ return []schema.Event{
+ // A Codex turn span (aggregate, base rates): 1000 in, 4000 cache read, 200 out.
+ usageEventFixture("2026-06-11T10:00:00Z", "codex_cli", "codex-1", "gpt-5", chain(
+ withUsage(1000, 200, 4000, 0, 0, 0), collected("otlp"),
+ func(e *schema.Event) { e.Raw = map[string]interface{}{"source": "codex_turn_span"} })),
+ // An OpenCode step (one request) on the internal model, past its band threshold.
+ usageEventFixture("2026-06-11T10:01:00Z", "opencode", "oc-1", "acme-coder-2", chain(
+ withUsage(250_000, 1000, 0, 0, 0, 0), collected("plugin"))),
+ // A gateway alias for claude-sonnet-4-5 ($3 in, $15 out).
+ usageEventFixture("2026-06-11T10:02:00Z", "gemini_cli", "gw-1", "my-gateway-model", chain(
+ withUsage(1000, 100, 0, 0, 0, 0), collected("otlp"))),
+ // Nobody prices this one.
+ usageEventFixture("2026-06-11T10:03:00Z", "gemini_cli", "gw-2", "mystery-model", withUsage(10, 0, 0, 0, 0, 0)),
+ }
+}
+
+func TestAggregatePricesWithOverrides(t *testing.T) {
+ catalog := pricing.Default()
+ events := overridesFixtureEvents()
+
+ // Without the file, the internal model and the alias are unpriced and gpt-5 is list price:
+ // 1000 x $1.25 + 4000 x $0.125 + 200 x $10 = 3750 microdollars.
+ plain := Aggregate(events, Options{})
+ if got := plain.Totals.estimated; got != 3750 {
+ t.Fatalf("catalog-only estimate = %d, want 3750", got)
+ }
+ if plain.Pricing.Overrides != nil || len(plain.Pricing.Unpriced) != 3 {
+ t.Fatalf("catalog-only pricing = %+v", plain.Pricing)
+ }
+
+ o, err := pricing.LoadOverrides([]byte(orgOverrides), catalog)
+ if err != nil {
+ t.Fatal(err)
+ }
+ report := Aggregate(events, Options{Pricer: pricing.NewPricer(catalog, o)})
+
+ // gpt-5 at $1 in (cache reads at the input rate: the row publishes none), $8 out:
+ // 1000 + 4000 + 1600 = 6600. acme-coder-2 in its band: 250000 x $2 + 1000 x $6 = 506000.
+ // my-gateway-model at claude-sonnet-4-5's list price: 1000 x $3 + 100 x $15 = 4500.
+ if got := report.Totals.estimated; got != 6600+506_000+4500 {
+ t.Fatalf("estimate = %d, want %d", got, 6600+506_000+4500)
+ }
+ if got := report.Totals.EffectiveCostUSD; !approxEqual(got, usd(6600+506_000+4500)) {
+ t.Fatalf("effective = %v", got)
+ }
+ if report.Totals.UnpricedEvents != 1 || report.Totals.UnpricedTokens != 10 {
+ t.Fatalf("unpriced = %d events %d tokens", report.Totals.UnpricedEvents, report.Totals.UnpricedTokens)
+ }
+
+ block := report.Pricing
+ if block.Overrides == nil || block.Overrides.SHA256 != o.SHA256() || block.Overrides.Models != 2 || block.Overrides.Aliases != 1 || block.Overrides.Error != "" {
+ t.Fatalf("overrides block = %+v", block.Overrides)
+ }
+ byModel := map[string]ModelPricing{}
+ for _, m := range block.Models {
+ byModel[m.Model] = m
+ }
+ if m := byModel["gpt-5"]; m.Source != pricing.SourceOverride || m.Key != "gpt-5" || m.Rates.Input != 1 || m.Rates.CacheRead != 0 ||
+ !reflect.DeepEqual(m.Fallbacks, []string{"cache_read_at_input_rate"}) || m.EstimatedCostUSD != usd(6600) {
+ t.Fatalf("gpt-5 = %+v", m)
+ }
+ if m := byModel["acme-coder-2"]; m.Source != pricing.SourceOverride || m.Provider != "acme" ||
+ !reflect.DeepEqual(m.BandsApplied, []BandUse{{AboveTokens: 200_000, Requests: 1}}) {
+ t.Fatalf("acme-coder-2 = %+v", m)
+ }
+ if m := byModel["my-gateway-model"]; m.Source != pricing.SourceCatalog || m.Alias != "my-gateway-model" || m.Key != "claude-sonnet-4-5" || m.Rates.Input != 3 {
+ t.Fatalf("my-gateway-model = %+v", m)
+ }
+ if len(block.Unpriced) != 1 || block.Unpriced[0].Model != "mystery-model" {
+ t.Fatalf("unpriced = %+v", block.Unpriced)
+ }
+
+ var text bytes.Buffer
+ RenderText(&text, report)
+ for _, want := range []string{
+ "or at your overrides file's rate for the models it names",
+ "overrides from (sha256 " + o.SHA256()[:12] + ", 2 model(s), 1 alias(es))",
+ "priced by the overrides file: acme-coder-2, gpt-5, my-gateway-model",
+ "beacon pricing show <model>",
+ } {
+ if !strings.Contains(text.String(), want) {
+ t.Fatalf("text missing %q:\n%s", want, text.String())
+ }
+ }
+}
+
+// A reported cost still beats any estimate, however it was priced: an override is a better
+// estimate, not a reported figure.
+func TestOverridesDoNotDisplaceReportedCost(t *testing.T) {
+ catalog := pricing.Default()
+ o, err := pricing.LoadOverrides([]byte(`{"schema":"beacon.pricing.overrides/v1","models":{"claude-sonnet-4-5":{"input_usd_per_mtok":1,"output_usd_per_mtok":1}}}`), catalog)
+ if err != nil {
+ t.Fatal(err)
+ }
+ events := []schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "claude_code", "s1", "claude-sonnet-4-5", withUsage(1000, 0, 0, 0, 0, 0.25)),
+ }
+ report := Aggregate(events, Options{Pricer: pricing.NewPricer(catalog, o)})
+ if report.Totals.EffectiveCostUSD != 0.25 || report.Totals.CostSource != CostSourceReported || report.Totals.estimated != 1000 {
+ t.Fatalf("totals = %+v", report.Totals)
+ }
+}
+
+func TestOverridesTieIsReportedWithItsSource(t *testing.T) {
+ catalog := pricing.Default()
+ o, err := pricing.LoadOverrides([]byte(`{"schema":"beacon.pricing.overrides/v1","models":{
+ "gw-a/acme-x":{"input_usd_per_mtok":1,"output_usd_per_mtok":1},
+ "gw-b/acme-x":{"input_usd_per_mtok":2,"output_usd_per_mtok":2}}}`), catalog)
+ if err != nil {
+ t.Fatal(err)
+ }
+ report := Aggregate([]schema.Event{
+ usageEventFixture("2026-06-11T10:00:00Z", "gemini_cli", "s1", "acme-x", withUsage(10, 0, 0, 0, 0, 0)),
+ }, Options{Pricer: pricing.NewPricer(catalog, o)})
+ u := report.Pricing.Unpriced
+ if len(u) != 1 || u[0].CandidatesSource != pricing.SourceOverride || !reflect.DeepEqual(u[0].Candidates, []string{"gw-a/acme-x", "gw-b/acme-x"}) {
+ t.Fatalf("unpriced = %+v", u)
+ }
+}
diff --git a/cli/beacon/internal/tokens/report.go b/cli/beacon/internal/tokens/report.go
index 0a7c427a..e594b840 100644
--- a/cli/beacon/internal/tokens/report.go
+++ b/cli/beacon/internal/tokens/report.go
@@ -5,6 +5,8 @@ import (
"io"
"strings"
"text/tabwriter"
+
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/pricing"
)
// RenderText writes a human-readable token usage report.
@@ -156,9 +158,40 @@ func writePricingFooter(w io.Writer, report Report) {
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:")
+ overrides := report.Pricing.Overrides
+ if overrides != nil && overrides.Error == "" {
+ fmt.Fprintln(w, "COST USD is what the runtimes reported. EST COST USD is an estimate at list price,")
+ fmt.Fprintln(w, "or at your overrides file's rate for the models it names:")
+ } else {
+ 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)
+ if overrides != nil {
+ if overrides.Error != "" {
+ fmt.Fprintf(w, " overrides file NOT used, list prices only: %s;\n", overrides.Error)
+ } else {
+ digest := overrides.SHA256
+ if len(digest) > 12 {
+ digest = digest[:12]
+ }
+ var byOverride []string
+ for _, m := range report.Pricing.Models {
+ if m.Source == pricing.SourceOverride || m.Alias != "" {
+ byOverride = append(byOverride, m.Model)
+ }
+ }
+ fmt.Fprintf(w, " overrides from %s (sha256 %s, %d model(s), %d alias(es));\n",
+ overrides.Path, digest, overrides.Models, overrides.Aliases)
+ if len(byOverride) > 0 {
+ fmt.Fprintf(w, " priced by the overrides file: %s;\n", strings.Join(byOverride, ", "))
+ }
+ }
+ }
+ if overrides != nil && overrides.Error == "" {
+ fmt.Fprintf(w, " catalog rates are %s tier, no batch, priority or subscription discounts;\n", report.Pricing.Tier)
+ } else {
+ 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",
@@ -178,6 +211,7 @@ func writePricingFooter(w io.Writer, report Report) {
}
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, ", "))
+ fmt.Fprintln(w, " 'beacon pricing show <model>' explains a lookup; an overrides file can price the rest.")
}
}
diff --git a/cli/beacon/internal/tokens/tokens.go b/cli/beacon/internal/tokens/tokens.go
index 26dd5517..81df649c 100644
--- a/cli/beacon/internal/tokens/tokens.go
+++ b/cli/beacon/internal/tokens/tokens.go
@@ -132,6 +132,9 @@ type Options struct {
SessionID string
// TopLimit caps each group list (0 keeps all groups).
TopLimit int
+ // Pricer prices the list-price estimate: an overrides file over the catalog. Nil prices
+ // from the embedded catalog alone.
+ Pricer *pricing.Pricer
}
type Report struct {
@@ -216,7 +219,11 @@ func aggregate(events []schema.Event, opts Options, sessionUsers sessionUserInde
// 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())
+ pricer := opts.Pricer
+ if pricer == nil {
+ pricer = pricing.NewPricer(priceCatalog(), nil)
+ }
+ report.Pricing = priceUsageEvents(usageEvents, pricer)
byModel := map[string]*Usage{}
bySession := map[string]*Usage{}
diff --git a/docs/cli/pricing.mdx b/docs/cli/pricing.mdx
new file mode 100644
index 00000000..c280adfe
--- /dev/null
+++ b/docs/cli/pricing.mdx
@@ -0,0 +1,222 @@
+---
+title: "beacon pricing"
+description: "Inspect the price list behind token cost estimates, and price models with your own rates"
+---
+
+## Command overview
+
+`beacon pricing` shows how [`beacon token-usage`](/cli/token-usage) and the dashboard's token
+view turn tokens into an estimated cost, and checks the overrides file you can use to price
+models with your own rates.
+
+```bash title="Command syntax"
+beacon pricing show <model> [--json]
+beacon pricing list [--provider <name>] [--json]
+beacon pricing info [--json]
+beacon pricing validate [--json]
+```
+
+Every command takes `--pricing-file <path>` to use a specific overrides file, and `--user`
+(the default) or `--system` to pick which endpoint's default file is read. Every command is
+offline: nothing is fetched, and nothing is written.
+
+## Where prices come from
+
+Estimates come from two lists, checked in this order:
+
+1. **Your overrides file**, if there is one. It can price models the catalog cannot know
+ (internal or proprietary models, releases newer than your Beacon build, names a gateway
+ invents) and replace list prices with the rates your organisation actually pays.
+2. **The catalog** embedded in Beacon: the providers' published standard-tier API list
+ prices, generated from LiteLLM's model price list. `beacon pricing info` prints its source,
+ upstream commit and generation date.
+
+A model that neither list prices is left out of every estimate and counted as unpriced. It is
+never treated as free.
+
+## The overrides file
+
+Beacon reads the overrides file from the endpoint directory:
+
+| Mode | Path |
+|------|------|
+| User (default) | `~/.beacon/endpoint/pricing/overrides.json` |
+| System (`--system`) | `/Library/Application Support/Beacon/Endpoint/pricing/overrides.json` on macOS, `/etc/beacon/endpoint/pricing/overrides.json` on Linux |
+
+The file is yours. Beacon never creates, edits or rewrites it, and the dashboard only reads it;
+write it by hand or from your own tooling. If it is missing, estimates use the catalog alone.
+`beacon token-usage --pricing-file <path>` and `beacon pricing --pricing-file <path>` read a
+different file instead; a file named that way must exist.
+
+Keep it readable only by you (`chmod 600`, in a `0700` directory) if the rates are
+confidential: Beacon does not put rates in any event, but the file itself is plain JSON.
+
+```json title="~/.beacon/endpoint/pricing/overrides.json"
+{
+ "schema": "beacon.pricing.overrides/v1",
+ "comment": "Acme enterprise agreement, effective 2026-07-01",
+ "models": {
+ "claude-sonnet-4-5": {
+ "provider": "anthropic",
+ "comment": "20% off list",
+ "input_usd_per_mtok": 2.4,
+ "output_usd_per_mtok": 12,
+ "cache_read_usd_per_mtok": 0.24,
+ "cache_write_usd_per_mtok": 3,
+ "cache_write_1h_usd_per_mtok": 4.8,
+ "bands": [
+ { "above_tokens": 200000, "input_usd_per_mtok": 4.8, "output_usd_per_mtok": 18,
+ "cache_read_usd_per_mtok": 0.48, "cache_write_usd_per_mtok": 6,
+ "cache_write_1h_usd_per_mtok": 9.6 }
+ ]
+ },
+ "acme-coder-2": {
+ "provider": "acme",
+ "input_usd_per_mtok": 1,
+ "output_usd_per_mtok": 4
+ }
+ },
+ "aliases": {
+ "my-gateway-model": "claude-sonnet-4-5",
+ "router/fast": "gpt-5-mini"
+ }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `schema` | Required. Must be `beacon.pricing.overrides/v1` |
+| `comment` | Optional note about the file, such as the agreement it comes from |
+| `models` | Price rows, keyed by the model name a runtime reports |
+| `models.<name>.input_usd_per_mtok` | Required. US dollars per million uncached input tokens |
+| `models.<name>.output_usd_per_mtok` | Required. US dollars per million output tokens (reasoning tokens are part of output) |
+| `models.<name>.cache_read_usd_per_mtok` | Optional. Price of a prompt-cache hit |
+| `models.<name>.cache_write_usd_per_mtok` | Optional. Price of a cache write with the default (five-minute) TTL |
+| `models.<name>.cache_write_1h_usd_per_mtok` | Optional. Price of a one-hour cache write |
+| `models.<name>.bands` | Optional long-context bands: `above_tokens` plus any rates that change above it |
+| `models.<name>.provider` | Optional label shown in reports |
+| `models.<name>.comment` | Optional note shown by `beacon pricing show` |
+| `aliases` | Map from a reported model name to an exact model in this file or catalog key |
+
+### Rules
+
+- **Rates are US dollars per million tokens**, written as JSON numbers: `3`, `0.3`, `2.5e-1`.
+ Beacon converts each one exactly to integer microdollars, so `0.3` is exactly 300,000
+ microdollars per million tokens. A value finer than one microdollar per million tokens (more
+ than six decimal places) is refused rather than rounded.
+- **Refused values**, each with an error naming the key: negative numbers, `0` (leave a field
+ out when a rate is unpublished; a zero would make tokens free), quoted numbers such as
+ `"3.00"`, anything above $100,000 per million tokens (almost always a per-token or
+ per-thousand price in the wrong field), unknown fields (usually a misspelled rate), and a key
+ written twice.
+- **A row replaces the catalog row whole.** Fields you leave out are unpublished, not
+ inherited from the catalog, and are priced the way the catalog prices a missing rate: cache
+ reads and cache writes at the row's input rate, one-hour writes at its five-minute write
+ rate. Those fallbacks are named in the report's `pricing.models[].fallbacks` and by
+ `beacon pricing show`.
+- **Bands** apply to every token of a single request whose prompt (input plus cache read plus
+ cache write) is above `above_tokens`, exactly as the catalog's bands do, and only to usage
+ Beacon knows is one request (see [How the estimate is computed](/cli/token-usage#how-the-estimate-is-computed)).
+ A band needs to state only what changes; every rate it leaves out is the row's base rate.
+ Bands may be listed in any order; two bands at the same threshold are refused.
+- **Matching.** A row or alias name is matched with the same ladder as the catalog: the exact
+ reported name first, then case and provider prefix (`anthropic/Claude-Sonnet-4-5`), dotted
+ versions (`claude-sonnet-4.5`), Bedrock route prefixes, and after stripping a `[1m]` marker,
+ a snapshot date or an effort suffix. So a row for `claude-sonnet-4-5` also prices
+ `claude-sonnet-4-5-20250929`, even though the catalog has a row for that exact snapshot.
+- **Overrides win.** When any name in the file matches a model, the file decides; the catalog
+ is consulted only for models no override name reaches. If two names in the file match a model
+ at the same rung with different prices, the model is left unpriced rather than priced at a
+ list price the file was written to replace; `beacon pricing validate` warns about such names.
+- **Aliases** point at an exact name: a row in this file (checked first) or a catalog key from
+ `beacon pricing list`. An alias cannot also be a row, and a target that exists in neither list
+ is refused.
+
+## Auditing an estimate
+
+When an overrides file is in use, the report's `pricing` block says so:
+
+```json
+"pricing": {
+ "catalog": { "name": "LiteLLM model_prices_and_context_window.json", "commit": "1238cfe9...", "generated_at": "2026-10-05" },
+ "overrides": {
+ "path": "/Users/alice/.beacon/endpoint/pricing/overrides.json",
+ "sha256": "db4de2c8d714...",
+ "models": 2,
+ "aliases": 2
+ },
+ "models": [
+ { "model": "acme-coder-2", "key": "acme-coder-2", "source": "override", "match": "exact", "...": "..." },
+ { "model": "my-gateway-model", "key": "claude-sonnet-4-5", "source": "override", "alias": "my-gateway-model", "...": "..." }
+ ]
+}
+```
+
+`source` is `override` for a model priced by a row of the file and `catalog` for one priced by
+the catalog; `alias` is set when the model reached its entry through an alias (an alias to a
+catalog key has `source: catalog`). The `sha256` is the digest of the file's bytes, so an
+estimate can be traced to the exact file that produced it. The text report prints the same
+path and digest in its footer and lists the models the file priced.
+
+If the default overrides file is invalid, `beacon token-usage` fails with the error rather than
+quietly printing list prices. The dashboard keeps answering: it prices from the catalog alone
+and reports the problem in `pricing.overrides.error`.
+
+## beacon pricing show
+
+Explains how one model name resolves: the entry that priced it (catalog key or override), the
+match rung and any stripped decorations, the rates in USD per million tokens, its bands, and
+which rates are unpublished. For an unpriced model it says so, and lists the tied candidates
+when several entries matched with different prices.
+
+```bash
+beacon pricing show 'claude-sonnet-4-5-20250929[1m]'
+```
+
+```text
+Model: claude-sonnet-4-5-20250929[1m]
+Priced by: catalog key "claude-sonnet-4-5-20250929"
+Provider: anthropic
+Match: exact after stripping context_window
+Rates (USD per million tokens):
+ input 3.00
+ output 15.00
+ cache read 0.30
+ cache write (5m) 3.75
+ cache write (1h) 6.00
+Long-context bands (a single request whose prompt is above the threshold is billed at the band's rates for every token):
+ above 200000: input 6.00, output 22.50, cache read 0.60, cache write 7.50, cache write 1h 12.00
+```
+
+## beacon pricing list
+
+Lists every catalog entry and every row and alias of the overrides file, with base rates in USD
+per million tokens. Override rows come first; a catalog entry replaced by a row of the same
+name is marked `catalog*` (`"overridden": true` in JSON). `--provider` keeps only the entries
+of one provider, such as `anthropic`, `openai`, `gemini` or `bedrock_converse`.
+
+## beacon pricing info
+
+Prints the catalog's provenance (source URL, upstream commit, fetch and generation dates, model
+count, tier) and the overrides file that would be used, with its digest, or why it cannot be.
+`info` reports an invalid file instead of failing on it.
+
+## beacon pricing validate
+
+Checks the overrides file: every error names the key, and on success it lists each row (and
+whether it replaces a catalog entry), each alias and its target, and the rates each row leaves
+unpublished. Name collisions that would leave a model unpriced are printed as warnings on
+stderr. It fails when the file is missing.
+
+```bash
+beacon pricing validate --pricing-file ./overrides.json
+```
+
+```text
+ok: ./overrides.json (sha256 db4de2c8d714): 2 model(s), 2 alias(es)
+ model acme-coder-2
+ unpublished, priced by fallback: cache_read_at_input_rate, cache_write_at_input_rate, cache_write_1h_at_write_rate
+ model claude-sonnet-4-5 replaces the catalog entry of the same name
+ alias my-gateway-model -> claude-sonnet-4-5 (override)
+ alias router/fast -> gpt-5-mini (catalog)
+```
diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdx
index 1b7e2410..806177dd 100644
--- a/docs/cli/token-usage.mdx
+++ b/docs/cli/token-usage.mdx
@@ -115,14 +115,15 @@ Each usage row in the report (totals, every grouping, time buckets, the session
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.
+`unpriced_events` and `unpriced_tokens` count usage whose model neither the catalog nor your overrides file prices. Those tokens are in every token total and in no estimate: an unknown model stays unknown rather than reading as free. `beacon pricing show <model>` explains why a model is unpriced, and an [overrides file](/cli/pricing#the-overrides-file) can price it.
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.
+- **Overrides.** A local overrides file (`~/.beacon/endpoint/pricing/overrides.json`, or `--pricing-file`) prices models the catalog does not know and replaces list prices with your negotiated rates. It wins over the catalog for every model one of its names matches. `pricing.overrides` records its path and SHA-256 digest, and each `pricing.models[]` entry says `source: override` or `source: catalog` (plus `alias` when a gateway name was mapped). An invalid file is an error, not a silent fallback to list prices; the dashboard, which must keep answering, falls back and reports it in `pricing.overrides.error`. See [beacon pricing](/cli/pricing).
+- **Standard tier only.** The catalog has no batch, flex or priority tiers, regional surcharges, or subscription and enterprise discounts: nothing in a usage record says a call used them. Put negotiated rates in the overrides file.
- **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.
@@ -225,6 +226,7 @@ By default, the command reads the per-user endpoint runtime log. Use `--system`
| `--system` | Use system endpoint paths |
| `--log-path <path>` | Runtime JSONL log path. In CI, point this at the session log |
| `--json` | Print the token usage report as JSON |
+| `--pricing-file <path>` | Pricing overrides file for the cost estimate. Defaults to `pricing/overrides.json` in the endpoint directory when it exists. See [beacon pricing](/cli/pricing) |
## Related
diff --git a/docs/docs.json b/docs/docs.json
index ee335d06..e3edafe3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -362,6 +362,7 @@
"cli/lenses",
"cli/git",
"cli/token-usage",
+ "cli/pricing",
"cli/version"
]
}