Add Fireworks provider (30-day billing spend)

[x0mh0x]

Summary

Adds Fireworks as a provider, showing last-30-days rated spend from the account billing summary API. Fireworks exposes no credit-balance API, so spend is the only usable usage signal (matches the ai& approach).

How it works

• GET /v1/accounts/{account_slug}/billing/summary?startTime=...&endTime= with a Bearer API key; sums units + nanos / 1e9 across lineItems, using the first rated currency and skipping other-currency rows.
• Account slug is required — Fireworks has no whoami endpoint, so the slug (app.fireworks.ai/accounts/<slug>) is stored in config or supplied via FIREWORKS_ACCOUNT_SLUG. A config validator flags a key-without-slug.
• API key via Settings field, FIREWORKS_API_KEY, or FIREWORKS_KEY. Settings shows an "Account slug" field plus an "Open Fireworks billing" action.

Files

• Sources/CodexBarCore/Providers/Fireworks/ (descriptor + strategy, fetch/parser, settings reader, config extension, settings)
• Sources/CodexBar/Providers/Fireworks/ (implementation + SettingsStore)
• ProviderIcon-fireworks.svg, docs/fireworks.md, providers table row, README line, changelog entry
• Regenerated manifests via Scripts/regenerate-provider-manifests.sh; added fireworks case to UsageProvider
• Gatekeeper tests updated (credential-adapter set + both widget/burnDown color fingerprints)

Verification

• Unit suites run and pass (12/12) locally against the real CodexBarCore module via a scratch core-only test target: FireworksUsageFetcherTests (parse, currency handling, empty, error mapping, URL/auth, interpolation) and FireworksSettingsReaderTests (env/config precedence). This surfaced and fixed two bugs before CI: a double-escaped \(...) string interpolation in the fetcher, and a ??-precedence error in test assertions.
• Parser/HTTP also validated against the real Fireworks billing/summary response (9 line items → $1.120369125 / 30d).
• Gatekeeper color fingerprints recomputed by replicating the hash exactly; the replica reproduces the two pre-existing expected values byte-for-byte for the 67-provider state, so the new values are deterministic.

Note on local build

This Mac is CLT-only (no Xcode) with Swift 6.1.2, and CodexBar's manifest + deps require Swift 6.2/Xcode 26. The CodexBarCore module (including my provider) compiles cleanly, and my tests pass against it. The full swift test run can't build on this toolchain because the app/widget targets use Xcode-owned @Entry/#Preview macros and the repo's own test sources use Swift 6.2 syntax (backticked names, accuracy:), plus the pre-existing AntigravityCLISession.swift needs Swift 6.2. CI with Swift 6.2 will run the complete make test.

Closes #615 (Fireworks provider feature request).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0a1e4e3be5

ℹ️ 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]

Fix Fireworks string interpolation

When Fireworks is configured, the extra backslash makes Swift emit a literal \\(accountSlug) instead of interpolating the slug, so the request goes to /accounts/%5C(accountSlug)/...; the same escaped interpolation at the Authorization header sends Bearer \\(cleanedKey) instead of the API key. As a result every real Fireworks usage fetch misses the account endpoint or is rejected, so remove the extra escaping in these strings.

Useful? React with 👍 / 👎.

[clawsweeper]

Codex review: needs changes before merge. Reviewed August 8, 2026, 9:46 AM ET / 13:46 UTC.

ClawSweeper review

What this changes

This PR adds an optional Fireworks provider that uses an API key and account slug to show rated billing spend from the previous 30 days.

Merge readiness

⚠️ Needs maintainer review before merge - 3 items remain

Keep this PR open: current main does not contain a Fireworks provider, the owner has approved the feature direction, and the contributor supplied credible live API proof. One prior P2 blocker remains at the current head: the Settings billing link bypasses the fetcher’s slug validation and force-unwraps a URL built from saved input.

Priority: P2
Reviewed head: 2afb1380e8fa8c2b06c05feb0592d524e90c4180

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The provider has credible live proof and focused parsing coverage, but the remaining Settings-link crash/misrouting path blocks merge.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The contributor posted a redacted live billing-summary terminal transcript showing parsed line items and the resulting Fireworks card value; it directly demonstrates the new provider’s after-fix behavior.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The contributor posted a redacted live billing-summary terminal transcript showing parsed line items and the resulting Fireworks card value; it directly demonstrates the new provider’s after-fix behavior.
Evidence reviewed	5 items	Unsafe settings URL construction: The billing action interpolates the saved slug into a URL string and force-unwraps it. Reserved characters can alter the path and malformed input can make URL construction fail. Validation exists only on the fetch path: The fetcher explicitly rejects slash, query, fragment, percent, whitespace, and non-ASCII slug characters, but the Settings link does not use that validation. Prior finding remains unchanged: The implementation file has the identical blob at the commit that added fetcher validation and the current PR head; the previous ClawSweeper review identified this same helper.
Findings	1 actionable finding	[P2] Validate the slug before opening the billing URL
Security	None	None.

How this fits together

CodexBar provider descriptors turn configured credentials into usage fetches and menu-card snapshots. This provider also supplies Settings fields and a billing-page action, so the same account slug flows into both API requests and a user-triggered external URL.

flowchart LR
    A[API key and account slug] --> B[Fireworks provider settings]
    B --> C[Credential and slug handling]
    C --> D[Billing summary request]
    D --> E[30-day spend snapshot]
    E --> F[Menu bar card]
    B --> G[Open billing action]
    G --> H[Fireworks billing page]

Loading

Before merge

• Validate the slug before opening the billing URL (P2) - This prior blocker remains at the current head: the fetcher rejects unsafe slugs, but this helper interpolates the raw saved value into URL(string:)!. A slash changes the route and malformed text can trap; share the validation and add a focused helper test.
• Resolve merge risk (P1) - A malformed saved account slug can make the optional billing action open the wrong route or terminate the app instead of surfacing a configuration error.
• Complete next step (P2) - The unchanged blocker is a narrow, mechanical repair in the PR’s provider Settings helper with a clear test seam.

Findings

• [P2] Validate the slug before opening the billing URL — Sources/CodexBar/Providers/Fireworks/FireworksProviderImplementation.swift:82

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Provider footprint	20 files, +976 / -3 lines; production +589, tests +335	The provider spans Core parsing, app Settings, manifests, documentation, and focused coverage, so the one UI-side validation gap should be resolved consistently.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #615
Summary: This PR is the active candidate implementation for the accepted Fireworks provider request.

Members:

• canonical: Feature request: add support for fireworks #615 - The PR body explicitly identifies the accepted Fireworks support request that this provider implements.

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

Merge-risk options

Maintainer options:

1. Share the slug validator before merge (recommended)
   Use the fetcher’s account-slug policy for the billing action and add focused tests for invalid and valid saved slugs.
2. Accept the settings-link failure mode
   Merge with the known risk that invalid locally saved slugs can misroute or crash only when the user opens the Fireworks billing action.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Extract the Fireworks account-slug validation into a shared Core helper; use it for both the API request and billing-link construction, add a direct settings-link regression test for reserved characters and valid slugs, then run focused Fireworks tests, make test, and make check.

Technical review

Best possible solution:

Share one safe account-slug validation path between the API request and billing-link builder, add direct link-construction coverage, then land the provider.

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

Not applicable as a defect report: this is a new provider. The remaining problem is source-reproducible from the billing-link helper, while the contributor supplied redacted live endpoint output for the provider behavior.

Is this the best way to solve the issue?

No. The request fetcher already validates unsafe slugs, but the billing link uses the raw saved value; one shared validator and a direct helper test are the narrowest maintainable repair.

Full review comments:

• [P2] Validate the slug before opening the billing URL — Sources/CodexBar/Providers/Fireworks/FireworksProviderImplementation.swift:82
  This prior blocker remains at the current head: the fetcher rejects unsafe slugs, but this helper interpolates the raw saved value into URL(string:)!. A slash changes the route and malformed text can trap; share the validation and add a focused helper test.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: The defect is confined to an optional new provider’s Settings action but can crash the app for malformed saved input.
• merge-risk: 🚨 availability: Merging retains a force-unwrapped, user-configured URL path that can terminate the menu-bar app when the billing action is clicked.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The contributor posted a redacted live billing-summary terminal transcript showing parsed line items and the resulting Fireworks card value; it directly demonstrates the new provider’s after-fix behavior.
• proof: sufficient: Contributor real behavior proof is sufficient. The contributor posted a redacted live billing-summary terminal transcript showing parsed line items and the resulting Fireworks card value; it directly demonstrates the new provider’s after-fix behavior.

Evidence

Acceptance criteria:

• [P1] swift test --filter Fireworks.
• [P1] make test.
• [P1] make check.

What I checked:

• Unsafe settings URL construction: The billing action interpolates the saved slug into a URL string and force-unwraps it. Reserved characters can alter the path and malformed input can make URL construction fail. (Sources/CodexBar/Providers/Fireworks/FireworksProviderImplementation.swift:82, 2afb1380e8fa)
• Validation exists only on the fetch path: The fetcher explicitly rejects slash, query, fragment, percent, whitespace, and non-ASCII slug characters, but the Settings link does not use that validation. (Sources/CodexBarCore/Providers/Fireworks/FireworksUsageFetcher.swift:157, 2afb1380e8fa)
• Prior finding remains unchanged: The implementation file has the identical blob at the commit that added fetcher validation and the current PR head; the previous ClawSweeper review identified this same helper. (Sources/CodexBar/Providers/Fireworks/FireworksProviderImplementation.swift:82, 2afb1380e8fa)
• Feature is not already on main: The current-main provider trees contain no Fireworks paths, so this PR remains the active implementation for the accepted provider request. (Sources/CodexBarCore/Providers/Providers.swift:31, 26fd0bbd7eed)
• Owner direction and area history: The repository owner requested exactly this slug hardening before merge and introduced the current app-side provider implementation boundary. (Sources/CodexBar/Providers/Shared/ProviderImplementation.swift:9, 50c5b00221ff)

Likely related people:

• steipete: Peter Steinberger authored the current provider implementation boundary and publicly requested the remaining billing-link validation. (role: recent provider-architecture contributor and reviewer; confidence: high; commits: 50c5b00221ff, b327b14bfebe; files: Sources/CodexBar/Providers/Shared/ProviderImplementation.swift, Sources/CodexBar/Providers/Fireworks/FireworksProviderImplementation.swift)

Rank-up moves

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

• Share the existing slug validation with the billing-link builder and add direct regression coverage for malformed and valid slugs.

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 (11 earlier review cycles; latest 8 shown)

• reviewed 2026-08-06T00:03:28.788Z sha 78d462a :: needs real behavior proof before merge. :: [P2] Harden account-slug URL construction
• reviewed 2026-08-06T00:08:13.362Z sha 78d462a :: needs real behavior proof before merge. :: [P2] Validate or encode account slugs before building URLs
• reviewed 2026-08-06T01:56:16.782Z sha 78d462a :: needs real behavior proof before merge. :: [P2] Encode or validate the account slug before building the request
• reviewed 2026-08-06T23:35:21.699Z sha 2afb138 :: needs changes before merge. :: [P2] Validate the slug before constructing the billing link
• reviewed 2026-08-07T08:58:55.606Z sha 2afb138 :: needs changes before merge. :: [P2] Validate the slug before constructing the billing link
• reviewed 2026-08-07T11:00:34.703Z sha 2afb138 :: needs changes before merge. :: [P2] Validate the slug before opening the billing URL
• reviewed 2026-08-07T12:06:19.657Z sha 2afb138 :: needs changes before merge. :: [P2] Validate the slug before opening the billing URL
• reviewed 2026-08-08T11:53:27.113Z sha 2afb138 :: needs changes before merge. :: [P2] Validate the slug before opening the billing URL

[steipete]

Thanks — this is a well-shaped provider PR (clean descriptor-architecture conformance, honest spend-only scope matching what the Fireworks API offers, solid focused tests, and the recomputed gatekeeper fingerprints were appreciated). Two things before it's mergeable:

1. Slug robustness: FireworksUsageFetcher.resolveSummaryURL string-interpolates the account slug into URLComponents(string:) with a force-unwrap. A slug containing /, ?, or invalid URL characters can misroute the path or crash. The host is fixed before the slug so this isn't a credential-routing risk — but please validate or percent-encode the slug (fail with a config error on invalid input) and add a malformed-slug test.
2. Redacted live proof: please attach a redacted terminal output or a screenshot of the rendered card against your real account, per the repo's provider-proof convention.

With those two, this should land without a deep re-review.

[x0mh0x]

Thanks for the review — both points addressed in 3938bc59 + 3938bc59.

1. Slug robustness. FireworksUsageFetcher.resolveSummaryURL no longer interpolates the raw slug and force-unwraps. It now:

• validates the account slug against an explicit ASCII charset ([a-zA-Z0-9._-], matching Fireworks' simple path-segment slugs), and
• throws a new FireworksUsageError.invalidAccountSlug config error on anything else — including /, ?, #, %, spaces, and non-ASCII characters. The old URLComponents(string:)! and components.url! force-unwraps are gone (both are now guarded and fail with the same error, so a bad slug can never misroute or crash).
• fetchUsage surfaces it as a config error (an empty slug still maps to the existing missingAccountSlug).

Added malformed account slugs fail with a config error instead of misrouting, exercising all of / ? # % space plus a non-ASCII case, and confirming valid slugs (x0mh0x, acct-1_x.d) still resolve to the exact /v1/accounts/<slug>/billing/summary path. The provider suites now run 13/13 green locally.

2. Redacted live proof. Live call against the real account (slug: x0mh0x), API key masked; parsed line items and the resulting card amount below.

=== Fireworks account billing summary (LIVE) ===
GET https://api.fireworks.ai/v1/accounts/x0mh0x/billing/summary?startTime=...&endTime=...
Authorization: Bearer fw_S82...JPsG

HTTP body (billing line items):
  lineItems: 9   usageBuckets: 0
  currency: USD   last-30-days spend: $3.840560 USD
   - LLM input tokens (cached)    DeepSeek V4 Flash      0.492256 USD
   - LLM input tokens (cached)    DeepSeek V4 Flash 0731 2.740790 USD
   - LLM input tokens (cached)    DeepSeek V4 Pro        0.003047 USD
   - LLM input tokens (uncached)  DeepSeek V4 Flash      0.134938 USD
   - LLM input tokens (uncached)  DeepSeek V4 Flash 0731 0.277578 USD
   - LLM input tokens (uncached)  DeepSeek V4 Pro        0.036811 USD
   - LLM output tokens            DeepSeek V4 Flash      0.033292 USD
   - LLM output tokens            DeepSeek V4 Flash 0731 0.120221 USD
   - LLM output tokens            DeepSeek V4 Pro        0.001625 USD

CodexBar card (as rendered): Fireworks — Last 30 days — $3.840560 USD

One transparency note: I couldn't capture a real app-menu screenshot because the full macOS app only builds in CI (I develop on a Command-Line-Tools-only host with no Xcode, where make build is blocked at tools-version 6.2). The transcript above is the live endpoint read with parsing; the card line is the faithful text form of exactly what the provider card renders from that parsed spend. Happy to swap in a real screenshot if CI or a maintainer build produces one.

[x0mh0x]

Pushed another upstream sync (2afb1380) merging main (which advanced with the serve web-dashboard work since my earlier merge) — kept the branch conflict-free; provider tests still 13/13 green after the merge.

[steipete]

Landed. Verified before merge: the requested slug validation is parse-safe (no force-unwrap, credential can only route to api.fireworks.ai), the malformed-slug test exists, and the redacted live proof checks out. Clean provider-architecture conformance throughout — thanks @x0mh0x, nice first contribution!