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 19, 2026, 12:55 AM ET / 04:55 UTC.

ClawSweeper review

What this changes

Adds an OpenCode Go API-key usage source, overlays its quota windows onto local cost history, preserves cookie-derived balance data, and documents the revised source order.

Merge readiness

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

Keep open: current main lacks the OpenCode Go API-key usage source, and the patch appears coherent with existing provider patterns. It still needs redacted authenticated after-fix runtime evidence before merge.

Priority: P2
Reviewed head: d467b54df38127f6154b865e6579c35e0976eb25

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is well-scoped and covered by focused tests, but fixture-only proof does not establish real authenticated behavior.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Deterministic tests cover the request contract, but the PR has no redacted authenticated after-fix run against the real OpenCode Go API; add terminal output or runtime logs and redact private data. 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: Deterministic tests cover the request contract, but the PR has no redacted authenticated after-fix run against the real OpenCode Go API; add terminal output or runtime logs and redact private data. 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: The current main revision has no OpenCode Go API endpoint, API-key environment key, or API strategy; the added capability is not already implemented or released. Provider implementation: The PR adds API source selection, config-to-environment projection, API-window overlay, and compatibility fallback behavior in the existing OpenCode Go provider descriptor. Credential transport boundary: The fetcher sends the resolved key only as a Bearer credential to the fixed HTTPS OpenCode endpoint; this is the affirmative dependency signal for the OpenCode API contract.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar’s provider pipeline combines local usage history, provider APIs, and browser-cookie web sources into one usage snapshot for the menu app and CLI. This PR adds OpenCode Go’s authenticated API as an authoritative quota source while retaining existing local and web paths.

flowchart LR
A[Provider settings and credentials] --> B[Source selection]
B --> D[OpenCode usage API]
B --> E[Cookie web usage]
C[Local SQLite history] --> F[Usage overlay]
D --> F
E --> F
F --> G[CodexBar app and CLI]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Deterministic tests cover the request contract, but the PR has no redacted authenticated after-fix run against the real OpenCode Go API; add terminal output or runtime logs and redact private data. 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) - The endpoint schema and real credential acceptance are covered only by fixtures; merging without a redacted authenticated run could leave real OpenCode Go users unable to retrieve usage despite green contract tests.
• Complete next step (P2) - The remaining merge gate is contributor-supplied authenticated runtime proof, which an automated repair worker cannot create safely.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	13 files; +345/-41 lines	The feature spans provider routing, credential configuration, API parsing, tests, and user documentation.
Production versus tests	production +186/-17; tests +139/-10	Most implementation growth is accompanied by focused provider and request-contract coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #3065
Summary: This PR is the implementation candidate for the open request to support OpenCode Go’s public usage API with an API key.

Members:

• canonical: OpenCode Go: support the public usage API with an API key #3065 - The issue describes the same endpoint, credential sources, fallback constraints, and explicitly identifies this PR as the proposed implementation.
• adjacent_distinct: fix: disclose local OpenCode Go quota estimates #2987 - That merged PR addresses disclosure of local estimates; this PR extends the same provider with an independent API source while preserving that behavior.

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

Merge-risk options

Maintainer options:

1. Add authenticated runtime proof (recommended)
   Before merge, provide a redacted run from the current PR head that shows the real API response is accepted and that existing fallback behavior remains usable.

Technical review

Best possible solution:

Retain the provider-scoped implementation, then add redacted authenticated terminal output or runtime logs from the rebased head showing successful API windows and safe fallback behavior before merge.

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

Not applicable as a bug report: this PR adds a new API-backed source. The missing real-world validation is an authenticated after-fix proof requirement, not a current-main bug reproduction.

Is this the best way to solve the issue?

Yes, subject to live proof: the provider descriptor reuses the existing credential projection and local/web overlay seams instead of creating a parallel provider path.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a bounded provider capability with limited blast radius but real user-facing quota accuracy implications.
• merge-risk: 🚨 compatibility: The patch changes the established local, cookie, and scoped source ordering that existing OpenCode Go users rely on.
• merge-risk: 🚨 auth-provider: The patch adds persisted and environment API-key resolution plus Bearer authentication to a third-party 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: Deterministic tests cover the request contract, but the PR has no redacted authenticated after-fix run against the real OpenCode Go API; add terminal output or runtime logs and redact private data. 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: The current main revision has no OpenCode Go API endpoint, API-key environment key, or API strategy; the added capability is not already implemented or released. (a32989c750e6)
• Provider implementation: The PR adds API source selection, config-to-environment projection, API-window overlay, and compatibility fallback behavior in the existing OpenCode Go provider descriptor. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift:121, d467b54df381)
• Credential transport boundary: The fetcher sends the resolved key only as a Bearer credential to the fixed HTTPS OpenCode endpoint; this is the affirmative dependency signal for the OpenCode API contract. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoUsageFetcher.swift:208, d467b54df381)
• Focused contract coverage: Added tests assert the endpoint path, Bearer header, all returned windows, unauthorized mapping, strategy ordering, and preservation of local history plus web balance. (Tests/CodexBarTests/OpenCodeGoUsageFetcherErrorTests.swift:47, d467b54df381)
• Prior behavior provenance: The existing authoritative web-overlay behavior dates to a merged OpenCode Go fix, providing the compatibility baseline this PR extends. (Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift:223, cf7b74913366)
• Proof status: The PR body explicitly provides deterministic mocked request-contract tests and says that no live authenticated OpenCode Go capture is attached; this does not demonstrate after-fix behavior against the real API. (d467b54df381)

Likely related people:

• steipete: Merged the current local-estimate disclosure behavior and has extensive recent history across the OpenCode Go provider path. (role: recent area contributor; confidence: high; commits: 5dc260879ee3, 2af39f514e8f; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift, Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoUsageSnapshot.swift)
• Aaron: Introduced the web quota-window overlay that this change adapts for API responses. (role: introduced authoritative-overlay behavior; confidence: high; commits: cf7b74913366; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoProviderDescriptor.swift)
• akshayprabhu200: Has prior merged OpenCode Go work on current main in addition to this proposed API implementation. (role: adjacent area contributor; confidence: medium; commits: 1c4b04d82727; files: Sources/CodexBarCore/Providers/OpenCodeGo/OpenCodeGoUsageFetcher.swift)

Rank-up moves

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

• Add redacted authenticated terminal output or runtime logs from the current head showing rolling, weekly, and monthly API windows.
• Update the PR body after adding proof; if no fresh review appears, ask a maintainer to comment @clawsweeper re-review.

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 (8 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
• reviewed 2026-08-13T04:21:11.659Z 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

[akshayprabhu200]

Rebased onto current main (a32989c75) in signed commits through d467b54df.

The integration preserves #2987’s estimated-confidence and manual-token behavior while adding the authenticated API overlay and retaining Zen balance. The original worktree’s unrelated local edits were not touched. SwiftFormat and git diff --check pass; affected production sources compile cleanly. Current-head CI is the authoritative full validation.

Tracking issue: #3065.

— Akshay / Codex