feat(proxy): support Ultrafast service tier

[evan-choi]

Summary

OpenAI added the access-controlled Ultrafast Processing tier, currently documented for gpt-5.6-sol in the Responses API reference. This PR lets codex-lb accept the canonical service_tier: "ultrafast" value in API-key policies and the dashboard, then preserve it through the existing Responses routing and logging paths.

Type of change

• fix: — bug fix (no behavior change beyond the bug)
• feat: — new user-facing feature or capability
• refactor: — internal refactor (no behavior change, no API change)
• docs: — documentation only
• chore: / ci: / build: — tooling, CI, packaging
• test: — test-only change
• Breaking change (also append ! after the type, e.g. feat!: or include BREAKING CHANGE: footer)

Linked issue: N/A — no matching issue or discussion was found.

OpenSpec

• This PR includes / updates an OpenSpec change
• Not applicable — bug fix that matches the existing spec
• Not applicable — docs / CI / chore only
• This PR touches a codex-faithful path (image pipeline, request/response
  shape, SSE framing, OAuth flow) and preserves upstream-equivalent behavior

Change directory: openspec/changes/archive/2026-08-14-support-ultrafast-service-tier/

Changes

• Accept and persist canonical ultrafast API-key enforcement values without normalizing them to priority.
• Add Ultrafast to the API-key create/edit controls, Zod schemas, translations, and regression coverage.
• Keep account eligibility tied to live or retained upstream catalog metadata. The bundled catalog does not grant Ultrafast access, and this change adds no pricing assumption.
• Document availability, failure behavior, and an example Responses request.

Simplicity

• New feature defaults to off or works with zero config
• No new required setup step (or maintainer approval via simplicity-budget-approved label)
• New setting(s) and why each can't be a default: None.
• README sections / .env.example / dashboard nav within budget (none changed)

Test plan

uv run pytest tests/unit/test_api_keys_service.py tests/unit/test_model_registry.py tests/unit/test_openai_requests.py tests/unit/test_proxy_load_balancer_refresh.py -q
# 379 passed, 3 skipped

uv run pytest tests/integration/test_api_keys_api.py -k ultrafast -q
# 1 passed

cd frontend
bun test src/features/api-keys/schemas.test.ts src/features/api-keys/components/api-key-create-dialog.test.tsx src/features/api-keys/components/api-key-edit-dialog.test.tsx
# 50 passed

uv run pre-commit run local-ci --hook-stage manual --all-files
# Frontend lint/typecheck/full coverage/build and backend architecture/Ruff/typecheck/unit/core integration passed.
# The PostgreSQL stage initially could not connect because the local database was not running.

make test-postgres
# 130 passed after starting the repository PostgreSQL 18 service

openspec validate support-ultrafast-service-tier --strict
# Passed before archive

openspec validate --specs --strict
# 49 passed, 8 failed due to pre-existing invalid requirements on upstream/main

OpenSpec verification completed with 7/7 tasks, 3/3 requirements, and 6/6 scenarios covered, with no critical, warning, or suggestion findings. The full main-spec validation remains blocked by existing upstream validation debt; the added api-keys requirement validates strictly, and the new requirements add no validation errors.

Screenshots / output

Before:

After:

Checklist

• Title is in Conventional Commits format (<type>(<scope>)?: <subject>).
• Linked the related issue / discussion above — N/A; no matching item was found.
• Added or updated tests covering the change.
• Ran uv run pre-commit run local-ci --hook-stage manual --all-files or the relevant make <target> subset locally.
• If touching specs: openspec validate --specs passes and /opsx:verify is clean — verification is clean; full spec validation has pre-existing upstream failures described above.
• Simplicity gates reviewed: the five simplicity rules (PRINCIPLES.md P1-P5).
• CHANGELOG is not edited by hand (release-please handles it).

Summary by CodeRabbit

• New Features

  • Added support for the Ultrafast service tier when creating and editing API keys.
  • Ultrafast requests are routed only through eligible accounts and preserved through API requests and billing records.
  • Added localized Ultrafast labels in the dashboard.

• Documentation

  • Updated troubleshooting and service-tier documentation with Ultrafast details.
  • Added contributor attribution.

• Tests

  • Expanded coverage for Ultrafast validation, routing, forwarding, persistence, and dashboard behavior.

[Komzpa]

@codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[Soju06]

Reviewed end to end — this is a very clean change. I traced every normalization site (_normalize_service_tier_alias_value, canonical_service_tier_value, the api-keys strict/lenient normalizers, and pricing's _uses_priority_tier) and they all use exact-match sets, so ultrafast correctly survives the legacy fast→priority alias everywhere. The decision to keep entitlement on live catalog metadata and not touch bootstrap or pricing is the right call and matches how the fallback in apply_enforced_service_tier_model_fallback actually behaves.

One small non-blocking note: repurposing test_api_key_enforces_service_tier_for_responses into the ultrafast test dropped the only end-to-end integration assertion that an enforced fast reaches upstream as priority (unit tests still cover both halves in test_create_key_normalizes_fast_service_tier_alias and test_responses_normalizes_fast_service_tier_to_priority_for_upstream). Parametrizing the integration test over both tiers would restore that coverage cheaply, either here or in a follow-up.

Thanks for the thorough OpenSpec artifacts and the before/after screenshots — this made the review straightforward.

[evan-choi]

Thank you for the thorough review. I merged the latest main to resolve the conflicts and parametrized the integration test to cover both fast → priority and Ultrafast end to end.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b2c694c0-8564-493b-974e-f31256794f71

📥 Commits

Reviewing files that changed from the base of the PR and between 6ed5f71 and adeb15d.

📒 Files selected for processing (16)

• .all-contributorsrc
• README.md
• app/modules/api_keys/schemas.py
• app/modules/api_keys/service.py
• frontend/src/features/api-keys/components/api-key-create-dialog.test.tsx
• frontend/src/features/api-keys/components/api-key-create-dialog.tsx
• frontend/src/features/api-keys/components/api-key-edit-dialog.test.tsx
• frontend/src/features/api-keys/components/api-key-edit-dialog.tsx
• frontend/src/features/api-keys/schemas.test.ts
• frontend/src/features/api-keys/schemas.ts
• frontend/src/i18n/locales/en.json
• frontend/src/i18n/locales/ko.json
• frontend/src/i18n/locales/zh-CN.json
• tests/integration/test_api_keys_api.py
• tests/unit/test_api_keys_service.py
• tests/unit/test_openai_requests.py

🚧 Files skipped from review as they are similar to previous changes (15)

• frontend/src/features/api-keys/components/api-key-edit-dialog.test.tsx
• frontend/src/features/api-keys/components/api-key-create-dialog.tsx
• frontend/src/i18n/locales/zh-CN.json
• tests/unit/test_api_keys_service.py
• frontend/src/i18n/locales/ko.json
• tests/unit/test_openai_requests.py
• README.md
• .all-contributorsrc
• frontend/src/features/api-keys/components/api-key-create-dialog.test.tsx
• frontend/src/features/api-keys/schemas.ts
• frontend/src/i18n/locales/en.json
• frontend/src/features/api-keys/schemas.test.ts
• frontend/src/features/api-keys/components/api-key-edit-dialog.tsx
• tests/integration/test_api_keys_api.py
• app/modules/api_keys/schemas.py

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds ultrafast service-tier support across API-key validation, dashboard controls, routing and Responses contracts, localization, documentation, and regression tests. Adds contributor attribution for Evan Choi and Sakthimaran.

Changes

Ultrafast service-tier support

Layer / File(s)	Summary
Service-tier contracts and specifications openspec/changes/archive/..., openspec/specs/..., docs/troubleshooting.md	Defines canonical ultrafast API-key behavior, entitlement-based routing, Responses forwarding, logging fields, and troubleshooting guidance.
Backend enforcement and compatibility validation app/modules/api_keys/..., tests/integration/..., tests/unit/...	Accepts ultrafast in API-key validation and verifies normalization, entitlement selection, upstream forwarding, metadata exclusion, and recorded service-tier values.
Dashboard controls and localization frontend/src/features/api-keys/..., frontend/src/i18n/locales/*	Adds ultrafast to frontend schemas and API-key dialogs, adds localized labels, improves edit-control labeling, and covers create and edit flows.

Contributor records

Layer / File(s)	Summary
Contributor attribution .all-contributorsrc, README.md	Adds contributor entries and contribution links for Evan Choi and Sakthimaran.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to adeb1

This change adds opt-in support for the Ultrafast service tier while preserving existing routing and policy behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant APIKeyAPI
  participant AccountCatalog
  participant UpstreamResponsesAPI
  participant RequestLog
  APIKeyAPI->>AccountCatalog: Check advertised ultrafast tier
  AccountCatalog-->>APIKeyAPI: Return eligible account
  APIKeyAPI->>UpstreamResponsesAPI: Forward service_tier: ultrafast
  UpstreamResponsesAPI-->>APIKeyAPI: Return actual and billable tier
  UpstreamResponsesAPI->>RequestLog: Record requested, actual, and effective tiers

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding support for the Ultrafast service tier.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[evan-choi]

@Soju06 The conflicts are resolved and feedback addressed. When you have a chance, could you please approve the pending workflows? Thank you!

[Soju06]

Thanks for the fast turnaround — the parametrized integration test restores the fast→priority end-to-end coverage and the added request-log assertions (requested/actual/billable all ultrafast) are a nice bonus. Verified the merge with current main locally: full unit suite and the service-tier integration selection are green. The fork CI run is approved and in flight; will merge once it confirms.

[evan-choi]

@Soju06, the branch was updated to resolve the latest conflicts, so the workflows are awaiting approval again. Could you please approve them when convenient? Thank you.