Add Charm Hyper balance provider

[akshayprabhu200]

Summary

• add Charm Hyper as an opt-in API-key provider using HYPER_API_KEY, saved provider keys, and token accounts
• fetch the documented GET https://hyper.charm.land/v1/credits endpoint and show the result as a Hypercredit balance in the menu bar, menu card, and CLI
• register Hyper across provider configuration, diagnostics, widgets, icons, documentation, and generated provider counts
• cover request construction, response validation, credential handling, menu-bar/card presentation, CLI output, and icon availability

Context

Relates to #2318 and credits the original direction in #2379.

This draft differs from #2379 in two reviewed behavior details:

• it uses Charm's maintained https://hyper.charm.land/v1/credits contract instead of the incorrect api.hyper.charm.land host
• it renders Balance: <amount> HC instead of treating a balance as Cost: <amount> / 0

The API contract and HYPER_API_KEY convention are corroborated by Charm's maintained pi Hyper provider and Crush provider documentation.

The implementation deliberately does not inspect browser cookies or reuse OAuth refresh tokens. It only sends an explicitly configured API key to Charm Hyper.

Hypercredit unit semantics

Charm currently documents 1 Hypercredit = 5¢ USD. This provider keeps the API's native HC balance authoritative, matching how CodexBar preserves other provider-specific credit units. It does not relabel HC as USD or hard-code a conversion into the usage snapshot, because the published rate is product pricing and may change independently of the API contract. A future presentation-only USD equivalent could be shown as approximate without replacing the HC value.

Validation

• DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer make check
• git diff --check
• make test was invoked locally, but test discovery cannot start because the installed Xcode 15.3 provides Swift 5.10 while this package requires Swift 6.2; the draft PR's Xcode 26 macOS CI is the authoritative full-suite run

Redacted live behavior proof

After the implementation was complete, a temporary API key was supplied only through hidden process input and used for one real request against the exact endpoint configured by this provider. The credential, authorization header, team identifier, and account identity were not logged or retained.

LIVE_PROOF provider=hyper endpoint=/v1/credits http=200
Balance: 90 HC

This establishes that the production endpoint accepts the documented bearer credential, returns the numeric balance contract parsed by HyperUsageFetcher, and produces the HC balance presentation covered by the focused CLI/menu regression tests. No Keychain or browser-cookie import was used.

UI evidence

No runtime screenshot is included because the installed local Xcode cannot build the Swift 6.2 app. The redacted live request above verifies the production API contract, while focused model tests assert the exact menu-bar, menu-card, and CLI balance presentation.

Decision requested

Please confirm that a balance-only API-key v1 is acceptable for #2318. This remains a draft while that product decision and the full CI result are pending.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 28, 2026, 6:12 AM ET / 10:12 UTC.

ClawSweeper review

What this changes

Adds Charm Hyper as an opt-in API-key provider that fetches a remaining Hypercredit balance and displays it in CodexBar’s menu bar, provider card, CLI, settings, diagnostics, documentation, and tests.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this PR open for a maintainer decision rather than closing either candidate: it has credible live endpoint proof and a focused API-key design, but it overlaps the still-open Charm Hyper implementation at #2379. The two paths should be consolidated before a provider contract is merged.

Priority: P3
Reviewed head: 7988efc0f12e96cc6d139ab064d7a2d2f36c2ea9
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The PR has solid real endpoint proof and focused coverage, but merge readiness depends on selecting one of two overlapping provider implementations.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body includes redacted after-fix live output from the configured production credits endpoint, showing HTTP 200 and Balance: 90 HC; focused tests supplement that proof. Any subsequent evidence should remain redacted.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body includes redacted after-fix live output from the configured production credits endpoint, showing HTTP 200 and Balance: 90 HC; focused tests supplement that proof. Any subsequent evidence should remain redacted.
Evidence reviewed	4 items	Overlapping open implementation: This PR and #2379 both implement the same user-facing Charm Hyper API-key balance provider. This PR explicitly identifies endpoint and presentation differences, so landing both would create competing implementations. Narrow credential path: The proposed provider uses an explicitly configured HYPER_API_KEY to request Charm Hyper’s credits endpoint and does not add browser-cookie import or OAuth refresh-token reuse. After-fix production evidence: The PR body includes redacted live output from the configured production credits endpoint: HTTP 200 followed by Balance: 90 HC; focused tests cover request construction and presentation separately.
Findings	None	None.
Security	None	None.

How this fits together

CodexBar resolves provider credentials from environment variables, saved provider settings, and token accounts, then normalizes provider responses into usage snapshots. Those snapshots feed menu-bar text, detail cards, diagnostics, and CLI output.

flowchart LR
  A[API key or token account] --> B[Charm Hyper provider]
  B --> C[Credits API request]
  C --> D[Hypercredit balance snapshot]
  D --> E[Menu bar]
  D --> F[Provider card]
  D --> G[CLI and diagnostics]

Loading

Decision needed

Question	Recommendation
Should CodexBar support Charm Hyper as an API-key-only, balance-only provider now, and which of the two open implementations should become the single supported landing path?	Adopt this API-key-only v1: Use this PR as the single Charm Hyper path because it targets the maintained credits endpoint and renders the returned balance in native HC units.

Why: Both open PRs address the same capability, while this PR deliberately limits v1 to the documented credits endpoint and avoids cookie/OAuth scope. Selecting the durable provider contract and consolidation path needs maintainer intent.

Before merge

• Resolve merge risk (P1) - Merging this PR alongside Add Charm Hyper provider #2379 would leave two overlapping Charm Hyper provider paths and a competing source of truth for endpoint, credential, and balance-presentation behavior.
• Resolve merge risk (P1) - Adding HYPER_API_KEY, saved provider keys, and token accounts creates a supported auth-provider contract; maintainers should explicitly accept the API-key-only, balance-only v1 before merge.
• Resolve merge risk (P1) - The supplied check state includes runs still in progress, so the final merge decision should recheck required results for the exact head commit.
• Complete next step (P2) - A maintainer must choose the durable Charm Hyper v1 contract and a single implementation before any mechanical consolidation or merge work.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Feature surface	35 files changed; 610 added, 83 removed	The provider is registered across core fetching, UI, CLI, settings, diagnostics, resources, tests, and documentation.
Real behavior proof	1 redacted live HTTP 200 credits request	The PR body directly demonstrates the production endpoint accepting the configured bearer key and producing an HC balance.

Merge-risk options

Maintainer options:

1. Select and consolidate one provider path (recommended)
   Choose one Charm Hyper implementation before merge and retain the explicit HYPER_API_KEY path so users do not receive overlapping integrations.
2. Pause the competing implementations
   Defer both PRs if the product requires a reset timer or account data that the documented API-key endpoint cannot provide.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
After maintainer approval of the API-key-only balance scope, consolidate on the documented hyper.charm.land credits endpoint, retain native HC balance presentation, and validate provider parsing, credential resolution, and CLI/menu rendering on the exact head.

Technical review

Best possible solution:

Choose one Charm Hyper implementation, preserve the documented https://hyper.charm.land/v1/credits API-key path and native Balance: <amount> HC display, and land it as the sole supported provider integration with focused credential, parsing, and rendering coverage.

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

Not applicable: this PR adds a provider capability rather than repairing established failing behavior. Its redacted live request is after-fix feature proof, not a bug reproduction.

Is this the best way to solve the issue?

Unclear: the API-key-only balance design is narrow and evidence-backed, but maintainers must select it as the permanent v1 scope and consolidate it with #2379 before merge.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P3: Charm Hyper support is an optional provider addition, not a regression in an existing workflow.
• merge-risk: 🚨 auth-provider: The PR adds a new API-key environment convention, saved key setting, token-account route, and bearer-authenticated request.
• merge-risk: 🚨 compatibility: A second open PR implements the same provider capability, making duplicate supported paths a concrete maintenance and behavior risk.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes redacted after-fix live output from the configured production credits endpoint, showing HTTP 200 and Balance: 90 HC; focused tests supplement that proof. Any subsequent evidence should remain redacted.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted after-fix live output from the configured production credits endpoint, showing HTTP 200 and Balance: 90 HC; focused tests supplement that proof. Any subsequent evidence should remain redacted.

Evidence

What I checked:

• Overlapping open implementation: This PR and Add Charm Hyper provider #2379 both implement the same user-facing Charm Hyper API-key balance provider. This PR explicitly identifies endpoint and presentation differences, so landing both would create competing implementations.
• Narrow credential path: The proposed provider uses an explicitly configured HYPER_API_KEY to request Charm Hyper’s credits endpoint and does not add browser-cookie import or OAuth refresh-token reuse. (Sources/CodexBarCore/Providers/Hyper/HyperUsageFetcher.swift:1, 7988efc0f12e)
• After-fix production evidence: The PR body includes redacted live output from the configured production credits endpoint: HTTP 200 followed by Balance: 90 HC; focused tests cover request construction and presentation separately. (Tests/CodexBarTests/HyperUsageFetcherTests.swift:1, 7988efc0f12e)
• Repository policy applied: The supplied repository policy favors focused provider/parser coverage, avoids unrequested Keychain and browser-cookie probing, and requires provider data to remain siloed. The API-key-only design follows those review constraints. (AGENTS.md:1)

Likely related people:

• JavaGT: Authored the related feature request and the other open Charm Hyper implementation, including the API-surface investigation that frames the remaining scope choice. (role: adjacent implementation author; confidence: medium; commits: 9c876892b5f8; files: Sources/CodexBarCore/Providers/Providers.swift, docs/providers.md)

Rank-up moves

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

• Confirm API-key-only, balance-only v1 as the Charm Hyper contract.
• Consolidate this work with Add Charm Hyper provider #2379 so only one provider implementation lands.
• Recheck required checks for the exact head before merge.

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 (4 earlier review cycles)

• reviewed 2026-07-28T05:49:05.141Z sha cf9dfe2 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-28T06:26:08.245Z sha e1e0f47 :: needs maintainer review before merge. :: none
• reviewed 2026-07-28T07:29:05.032Z sha 7988efc :: needs maintainer review before merge. :: none
• reviewed 2026-07-28T09:07:00.698Z sha 7988efc :: needs maintainer review before merge. :: none

[akshayprabhu200]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[steipete]

Status from maintainer triage: your implementation (API-key-only, native HC balance) and #2379 (GET /v1/credits) both target issue #2318, and your redacted live proof is appreciated. We're getting a Charm Hyper account so this can be verified properly before landing either.

Direction we're leaning: support both auth paths rather than picking one — API key when present, and a signed-in session when available (preferring the richer source) — consistent with how most CodexBar providers behave. We'll converge the two PRs into that shape once testing is possible, crediting both of you.

Heads up: this branch is now conflicted against main (Qwen Cloud, ZoomMate, and Alibaba Personal providers landed, which moved provider counts, registries, docs, and the generated parser hash). No need to churn on rebases until the direction is settled. Thanks @akshayprabhu200!

[steipete]

Update on Charm Hyper: Peter is on the Charm Hyper waitlist, so we can't verify either implementation against a live account just yet.

Rather than leave two competing PRs sitting stale, we're combining them into a single new PR that implements both auth paths:

• API key present → infer usage/balance from it (the Add Charm Hyper balance provider #2476 shape).
• Signed-in session → prefer it when available, since it exposes more (the Add Charm Hyper provider #2379 /v1/credits shape).

Both of you will be credited as co-authors on the combined PR. It'll be prepared, tested, and CI-green so it can merge the moment account access comes through and the live behavior checks out. We'll link it here when it's up — thanks for the work and the patience, @JavaGT and @akshayprabhu200.

[steipete]

The combined Charm Hyper PR is up: #2502 — "Add Charm Hyper provider (API key + session)".

It implements both auth paths as planned: a signed-in hyper.charm.land session is preferred in Auto mode (imported from Chrome or supplied as a manual Cookie header), falling back to an explicit API key from configuration, HYPER_API_KEY, or a token account. Balance data stays honest — no inferred plan limit, usage percentage, quota, or reset timestamp — and malformed successful responses fail closed rather than hiding an upstream contract change.

Both of you are recorded as co-authors on the combined commit, and the PR credits #2379 and #2476 explicitly.

It is not merging yet: Peter is on the Charm Hyper waitlist, so nobody has confirmed the behavior against a real account. Once access lands we'll verify session auth, the session-over-key preference and fallback, API/session balance parity, and HC rendering — then it goes in. CI is green apart from one macOS shard still queued.

Keeping #2379 and #2476 open for now so you can review the combined result and flag anything we got wrong about your implementations.