fix(pricing): apply LiteLLM request bands per request (#1305)

AgentsView currently flattens LiteLLM catalog rows, which undercounts long-context requests such as Codex above 272K input tokens and Claude above 200K, causing its totals to diverge from tools that honor those thresholds.

This preserves deterministic standard threshold metadata in fetched and embedded catalogs, then selects the highest eligible band for each request-scoped usage row. Aggregate-only rows stay on base rates because their request boundaries are unknown, and custom pricing remains deliberately flat.

Complete bands now survive SQLite, PostgreSQL, and DuckDB transport with atomic revisions and reproducible digests. Schema-v4 pricing provenance exposes both available bands and how many report rows selected each one, while service-tier-specific variants remain excluded when transcripts cannot identify the tier.

Co-authored-by: Marius van Niekerk <mariusvniekerk@users.noreply.github.com>

Author: mariusvniekerk

cmd/agentsview/export.go

@@ -553,6 +553,11 @@ func cloneExportSessionsModelRate(
 		pattern := *rate.MatchedPattern
 		rate.MatchedPattern = &pattern
 	}
+	rate.Bands = append([]export.PricingBand(nil), rate.Bands...)
+	rate.Application.Bands = append(
+		[]export.AppliedPricingBand(nil),
+		rate.Application.Bands...,
+	)
 	return rate
 }
 
@@ -576,10 +581,8 @@ func mergeExportSessionsModelProvenance(
 	for _, rate := range next.Resolutions {
 		key := exportSessionsModelRateKey(rate)
 		if i, ok := positions[key]; ok {
-			merged.Resolutions[i].CostSource =
-				mergeExportSessionsCostSource(
-					merged.Resolutions[i].CostSource,
-					rate.CostSource)
+			merged.Resolutions[i] = mergeExportSessionsModelRate(
+				merged.Resolutions[i], rate)
 			continue
 		}
 		positions[key] = len(merged.Resolutions)
@@ -600,6 +603,26 @@ func mergeExportSessionsModelProvenance(
 	return merged
 }
 
+func mergeExportSessionsModelRate(
+	base, next export.EffectiveModelRate,
+) export.EffectiveModelRate {
+	merged := cloneExportSessionsModelRate(base)
+	if merged.MatchedPattern == nil && next.MatchedPattern != nil {
+		pattern := *next.MatchedPattern
+		merged.MatchedPattern = &pattern
+	}
+	if len(merged.Bands) == 0 && len(next.Bands) > 0 {
+		merged.Bands = append([]export.PricingBand(nil), next.Bands...)
+	}
+	merged.Application = mergeExportSessionsPricingApplication(
+		merged.Application,
+		next.Application,
+	)
+	merged.CostSource = mergeExportSessionsCostSource(
+		merged.CostSource, next.CostSource)
+	return merged
+}
+
 func exportSessionsModelRateKey(
 	rate export.EffectiveModelRate,
 ) exportSessionsModelResolutionKey {
@@ -613,6 +636,34 @@ func exportSessionsModelRateKey(
 	return key
 }
 
+func mergeExportSessionsPricingApplication(
+	base, next export.PricingApplication,
+) export.PricingApplication {
+	merged := export.PricingApplication{
+		BaseRequestCount:  base.BaseRequestCount + next.BaseRequestCount,
+		AggregateRowCount: base.AggregateRowCount + next.AggregateRowCount,
+	}
+	counts := make(map[int]int, len(base.Bands)+len(next.Bands))
+	for _, band := range base.Bands {
+		counts[band.AboveInputTokens] += band.RequestCount
+	}
+	for _, band := range next.Bands {
+		counts[band.AboveInputTokens] += band.RequestCount
+	}
+	thresholds := make([]int, 0, len(counts))
+	for threshold := range counts {
+		thresholds = append(thresholds, threshold)
+	}
+	sort.Ints(thresholds)
+	for _, threshold := range thresholds {
+		merged.Bands = append(merged.Bands, export.AppliedPricingBand{
+			AboveInputTokens: threshold,
+			RequestCount:     counts[threshold],
+		})
+	}
+	return merged
+}
+
 func mergeExportSessionsCostSource(
 	a, b export.CostSource,
 ) export.CostSource {

cmd/agentsview/export_sessions_test.go

@@ -327,6 +327,45 @@ func TestMergeExportSessionsPricingCombinesReportedModelResolutions(t *testing.T
 		provenance.Resolutions[1].CostSource)
 }
 
+func TestMergeExportSessionsModelRateSumsPricingApplications(t *testing.T) {
+	base := export.EffectiveModelRate{
+		Bands: []export.PricingBand{{AboveInputTokens: 200_000}},
+		Application: export.PricingApplication{
+			BaseRequestCount:  1,
+			AggregateRowCount: 2,
+			Bands: []export.AppliedPricingBand{{
+				AboveInputTokens: 200_000,
+				RequestCount:     3,
+			}},
+		},
+	}
+	next := export.EffectiveModelRate{
+		Bands: []export.PricingBand{{AboveInputTokens: 200_000}},
+		Application: export.PricingApplication{
+			BaseRequestCount:  4,
+			AggregateRowCount: 5,
+			Bands: []export.AppliedPricingBand{
+				{AboveInputTokens: 200_000, RequestCount: 6},
+				{AboveInputTokens: 272_000, RequestCount: 7},
+			},
+		},
+	}
+
+	got := mergeExportSessionsModelRate(base, next)
+	next.Bands[0].AboveInputTokens = 1
+	next.Application.Bands[0].RequestCount = 99
+
+	assert.Equal(t, []export.PricingBand{{AboveInputTokens: 200_000}}, got.Bands)
+	assert.Equal(t, export.PricingApplication{
+		BaseRequestCount:  5,
+		AggregateRowCount: 7,
+		Bands: []export.AppliedPricingBand{
+			{AboveInputTokens: 200_000, RequestCount: 9},
+			{AboveInputTokens: 272_000, RequestCount: 7},
+		},
+	}, got.Application)
+}
+
 func TestExportSessionsAllNDJSONCursorNextEmpty(t *testing.T) {
 	seedExportSessionsArchive(t)
 

cmd/agentsview/usage.go

@@ -420,26 +420,49 @@ func ensureUsagePricing(
 func applyFallbackPricing(
 	database *db.DB, custom map[string]config.CustomModelRate,
 ) {
-	rates := make(map[string]config.CustomModelRate)
-	sources := make(map[string]export.PricingRowSource)
+	rates := make(map[string]export.ModelRates)
 	for _, p := range pricing.FallbackPricing() {
 		// These keys are the same concrete model-pattern keys that the
 		// model_pricing table stores. SQLite usage lookups run the merged map
 		// through pricing.Resolve, so normalized/canonical aliases still match
 		// when this read-only path cannot seed model_pricing rows.
-		rates[p.ModelPattern] = config.CustomModelRate{
-			InputMicrodollarsPerMTok:         p.InputPerMTok.Microdollars,
-			OutputMicrodollarsPerMTok:        p.OutputPerMTok.Microdollars,
-			CacheCreationMicrodollarsPerMTok: p.CacheCreationPerMTok.Microdollars,
-			CacheReadMicrodollarsPerMTok:     p.CacheReadPerMTok.Microdollars,
+		bands := make([]export.PricingBand, len(p.Bands))
+		for i, band := range p.Bands {
+			bands[i] = export.PricingBand{
+				AboveInputTokens:  band.AboveInputTokens,
+				InputPerMTok:      band.InputPerMTok,
+				OutputPerMTok:     band.OutputPerMTok,
+				CacheWritePerMTok: band.CacheCreationPerMTok,
+				CacheReadPerMTok:  band.CacheReadPerMTok,
+			}
+		}
+		rates[p.ModelPattern] = export.ModelRates{
+			InputPerMTok:      p.InputPerMTok,
+			OutputPerMTok:     p.OutputPerMTok,
+			CacheWritePerMTok: p.CacheCreationPerMTok,
+			CacheReadPerMTok:  p.CacheReadPerMTok,
+			Source:            export.PricingRowSourceEmbedded,
+			Bands:             bands,
 		}
-		sources[p.ModelPattern] = export.PricingRowSourceEmbedded
 	}
 	for model, rate := range custom {
-		rates[model] = rate
-		sources[model] = export.PricingRowSourceCustom
+		rates[model] = export.ModelRates{
+			InputPerMTok: money.Money{
+				Microdollars: rate.InputMicrodollarsPerMTok,
+			},
+			OutputPerMTok: money.Money{
+				Microdollars: rate.OutputMicrodollarsPerMTok,
+			},
+			CacheWritePerMTok: money.Money{
+				Microdollars: rate.CacheCreationMicrodollarsPerMTok,
+			},
+			CacheReadPerMTok: money.Money{
+				Microdollars: rate.CacheReadMicrodollarsPerMTok,
+			},
+			Source: export.PricingRowSourceCustom,
+		}
 	}
-	database.SetEffectivePricing(rates, sources)
+	database.SetEffectivePricing(rates)
 }
 
 func fetchHTTPDailyUsage(

cmd/agentsview/usage_test.go

@@ -853,6 +853,38 @@ func TestRunUsageDailyOfflineUsesReadOnlyDBWhenWriteLockHeld(t *testing.T) {
 		"offline read-only usage must preserve custom pricing")
 }
 
+func TestApplyFallbackPricingPreservesReadOnlyLongContextBands(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "sessions.db")
+	writable := dbtest.OpenTestDBAt(t, dbPath)
+	startedAt := "2026-07-03T12:00:00Z"
+	require.NoError(t, writable.UpsertSession(db.Session{
+		ID: "long-context", Project: "pricing", Machine: "local", Agent: "codex",
+		StartedAt: &startedAt,
+	}))
+	ordinal := 1
+	require.NoError(t, writable.ReplaceSessionUsageEvents("long-context", []db.UsageEvent{{
+		MessageOrdinal: &ordinal,
+		Source:         "codex",
+		Model:          "gpt-5.5",
+		InputTokens:    272_001,
+		OccurredAt:     startedAt,
+		DedupKey:       "request-1",
+	}}))
+	require.NoError(t, writable.Close())
+
+	readonly, err := db.OpenReadOnly(dbPath)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, readonly.Close()) })
+	applyFallbackPricing(readonly, nil)
+
+	got, err := readonly.GetDailyUsage(context.Background(), db.UsageFilter{
+		From: "2026-07-03", To: "2026-07-03", Timezone: "UTC",
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, money.Money{Microdollars: 2_720_010}, got.Totals.TotalCost)
+}
+
 func TestArchiveQueryBackendNoSyncStartsNoSyncDaemonForDailyUsage(t *testing.T) {
 	newAgentDataDir(t)
 	var started bool

docs/activity.md

@@ -155,20 +155,21 @@ surfaces. Usage and activity already emitted `schema_version: 1` before 0.38,
 and the session-summary v1 contract shipped in 0.37.1. Releases 0.38.0 and
 0.38.1 emitted the substantially revised project-evidence shape while still
 reporting version 1. Version 2 corrected those markers, version 3 introduced
-exact microdollar money objects, and current builds emit version 4 with
-resolved-model pricing provenance. Those two transitional releases must not be
-treated as v1-compatible. Consumers should require the expected `schema_version`
-and ignore unknown additive fields. The commands do not provide an
-earlier-version output mode.
+exact microdollar money objects, and version 4 adds resolved-model pricing
+provenance with complete request-pricing bands and application counts. Those
+two transitional releases must not be treated as v1-compatible. Consumers
+should require the expected `schema_version` and ignore unknown additive fields.
+The commands do not provide an earlier-version output mode.
 
 The activity report includes the shared report-level `pricing` and `projects`
 blocks. `pricing.models` is keyed by reported model names. Each entry contains
 an aggregate `cost_source` and explicit `resolutions` with `priced_model` and
 effective rate fields such as `input_cost_per_mtok`, `output_cost_per_mtok`,
-`cache_write_cost_per_mtok`, and `cache_read_cost_per_mtok`. Every
-project-bearing report row contains an opaque `project_key`. `projects` is keyed
-by that value and carries the presentation-only `display_label`; unknown project
-identity is represented by an explicit `resolution` with `identity` omitted.
+`cache_write_cost_per_mtok`, and `cache_read_cost_per_mtok`, plus available
+`bands` and report-specific `application` counts. Every project-bearing report
+row contains an opaque `project_key`. `projects` is keyed by that value and
+carries the presentation-only `display_label`; unknown project identity is
+represented by an explicit `resolution` with `identity` omitted.
 
 See [Token Usage & Costs](/token-usage/#json-contract) for the shared bump
 rules, [Pricing Provenance](/token-usage/#pricing-provenance) for pricing digest

docs/internal/session-format-sources.md

@@ -18,6 +18,30 @@ computes later with its pricing catalog. A compatible upstream implementation,
 independent parser, or recorded fixture is useful evidence for a format, but is
 called out when it is not the product's own producer source.
 
+## Pricing Catalog Evidence
+
+Agentsview's fetched and embedded token prices come from LiteLLM's
+[`model_prices_and_context_window.json`](https://github.com/BerriAI/litellm/blob/551e5d097c11f08fd2400a25a651b1844fcf89c2/model_prices_and_context_window.json)
+at pinned commit `551e5d097c11f08fd2400a25a651b1844fcf89c2`. LiteLLM's
+[`cost_per_token` implementation](https://github.com/BerriAI/litellm/blob/551e5d097c11f08fd2400a25a651b1844fcf89c2/litellm/litellm_core_utils/llm_cost_calc/utils.py)
+shows that these catalog fields are request-pricing thresholds rather than
+model-name conventions.
+
+Agentsview recognizes the anchored standard field shape
+`input_cost_per_token_above_<N>[k]_tokens`, including the published 200K and
+272K bands, and reads output, cache-creation, and cache-read companions with the
+same suffix. A band applies only when whole-request input is strictly greater
+than its threshold; when several bands exist, the highest eligible threshold
+wins. Additional suffixes for Batch, Flex, Priority, regional, or other service
+tiers are deliberately excluded because stored usage does not identify those
+variants.
+
+Claude and Codex session artifacts provide normalized input, output,
+cache-creation, and cache-read token categories, but they do not supply this
+pricing metadata. Agentsview therefore uses their request boundaries and token
+counts with the catalog bands; it does not infer thresholds from provider or
+model names.
+
 Unless an entry states otherwise, entries were last verified on 2026-07-19. A
 pinned revision is a reproducible research snapshot, not a claim that it
 produced every historical artifact that Agentsview accepts. Where an entry

docs/session-api.md

@@ -813,7 +813,7 @@ Response excerpt:
 
 ```json
 {
-  "schema_version": 2,
+  "schema_version": 4,
   "pricing": {
     "source": "fetched",
     "table_version": "litellm-398a0b15378c",
@@ -829,11 +829,27 @@ Response excerpt:
     "models": {
       "gpt-5.4": {
         "matched_pattern": "gpt-5.4",
-        "input_cost_per_mtok": 2,
-        "output_cost_per_mtok": 8,
-        "cache_write_cost_per_mtok": 3,
-        "cache_read_cost_per_mtok": 0.5,
-        "cost_source": "computed"
+        "input_cost_per_mtok": {"microdollars": 2500000},
+        "output_cost_per_mtok": {"microdollars": 15000000},
+        "cache_write_cost_per_mtok": {"microdollars": 0},
+        "cache_read_cost_per_mtok": {"microdollars": 250000},
+        "cost_source": "computed",
+        "bands": [
+          {
+            "above_input_tokens": 272000,
+            "input_cost_per_mtok": {"microdollars": 5000000},
+            "output_cost_per_mtok": {"microdollars": 22500000},
+            "cache_write_cost_per_mtok": {"microdollars": 0},
+            "cache_read_cost_per_mtok": {"microdollars": 500000}
+          }
+        ],
+        "application": {
+          "base_request_count": 14,
+          "aggregate_row_count": 0,
+          "bands": [
+            {"above_input_tokens": 272000, "request_count": 2}
+          ]
+        }
       }
     }
   },

docs/session-export.md

@@ -52,7 +52,13 @@ JSON output is one document:
             "output_cost_per_mtok": {"microdollars": 8000000},
             "cache_write_cost_per_mtok": {"microdollars": 3000000},
             "cache_read_cost_per_mtok": {"microdollars": 500000},
-            "cost_source": "computed"
+            "cost_source": "computed",
+            "bands": null,
+            "application": {
+              "base_request_count": 1,
+              "aggregate_row_count": 0,
+              "bands": null
+            }
           }
         ]
       }
@@ -279,13 +285,14 @@ current privacy-bounded project, repository, worktree, and checkout evidence
 shape but mistakenly continued to report version 1. Current builds report
 version 4. Version 2 corrected the project-evidence marker, version 3 introduced
 exact microdollar money objects, and version 4 adds explicit
-reported-to-priced-model resolutions. Payloads from the two transitional
-releases must not be treated as v1-compatible. There is no flag to request an
-earlier output version. Additive fields do not require a bump, but row semantic
-changes, field type changes, sort order changes, cursor semantics changes,
-required-field meaning changes, field removal, pricing digest canonicalization
-changes, project key derivation changes, remote normalization changes, path
-fallback normalization changes, and new closed-enum values require a bump.
+reported-to-priced-model resolutions with complete request-pricing bands and
+application counts. Payloads from the two transitional releases must not be
+treated as v1-compatible. There is no flag to request an earlier output version.
+Additive fields do not require a bump, but row semantic changes, field type
+changes, sort order changes, cursor semantics changes, required-field meaning
+changes, field removal, pricing digest canonicalization changes, project key
+derivation changes, remote normalization changes, path fallback normalization
+changes, and new closed-enum values require a bump.
 
 Consumers should require the expected `schema_version` and ignore unknown
 additive fields.