Copilot Business (token-based billing): surface GitHub AI credit usage — card is blank because every quota reports unlimited/zero-entitlement

[KSEGIT]

Summary

On a Copilot Business seat with token-based billing, the Copilot card renders no usage at all — just the plan label. This is currently correct behaviour (it's the guard added for #1258 to avoid a fake "0% used"), but it leaves the card empty even though GitHub does expose real consumption for these accounts — just on a different endpoint than the one CodexBar reads.

Request: add GitHub AI credit usage as a Copilot data source, so token-based-billing accounts get a real metric instead of a blank card.

Why the card is blank today

GET /copilot_internal/user on a Business token-billing seat returns every quota as unlimited with zero entitlement (redacted, live, v0.46.0):

"quota_snapshots": {
  "premium_interactions": {
    "unlimited": true, "entitlement": 0, "remaining": 0,
    "percent_remaining": 100.0, "quota_remaining": 0.0,
    "credits_used": 31,            // <-- real usage, currently not decoded
    "token_based_billing": true, "overage_permitted": true
  },
  "chat":        { "unlimited": true, "entitlement": 0, "credits_used": 0 },
  "completions": { "unlimited": true, "entitlement": 0, "credits_used": 0 }
},
"copilot_plan": "business",
"access_type_sku": "copilot_for_business_seat_quota",
"token_based_billing": true,
"quota_reset_date": "2026-09-01"

That payload is dropped on purpose, in two places:

• CopilotUsageFetcher.swift:149 — guard !snapshot.unlimited else { return nil }
• CopilotUsageFetcher.swift:86 — usage.tokenBasedBilling || hasUnlimitedQuota → primary = nil, secondary = nil

No complaint about those guards — a percent bar genuinely is meaningless here. The gap is that there's no alternative metric for this account class.

What GitHub actually exposes

GET /orgs/{org}/settings/billing/ai_credit/usage returns per-model AI credit consumption (redacted, live):

{
  "timePeriod": { "year": 2026, "month": 8 },
  "organization": "<ORG>",
  "usageItems": [
    { "product": "Copilot", "sku": "Copilot AI Credits",  "model": "Code Review model",
      "unitType": "ai-credits", "pricePerUnit": 0.01, "grossQuantity": 31.13, "netAmount": 0.0 },
    { "product": "Copilot", "sku": "Copilot Cloud Agent", "model": "Coding Agent model",
      "unitType": "ai-credits", "pricePerUnit": 0.01, "grossQuantity": 49.97, "netAmount": 0.0 }
  ]
}

31.13 + 49.97 = 81.10, which matches the "81 / 6,000 AI credits" shown on the org's Billing → AI usage page exactly. So the numerator is available over the REST API, with a per-model breakdown that's arguably nicer than a single bar.

Caveat worth stating up front: the 6,000 denominator is not in that response. I probed /orgs/{org}/settings/billing/usage and /orgs/{org}/copilot/billing too — neither carries the included-credit entitlement. So either the bar needs a user-supplied entitlement, or this ships as a credits-consumed + spend figure without a denominator.

Auth / scope — the blocker from #1276

#1276 was closed with budget windows (#1273), and the reason AI credits were deferred was that the auth and account-scope model needed maintainer sign-off. One data point that may make this cheaper than expected:

The org call above succeeded with a classic token carrying only gist, read:org, repo, workflow — no admin:org, no manage_billing:*. (The authenticating account is an owner of the org, so org-ownership may be doing the work rather than the scopes; I haven't isolated which.)

CodexBar's device flow currently requests read:user only, so this would still mean widening the requested scope — that's the real cost, and it's a genuine UX tradeoff, not a free win. Whether read:user alone suffices for an org owner is the open question I couldn't answer without minting a separate token.

For reference, the user-scope sibling GET /users/{username}/settings/billing/ai_credit/usage 404'd for me and asks for the user scope, so per-user attribution likely needs its own decision.

Proposal

Rough shape, smallest first:

1. Decode credits_used from the snapshots CodexBar already fetches. No new endpoint, no new scope, no cookies — the field is sitting in the existing /copilot_internal/user response and CopilotUsageModels.swift simply doesn't have a CodingKey for it. On this account that alone would turn a blank card into "31 credits used · resets 1 Sep". Happy to split this into its own issue if you'd prefer it decoupled from the org work.
2. Optional org AI-credit source behind a setting, mirroring how "Budget extras" is already opt-in — call /orgs/{org}/settings/billing/ai_credit/usage, show credits consumed and net spend, optionally broken down per model.
3. Optional user-entered entitlement (e.g. 6,000) to turn (2) into a real progress bar, since GitHub won't give the denominator.

I'd be glad to take a swing at (1) as a PR with fixtures if it's a shape you'd accept — it's contained to the model decoder plus the fetcher's token-billing branch.

Environment

• CodexBar 0.46.0 (build 110, commit 7760f349)
• macOS 26.5.2 (25F84)
• Copilot Business seat, token_based_billing: true, org-owned

Related

• Copilot Business token-based billing shows 0% used instead of actual usage #1258 — added the guards that (correctly) blank the card for this payload
• Add support for new GitHub Copilot usage-based billing #1276 — usage-based billing request; closed via Add optional Copilot budget extras #1273 with budget windows, AI credits deferred on auth/scope

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 3, 2026, 6:38 PM ET / 22:38 UTC.

Summary
Keep open: current main deliberately leaves token-billed Copilot seats plan-only and does not decode credits_used; the remaining work is a new provider-display and authorization/privacy decision, not a regression repair. The linked draft PR is a useful parsing slice but intentionally does not make the requested metric visible.

Reproducibility: yes. —source-reproducible: current fixtures and fetcher logic show token-billed zero-entitlement snapshots become no visible usage windows, although this read-only review did not execute the test suite.

Root-cause cluster
Relationship: canonical
Canonical: #2593
Summary: This issue is the canonical product-direction item for a truthful token-billed Copilot credit metric; the linked PR is only a partial parser slice.

Members:

• partial_overlap: Decode Copilot credits_used for token-billed seats (#2593) #2613 - It decodes the raw counter but intentionally leaves the requested visible metric and authorization direction unresolved.
• adjacent_distinct: Copilot Business token-based billing shows 0% used instead of actual usage #1258 - It fixed the misleading fake 0% display; this issue seeks a truthful alternative metric after that safeguard.
• partial_overlap: Add support for new GitHub Copilot usage-based billing #1276 - It requested usage-based billing support, but its merged budget follow-up did not establish the token-billed credit-display contract requested here.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Maintainer decision needed

Question	Recommendation
Should CodexBar show an absolute credits_used count from the existing Copilot response for token-billed seats, and should organization AI-credit aggregation remain a separate opt-in capability?	Approve an absolute-credit first slice: Display the already-returned credits_used value and reset date without a percentage bar or additional authorization, then evaluate organization billing separately.

Why: The existing percentage abstraction cannot truthfully represent a zero-entitlement plan, while organization-level billing would change the GitHub authorization and privacy boundary; source inspection cannot choose those user-facing semantics.

Next step
A maintainer must choose the user-visible absolute-credit semantics and organization-billing authorization boundary before the open parser-only PR can become a complete solution.

Security
Needs attention: The proposed organization billing source would alter Copilot authorization and expose billing data, so its scope and opt-in privacy boundary need explicit review.

Review details

Best possible solution:

First choose whether the existing response’s absolute credits_used value should appear as a non-percentage Copilot metric with its reset date; treat any organization AI-credit aggregation as a separate opt-in feature with explicit authorization and privacy boundaries.

Do we have a high-confidence way to reproduce the issue?

Yes—source-reproducible: current fixtures and fetcher logic show token-billed zero-entitlement snapshots become no visible usage windows, although this read-only review did not execute the test suite.

Is this the best way to solve the issue?

Unclear: decoding and displaying an absolute credit count is the narrowest no-new-scope path, but a maintainer must first approve its label and presentation; the organization endpoint proposal is a separate authorization-sensitive feature.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• An organization AI-credit integration may require broader OAuth or organization billing access and expose organization billing data; it needs an explicit opt-in, privacy, and failure-mode decision before implementation.

Codex review notes: model internal, reasoning high; reviewed against 47e1d0426236.

Label changes

Label changes:

• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P3: This is a useful but optional provider-display feature that needs product and authorization direction rather than an urgent repair.
• impact:ux-friction: Affected Copilot Business users receive a plan-only card despite available consumption data, but the app remains usable.

Evidence reviewed

Security concerns:

• [low] Require explicit billing-data authorization design — docs/copilot.md:23
  Current Copilot device flow requests only read:user; any organization billing access must define scopes, organization selection, storage, and safe failure behavior before implementation.
  Confidence: 0.93

What I checked:

• Current implementation intentionally suppresses the card metric: Current main sets both usage windows to nil when token-based billing or an unlimited quota is present, so the reported plan-only card remains the observable behavior. (Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift:86, 47e1d0426236)
• The response model has no credits-used field: QuotaSnapshot decodes entitlement, remaining, percentage, quota ID, and unlimited status, but its coding keys do not include credits_used. (Sources/CodexBarCore/CopilotUsageModels.swift:58, 47e1d0426236)
• Current regression coverage codifies the blank state: The token-billing fixture asserts that zero-entitlement Business snapshots resolve to no premium or chat snapshot, confirming this is deliberate current behavior rather than an accidental display failure. (Tests/CodexBarTests/CopilotUsageModelsTests.swift:441, 47e1d0426236)
• Existing authorization boundary is narrow: Copilot documentation says device flow requests read:user, while the existing optional budget feature uses a separate cookie-backed, opt-in path; organization billing access therefore needs an explicit product and privacy decision. (docs/copilot.md:23, 47e1d0426236)
• Feature provenance: Blame attributes the current token-billing suppression branch to the v0.47.0 release snapshot, establishing that this behavior is present in the shipped baseline and remains unchanged in the inspected source. (Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift:86, 6a16c23313a7)
• Release and main check: The v0.47.0 tag is an ancestor of current main, and its Copilot fetcher contains the same token-billing plan-only branch; current main therefore has not already implemented the requested display. (Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift:86, 6a16c23313a7)

Likely related people:

• Peter Steinberger: Current source blame attributes the token-billing placeholder behavior and fetcher branch to the v0.47.0 release snapshot, and Peter authored the current main tip. (role: current-main feature-history contributor; confidence: medium; commits: 6a16c23313a7, 47e1d0426236; files: Sources/CodexBarCore/CopilotUsageModels.swift, Sources/CodexBarCore/Providers/Copilot/CopilotUsageFetcher.swift)
• Quicksaver: Authored the merged optional Copilot budget-extras work, which established the existing opt-in billing-data pattern relevant to any future credit source. (role: adjacent provider-data contributor; confidence: medium; commits: 7a703369f453; files: docs/copilot.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.