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 Usage.Service as the shared usage orchestration layer, exposes GET /usage through both the default Hono route and Effect HttpApi adapter, regenerates SDK/OpenAPI support, and adds 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 refreshes all authenticated usage providers and opens the detail dialog.
• /usage --used / /usage --remaining select the display mode for that dialog invocation.
• /usage --background refreshes all provider usage data and updates the shared sidebar resource 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 Usage.Service as the source of truth for usage orchestration, storage, cache reads/writes, usage.updated events, in-flight fetch dedupe, and response assembly.
• Adds GET /usage under both packages/opencode/src/server/routes/instance/usage.ts and the Effect HttpApi usage group/handler.
• 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 token-scoped usage snapshots with a 5-minute cache TTL.
• 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 in both route adapters.
• 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.
• Claude/OpenAI OAuth refresh persistence is handled by the usage service, with actionable Claude reauth errors when refresh is not recoverable.

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

• bun typecheck from packages/opencode
• bun typecheck from packages/sdk/js
• git diff --check
• bun test --timeout 120000 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 test/plugin/copilot-auth.test.ts test/server/httpapi-bridge.test.ts test/server/httpapi-provider.test.ts test/server/httpapi-sdk.test.ts test/cli/tui/editor-context.test.tsx

94 tests pass in the targeted usage/HttpApi/TUI suite.

Push hook: bun turbo typecheck passed, 12/12 tasks.

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.