Estimate Codex usage cost from the actual model and OpenAI list prices

[dnviti]

Problem / Motivation

Codex users can see how many tokens their work consumed and which model ran, but they cannot see a comparable dollar value because Codex does not report monetary cost. Every eligible Codex turn therefore leaves the live session and permanent usage history saying “cost not reported.”

This makes Codex usage incomplete beside agents that already report API-list-price cost, prevents reliable cost comparisons across agents, and forces users to calculate large token volumes manually.

The requested value is an estimated API-equivalent USD amount: what the reported usage would cost at OpenAI’s published API list price. It is not the amount charged to a ChatGPT subscription or an API invoice. Official rates come from OpenAI API pricing; subscription and API-key access remain distinct billing relationships, as described in Codex authentication.

Related context: #56, #75, #136, #137, #142, and #171.

Current Behavior

1. Sign in to Codex through a ChatGPT subscription or API key.
2. Start a Codex conversation and complete a turn.
3. Observe that the product receives token usage and the effective model.
4. Observe “cost not reported” in the live cost position and no Codex dollar value in the permanent accounting surfaces.

This has never worked for Codex because its runtime reports tokens but does not price them. The current workaround is manual calculation against OpenAI’s published rates.

Goal

Provide a trustworthy, clearly labeled API-equivalent USD estimate whenever Codex reports enough model and token information to calculate one. The estimate must stay consistent across live, historical, per-model, and exported accounting without being presented as actual billed spend.

Scope

• Cover every Codex session that reports sufficient token usage and a runtime-confirmed effective model, regardless of authentication method.
• Price uncached input, cached input, and output using the corresponding official rate. Count reasoning output only once as part of output.
• Use the effective model Codex confirms actually ran, never merely the model requested in settings.
• Use the official standard rate when Codex does not report a special pricing mode. Apply fast, long-context, regional, or other adjustments only when Codex reports enough information to establish them.
• Refresh prices automatically from OpenAI’s public official pricing source and adopt successful published changes within 24 hours.
• Continue using the last known official price during an outage, disclose its date, and replace it after the next successful refresh.
• Preserve the model rate, official source, and retrieval or update date behind each estimate.
• Keep an already recorded estimate unchanged when OpenAI later changes the price.
• Backfill historical Codex records that contain a confirmed model and sufficient token detail. Mark these values as retrospective estimates made with the official rate available at backfill time.
• Estimate reported usage for successful, failed, interrupted, and cancelled turns whenever the required usage data exists.
• For multi-model work, price only usage attributable to a confirmed model. Show a partial amount with explicit coverage when unpriced usage remains; never assign aggregate tokens to the primary or most expensive model by guesswork.
• Show “price unavailable” when no official price exists, while preserving token counts and never substituting zero or a neighboring model.
• Enable the behavior automatically without a user or administrator toggle.
• Retain the estimate and its pricing metadata for the same lifecycle as the corresponding usage history.
• Use the result consistently in the live header, per-turn display, status panel, usage history and dashboard, model breakdowns, and exports.
• Mark calculated values as estimated wherever space permits.
• Expose the applied rate, official source, and pricing date in expanded details.
• Communicate estimated, partial, stale-source, and unavailable states through accessible text or names rather than color, icons, or hover alone.

Non-goals

• Reporting actual subscription charges, included allowance, remaining or consumed ChatGPT credits, API invoice totals, or billing reconciliation.
• Adding price comparisons or rate details to the model picker before work runs.
• Estimating other runtimes or Codex modes that do not report sufficient confirmed model and token data.
• Guessing a model, token attribution, or special pricing mode that Codex did not report.
• Repricing estimates already recorded when OpenAI later changes a rate.
• Adding user-editable prices, a feature toggle, an administrator control, new quota behavior, or a separate success notification.
• Adding new usage telemetry or a new localization system.

Security / Safety Considerations

Price refreshes retrieve only OpenAI’s public pricing resource. They must not send conversation content, token counts, account data, model-selection data, or user information.

The feature performs no destructive action and changes no user permissions or access controls. Estimated values must remain visibly distinct from actual billing information.

Acceptance Criteria

• A Codex turn with a known effective model and known token buckets produces an API-equivalent USD estimate that exactly matches the official uncached-input, cached-input, and output formula before display rounding.
• Reasoning output is not charged a second time when it is already included in output tokens.
• The same eligible usage produces an estimate for both ChatGPT-authenticated and API-key-authenticated Codex sessions.
• Every existing cost surface shows the same total: live header, per-turn display, status panel, usage history and dashboard, model breakdowns, and exports.
• Each calculated value is visibly or accessibly identified as estimated and is never described as an actual subscription charge or invoice amount.
• Expanded details show the effective model, applied official rate, source, and pricing retrieval or update date.
• Switching the effective model causes later usage to use the later model’s rate without changing estimates already recorded.
• A supported published price change is used for new estimates within 24 hours of a successful refresh.
• When the pricing source is unavailable, the last known official rate remains usable and its date is disclosed.
• When no official price has ever been obtained for the effective model, the product shows “price unavailable,” preserves the token counts, and does not show zero.
• Eligible historical Codex records receive retrospective estimates identified as such; records without sufficient confirmed data remain unpriced.
• A later price change does not rewrite a previously recorded live or retrospective estimate.
• Failed, interrupted, and cancelled turns use only the token data Codex actually reported and never invent missing usage.
• Multi-model usage is priced per attributable model; partial totals identify excluded coverage, and unattributed tokens are not assigned to another model.
• Removing a usage record also removes its estimate and pricing metadata under the existing data-lifecycle behavior.
• A price refresh sends only the request needed to retrieve the public pricing resource and sends no conversation, usage, account, model-selection, or user data.
• Estimated and partial states remain understandable without relying on color, icons, or hover.
• User-facing accounting documentation and the changelog explain the new behavior, historical backfill, failure states, and the difference between API-equivalent estimates and billed spend.
• The repository owner can demonstrate known-token arithmetic, a model switch, historical backfill, an unknown-price state, multi-model partial coverage, and matching totals across every cost surface.