feat(usage): unified usage tracking with auth refresh (#9281)

[CasualDeveloper]

Summary

Adds built-in usage tracking for OAuth-authenticated providers: Anthropic Claude, GitHub Copilot, and OpenAI ChatGPT.

This PR implements the shared GET /usage endpoint, generated SDK support, and terminal TUI surfaces. In the terminal TUI, users can view usage through a /usage detail dialog and a sidebar Usage section. /usage is the detailed all-provider view, while the sidebar remains configurable as a glance view.

Web/app UI is intentionally left for a follow-up; client.usage.get(...) is available for that future integration.

Closes #9281
Related: #768
Supersedes #6905, #7837
Alternate implementation to #9301

Behavior

• /usage fetches all authenticated usage providers and opens the detail dialog.
• /usage --used / /usage --remaining select the display mode for that dialog invocation.
• /usage --refresh refreshes all provider caches and updates the sidebar without opening the dialog.
• tui.show_usage_provider_scope applies to the sidebar only (current / all).
• tui.show_usage_value_mode controls the initial used/remaining display mode.
• Sidebar refreshes after assistant turns and after /usage fetches by explicitly refetching the shared usage resource.

Core

• Adds GET /usage under packages/opencode/src/server/routes/instance/usage.ts.
• Adds provider fetchers under packages/opencode/src/usage/providers/ for Anthropic Claude, GitHub Copilot, and OpenAI ChatGPT.
• Normalizes provider responses into shared usage snapshot schemas with rate-limit windows, reset times, credits/quota, and plan type.
• Keeps a 5-minute usage snapshot cache with in-flight request deduping.
• Publishes usage.updated when stored snapshots change.
• Regenerates OpenAPI and JavaScript SDK output.

Auth

• Extends the plugin auth contract with optional OAuth follow-up support (AuthOAuthFollowup).
• Adds provider.oauth.followup.authorize / provider.oauth.followup.callback server endpoints.
• Copilot usage tracking is opt-in: main Copilot login completes first, then CLI/TUI asks whether to run the extra GitHub device flow needed for copilot_internal/user usage data.
• Follow-up credentials are merged into the existing OAuth auth entry.

TUI

• Adds a scrollable /usage dialog with provider-specific windows, progress bars, reset labels, and credits/quota details.
• Adds an internal sidebar Usage feature-plugin.
• Dialog reset times are locale-aware absolute values; sidebar reset labels stay compact/relative.
• End-of-turn refresh is throttled and only emits toasts when crossing warning thresholds (80/90/95%).

Follow-up

• Add web/app UI using the same GET /usage endpoint, likely as a Usage tab in the existing top-right status popover rather than a custom side panel.

Verification

• ./script/generate.ts
• bun turbo typecheck
• bun --cwd packages/opencode test --timeout 600000 test/plugin/copilot-auth.test.ts test/server/usage.test.ts test/server/usage-copilot.test.ts test/cli/tui/usage-command.test.ts test/cli/tui/usage-format.test.ts test/cli/tui/usage-toast.test.ts

48 tests pass in the targeted usage suite.

AI Assistance

• Tools: OpenCode + GPT-5.x family models
• Review: Human-guided and reviewed throughout

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential Duplicates Found:

1. PR #9301: feat(tui): add /usage command and sidebar usage section

• feat(tui): add /usage command and sidebar usage section #9301
• Why related: This PR directly addresses the same /usage command and sidebar usage panel features. The current PR (9545) explicitly mentions it as an "Alternate implementation to feat(tui): add /usage command and sidebar usage section #9301", indicating significant overlap in functionality.

2. PR #6905: feat: display Anthropic and OpenAI OAuth usage in status dialog and sidebar

• feat: display Anthropic and OpenAI OAuth usage in status dialog and sidebar #6905
• Why related: Similar goal of displaying provider usage data in the sidebar and dialog. The current PR supersedes this one (as noted in the description).

3. PR #9069: feat: Multi-Account OAuth Rotation with Settings UI and CLI Enhancements

• feat: Multi-Account OAuth Rotation with Settings UI and CLI Enhancements #9069
• Why related: Related to auth token management and OAuth handling, which overlaps with the token refresh and auth flow changes in the current PR.

[Copilot]

Pull request overview

This PR introduces a unified /usage API as the single source of truth for usage/rate-limit snapshots across OpenAI ChatGPT (Codex), GitHub Copilot, and Anthropic Claude, and wires it into the TUI (dialog + sidebar + toast warnings) with provider-specific auth handling (including optional Copilot “usage token” capture and Claude refresh-on-401).

Changes:

• Add core usage module + provider fetchers with caching, schema validation, and usage.updated bus events.
• Add GET /usage server route (provider filter + refresh + slash-command parsing) and regenerate SDK/OpenAPI types/clients.
• Add TUI integrations: /usage command + dialog, sidebar usage panel, and automatic refresh/toast warnings after assistant turns; extend OAuth schema with optional usage token.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/sdk/openapi.json	Adds /usage endpoint + usage.updated event + OAuth usage field to OpenAPI schema.
packages/sdk/js/src/v2/gen/types.gen.ts	Regenerates SDK types for /usage, event, and OAuth usage?: string.
packages/sdk/js/src/v2/gen/sdk.gen.ts	Regenerates JS SDK client with client.usage.get(...).
packages/plugin/src/index.ts	Extends plugin-facing OAuth result typing with optional usage token.
packages/opencode/src/auth/index.ts	Extends persisted OAuth auth schema with optional usage token.
packages/opencode/src/usage/types.ts	Defines zod schemas + TS types for usage snapshots.
packages/opencode/src/usage/registry.ts	Defines supported usage providers and their auth requirements.
packages/opencode/src/usage/store.ts	Adds usage cache storage, usage.updated bus event, and auth/provider helpers.
packages/opencode/src/usage/providers/openai.ts	Implements ChatGPT usage fetcher (/backend-api/wham/usage) + normalization.
packages/opencode/src/usage/providers/github-copilot.ts	Implements Copilot usage fetcher (copilot_internal/user) + token fallback parsing.
packages/opencode/src/usage/providers/anthropic.ts	Implements Claude OAuth usage fetcher + refresh-on-expiry/401 flow.
packages/opencode/src/usage/index.ts	Exposes usage module API (Usage.*) and provider fetchers.
packages/opencode/src/usage/command.ts	Adds /usage command parsing and “current vs all” provider resolution logic.
packages/opencode/src/server/usage.ts	Adds GET /usage route: filtering, refresh behavior, concurrency dedupe, cached fallback errors.
packages/opencode/src/server/instance.ts	Registers /usage routes in server instance router.
packages/opencode/src/plugin/github-copilot/copilot.ts	Updates Copilot auth flow (optional second device flow for usage token) + service token exchange + header fixes.
packages/opencode/src/config/tui-schema.ts	Adds TUI config options for usage scope + used/remaining display mode.
packages/opencode/src/cli/cmd/tui/plugin/internal.ts	Registers new sidebar usage internal plugin.
packages/opencode/src/cli/cmd/tui/feature-plugins/sidebar/usage.tsx	Adds sidebar Usage panel rendering + refetch on events/turn completion.
packages/opencode/src/cli/cmd/tui/component/usage-data.ts	Adds TUI-side usage data shapes.
packages/opencode/src/cli/cmd/tui/component/usage-client.ts	Adds /usage client/resource + event-driven refetch logic.
packages/opencode/src/cli/cmd/tui/component/usage-format.ts	Adds formatting helpers (labels, bars, resets, credits).
packages/opencode/src/cli/cmd/tui/component/usage-toast.ts	Adds threshold-crossing detection + refresh/backoff helpers for toast warnings.
packages/opencode/src/cli/cmd/tui/component/dialog-usage.tsx	Adds /usage dialog UI with used/remaining toggle.
packages/opencode/src/cli/cmd/tui/component/dialog-command.tsx	Adds slashDescription field used for slash-command UI descriptions.
packages/opencode/src/cli/cmd/tui/component/prompt/index.tsx	Implements built-in /usage command handling + post-turn refresh/toast logic + submission refactor.
packages/opencode/test/server/usage.test.ts	Adds server+fetcher tests for cache behavior, parsing, provider filtering, and error fallback.
packages/opencode/test/server/usage-copilot.test.ts	Adds Copilot fallback behavior test when usage endpoint fails.
packages/opencode/test/plugin/copilot-auth.test.ts	Adds tests for Copilot dual device-flow + optional usage polling + service token behavior.
packages/opencode/test/cli/tui/usage-toast.test.ts	Adds tests for warning thresholds, refresh cooldown/backoff, and dedupe/eviction.
packages/opencode/test/cli/tui/usage-format.test.ts	Adds tests for formatting/labeling and used vs remaining display conversion.
packages/opencode/test/cli/tui/usage-command.test.ts	Adds tests for /usage command parsing and conflict validation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[CasualDeveloper]

Fork updated to sync with dev (as of cb1a500).