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

[huzky-v]

Summary

Add account_pool_usage (primary/secondary remaining percent) to /v1/usage, and add a usage_sections field to API keys so admins can toggle which sections are exposed to clients.

This rebuilt branch also folds #748, so API-key usage section persistence and new-limit request-log backfill move as one API-key usage feature.

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
• Base: main
• Current head: f0c54e194a6f3355f2591aa47771f27e2201d3ad

OpenSpec

• Change directory: openspec/changes/add-account-pool-usage-to-v1-usage/
• Additional usage change directory: openspec/changes/backfill-api-key-limit-current-usage/

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.
• Add the API-key create/edit UI for usage section selection.
• 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.

Test plan

uv run pytest tests/unit/test_api_keys_service.py -q
uv run pytest tests/integration/test_api_keys_api.py -q
uv run pytest tests/integration/test_v1_usage.py -q

Screenshots

The example /v1/usage API output when both sections are enabled.

The API configuration page added this.

[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. 🚀

ℹ️ 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]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ 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]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

codex-lb/app/modules/api_keys/service.py

Line 475 in f0c54e1

needs_all_accounts = any(not assigned_ids for assigned_ids in assigned_ids_by_key.values())

Keep scoped empty pools from falling back to all accounts

When a key remains scoped but its assigned rows are gone (for example, after the assigned account is deleted), assigned_ids_by_key[row.id] is empty even though account_assignment_scope_enabled is still true. This makes the dashboard list path load all accounts here, and _compute_pooled_credits() treats an empty assigned_account_ids list as an unscoped all-account pool, so /api/api-keys/ can show pooled credit values from unrelated accounts for a key that should have no usable pool. Use the scope flag when deciding whether an empty assignment list means “all accounts” or “no scoped accounts.”

ℹ️ 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: the current-main code/test path is mostly healthy, but I still see one scoped-pool correctness bug plus OpenSpec/merge-gate issues before this should merge.

Evidence:

app/modules/api_keys/service.py:472-490
list_keys() derives assigned_ids_by_key only from live assignment rows, then sets needs_all_accounts = any(not assigned_ids). For a key that still has account_assignment_scope_enabled=true but whose assigned account rows are gone, assigned_ids_by_key[row.id] is empty, so the pooled-credit fetch falls back to all accounts.

app/modules/api_keys/service.py:350-353
_compute_pooled_credits() also interprets an empty assigned_account_ids list as "use every account in all_accounts", so the dashboard/list pooled credits can show global pool capacity for a still-scoped key whose scoped pool is empty. The /v1/usage path avoids this by passing account_assignment_scope_enabled separately; list_keys() needs the same distinction.

openspec/changes/add-account-pool-usage-to-v1-usage/specs/account-pool-usage-v1-usage/spec.md:33-37
Scenario says when usage_sections excludes account_pool_usage, the response does NOT include account_pool_usage.

openspec/changes/add-account-pool-usage-to-v1-usage/specs/account-pool-usage-v1-usage/spec.md:55-59
A later scenario says the same excluded section is present as account_pool_usage: null. The implementation/tests follow the null contract: app/modules/proxy/api.py:668-688, app/modules/proxy/schemas.py:215-224, tests/integration/test_v1_usage.py:302-320.

openspec/changes/add-account-pool-usage-to-v1-usage/tasks.md:1-59
Every task is still unchecked, including implemented backend/frontend/test work.

Issue #518 is explicitly referenced by openspec/changes/backfill-api-key-limit-current-usage/proposal.md, but the PR body currently has no Fixes/Closes/Resolves #518 wording (or a partial-scope statement), which is a repo merge-gate expectation for issue-covering PRs.

Requested fix:

1. Preserve scoped-empty semantics in ApiKeysService.list_keys() / pooled-credit computation. A scoped key with no surviving assignments should return no pool capacity, not global capacity. Add a regression for account_assignment_scope_enabled=true with empty assignment rows.
2. Make the OpenSpec contract single-source-of-truth: consistently require either null for disabled sections or omission, then align implementation/tests if needed.
3. Check off completed tasks, or leave only genuinely pending tasks unchecked.
4. Add the proper Fixes #518 / Closes #518 wording if this PR fully resolves it, or explicitly state partial coverage.

For context, the previous migration-graph blocker appears resolved on my local current-main probe: merging origin/main textually succeeded, Alembic reports a single head 20260601_010000_add_api_key_usage_sections, fresh DB upgrade completed, and focused usage/API-key tests passed (90 passed).