The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
feat(pricing): local price overrides and a beacon pricing command group
Claude15d8ffd4aaa3
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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.txtfor forbidden in init update claude cursor dep-scan config; doif grep -E "^[[:space:]]+$forbidden([[:space:]]|$)" /tmp/beacon-help.txt; thenecho "forbidden command exposed: $forbidden"diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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 stringtop intcoverage 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.goindex 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. Adiff --git a/cli/beacon/internal/endpoint/dashboard/static/app.js b/cli/beacon/internal/endpoint/dashboard/static/app.jsindex 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.gonew file mode 100644index 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.goindex 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.goindex 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 pricingdiff --git a/cli/beacon/internal/pricing/lookup.go b/cli/beacon/internal/pricing/lookup.goindex effca5c6..4c8310fb 100644--- a/cli/beacon/internal/pricing/lookup.go+++ b/cli/beacon/internal/pricing/lookup.go@@ -3,6 +3,7 @@ package pricingimport ("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 MatchStripped []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 intconst (@@ -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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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) *PricingSuFetchedAt: 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) *PricingSuif 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) *PricingSuentry := 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) *PricingSureturn 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, sreturn 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.gonew file mode 100644index 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.goindex 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.Totalsfmt.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.goindex 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.mdxnew file mode 100644index 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.mdxindex 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 sessionA 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) |## Relateddiff --git a/docs/docs.json b/docs/docs.jsonindex 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"]}