feat(usage-api): add toggle to query additional usage, and add pooled usage to /v1/usage

[huzky-v]

Summary

Adds configurable API-key usage exposure in one reviewable branch:

• account_pool_usage for /v1/usage
• usage_sections on API keys so admins can choose exposed usage sections
• request-log backfill for newly added API-key limit rules
• hide_upstream_quota_from_api_keys so API-key clients can be prevented from seeing owner/upstream quota state

This branch absorbs #890 and #898, and keeps the earlier folded #748 work, so #518 and #826 land through one API-key usage/quota PR.

Fixes #518.
Closes #826.

Folded PRs

• Surviving PR: feat(usage-api): add toggle to query additional usage, and add pooled usage to /v1/usage #832
• Folded into this branch: fix(api-keys): backfill new limit usage #748, fix(api-keys): seed added limits from existing usage #890, feat(api-keys): hide upstream quota for key clients #898
• Current head: 940ea651fcac90625dfc853b075e67155a8b27dd

OpenSpec

• openspec/changes/add-account-pool-usage-to-v1-usage/
• openspec/changes/backfill-api-key-limit-current-usage/
• openspec/changes/hide-upstream-quota-from-api-keys/

Changes

• Add usage_sections to API keys so clients can expose upstream_limits, account_pool_usage, or both.
• Add account_pool_usage to /v1/usage by reusing pooled-credit computation.
• Keep scoped-empty account pools empty instead of falling back to global account capacity.
• Backfill newly added API-key limits from successful request-log usage in the active lookback window.
• Preserve explicit resetUsage behavior and per-request truncated microdollar accounting.
• Add the API-key create/edit UI for usage section selection.
• Add the dashboard setting and Settings UI toggle for hiding upstream quota from API-key clients.
• Suppress /v1/usage upstream limits and API-key proxy quota headers when the new setting is enabled.
• Rebase onto current main and merge the API-key usage/quota-visibility migration head with the reauth account-status head.

Validation

uv run pytest tests/unit/test_api_keys_service.py tests/unit/test_api_keys_repository.py tests/unit/test_api_keys_validation_error.py tests/unit/test_pooled_credits.py tests/integration/test_api_keys_api.py tests/integration/test_v1_usage.py tests/integration/test_proxy_compact.py tests/integration/test_settings_api.py tests/integration/test_settings_audit_changed_fields.py -q
uv run pytest tests/unit/test_db_migrate.py tests/unit/test_db_rate_limiter.py tests/integration/test_migrations.py -q
uv run ruff check app/modules/api_keys app/modules/proxy/api.py app/modules/settings tests/unit/test_api_keys_service.py tests/unit/test_api_keys_repository.py tests/integration/test_v1_usage.py tests/integration/test_proxy_compact.py tests/integration/test_settings_api.py
uv run ty check app/modules/api_keys app/modules/proxy/api.py app/modules/settings
uv run openspec validate add-account-pool-usage-to-v1-usage --strict
uv run openspec validate backfill-api-key-limit-current-usage --strict
uv run openspec validate hide-upstream-quota-from-api-keys --strict
make migration-check
cd frontend && bun run lint
cd frontend && bun run test -- src/features/settings/payload.test.ts src/features/api-keys/schemas.test.ts src/features/api-keys/components/usage-sections-multi-select.test.tsx src/features/settings/schemas.test.ts src/features/settings/components/routing-settings.test.tsx src/features/settings/components/session-settings.test.tsx src/features/settings/components/totp-settings.test.tsx
cd frontend && bun run typecheck

Local result on 940ea651fcac90625dfc853b075e67155a8b27dd: backend/API pytest focus passed (204 tests); migration pytest focus passed (55 passed, 3 skipped); make migration-check passed with current_revision=20260604_010000_merge_api_key_usage_and_reauth_heads; seven focused frontend test files passed (59 tests); ruff, ty, OpenSpec strict validation, frontend lint, and frontend typecheck passed.

GitHub CI is green for the new head. Current-head Codex review has been requested and is still pending, so codex: ok is intentionally not set yet.

[Soju06]

@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.

[huzky-v]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 63d756ca23

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[huzky-v]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 561c21dd68

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[huzky-v]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aaea5e32ff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[huzky-v]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[huzky-v]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e04b83e523

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[huzky-v]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Soju06]

Hermes owner-review blocker (current main drift / DB migration graph): this PR's migration was authored on the old usage-raw head, but main now has 20260601_000000_merge_relative_availability_and_usage_raw_heads. A local merge probe against current origin/main merges textually, but leaves two Alembic heads and fresh DB upgrade fails.

Evidence after git fetch origin main && git merge --no-commit --no-ff origin/main:

heads= ['20260527_000000_add_api_key_usage_sections', '20260601_000000_merge_relative_availability_and_usage_raw_heads']
policy_violations= ('alembic_head_count_invalid expected=1 actual=2 heads=20260527_000000_add_api_key_usage_sections,20260601_000000_merge_relative_availability_and_usage_raw_heads',)

And the official migration entrypoint fails on a fresh DB:

uv run python -m app.db.migrate --db-url sqlite+aiosqlite:////tmp/pr832-current-main-upgrade.db upgrade
...
alembic.util.exc.CommandError: Multiple head revisions are present for given argument 'head'

Please rebase/update onto current main and add/adjust the migration merge node (or reparent this migration) so the Alembic graph has a single head again. After that, re-run the focused /v1/usage/API-key tests and migration upgrade check.

[Soju06]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: 8578e18051

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Komzpa]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: ddd54e2b2c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

This pull request has been automatically marked as stale because it has had no activity for 7 days.

It will be closed in 23 more days unless there is new activity.

If this is still relevant, please:

• Rebase or push an update if the branch drifted
• Address pending review feedback if there is any
• Leave a short comment confirming it is still being worked on

Thanks for the contribution 🙏