codex-usage-tracking 0.18.0__tar.gz → 0.20.0__tar.gz

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.20.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Unofficial local Codex usage dashboard and MCP diagnostics from local session logs.",
   "author": {
     "name": "Douglas Monsky"

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.20.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.20.0 - 2026-07-16
+
+- Reinvent the Threads tab around inline row expansion, progressively loading and virtualizing every call in the selected thread while preserving explicit investigator actions, deep links, responsive layouts, retry recovery, and aggregate-first privacy boundaries.
+- Complete the Simplified Chinese dashboard experience across React views, visualization metadata, tables, accessibility text, CLI help, and dashboard lifecycle messages while preserving user-provided data verbatim.
+- Improve the Overview token-flow chart at constrained desktop widths with a taller single-column layout, larger Sankey node gaps, and label-safe padding; keep virtualized evidence-table actions on one row.
+- Apply official long-context input, cached-input, and output price multipliers to concrete calls above 272K input tokens when the selected OpenAI service tier publishes long-context rates, while keeping aggregate summaries from being incorrectly thresholded.
+
+## 0.19.0 - 2026-07-15
+
+- Redesign Limits Intelligence around weekly credits-per-percentage capacity
+  history, a compact current-status row, automatic revision analysis, and zero,
+  one, or multiple family-wise-controlled capacity changes. Rejected split
+  statistics stay hidden, five-hour usage remains observed context, and the v2
+  API/MCP contracts expose capacity points, regimes, provenance, and copied-row
+  diagnostics by default.
+
 ## 0.18.0 - 2026-07-15
 
 - Exclude exact historical calls copied by cloned Codex tasks from default dashboard, CLI, MCP, report, allowance, compression, recommendation, and export totals while retaining every physical source row for local provenance.

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.18.0
+Version: 0.20.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -237,12 +237,12 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including evidence-graded weekly allowance analysis and on-demand usage-drain report runs.
+- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including responsive token-flow visualization, evidence-graded weekly allowance analysis, and on-demand usage-drain report runs.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.
 - Companion Codex skills for operational setup and conversational usage analysis.
-- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
+- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration, including per-call long-context pricing above 272K input tokens for OpenAI service tiers that publish long-context rates.
 
 ## Dashboard Language
 
@@ -262,7 +262,7 @@ CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
 
 The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
 
-Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. Simplified Chinese also localizes CLI help and dashboard lifecycle messages. Localization never rewrites raw Codex log content, thread names, project names, paths, or data exports.
 
 ### Adding A Dashboard Language
 

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.20.0}/README.md

@@ -189,12 +189,12 @@ The tracker cannot read your logged-in ChatGPT plan or live remaining usage auto
 
 - Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
 - Static dashboard generation plus localhost live refresh.
-- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including evidence-graded weekly allowance analysis and on-demand usage-drain report runs.
+- `Overview`, `Investigate`, `Calls`, `Threads`, `Limits`, and `Diagnostics` dashboard views, including responsive token-flow visualization, evidence-graded weekly allowance analysis, and on-demand usage-drain report runs.
 - Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
 - CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
 - MCP tools for Codex sessions that want to query local usage data.
 - Companion Codex skills for operational setup and conversational usage analysis.
-- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
+- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration, including per-call long-context pricing above 272K input tokens for OpenAI service tiers that publish long-context rates.
 
 ## Dashboard Language
 
@@ -214,7 +214,7 @@ CODEX_USAGE_TRACKER_LANG=vi codex-usage-tracker serve-dashboard --open
 
 The dashboard also includes a language selector. Browser selections are stored locally and can override the generated default for that browser.
 
-Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. This localizes dashboard UI text, not raw Codex log content, thread names, project names, paths, full CLI output, or data exports.
+Supported dashboard locales include English, Vietnamese, Spanish, French, German, Portuguese, Japanese, Simplified Chinese, Korean, Russian, Italian, and Arabic. Simplified Chinese also localizes CLI help and dashboard lifecycle messages. Localization never rewrites raw Codex log content, thread names, project names, paths, or data exports.
 
 ### Adding A Dashboard Language
 

codex_usage_tracking-0.20.0/docs/allowance-intelligence.md

@@ -0,0 +1,199 @@
+# Allowance Intelligence
+
+Allowance Intelligence is a local, aggregate-only workflow for understanding the
+weekly and 5-hour percentages observed in Codex logs. It is not an OpenAI ledger,
+does not know the account's hidden allowance denominator, and cannot see usage
+from other agentic surfaces.
+
+The v2 workflow is deliberately conservative: current observations are facts;
+reconstructed values, personal calibration, forecasts, and change claims remain
+separate estimates with visible quality gates.
+
+## Truth Layers
+
+The dashboard and API keep five layers distinct:
+
+1. **Observed allowance** is the percentage and reset metadata written in local
+   `token_count.rate_limits` events or copied into the optional local allowance
+   configuration.
+2. **Canonical usage** is token and locally estimated credit activity after
+   high-confidence copied-clone rows are excluded. This is the default input to
+   reports, the dashboard, and MCP.
+3. **Reconstructed usage** estimates movement between sparse observations using
+   only calibration data available before each interval ended.
+4. **Validated forecast** is shown numerically only after time-ordered holdout
+   testing beats the relevant simple baselines and interval coverage is adequate.
+5. **Physical provenance** preserves source rows and record identifiers for local
+   debugging. It is opt-in and never changes billable totals.
+
+Copied clone rows excluded from canonical totals are always disclosed through
+`quality.copied_rows_excluded` or `copied_rows_excluded`. Similar token counts by
+themselves never cause exclusion.
+
+## Reset And Cohort Semantics
+
+Allowance observations are grouped by window kind, limit identity, plan metadata,
+and normalized reset time. Reset timestamps within 60 seconds are treated as the
+same reset boundary. A reset starts a new cycle and produces a chart break; the
+model never interpolates or fits a continuous line across it.
+
+The normal Codex cohort is selected independently for weekly and 5-hour windows.
+Conflicting simultaneous observations, ambiguous cohort changes, reversals, gaps,
+and reset uncertainty remain visible as conflicts or censored intervals. They are
+not silently converted into positive usage movement.
+
+Weekly data is the primary long-range signal. The 5-hour value is useful current
+context, but its rolling-window behavior makes it unsuitable as the primary
+capacity or regime-change claim.
+
+## Freshness
+
+- Weekly and 5-hour observations are `fresh` through five minutes.
+- Weekly observations are `aging` after five minutes through six hours.
+- Five-hour observations are `aging` after five minutes through 15 minutes.
+- Older observations are `stale`.
+- Passing the reported reset time makes an older observation stale immediately,
+  even when its age would otherwise be acceptable.
+
+The status endpoint is constant size. Poll it every 30 seconds while data is fresh
+or aging and every 60 seconds while it is stale, partial, empty, or unchanged.
+Hidden browser tabs stop polling. Transient failures back off exponentially to a
+maximum of five minutes.
+
+## Personal Calibration And Forecasts
+
+`credits_per_percent` is a personal, empirical calibration derived from local
+history. A value such as `105.11` means the user's eligible completed reset windows
+imply approximately 105.11 locally estimated credits per one observed percentage
+point. It is not an official conversion, a hardcoded product rule, or the hidden
+allowance denominator.
+
+Calibration uses completed quality-approved weekly reset identities as the unit of
+evidence. Interleaved observations carrying the same canonical reset timestamp are
+coalesced into one reset window, so concurrent sessions cannot fragment one window
+into many low-movement pseudo-cycles. Weights include recency, interval quality,
+and price coverage, with each reset window's influence capped. At least two
+completed approved reset windows are required before the
+capacity can move beyond a descriptive result.
+
+Each completed reset window also retains the explicitly logged subscription
+`plan_type`. Capacity points and trailing statistics are separated by plan, so a
+Pro Lite window cannot pull the Pro line up or down. Missing plan metadata is
+reported as `unknown`, and a reset window containing multiple explicit plans is
+reported as `mixed`; neither is guessed from its capacity value.
+
+Each reconstructed interval sees only cycles completed before that interval ended.
+Forecast validation is walk-forward and reports sample size, MAE, RMSE, empirical
+50/80/95% interval coverage, and simple baselines. A numerical forecast is
+`validated` only when the time-ordered holdout beats every relevant baseline and
+all advertised interval coverages meet the minimum gate. A failed forecast is
+reported with the specific failed validation gate; it does not make descriptive
+capacity unavailable. The capacity-first Limits page does not foreground the
+percentage forecast or conditional pace.
+
+Missing price coverage is explicit. Change detection requires at least 95% priced
+credit coverage for each eligible reset window. Forecast and calibration payloads
+report their own coverage gaps and never substitute token-count similarity for
+pricing. The Limits chart keeps an open methodology panel beside the evidence: it
+states the ratio formula, explains every mark and filter, shows the observed plan
+color key, and reports the current eligible, excluded, tested, and supported
+counts rather than asking users to infer the method from the visualization.
+
+## Change Analysis
+
+Allowance change analysis is a persisted, revision-keyed background job. It tests
+weekly cycle capacities with a hierarchical maximum-statistic cycle-block
+permutation detector. The result is one of:
+
+- `insufficient_evidence`
+- `no_supported_change`
+- `supported_changes`
+
+A supported parent boundary may split the history into child segments. Each child
+receives half its parent's alpha budget, so the discovered tree controls
+family-wise false positives rather than treating recursive searches as independent
+tests. Histories are first split at every explicitly observed subscription-plan
+transition, and candidate boundaries are tested only within those continuous plan
+segments. The family-wise alpha budget is divided across analyzable plan segments,
+so a Pro Lite-to-Pro transition is visible provenance but can never itself become a
+capacity-change claim. A boundary must also have an absolute Cliff's delta of at least `0.474`.
+Exact permutations are used where bounded; otherwise the detector uses `1,999`
+deterministic Monte Carlo permutations and requires the upper 95% Monte Carlo
+uncertainty bound to clear the allocated alpha—not merely the point estimate.
+
+A raw best split is never presented as significant. Conflict-heavy cycles,
+insufficient samples, low price coverage, weak effects, or selection-corrected
+uncertainty block strong claims. Results expose zero, one, or multiple supported
+`boundaries` and the resulting `regimes`. Deprecated singular fields are populated
+only when exactly one boundary is supported. Rejected candidate p-values and
+before/after medians are omitted from default dashboard and MCP results.
+
+The dashboard starts analysis automatically when a new semantic revision lacks a
+result. MCP callers start or reuse the same job, poll every 500 milliseconds only
+while it is pending, queued, or running, then reload the persisted result.
+Identical source/model/rate-card keys reuse the same snapshot or in-flight job.
+
+The release gate simulates 1,000 deterministic no-change histories across
+Gaussian, skewed, outlier-contaminated, and heteroskedastic families. The detector
+ships only when the upper 95% Wilson bound for its family-wise false-positive rate
+is at most `0.05`.
+
+## Dashboard Workflow
+
+Open `Limits` from the live localhost dashboard to see:
+
+- one compact row for weekly observed use, 5-hour observed context, weekly reset,
+  and personal weekly capacity;
+- weekly `credits / 1%` history with completed-cycle points, an eight-cycle rolling
+  median and interquartile band, robust outlier display, and every supported change;
+- 8-week, 6-month, all available aggregate-cycle, or bounded custom ranges;
+- cycle, week, or month granularity;
+- an automatic newest-first capacity-change timeline that suppresses rejected
+  candidate statistics; and
+- latest-first evidence in 50-row pages.
+
+Physical source links are hidden by default. Enable **Show physical source links**
+only for local provenance/debugging. Static dashboards show an aggregate fallback
+because they cannot poll the v2 localhost services or analysis jobs.
+
+## HTTP And MCP Contracts
+
+The default v2 surfaces are:
+
+| Purpose | HTTP | MCP |
+| --- | --- | --- |
+| Poll current state | `GET /api/allowance/status` | `usage_allowance_status(...)` |
+| Query a finite timeline | `GET /api/allowance/series` | `usage_allowance_series(...)` |
+| Page latest-first evidence | `GET /api/allowance/evidence` | `usage_allowance_evidence(...)` |
+| Read/start analysis | `GET`/`POST /api/allowance/analysis` | `usage_allowance_analysis(...)` |
+| Poll analysis job | `GET /api/allowance/analysis/jobs/{job_id}` | `usage_allowance_analysis_status(job_id)` |
+
+Series presets are `24h`, `7d`, `8w`, `6m`, and `all`; custom ranges are limited
+to 366 days. The `all` capacity view scans indexed aggregate cycle rows, not raw
+transcripts. Evidence limits are 1–500 and the dashboard defaults to 50;
+interactive evidence never accepts an unlimited-history setting.
+
+Normal and strict evidence return aggregate provenance. `privacy_mode="local"`
+opts into bounded physical record identifiers. Full strict evidence export remains
+the explicit offline `usage_allowance_export(...)` compatibility workflow.
+
+See [CLI, MCP, and Dashboard JSON Schemas](cli-json-schemas.md) for synthetic v2
+payloads and [MCP And Codex Skills](mcp.md) for polling examples.
+
+## V1 Compatibility
+
+`usage_allowance_history`, `usage_allowance_diagnostics`, and
+`usage_allowance_export` remain available for compatibility and explicit offline
+diagnostics. New dashboard, plugin, and MCP workflows should start with the v2
+status/series/evidence/analysis tools. Interactive v2 paths never use `limit=0`.
+
+## Privacy
+
+Normal v2 payloads are aggregate-first and never include prompts, assistant text,
+tool output, command output, or indexed transcript fragments. Strict mode also
+removes stable local identifiers. Local physical provenance is a deliberate,
+bounded opt-in for the owner of the local database.
+
+This project is unofficial, independent, and local-first. Its estimates are tools
+for personal investigation, not statements about OpenAI's internal billing or
+allowance systems.

{codex_usage_tracking-0.18.0 → codex_usage_tracking-0.20.0}/docs/architecture.md

@@ -2,9 +2,10 @@
 
 Codex Usage Tracker is a local sidecar app. It reads Codex session JSONL logs, stores tracker-owned indexes in SQLite, and exposes usage data through CLI commands, MCP tools, CSV export, generated dashboards, and the localhost React dashboard.
 
-The current storage model has two layers:
+The current storage model has three layers:
 
 - Aggregate usage index: token counters, model/effort metadata, call origins, diagnostic labels, thread summaries, pricing/credit estimates, allowance snapshots, and safe report payloads.
+- Canonical/materialized intelligence: physical usage provenance plus logical usage fingerprints and canonical pointers, reset-aware allowance observations/cycles/intervals, source revisions, and persisted analysis snapshots/jobs. Default totals read canonical rows; physical rows remain available for bounded local diagnostics.
 - Local content index: normalized conversation turns, bounded content fragments, tool calls, command runs, file events, persisted investigation run summaries, and source provenance for explicit local MCP/API investigation.
 
 The aggregate index preserves every parsed row in `usage_events` for source provenance. A versioned strict fingerprint links exact copies of the same logged model call, and the `canonical_usage_events` view selects one physical representative for default totals. Only high-confidence fingerprint matches are excluded; ambiguous or merely similar calls remain canonical. If the original source disappears, the surviving physical copy is promoted without changing the logical call identity.
@@ -21,6 +22,15 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
 - `schema.py` owns persisted SQLite columns and migrations. Add columns or tables there before changing refresh, export, or MCP behavior.
 - `store.py` and `store/api.py` own SQLite setup, refresh, rebuild, query access, previous/next call links, materialized thread summaries, source-file refresh cursors, SQL-backed live dashboard API slices, and cleanup ordering.
 - `source_records.py` owns source-file provenance, parser coverage, incremental cursors, and replacement on source-file changes.
+- `dedupe.py` and store migrations own conservative logical identity. Indexed
+  fingerprint lookup is O(1) per parsed event; only high-confidence identical
+  events are linked to a canonical record. No raw-content or fuzzy token-count
+  scan participates in default exclusion.
+- `allowance_intelligence/` owns cohort selection, reset-aware cycle and interval
+  materialization, prior-only calibration/forecasting, selection-corrected change
+  detection, and the constant-size status/finite series/latest-first evidence
+  services. `server/analysis_jobs.py` owns bounded asynchronous execution and
+  revision-keyed persisted results.
 - `reports.py` is the application-service layer for summaries, expensive-call reports, recommendations, pricing coverage, source coverage, allowance reports, and filtered query payloads. CLI and MCP wrappers should call this layer instead of duplicating report assembly.
 - `api_payloads.py` owns stable JSON payload helpers shared by CLI and MCP. `json_contracts.py` owns lightweight contract checks for schema-versioned CLI/MCP payloads and localhost live API payloads.
 - `costing.py`, `pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `allowance.py` own cost, credit, rate-card, and allowance annotation. Keep estimate confidence and source metadata attached to rows.
@@ -47,7 +57,11 @@ Shareable outputs remain aggregate-first and must omit indexed/raw content unles
 11. Register each dashboard route in `server.route_inventory`. Interactive routes must be bounded and index-backed; unavoidable all-history detector work uses the shared asynchronous job lifecycle.
 12. Cache only immutable aggregate responses. Server keys include source generation and semantic/configuration inputs; browser persistence rejects raw or indexed content.
 13. Add or change a route budget only from repeatable synthetic evidence. Database indexes require an additive migration, query-plan or timing evidence, and focused migration coverage.
-14. Preserve physical usage rows for provenance, but route default usage totals and detector folds through `canonical_usage_events`. New physical-row investigation surfaces must be explicitly labeled and tested against an original/copy/new-call fixture.
+14. Preserve physical usage rows for provenance, but route default dashboard,
+    API, report, recommendation, diagnostic, thread-summary, detector, and MCP
+    totals through `canonical_usage_events`. New physical-row investigation
+    surfaces must be bounded, explicitly labeled, and tested against an
+    original/copy/new-call fixture.
 
 Normal aggregate responses use a 64-entry, 256-KiB-per-entry process cache.
 Allowance history and diagnostics use a separate four-entry, 8-MiB-per-entry