feat(usage): attribute xAI attempts to their resolved credential source

[lidge-jun]

Summary

• Carry Record xAI credential provenance per usage attempt #3642 onto the current release stack. New physical xAI attempts record grok-oauth or xai-api-key from the resolved upstream transport; historical, custom and other-provider attempts remain unlabelled.
• Rederive the value after provider-bearing retry and account/key rebuilds. Clear stale values when attempt identity changes; combo finalization preserves each child's existing attribution.
• Persist only the two allowed values and document the per-attempt contract. No credential, URL or account identifier is added to usage records.

Co-authored-by: olddonkey olddonkeyblog@gmail.com

Verification

• Main full-delta and composed-callsite audit passed; independent xai/grok-4.6 plan review passed. Independent implementation/security review passed through 63282e4. Added seal identity clearing/preservation, actual-adapter exclusion and real native Chat key-429 rotation regression fixtures.
• Carried regression fixtures cover canonical/custom transports, fixed-enum JSONL round trips, physical combo attempts, OAuth 401 replay with two sends, and native Chat API-key attribution.
• Hosted CI will verify this branch; no local test suite, typecheck or build was run. No live provider request was made for this change.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

This is the next layer above #3758 in the manual dependent PR chain. Source #3642 remains open until this attributed carry lands. The repository owner authorized bottom-up maintainer integration after current-head CI passes.

Native stack #3759 was dissolved at the owner's explicit request. The PR head is preserved; integration continues bottom-up with ordinary PRs and admin merge after current-head CI.

Sidecar verification

Exact-head Cross-platform CI 34026465820 completed SUCCESS on 63282e4 (Linux test 1/4-4/4, macOS 1/2-2/2, gates, ci). Independent source/security review already passed through this head. Maintainer-integration choice: admin merge into current dev after assert-mergeable-review.sh --maintainer-integration 3762; no rebase; no branch delete. Native stack #3759 remains dissolved.

Summary by CodeRabbit

• New Features

  • Usage logs now identify whether eligible xAI requests used Grok CLI OAuth or a public xAI API key.
  • Credential-source attribution remains accurate across retries, key rotation, adapter resolution, and combined requests.
  • Logs exclude credentials and account identifiers, and only record recognized xAI sources.

• Documentation

  • Clarified xAI adapter resolution and authentication options.
  • Documented credential-source fields, attribution behavior, exclusions, and the distinction between usage reporting and subscription billing.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: d20c9192-3c58-4945-a9d0-996342f342bb

📥 Commits

Reviewing files that changed from the base of the PR and between 9162b3b and 63282e4.

📒 Files selected for processing (9)

• docs-site/src/content/docs/reference/adapters.md
• docs-site/src/content/docs/reference/management-api.md
• src/server/chat-native.ts
• src/server/request-log.ts
• src/server/responses/core.ts
• src/usage/log.ts
• tests/server/server-xai-oauth-401-replay.test.ts
• tests/usage/request-log.test.ts
• tests/usage/usage-log.test.ts

---

📝 Walkthrough

Walkthrough

The change adds request-time xAI credential-source tracking for OAuth and API-key transports. It records sources across retries and provider changes, filters invalid values during usage-log normalization, tests persistence and masking, and documents the resulting fields.

Changes

xAI credential-source tracking

Layer / File(s)	Summary
Credential-source contract and validation src/usage/log.ts, src/server/request-log.ts, tests/usage/request-log.test.ts, tests/usage/usage-log.test.ts	Adds UsageCredentialSource and optional attempt-level storage. recordAttemptCredentialSource recognizes only canonical xAI OAuth and API-key transports. Identity sealing clears stale attribution when the provider or adapter changes. Normalization removes unsupported or non-xAI values. Tests cover these rules and combo attempts.
Request-path attribution src/server/chat-native.ts, src/server/responses/core.ts	Records credential sources during native Chat request builds and Responses request resolution, rebuilds, retries, OAuth refreshes, account rotations, and adapter failovers.
Persisted behavior and reference documentation tests/server/server-xai-oauth-401-replay.test.ts, docs-site/src/content/docs/reference/adapters.md, docs-site/src/content/docs/reference/management-api.md	Verifies OAuth replay, API-key requests, key-pool rotation, token masking, and persisted attempt fields. Documents resolved transports, supported labels, and attribution limits.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant NativeChat
  participant ResponsesCore
  participant RequestLog
  participant UsageLog
  Client->>NativeChat: Submit a native Chat request
  NativeChat->>RequestLog: Record active provider and adapter
  Client->>ResponsesCore: Submit a Responses request
  ResponsesCore->>RequestLog: Record resolved or rebuilt attempt
  RequestLog->>UsageLog: Persist canonical xAI credentialSource

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/release-244-usage-source-07c0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

Exact-head Cross-platform CI 34026465820 completed SUCCESS on 63282e4 (Linux test 1/4-4/4, macOS 1/2-2/2, gates, ci). Independent source/security review already passed through this head. Maintainer-integration choice: admin merge into current dev after assert-mergeable-review.sh --maintainer-integration 3762; no rebase; no branch delete. Native stack #3759 remains dissolved.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T10:22:20.466149Z	63282e4	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.