feat(ai): track real usage for BYOK provider calls

[JSONbored]

Summary

callAiProvider in src/services/ai-review.ts is the shared HTTP helper for every BYOK (bring-your-own-key) AI call — used by ai-review.ts's BYOK advisory write-up and ai-slop.ts's BYOK slop-advisory path. It POSTs directly to https://api.anthropic.com/v1/messages or https://api.openai.com/v1/chat/completions but only ever returned { text }, discarding the response body's usage field. That meant BYOK calls never populated provider/effort/input_tokens/output_tokens/total_tokens/cost_usd in ai_usage_events (migration 0109's columns), even though the maintainer is billing these calls to their own Anthropic/OpenAI account in real dollars.

This PR:

• Extends callAiProvider's return type with an optional usage field.
• Adds coerceByokUsage() to normalize Anthropic's usage: {input_tokens, output_tokens} and OpenAI's usage: {prompt_tokens, completion_tokens, total_tokens} — both snake_case, provider-specific — into the same AiReviewActualUsage shape coerceAiUsage already produces for the free/self-host path.
• Adds a static per-model USD/MTok pricing table (BYOK_MODEL_PRICING_USD_PER_MTOK) to compute costUsd, since neither provider's API reports a dollar figure directly. A model absent from the table leaves costUsd undefined rather than fabricated.
• Threads the new usage field through runProviderReview's diagnostic in ai-review.ts (flows automatically into the existing aggregateActualUsage/record()/recordAiUsageEvent plumbing — no other changes needed there) and into ai-slop.ts's BYOK branch.

Not in scope (flagged for a possible follow-up, not a defect in this PR): Anthropic's usage object can carry cache_creation_input_tokens/cache_read_input_tokens at different price multipliers when prompt caching is active. callAiProvider never sends a cache_control marker on its request body, so Anthropic never populates those fields on this path today — documented inline so a future reader doesn't need to rediscover this.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed. (No issue: a targeted, self-contained usage-tracking fix on the existing BYOK path, explicitly scoped and requested directly.)

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally — 100% branch/line coverage on every changed line, verified via lcov diff-mapping against the exact hunks in this diff.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate — 0 vulnerabilities.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries — 8 new tests across ai-review.test.ts/ai-slop.test.ts covering both providers, priced/unpriced models, partial usage fields, and malformed response bodies.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests. (N/A — no auth/session/CORS changes.)
• API/OpenAPI/MCP behavior is updated and tested where needed. (N/A — no public API/schema shape change; internal usage-tracking only.)
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks. (N/A — no UI changes.)
• Visible UI changes include a UI Evidence section below with screenshots. (N/A — no visible UI changes; backend-only.)
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs. (N/A — no public docs affected.)

Notes

• The BYOK daily-repo quota and free-tier neuron budget accounting are unchanged — both were already independent of real usage data before this PR.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.46%. Comparing base (079ee51) to head (e93a2fd).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3382   +/-   ##
=======================================
  Coverage   93.46%   93.46%           
=======================================
  Files         287      287           
  Lines       30763    30781   +18     
  Branches    11210    11219    +9     
=======================================
+ Hits        28752    28770   +18     
  Misses       1355     1355           
  Partials      656      656           

Files with missing lines	Coverage Δ
src/services/ai-review.ts	96.24% <100.00%> (+0.14%)	⬆️
src/services/ai-slop.ts	92.00% <100.00%> (+0.10%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-05 05:50:37 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This change correctly threads BYOK provider token usage from the shared HTTP helper into both review and slop advisory diagnostics, and the normalization handles the two provider response shapes shown in the diff without fabricating costs for unknown models. The tests exercise the durable audit row for both paths and cover missing/partial usage fields, which is the right level for this wiring change. I do not see a reachable correctness break in the provided diff.

Nits — 4 non-blocking

• nit: src/services/ai-review.ts:890 anchors BYOK pricing in a static table without a source/date note, so future maintainers have no way to know when these rates were last verified or whether a model rename needs an update.
• nit: src/services/ai-review.ts:948 adds a provider-specific usage parser but keeps it private to ai-review.ts even though ai-slop.ts now relies on the same behavior indirectly through callAiProvider; consider keeping provider usage normalization near the shared provider client boundary if this file grows further.
• src/services/ai-review.ts:890 Add a short comment with the pricing source and last-verified date, or move the pricing table into a clearly named provider-pricing constant/module so updates are easier to audit.
• src/services/ai-review.ts:934 Consider adding a focused unit test for OpenAI usage where total_tokens is absent, since the fallback total calculation is shared but the current partial-field tests only exercise the Anthropic field names.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 56 registered-repo PR(s), 46 merged, 416 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 56 PR(s), 416 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 56 PR(s), 416 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.