mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
efrazer-oai
c8e5db16c9
## Summary
Enterprise users can have an effective monthly credit limit, but Codex
`/status` currently drops that metadata from the account-usage response.
This change adds the optional `spend_control.individual_limit`
projection to the existing rate-limit snapshot flow. The backend client
reads the monthly limit, app-server exposes it as `individualLimit`, and
the TUI renders a `Monthly credit limit` row through the existing
progress-bar renderer.
When the backend does not return an effective monthly limit, existing
rate-limit behavior is unchanged.
## Existing backend state
The account-usage backend already returns the effective monthly limit
and current usage together:
```json
{
"spend_control": {
"reached": false,
"individual_limit": {
"limit": "25000",
"used": "8000",
"remaining": "17000",
"used_percent": 32,
"remaining_percent": 68,
"reset_after_seconds": 86400,
"reset_at": 1778137680
}
}
}
```
Before this change, Codex projected rolling `primary` and `secondary`
windows plus `credits`. It ignored `spend_control.individual_limit`, so
app-server clients and `/status` could not render the monthly cap.
The updated flow is:
```text
account usage backend
-> backend-client reads spend_control.individual_limit
-> existing rate-limit snapshot carries optional individual_limit
-> app-server exposes optional individualLimit
-> TUI renders Monthly credit limit
```
## App-server contract
`account/rateLimits/read` and sparse `account/rateLimits/updated`
notifications now include an additive nullable
`rateLimits.individualLimit` field:
```json
{
"individualLimit": {
"limit": "25000",
"used": "8000",
"remainingPercent": 68,
"resetsAt": 1778137680
}
}
```
In an `account/rateLimits/read` response, `null` means no monthly limit
is available. `account/rateLimits/updated` remains a sparse rolling
notification: clients merge available values into their most recent
`account/rateLimits/read` snapshot or refetch. Nullable account metadata
in a rolling notification does not clear a previously observed value.
## Design decisions
- Extend the existing rate-limit snapshot instead of introducing a
separate request or wire-level update protocol.
- Keep the Codex projection narrow: `/status` needs the effective limit,
current usage, remaining percentage, and reset timestamp.
- Render the monthly row through the existing progress-bar renderer,
with one optional detail line for `8,000 of 25,000 credits used`.
- Keep the backend response optional so existing accounts and older
usage states preserve their current behavior.
- Preserve cached monthly metadata when sparse rolling notifications
omit it. Live account-usage reads remain authoritative and can clear a
removed limit.
## Visual evidence
```text
Monthly credit limit: [██████████████░░░░░░] 68% left (resets 07:08 on 7 May)
8,000 of 25,000 credits used
```
Snapshot:
`codex-rs/tui/src/status/snapshots/codex_tui__status__tests__status_snapshot_includes_enterprise_monthly_credit_limit.snap`
## Testing
Tests: generated app-server schema verification, protocol tests,
backend-client tests, app-server integration coverage, TUI snapshot
coverage, formatting, and workspace lint cleanup.
192 lines
4.1 KiB
JSON
Generated
192 lines
4.1 KiB
JSON
Generated
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"definitions": {
|
|
"CreditsSnapshot": {
|
|
"properties": {
|
|
"balance": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"hasCredits": {
|
|
"type": "boolean"
|
|
},
|
|
"unlimited": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"hasCredits",
|
|
"unlimited"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"PlanType": {
|
|
"enum": [
|
|
"free",
|
|
"go",
|
|
"plus",
|
|
"pro",
|
|
"prolite",
|
|
"team",
|
|
"self_serve_business_usage_based",
|
|
"business",
|
|
"enterprise_cbp_usage_based",
|
|
"enterprise",
|
|
"edu",
|
|
"unknown"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"RateLimitReachedType": {
|
|
"enum": [
|
|
"rate_limit_reached",
|
|
"workspace_owner_credits_depleted",
|
|
"workspace_member_credits_depleted",
|
|
"workspace_owner_usage_limit_reached",
|
|
"workspace_member_usage_limit_reached"
|
|
],
|
|
"type": "string"
|
|
},
|
|
"RateLimitSnapshot": {
|
|
"properties": {
|
|
"credits": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/CreditsSnapshot"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"individualLimit": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/SpendControlLimitSnapshot"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"limitId": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"limitName": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"planType": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/PlanType"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"primary": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/RateLimitWindow"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"rateLimitReachedType": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/RateLimitReachedType"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"secondary": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/definitions/RateLimitWindow"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"type": "object"
|
|
},
|
|
"RateLimitWindow": {
|
|
"properties": {
|
|
"resetsAt": {
|
|
"format": "int64",
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
]
|
|
},
|
|
"usedPercent": {
|
|
"format": "int32",
|
|
"type": "integer"
|
|
},
|
|
"windowDurationMins": {
|
|
"format": "int64",
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
"required": [
|
|
"usedPercent"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"SpendControlLimitSnapshot": {
|
|
"properties": {
|
|
"limit": {
|
|
"type": "string"
|
|
},
|
|
"remainingPercent": {
|
|
"format": "int32",
|
|
"type": "integer"
|
|
},
|
|
"resetsAt": {
|
|
"format": "int64",
|
|
"type": "integer"
|
|
},
|
|
"used": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"limit",
|
|
"remainingPercent",
|
|
"resetsAt",
|
|
"used"
|
|
],
|
|
"type": "object"
|
|
}
|
|
},
|
|
"description": "Sparse rolling rate-limit update.\n\nClients should merge available values into the most recent `account/rateLimits/read` response or refetch that snapshot. Nullable account metadata may be unavailable in a rolling update and does not clear a previously observed value.",
|
|
"properties": {
|
|
"rateLimits": {
|
|
"$ref": "#/definitions/RateLimitSnapshot"
|
|
}
|
|
},
|
|
"required": [
|
|
"rateLimits"
|
|
],
|
|
"title": "AccountRateLimitsUpdatedNotification",
|
|
"type": "object"
|
|
} |