Add OpenCode Go usage API support

[akshayprabhu200]

Summary

• use OpenCode Go's public GET /zen/go/v1/usage API for rolling, weekly, and monthly utilization
• accept OPENCODE_API_KEY from CodexBar settings, provider config, or the environment
• preserve local daily cost/model history while overlaying authoritative API windows
• preserve an existing cookie-derived Zen balance independently of the API windows
• retain the existing cookie-backed web path as a compatibility fallback

Why

OpenCode Go now exposes an authenticated public usage endpoint. CodexBar previously depended on local estimates or private web-session requests, even when a stable API key was available.

Behavior and compatibility

• Automatic, unscoped discovery tries local history, then the public API, then the legacy web path.
• Account-scoped discovery keeps the existing web/local ordering and uses the public API only as a fallback because an API key is not account-scoped.
• API failures in automatic mode fall through to existing sources; cancellation still propagates.
• Local cost and model history remain present when authoritative API utilization is overlaid.
• When both credentials exist, API quota windows stay authoritative while the cookie source contributes only its Zen balance.

Proof

• swift test --filter OpenCodeGo: 108 tests passed across 11 OpenCode Go suites on the initial implementation.
• Focused post-review compatibility run: 16 tests passed, including a combined API-key + cookie case that asserts API percentages, retained local daily history, and retained Zen balance.
• make check: passed after the review fix (formatting, SwiftLint, manifests, signing/package gates, and documentation links).
• Request-contract tests verify the exact endpoint, Bearer authorization, all three returned windows, unauthorized responses, source routing, configuration normalization, and local-history preservation.

No personal usage data or credentials are included in this change. A live authenticated endpoint capture is not attached because no OPENCODE_API_KEY is available in this environment; all included network proof is deterministic request-contract coverage.

Closes anomalyco/opencode#31084

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 13, 2026, 12:21 AM ET / 04:21 UTC.

ClawSweeper review

What this changes

The PR adds an OpenCode Go API-key usage source, integrates it with existing local and cookie-backed fallbacks, and documents the revised source order.

Merge readiness

⛔ Blocked until real behavior proof from a real setup is added - 4 items remain

Keep open. The branch is a coherent extension of the existing provider-routing design with no discrete source-level defect found, but it still lacks the requested after-fix authenticated runtime proof.

Priority: P2
Reviewed head: 2f42b83b74a77c546b9b1e5a97c450592103f1fb

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is coherent and well-covered at the request-contract level, but real authenticated behavior has not yet been demonstrated.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The supplied checks use deterministic mocked request contracts; add redacted output or logs from a real authenticated after-fix run before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The supplied checks use deterministic mocked request contracts; add redacted output or logs from a real authenticated after-fix run before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Current-main gap: Current main exposes only Auto and Web source modes and routes unscoped Auto from local history to web usage, so the requested API source is not already implemented. API dependency and implementation boundary: The branch directly calls OpenCode Go’s fixed HTTPS usage endpoint with a Bearer credential, making the external API contract an affirmative dependency of this PR. Fallback and configuration integration: The branch adds API routing before legacy web fallback while the shared environment resolver applies provider configuration into the fetch environment; the proposed descriptor uses that established path.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar’s provider layer selects local, API, or web usage sources and converts them into a common snapshot for the menu-bar app and CLI. This change adds an API-key source to OpenCode Go while retaining local cost history and cookie-derived fallback data.

flowchart LR
A[Local OpenCode history] --> D[OpenCode Go source selection]
B[Configured API key] --> C[Usage API]
C --> D
E[Browser or manual cookie] --> F[Legacy web usage]
F --> D
D --> G[Unified usage snapshot]
G --> H[CodexBar app and CLI]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The supplied checks use deterministic mocked request contracts; add redacted output or logs from a real authenticated after-fix run before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Merging changes automatic usage selection for enabled OpenCode Go setups with an ambient API key, so displayed quota windows may differ from the previous local/web result.
• Resolve merge risk (P2) - The new credential and upstream response contract have only mocked coverage; a redacted authenticated run is needed to establish real source selection, parsing, and fallback behavior.
• Complete next step (P2) - Await contributor-provided real authenticated proof; an automated repair lane cannot safely create or validate it without the contributor’s account.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Implementation and coverage delta	production +184/-19, tests +140/-11, docs +20/-13	The feature changes provider routing and credentials while adding substantial focused coverage for the new path.

Merge-risk options

Maintainer options:

1. Add authenticated runtime proof (recommended)
   Attach redacted terminal output or runtime logs showing the API source succeeds with all returned windows and that a legacy fallback remains usable.
2. Defer the new source
   Keep the existing local/web implementation if an authenticated account cannot provide proof of the public API contract.

Technical review

Best possible solution:

Retain the branch’s narrow fallback design and merge it only after a redacted authenticated run confirms the API windows and a fallback path on a real OpenCode Go account.

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

Not applicable as a bug reproduction: this is a new provider source. The branch has high-confidence mocked request-contract coverage, but no real authenticated after-fix execution.

Is this the best way to solve the issue?

Unclear until runtime proof is supplied. The descriptor-based source integration matches existing architecture, but the upstream API contract and real credential routing need a redacted authenticated trace.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a bounded provider integration whose remaining merge gate is proof rather than an urgent user-facing regression.
• merge-risk: 🚨 compatibility: Automatic source ordering can change displayed usage windows for existing OpenCode Go users with an ambient API key.
• merge-risk: 🚨 auth-provider: The PR introduces API-key resolution and Bearer authentication against a new provider endpoint.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The supplied checks use deterministic mocked request contracts; add redacted output or logs from a real authenticated after-fix run before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Current-main gap: Current main exposes only Auto and Web source modes and routes unscoped Auto from local history to web usage, so the requested API source is not already implemented. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift:93, 208016687098)
• API dependency and implementation boundary: The branch directly calls OpenCode Go’s fixed HTTPS usage endpoint with a Bearer credential, making the external API contract an affirmative dependency of this PR. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoUsageFetcher.swift:208, 2f42b83b74a7)
• Fallback and configuration integration: The branch adds API routing before legacy web fallback while the shared environment resolver applies provider configuration into the fetch environment; the proposed descriptor uses that established path. (Sources/CodexBarCore/Providers/ProviderEnvironmentResolver.swift:10, 208016687098)
• Focused automated coverage: The branch includes request-contract coverage for the endpoint, authorization header, returned windows, unauthorized responses, routing, and local-history/cookie-balance preservation. (Tests/CodexBarTests/OpenCodeGoUsageFetcherErrorTests.swift:47, 2f42b83b74a7)
• Proof remains mock-only: The PR body expressly says no authenticated API-key run is attached; its cited evidence is deterministic request-contract tests, so it does not demonstrate the after-fix upstream runtime path.
• Feature history: History shows the current local-first scoped routing and authoritative web-overlay behavior were established by focused OpenCode Go changes, making their authors useful reviewers for the new source ordering. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift:104, cf7b74913366)

Likely related people:

• steipete: Recent history includes the descriptor and credential-adapter refactors that define this integration boundary. (role: recent provider-descriptor architecture contributor; confidence: high; commits: c3895b816342, fc57a317cee4; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift, Sources/CodexBarCore/Providers/ProviderCredentialAdapter.swift)
• kiranmagic7: Introduced the OpenCode Go local-first and scoped-auto routing behavior that this PR extends. (role: source-routing contributor; confidence: high; commits: a05b0b9d64de, 828aebff9130; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift)
• Aaron: Added the current authoritative web-window overlay and local-history preservation behavior. (role: authoritative-overlay contributor; confidence: high; commits: cf7b74913366; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift, Tests/CodexBarTests/OpenCodeGoWebOverlayTests.swift)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach a redacted authenticated terminal or runtime trace showing API windows and source selection.
• Show a redacted fallback result when the API path is unavailable or unauthorized.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

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

History

Review history (7 earlier review cycles)

• reviewed 2026-08-12T07:51:40.538Z sha 55cdcad :: needs real behavior proof before merge. :: [P2] Preserve the cookie-sourced Zen balance after an API overlay
• reviewed 2026-08-12T08:13:02.720Z sha 55cdcad :: needs real behavior proof before merge. :: [P2] Keep the cookie-sourced Zen balance after API overlay
• reviewed 2026-08-12T08:30:43.558Z sha 801c317 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-12T08:51:21.530Z sha 801c317 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-12T09:07:37.419Z sha b839f54 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-13T03:09:37.314Z sha b839f54 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-13T03:54:48.839Z sha 2f42b83 :: needs real behavior proof before merge. :: none

[akshayprabhu200]

Fixed the failing macOS shard in signed commit b839f548.

The implementation intentionally adds OpenCode Go to the descriptor-derived API-key debug registry; the architecture gate's exact expected list had not been updated. The corrected gate now passes locally.

Verification:

• swift test --filter ProviderArchitectureGatekeeperTests — 38 tests passed
• swift test --filter OpenCodeGo — 108 tests passed

@clawsweeper re-review

— Akshay / Codex

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31581564049
• Updated: 2026-08-12T09:08:48.470Z

[akshayprabhu200]

Rebased this draft PR onto current upstream main (208016687) with no conflicts or scope changes. The rewritten head 2f42b83b7 is signed and GitHub-verified.

The prior aggregate failure was draft policy rather than a provider regression: required macOS tests were deferred while the PR was draft, so the aggregate correctly reported incomplete. GitHub now reports the rebased branch mergeable.

— Akshay / Codex

[akshayprabhu200]

Post-rebase verification is complete on head 2f42b83b7:

• lint: passed
• Linux x64: passed
• Linux ARM64: passed
• Linux musl: passed
• macOS shard 1/2: passed
• macOS shard 2/2: passed
• aggregate CI: passed
• GitGuardian: passed

GitHub reports the PR mergeable. ClawSweeper found no actionable implementation or security findings; its remaining gate is an authenticated OpenCode Go runtime trace, which requires contributor-provided account credentials and must be redacted before posting.

— Akshay / Codex