Add Poe current balance provider

[Yuxin-Qiao]

Summary

Adds minimal Poe provider support in response to #1182, using Poe's official Usage API.

• Adds API-key auth via POE_API_KEY
• Fetches current point balance from GET https://api.poe.com/usage/current_balance
• Parses the official current_point_balance response field
• Displays Poe as a balance-only provider without fake percentage, reset window, total quota, or usage history inference

Closes #1182.

Validation

• ./Scripts/lint.sh lint
• swift build
• swift test --filter PoeUsageFetcherTests

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed May 28, 2026, 3:44 AM ET / 07:44 UTC.

Summary
Adds Poe as a balance-only provider that reads POE_API_KEY or config API keys, calls Poe’s current balance API, registers provider UI/icon surfaces, and adds focused tests.

Reproducibility: not applicable. as a feature PR rather than a bug report. The patch is source-reviewable, but the real Poe API behavior is not proven because the PR body only lists lint/build/unit tests.

Review metrics: 2 noteworthy metrics.

• Changed surface: 25 files, 459 additions, 7 deletions. The provider spans core fetch logic, app registration, menu rendering, resources, widgets, and tests, so integration review matters more than fetcher-only review.
• Provider added: 1 new provider and API-key auth path. A new provider affects exhaustive switches, token routing, availability, display behavior, and maintainer support scope.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted live Poe API or app/menu proof showing a real balance fetch and render.
• Get maintainer confirmation that env/config API-key setup is the intended Poe provider scope.

Proof guidance:

• [P1] Needs real behavior proof before merge: Needs real behavior proof before merge: add redacted live Poe API output, terminal logs, app/menu screenshot, or recording showing the new provider fetching and rendering a balance; update the PR body afterward so ClawSweeper re-reviews automatically, or ask a maintainer to comment @clawsweeper re-review.

Risk before merge

• [P1] Contributor proof is still test-only; maintainers cannot yet see a real Poe token fetch and app/menu balance render after this patch.
• [P1] The PR adds a new API-key provider and token routing path, so maintainer sign-off is needed for provider/auth maintenance scope and privacy expectations.
• [P1] The PR is mergeable but currently reported as unstable, so checks or required status context still need to settle before merge.

Maintainer options:

1. Require live Poe proof and auth-scope approval (recommended)
   Before merge, require redacted live Poe API or app/menu proof and explicit maintainer approval that the env/config API-key setup is the intended scope.
2. Accept the env/config-only provider scope
   Maintainers may choose to merge with the current setup surface after confirming that no dedicated Poe settings UI is required for this release.
3. Pause for a fuller provider design
   If Poe needs account management, usage history, or a dedicated settings flow now, pause this PR and keep the linked feature request as the product discussion.

Next step before merge

• [P1] Human review remains needed because only the contributor can provide live Poe proof and maintainers need to approve the new provider/auth scope.

Security
Cleared: No concrete supply-chain or security regression was found; the diff adds a fixed HTTPS Poe API request path and no dependency, workflow, or script changes.

Review details

Best possible solution:

Land the narrow balance-only Poe provider after redacted live proof is added and maintainers approve the new API-key provider scope.

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

Not applicable as a feature PR rather than a bug report. The patch is source-reviewable, but the real Poe API behavior is not proven because the PR body only lists lint/build/unit tests.

Is this the best way to solve the issue?

Unclear until proof and sign-off land: the descriptor/fetcher shape is narrow and matches the documented current-balance endpoint, but the best merge path still requires live evidence and maintainer approval of the provider/auth scope.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against dcd43163e0f7.

Label changes

Label justifications:

• P2: This is a normal-priority provider integration with bounded blast radius but real auth and user-visible display behavior.
• merge-risk: 🚨 auth-provider: The PR adds a new API-key provider and token resolution path, so credential routing and live auth behavior need maintainer-visible review before merge.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab 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: Needs real behavior proof before merge: add redacted live Poe API output, terminal logs, app/menu screenshot, or recording showing the new provider fetching and rendering a balance; update the PR body afterward so ClawSweeper re-reviews automatically, or ask a maintainer to comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• AGENTS.md policy read: Read the full repository AGENTS.md and applied the provider-pattern, focused-test, and real-runtime-proof guidance to this PR review. (AGENTS.md:1, dcd43163e0f7)
• Current main has no Poe provider: A source/docs search on current main only found unrelated Usage API text and no Poe provider, POE_API_KEY, current_balance, or current_point_balance implementation, so this PR is not obsolete on main. (dcd43163e0f7)
• PR implements the requested provider path: The latest PR patch adds a Poe descriptor/fetch strategy, PoeUsageFetcher, token/config routing, provider registration, UI balance rendering, widget switch coverage, and tests at head 57d257cf1f302c5c6e1af1dd7cd8b692f0272b1c. (Sources/CodexBarCore/Providers/Poe/PoeProviderDescriptor.swift:6, 57d257cf1f30)
• Official Poe API shape matches the fetcher target: Poe’s Usage API docs describe Bearer API-key auth, GET https://api.poe.com/usage/current_balance, and the current_point_balance response field. (creator.poe.com)
• Previous balance/config concern appears addressed: The latest patch maps .poe to PoeSettingsReader.apiKeyEnvironmentKey, adds config override tests, adds .poe to balance-only providers, and adds menu descriptor coverage for Balance: 1,500 points. (Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift:108, 57d257cf1f30)
• Real behavior proof remains missing: The PR body lists lint, build, and focused unit tests, and the only issue comment is the prior ClawSweeper proof request; no live Poe API output, menu screenshot, terminal log, recording, or redacted runtime proof is present. (57d257cf1f30)

Likely related people:

• steipete: Blame on the central provider registry/config/menu files points to Peter Steinberger in the current release snapshot, and path history shows repeated provider additions and framework changes. (role: provider framework owner by history; confidence: high; commits: 14b2b2524f7c, daaa271c27e6, d715648cf23d; files: Sources/CodexBarCore/Providers/ProviderDescriptor.swift, Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift, Sources/CodexBar/MenuDescriptor.swift)
• Yuxin-Qiao: Beyond authoring this PR, Yuxin-Qiao has recent merged history in visible UI/menu-related files that this provider touches. (role: recent adjacent contributor; confidence: medium; commits: 2deb0f5c9a42, de7c25ba2ef0; files: Sources/CodexBar/MenuDescriptor.swift, Sources/CodexBar/StatusItemController+Animation.swift)
• mstallone: Recent OpenAI project scoping work touched provider config environment behavior, which is adjacent to this PR’s API-key override path. (role: recent auth/config contributor; confidence: medium; commits: 807d07d0c4d2; files: Sources/CodexBarCore/Config/ProviderConfigEnvironment.swift)
• willytop8: Recent balance-metric work introduced or maintained menu bar balance display behavior that this PR extends for Poe. (role: adjacent balance-display contributor; confidence: medium; commits: c7f38669a655; files: Sources/CodexBar/StatusItemController+Animation.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 917dad2d24

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Map Poe apiKey into the fetch environment

When a user configures Poe with source: api and an apiKey in the app config/settings, this advertises that the provider supports API-key config, so CodexBarConfigValidation accepts it. However ProviderConfigEnvironment.directAPIKeyEnvironmentKey(for:) has no .poe case, and UsageStore/ProviderRegistry only pass saved keys to fetchers through applyProviderConfigOverrides; as a result PoeAPIFetchStrategy still sees missing credentials unless POE_API_KEY is present in the process environment. Add a .poe mapping to PoeSettingsReader.apiKeyEnvironmentKey (and expose the settings field if desired) so saved Poe keys actually work.

Useful? React with 👍 / 👎.

[majo333333]

Hi, I opened the original issue (#1182).
Thank you so much for implementing this!

I'm a Poe Plus subscriber, so I'd be happy to
test and provide screenshots once this is merged.