@oh-my-pi/pi-ai 17.0.8 → 17.0.9

package/CHANGELOG.md

@@ -2,9 +2,18 @@
 
 ## [Unreleased]
 
+## [17.0.9] - 2026-07-23
+
+### Added
+
+- Added Synthetic (synthetic.new) usage provider: `/usage` now reports the rolling 5-hour request limit and weekly credit quota via `GET /v2/quotas`, including per-tick regeneration rates in the window labels.
+- Added optional `UsageWindow.resetLabel` so rolling windows can render their countdown with an accurate verb (e.g. "tick in 12m" / "regen in 51m" instead of "resets in") — both quota windows on Synthetic regenerate incrementally rather than hard-resetting.
+
 ### Fixed
 
 - Fixed GitHub Copilot OpenAI-compatible requests being rejected when the session's native OpenAI service tier was set to `priority` ([#5160](https://github.com/can1357/oh-my-pi/pull/5160) by [@audreyt](https://github.com/audreyt)).
+- Fixed OpenAI Responses token-cap truncations suppressing fully streamed function and custom tool calls whose inputs are complete.
+- Added SuperGrok (`xai-oauth`) usage tracking for weekly credits, product limits, and positive on-demand caps.
 
 ## [17.0.8] - 2026-07-22
 

package/dist/types/index.d.ts

@@ -39,6 +39,8 @@ export * from "./usage/ollama.js";
 export * from "./usage/openai-codex.js";
 export * from "./usage/openai-codex-reset.js";
 export * from "./usage/opencode-go.js";
+export * from "./usage/synthetic.js";
+export * from "./usage/xai-oauth.js";
 export * from "./usage/zai.js";
 export * from "./utils/anthropic-auth.js";
 export * from "./utils/event-stream.js";

package/dist/types/providers/openai-shared.d.ts

@@ -491,7 +491,7 @@ export declare function finalizePendingResponsesToolCalls(output: AssistantMessa
  * re-samples instead of ending. Callers set `output.stopReason` from the wire
  * status first via {@link mapOpenAIResponsesStopReason}.
  */
-export declare function promoteResponsesToolUseStopReason(output: AssistantMessage, endTurn: boolean | undefined): void;
+export declare function promoteResponsesToolUseStopReason(output: AssistantMessage, endTurn: boolean | undefined, promoteIncompleteToolUse?: boolean): void;
 /** Initial empty `AssistantMessage` that streaming providers accumulate into. */
 export declare function createInitialResponsesAssistantMessage(api: Api, provider: string, modelId: string): AssistantMessage;
 /** Extension fields we add on top of `ResponseCreateParamsStreaming` across the Responses-family providers. */

package/dist/types/registry/oauth/xai-oauth.d.ts

@@ -1,16 +1,13 @@
 import type { FetchImpl } from "../../types.js";
 import type { OAuthController, OAuthCredentials } from "./types.js";
+export declare function validateXAIEndpoint(url: string, field: string): string;
 /**
- * Validate an xAI OIDC endpoint against its scheme and host.
- *
- * The discovery response is long-lived and its token endpoint receives every
- * future refresh token. Rejecting non-HTTPS or non-`x.ai` / `*.x.ai` hosts
- * pins that endpoint to the xAI auth origin.
- *
- * @throws Error with message `Invalid xAI <field>: <url>` when the URL fails
- *         either scheme or host validation.
+ * Pin SuperGrok billing URLs to HTTPS `grok.com` / `*.grok.com`.
+ * The CLI billing proxy is intentionally not on `*.x.ai`.
  */
-export declare function validateXAIEndpoint(url: string, field: string): string;
+export declare function validateXAIBillingEndpoint(url: string, field?: string): string;
+/** Decode an xAI access-token JWT payload without verifying its signature. */
+export declare function parseXAIAccessTokenPayload(jwt: string): Record<string, unknown> | null;
 /**
  * Check whether a JWT access token is at or past its `exp` claim (with an
  * optional refresh-skew margin).
@@ -19,6 +16,25 @@ export declare function validateXAIEndpoint(url: string, field: string): string;
  * not token validation.
  */
 export declare function isXAIAccessTokenExpiring(jwt: string, skewSeconds?: number): boolean;
+/** Extract the stable xAI subject UUID from an access token. */
+export declare function extractXAIAccessTokenSubject(jwt: string): string | undefined;
+export interface XAIOAuthIdentity {
+    accountId?: string;
+    email?: string;
+    name?: string;
+}
+/** Fetch optional OIDC userinfo for a valid xAI access token. */
+export declare function fetchXAIOAuthIdentity(accessToken: string, fetchOverride?: FetchImpl, signal?: AbortSignal): Promise<XAIOAuthIdentity | null>;
+/** Build the SuperGrok CLI billing URL. */
+export declare function buildXAICliBillingUrl(format?: string): string;
+/**
+ * Headers for SuperGrok CLI billing (`cli-chat-proxy.grok.com`).
+ * Official Grok CLI also sends `X-XAI-Token-Auth: xai-grok-cli` on this host;
+ * include it so billing stays on the same product gate as chat inference.
+ */
+export declare function getXAICliBillingHeaders(options: {
+    accessToken: string;
+}): Record<string, string>;
 /** Log in to xAI Grok with the RFC 8628 device authorization grant. */
 export declare function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCredentials>;
 /**

package/dist/types/usage/synthetic.d.ts

@@ -0,0 +1,2 @@
+import type { UsageProvider } from "../usage.js";
+export declare const syntheticUsageProvider: UsageProvider;

package/dist/types/usage/xai-oauth.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SuperGrok (`xai-oauth`) subscription usage provider.
+ *
+ * Reads weekly credit and product utilization from the Grok CLI billing
+ * endpoint. Only OAuth access credentials are accepted; paid API keys are a
+ * separate product and must never be sent here.
+ */
+import type { UsageProvider } from "../usage.js";
+export declare const xaiOauthUsageProvider: UsageProvider;

package/dist/types/usage.d.ts

@@ -11,6 +11,12 @@ export interface UsageWindow {
     durationMs?: number;
     /** Absolute reset timestamp in milliseconds since epoch. */
     resetsAt?: number;
+    /**
+     * Verb rendered before the {@link resetsAt} countdown (e.g. "tick", "regen").
+     * Defaults to "resets" — override for rolling windows where the timestamp is
+     * an incremental regeneration step rather than a full window reset.
+     */
+    resetLabel?: string;
 }
 /** Quantitative usage data. */
 export interface UsageAmount {
@@ -157,6 +163,7 @@ export declare const usageWindowSchema: import("arktype/internal/variants/object
     label: string;
     durationMs?: number | undefined;
     resetsAt?: number | undefined;
+    resetLabel?: string | undefined;
 }, {}>;
 export declare const usageAmountSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     used?: number | undefined;
@@ -194,6 +201,7 @@ export declare const usageLimitSchema: import("arktype/internal/variants/object.
         label: string;
         durationMs?: number | undefined;
         resetsAt?: number | undefined;
+        resetLabel?: string | undefined;
     } | undefined;
     amount: {
         used?: number | undefined;
@@ -240,6 +248,7 @@ export declare const usageReportSchema: import("arktype/internal/variants/object
             label: string;
             durationMs?: number | undefined;
             resetsAt?: number | undefined;
+            resetLabel?: string | undefined;
         } | undefined;
         amount: {
             used?: number | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.0.8",
+	"version": "17.0.9",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.0.8",
-		"@oh-my-pi/pi-utils": "17.0.8",
-		"@oh-my-pi/pi-wire": "17.0.8",
+		"@oh-my-pi/pi-catalog": "17.0.9",
+		"@oh-my-pi/pi-utils": "17.0.9",
+		"@oh-my-pi/pi-wire": "17.0.9",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-storage.ts

@@ -11,7 +11,7 @@ import { Database, type Statement } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
+import { $env, getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
 import type { ApiKeyResolver } from "./auth-retry";
 import * as AIError from "./error";
 import { isUsageLimitOutcome } from "./error/rate-limit";
@@ -57,6 +57,8 @@ import {
 	listCodexResetCredits,
 } from "./usage/openai-codex-reset";
 import { opencodeGoUsageProvider } from "./usage/opencode-go";
+import { syntheticUsageProvider } from "./usage/synthetic";
+import { xaiOauthUsageProvider } from "./usage/xai-oauth";
 import { zaiRankingStrategy, zaiUsageProvider } from "./usage/zai";
 
 const USAGE_RANKING_METRIC_EPSILON = 1e-9;
@@ -596,6 +598,8 @@ const DEFAULT_USAGE_PROVIDERS: UsageProvider[] = [
 	opencodeGoUsageProvider,
 	githubCopilotUsageProvider,
 	cursorUsageProvider,
+	syntheticUsageProvider,
+	xaiOauthUsageProvider,
 ];
 
 const DEFAULT_USAGE_PROVIDER_MAP = new Map<Provider, UsageProvider>(
@@ -3227,6 +3231,29 @@ export class AuthStorage {
 				entries = dedupedEntries;
 			}
 
+			// SuperGrok billing only accepts OAuth bearers. Catalog envVars for
+			// xai-oauth are [XAI_OAUTH_TOKEN, XAI_API_KEY], so the generic path
+			// would (a) build api_key usage requests from stored keys / the paid
+			// API env var and (b) never fall through to XAI_OAUTH_TOKEN when a
+			// non-OAuth row is the only stored credential. Skip api_key material
+			// and only env-fallback to the dedicated OAuth bearer.
+			if (providerId === "xai-oauth") {
+				let hasUsableStoredOAuthCredential = false;
+				for (const entry of entries) {
+					if (entry.credential.type !== "oauth") continue;
+					const request = this.#buildUsageRequestForOauth(provider, entry.credential, baseUrl);
+					if (providerImpl.supports && !providerImpl.supports(request)) continue;
+					requests.push(request);
+					hasUsableStoredOAuthCredential = true;
+				}
+				const oauthToken = $env.XAI_OAUTH_TOKEN?.trim();
+				if (!hasUsableStoredOAuthCredential && oauthToken) {
+					const request = this.#buildUsageRequest(provider, { type: "oauth", accessToken: oauthToken }, baseUrl);
+					if (!providerImpl.supports || providerImpl.supports(request)) requests.push(request);
+				}
+				continue;
+			}
+
 			if (entries.length === 0) {
 				const runtimeKey = this.#runtimeOverrides.get(providerId);
 				const envKey = getEnvApiKey(providerId);

package/src/index.ts

@@ -39,6 +39,8 @@ export * from "./usage/ollama";
 export * from "./usage/openai-codex";
 export * from "./usage/openai-codex-reset";
 export * from "./usage/opencode-go";
+export * from "./usage/synthetic";
+export * from "./usage/xai-oauth";
 export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/event-stream";

package/src/providers/openai-shared.ts

@@ -2501,6 +2501,7 @@ export async function processResponsesStream<TApi extends Api>(
 			const entry = lookupOpenToolCallAlias(event, "custom_tool_call");
 			if (entry?.item.type === "custom_tool_call" && entry.block.type === "toolCall") {
 				finalizeCustomToolCallInputDone(entry.block, event.input);
+				entry.block[kStreamingArgumentsDone] = true;
 			}
 		} else if (event.type === "response.output_item.done") {
 			const item = structuredCloneJSON(event.item);
@@ -2620,6 +2621,10 @@ export async function processResponsesStream<TApi extends Api>(
 			}
 		} else if (terminalEvent) {
 			const response = terminalEvent.response;
+			const shouldPromoteIncompleteToolUse =
+				response?.status === "incomplete" &&
+				response.incomplete_details?.reason === "max_output_tokens" &&
+				hasExecutableIncompleteResponsesToolCalls(output);
 			finalizePendingResponsesToolCalls(output);
 			if (response?.id) {
 				output.responseId = response.id;
@@ -2656,7 +2661,11 @@ export async function processResponsesStream<TApi extends Api>(
 					kind: "content-blocked",
 				});
 			}
-			promoteResponsesToolUseStopReason(output, (response as { end_turn?: boolean } | undefined)?.end_turn);
+			promoteResponsesToolUseStopReason(
+				output,
+				(response as { end_turn?: boolean } | undefined)?.end_turn,
+				shouldPromoteIncompleteToolUse,
+			);
 			options?.onCompleted?.();
 			// `response.completed`/`response.incomplete`/`response.done` is the last event of a
 			// Responses stream. Stop pulling instead of waiting for the server to
@@ -2712,6 +2721,28 @@ export function mapOpenAIResponsesStopReason(status: ResponseStatus | undefined)
 	}
 }
 
+function hasExecutableIncompleteResponsesToolCalls(output: AssistantMessage): boolean {
+	let hasToolCall = false;
+	for (const block of output.content) {
+		if (block.type !== "toolCall") continue;
+		hasToolCall = true;
+		const pending = block as ToolCall & {
+			[kStreamingPartialJson]?: string;
+			[kStreamingArgumentsDone]?: boolean;
+		};
+		const rawArguments = pending[kStreamingPartialJson];
+		// `output_item.done` is not positive completion proof: our Responses
+		// compatibility encoder force-closes still-open calls before forwarding an
+		// upstream `length` stop. Only an explicit arguments/input-done event sets
+		// this marker; an open ordinary call can instead prove completion with its
+		// retained strict-complete JSON.
+		if (pending[kStreamingArgumentsDone]) continue;
+		if (pending.customWireName !== undefined || rawArguments === undefined) return false;
+		if (classifyJsonPrefix(rawArguments) !== "complete") return false;
+	}
+	return hasToolCall;
+}
+
 /**
  * Finalize any streamed toolCall block whose `output_item.done` never arrived
  * (lossy proxy, or a terminal event that raced the per-item done): parse the
@@ -2745,8 +2776,15 @@ export function finalizePendingResponsesToolCalls(output: AssistantMessage): voi
  * re-samples instead of ending. Callers set `output.stopReason` from the wire
  * status first via {@link mapOpenAIResponsesStopReason}.
  */
-export function promoteResponsesToolUseStopReason(output: AssistantMessage, endTurn: boolean | undefined): void {
-	if (output.content.some(block => block.type === "toolCall") && output.stopReason === "stop") {
+export function promoteResponsesToolUseStopReason(
+	output: AssistantMessage,
+	endTurn: boolean | undefined,
+	promoteIncompleteToolUse = false,
+): void {
+	if (
+		output.content.some(block => block.type === "toolCall") &&
+		(output.stopReason === "stop" || (promoteIncompleteToolUse && output.stopReason === "length"))
+	) {
 		output.stopReason = "toolUse";
 	}
 	if (endTurn === false && output.stopReason === "stop") {

package/src/registry/oauth/__tests__/xai-oauth.test.ts

@@ -1,19 +1,35 @@
 import { afterEach, describe, expect, it, vi } from "bun:test";
-import { isXAIAccessTokenExpiring, loginXAIOAuth, refreshXAIOAuthToken, validateXAIEndpoint } from "../xai-oauth";
+import {
+	buildXAICliBillingUrl,
+	extractXAIAccessTokenSubject,
+	fetchXAIOAuthIdentity,
+	getXAICliBillingHeaders,
+	isXAIAccessTokenExpiring,
+	loginXAIOAuth,
+	parseXAIAccessTokenPayload,
+	refreshXAIOAuthToken,
+	validateXAIBillingEndpoint,
+	validateXAIEndpoint,
+} from "../xai-oauth";
 
 afterEach(() => {
 	vi.restoreAllMocks();
 });
 
 function jwtWithExp(exp: number): string {
+	return jwtWithPayload({ exp });
+}
+
+function jwtWithPayload(payload: Record<string, unknown>): string {
 	const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
-	const payload = Buffer.from(JSON.stringify({ exp })).toString("base64url");
-	return `${header}.${payload}.sig`;
+	const encodedPayload = Buffer.from(JSON.stringify(payload)).toString("base64url");
+	return `${header}.${encodedPayload}.sig`;
 }
 
 const DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
 const DEVICE_CODE_URL = "https://auth.x.ai/oauth2/device/code";
 const TOKEN_ENDPOINT = "https://auth.x.ai/oauth2/token";
+const USERINFO_URL = "https://auth.x.ai/oauth2/userinfo";
 const CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 const SCOPE = "openid profile email offline_access grok-cli:access api:access";
 
@@ -43,7 +59,10 @@ function jsonResponse(body: unknown, status: number = 200): Response {
 	});
 }
 
-function createDeviceFlowFetch(tokenResponses: readonly TokenResponse[]) {
+function createDeviceFlowFetch(
+	tokenResponses: readonly TokenResponse[],
+	userinfoResponse: TokenResponse = { body: {} },
+) {
 	const requests: RecordedRequest[] = [];
 	let tokenResponseIndex = 0;
 	const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
@@ -64,6 +83,9 @@ function createDeviceFlowFetch(tokenResponses: readonly TokenResponse[]) {
 			}
 			return jsonResponse(tokenResponse.body, tokenResponse.status);
 		}
+		if (url === USERINFO_URL) {
+			return jsonResponse(userinfoResponse.body, userinfoResponse.status);
+		}
 		throw new Error(`Unexpected xAI OAuth request: ${url}`);
 	});
 
@@ -101,6 +123,109 @@ describe("isXAIAccessTokenExpiring", () => {
 	});
 });
 
+describe("xAI OAuth helpers", () => {
+	it("parses JWT payloads and extracts subjects", () => {
+		const token = jwtWithPayload({ sub: " subject-123 ", exp: 1_900_000_000 });
+
+		expect(parseXAIAccessTokenPayload(token)).toEqual({ sub: " subject-123 ", exp: 1_900_000_000 });
+		expect(extractXAIAccessTokenSubject(token)).toBe("subject-123");
+		expect(parseXAIAccessTokenPayload("not-a-jwt")).toBeNull();
+		expect(extractXAIAccessTokenSubject("not-a-jwt")).toBeUndefined();
+	});
+
+	it("builds the billing URL and CLI-aligned headers", () => {
+		expect(buildXAICliBillingUrl()).toBe("https://cli-chat-proxy.grok.com/v1/billing?format=credits");
+		expect(buildXAICliBillingUrl("tokens")).toBe("https://cli-chat-proxy.grok.com/v1/billing?format=tokens");
+		expect(getXAICliBillingHeaders({ accessToken: "access-token" })).toEqual({
+			Authorization: "Bearer access-token",
+			Accept: "application/json",
+			"X-XAI-Token-Auth": "xai-grok-cli",
+		});
+	});
+
+	it("pins SuperGrok billing URLs to https grok.com hosts", () => {
+		expect(validateXAIBillingEndpoint("https://cli-chat-proxy.grok.com/v1/billing")).toBe(
+			"https://cli-chat-proxy.grok.com/v1/billing",
+		);
+		expect(() => validateXAIBillingEndpoint("https://auth.x.ai/v1/billing")).toThrow(/Invalid xAI billing_url/);
+		expect(() => validateXAIBillingEndpoint("http://cli-chat-proxy.grok.com/v1/billing")).toThrow(
+			/Invalid xAI billing_url/,
+		);
+		expect(() => validateXAIBillingEndpoint("https://evil.com/v1/billing")).toThrow(/Invalid xAI billing_url/);
+	});
+
+	it("normalizes OIDC userinfo identity", async () => {
+		const requests: RecordedRequest[] = [];
+		const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+			requests.push({
+				url: typeof input === "string" ? input : input instanceof Request ? input.url : input.toString(),
+				init,
+			});
+			return jsonResponse({ sub: "profile-sub", email: "User@Example.com", name: "User" });
+		});
+
+		await expect(fetchXAIOAuthIdentity("access-token", fetchMock as unknown as typeof fetch)).resolves.toEqual({
+			accountId: "profile-sub",
+			email: "user@example.com",
+			name: "User",
+		});
+		expect(requests[0]?.url).toBe(USERINFO_URL);
+		expect(new Headers(requests[0]?.init?.headers)).toEqual(
+			new Headers({ Authorization: "Bearer access-token", Accept: "application/json" }),
+		);
+		expect(requests[0]?.init?.redirect).toBe("error");
+	});
+
+	it("combines caller cancellation with the 15-second userinfo timeout", async () => {
+		const timeoutControllers: AbortController[] = [];
+		const timeoutSpy = vi.spyOn(AbortSignal, "timeout").mockImplementation(timeoutMs => {
+			expect(timeoutMs).toBe(15_000);
+			const controller = new AbortController();
+			timeoutControllers.push(controller);
+			return controller.signal;
+		});
+		const requests: RecordedRequest[] = [];
+		const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+			requests.push({
+				url: typeof input === "string" ? input : input instanceof Request ? input.url : input.toString(),
+				init,
+			});
+			const { promise, reject } = Promise.withResolvers<Response>();
+			const requestSignal = init?.signal;
+			if (!requestSignal) {
+				reject(new Error("expected userinfo request signal"));
+			} else if (requestSignal.aborted) {
+				reject(requestSignal.reason);
+			} else {
+				requestSignal.addEventListener("abort", () => reject(requestSignal.reason), { once: true });
+			}
+			return promise;
+		});
+
+		const callerController = new AbortController();
+		const callerCancelled = fetchXAIOAuthIdentity(
+			"access-token",
+			fetchMock as unknown as typeof fetch,
+			callerController.signal,
+		);
+		callerController.abort();
+		await expect(callerCancelled).resolves.toBeNull();
+		expect(requests[0]?.init?.signal).not.toBe(callerController.signal);
+
+		expect(timeoutSpy).toHaveBeenCalledWith(15_000);
+		const timeoutCancelled = fetchXAIOAuthIdentity(
+			"access-token",
+			fetchMock as unknown as typeof fetch,
+			new AbortController().signal,
+		);
+		const timeoutController = timeoutControllers[1];
+		expect(timeoutController).toBeDefined();
+		timeoutController?.abort();
+		await expect(timeoutCancelled).resolves.toBeNull();
+		expect(requests[1]?.init?.signal).not.toBe(timeoutController?.signal);
+	});
+});
+
 describe("validateXAIEndpoint", () => {
 	it("rejects non-HTTPS URLs", () => {
 		expect(() => validateXAIEndpoint("http://x.ai/token", "token_endpoint")).toThrow(/Invalid xAI token_endpoint/);
@@ -131,6 +256,35 @@ describe("refreshXAIOAuthToken", () => {
 		);
 		expect(fetchMock).not.toHaveBeenCalled();
 	});
+
+	it("persists refreshed OAuth identity from OIDC userinfo", async () => {
+		const accessToken = jwtWithPayload({ sub: "jwt-sub" });
+		const requests: RecordedRequest[] = [];
+		const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+			const url = typeof input === "string" ? input : input instanceof Request ? input.url : input.toString();
+			requests.push({ url, init });
+			if (url === DISCOVERY_URL) return jsonResponse({ token_endpoint: TOKEN_ENDPOINT });
+			if (url === TOKEN_ENDPOINT) {
+				return jsonResponse({
+					access_token: accessToken,
+					expires_in: 3600,
+				});
+			}
+			if (url === USERINFO_URL) return jsonResponse({ sub: "profile-sub", email: "User@Example.com" });
+			throw new Error(`Unexpected xAI OAuth request: ${url}`);
+		});
+
+		await expect(
+			refreshXAIOAuthToken("old-refresh-token", fetchMock as unknown as typeof fetch),
+		).resolves.toMatchObject({
+			access: accessToken,
+			refresh: "old-refresh-token",
+			accountId: "profile-sub",
+			email: "user@example.com",
+		});
+		expect(requests.map(request => request.url)).toEqual([DISCOVERY_URL, TOKEN_ENDPOINT, USERINFO_URL]);
+		expect(requests.find(request => request.url === TOKEN_ENDPOINT)?.init?.redirect).toBe("error");
+	});
 });
 
 describe("loginXAIOAuth", () => {
@@ -165,7 +319,12 @@ describe("loginXAIOAuth", () => {
 			onManualCodeInput,
 		});
 
-		expect(requests.map(request => request.url)).toEqual([DISCOVERY_URL, DEVICE_CODE_URL, TOKEN_ENDPOINT]);
+		expect(requests.map(request => request.url)).toEqual([
+			DISCOVERY_URL,
+			DEVICE_CODE_URL,
+			TOKEN_ENDPOINT,
+			USERINFO_URL,
+		]);
 
 		const discoveryRequest = requests[0];
 		expect(discoveryRequest?.init?.method).toBe("GET");
@@ -230,6 +389,7 @@ describe("loginXAIOAuth", () => {
 
 		const tokenRequests = requests.filter(request => request.url === TOKEN_ENDPOINT);
 		expect(tokenRequests).toHaveLength(3);
+		expect(tokenRequests.every(request => request.init?.redirect === "error")).toBe(true);
 		expect(tokenRequests.map(request => Object.fromEntries(requestForm(request)))).toEqual([
 			{
 				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
@@ -252,6 +412,54 @@ describe("loginXAIOAuth", () => {
 		expect(credentials.refresh).toBe("eventual-refresh-token");
 	});
 
+	it("retains the JWT subject and succeeds when OIDC userinfo fails", async () => {
+		const accessToken = jwtWithPayload({ sub: "jwt-sub" });
+		const controller = new AbortController();
+		const { fetchMock, requests } = createDeviceFlowFetch(
+			[
+				{
+					body: {
+						access_token: accessToken,
+						refresh_token: "refresh-token",
+						expires_in: 3600,
+					},
+				},
+			],
+			{ body: { error: "userinfo unavailable" }, status: 503 },
+		);
+
+		const credentials = await loginXAIOAuth({ fetch: fetchMock, signal: controller.signal });
+
+		expect(credentials).toMatchObject({
+			access: accessToken,
+			refresh: "refresh-token",
+			accountId: "jwt-sub",
+		});
+		expect(requests.at(-1)?.url).toBe(USERINFO_URL);
+		expect(requests.at(-1)?.init?.signal).not.toBe(controller.signal);
+	});
+
+	it("keeps the JWT subject when userinfo returns only an email", async () => {
+		const accessToken = jwtWithPayload({ sub: "jwt-sub" });
+		const { fetchMock } = createDeviceFlowFetch(
+			[
+				{
+					body: {
+						access_token: accessToken,
+						refresh_token: "refresh-token",
+						expires_in: 3600,
+					},
+				},
+			],
+			{ body: { email: "User@Example.com" } },
+		);
+
+		await expect(loginXAIOAuth({ fetch: fetchMock })).resolves.toMatchObject({
+			accountId: "jwt-sub",
+			email: "user@example.com",
+		});
+	});
+
 	it("rejects a token response that omits access_token", async () => {
 		const { fetchMock, requests } = createDeviceFlowFetch([
 			{

package/src/registry/oauth/xai-oauth.ts

@@ -15,8 +15,12 @@ import type { OAuthController, OAuthCredentials } from "./types";
 const XAI_OAUTH_ISSUER = "https://auth.x.ai";
 const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
 const XAI_OAUTH_DEVICE_CODE_URL = `${XAI_OAUTH_ISSUER}/oauth2/device/code`;
+const XAI_OAUTH_USERINFO_URL = `${XAI_OAUTH_ISSUER}/oauth2/userinfo`;
 const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
 const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+const XAI_CLI_BILLING_BASE_URL = "https://cli-chat-proxy.grok.com";
+const XAI_CLI_BILLING_PATH = "/v1/billing";
+const XAI_CLI_BILLING_FORMAT = "credits";
 
 // Mirrors the 5-min skew used by anthropic.ts:160 — keeps every provider on the
 // same conservative client-side expiry window.
@@ -51,6 +55,15 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  * @throws Error with message `Invalid xAI <field>: <url>` when the URL fails
  *         either scheme or host validation.
  */
+function isXaiAuthHostname(host: string): boolean {
+	return host === "x.ai" || host.endsWith(".x.ai");
+}
+
+/** SuperGrok CLI billing proxy host (`cli-chat-proxy.grok.com`), not the OIDC issuer. */
+function isXaiBillingHostname(host: string): boolean {
+	return host === "grok.com" || host.endsWith(".grok.com");
+}
+
 export function validateXAIEndpoint(url: string, field: string): string {
 	let parsed: URL;
 	try {
@@ -62,7 +75,28 @@ export function validateXAIEndpoint(url: string, field: string): string {
 		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
 	}
 	const host = parsed.hostname.toLowerCase();
-	if (!host || (host !== "x.ai" && !host.endsWith(".x.ai"))) {
+	if (!host || !isXaiAuthHostname(host)) {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	return url;
+}
+
+/**
+ * Pin SuperGrok billing URLs to HTTPS `grok.com` / `*.grok.com`.
+ * The CLI billing proxy is intentionally not on `*.x.ai`.
+ */
+export function validateXAIBillingEndpoint(url: string, field: string = "billing_url"): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	if (parsed.protocol !== "https:") {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	const host = parsed.hostname.toLowerCase();
+	if (!host || !isXaiBillingHostname(host)) {
 		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
 	}
 	return url;
@@ -124,6 +158,22 @@ async function xaiOAuthDiscovery(
 	return { token_endpoint: tokenEndpoint };
 }
 
+/** Decode an xAI access-token JWT payload without verifying its signature. */
+export function parseXAIAccessTokenPayload(jwt: string): Record<string, unknown> | null {
+	try {
+		if (typeof jwt !== "string" || !jwt.includes(".")) return null;
+		const parts = jwt.split(".");
+		if (parts.length < 2) return null;
+		const payloadPart = parts[1];
+		if (!payloadPart) return null;
+		const decoded = Buffer.from(payloadPart, "base64url").toString("utf8");
+		const payload = JSON.parse(decoded) as unknown;
+		return isRecord(payload) && !Array.isArray(payload) ? payload : null;
+	} catch {
+		return null;
+	}
+}
+
 /**
  * Check whether a JWT access token is at or past its `exp` claim (with an
  * optional refresh-skew margin).
@@ -132,25 +182,100 @@ async function xaiOAuthDiscovery(
  * not token validation.
  */
 export function isXAIAccessTokenExpiring(jwt: string, skewSeconds: number = 0): boolean {
+	const payload = parseXAIAccessTokenPayload(jwt);
+	if (!payload) return false;
+	const exp = payload.exp;
+	if (typeof exp !== "number" || !Number.isFinite(exp)) return false;
+	const now = Math.floor(Date.now() / 1000);
+	const skew = Math.max(0, Math.floor(skewSeconds));
+	return exp <= now + skew;
+}
+
+/** Extract the stable xAI subject UUID from an access token. */
+export function extractXAIAccessTokenSubject(jwt: string): string | undefined {
+	const sub = parseXAIAccessTokenPayload(jwt)?.sub;
+	return typeof sub === "string" && sub.trim() ? sub.trim() : undefined;
+}
+
+export interface XAIOAuthIdentity {
+	accountId?: string;
+	email?: string;
+	name?: string;
+}
+
+/** Fetch optional OIDC userinfo for a valid xAI access token. */
+export async function fetchXAIOAuthIdentity(
+	accessToken: string,
+	fetchOverride?: FetchImpl,
+	signal?: AbortSignal,
+): Promise<XAIOAuthIdentity | null> {
+	const token = accessToken.trim();
+	if (!token) return null;
+	const fetchImpl = fetchOverride ?? fetch;
 	try {
-		if (typeof jwt !== "string" || !jwt.includes(".")) return false;
-		const parts = jwt.split(".");
-		if (parts.length < 2) return false;
-		const payloadPart = parts[1];
-		if (!payloadPart) return false;
-		const decoded = Buffer.from(payloadPart, "base64url").toString("utf8");
-		const payload: unknown = JSON.parse(decoded);
-		if (!isRecord(payload)) return false;
-		const exp = payload.exp;
-		if (typeof exp !== "number" || !Number.isFinite(exp)) return false;
-		const now = Math.floor(Date.now() / 1000);
-		const skew = Math.max(0, Math.floor(skewSeconds));
-		return exp <= now + skew;
+		const response = await fetchImpl(XAI_OAUTH_USERINFO_URL, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/json",
+			},
+			redirect: "error",
+			signal: signal
+				? AbortSignal.any([signal, AbortSignal.timeout(DISCOVERY_TIMEOUT_MS)])
+				: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
+		});
+		if (!response.ok) return null;
+		const payload = (await response.json()) as unknown;
+		if (!isRecord(payload) || Array.isArray(payload)) return null;
+		const sub = typeof payload.sub === "string" && payload.sub.trim() ? payload.sub.trim() : undefined;
+		const email = typeof payload.email === "string" && payload.email.trim() ? payload.email.trim() : undefined;
+		const name = typeof payload.name === "string" && payload.name.trim() ? payload.name.trim() : undefined;
+		if (!sub && !email && !name) return null;
+		return {
+			...(sub ? { accountId: sub } : {}),
+			...(email ? { email: email.toLowerCase() } : {}),
+			...(name ? { name } : {}),
+		};
 	} catch {
-		return false;
+		return null;
 	}
 }
 
+async function withXAIOAuthIdentity(
+	credentials: OAuthCredentials,
+	fetchOverride?: FetchImpl,
+	signal?: AbortSignal,
+): Promise<OAuthCredentials> {
+	const identity = await fetchXAIOAuthIdentity(credentials.access, fetchOverride, signal);
+	const accountId = identity?.accountId ?? credentials.accountId ?? extractXAIAccessTokenSubject(credentials.access);
+	const email = identity?.email ?? credentials.email;
+	return {
+		...credentials,
+		...(accountId ? { accountId } : {}),
+		...(email ? { email } : {}),
+	};
+}
+
+/** Build the SuperGrok CLI billing URL. */
+export function buildXAICliBillingUrl(format: string = XAI_CLI_BILLING_FORMAT): string {
+	const url = new URL(XAI_CLI_BILLING_PATH, XAI_CLI_BILLING_BASE_URL);
+	url.searchParams.set("format", format);
+	return validateXAIBillingEndpoint(url.toString());
+}
+
+/**
+ * Headers for SuperGrok CLI billing (`cli-chat-proxy.grok.com`).
+ * Official Grok CLI also sends `X-XAI-Token-Auth: xai-grok-cli` on this host;
+ * include it so billing stays on the same product gate as chat inference.
+ */
+export function getXAICliBillingHeaders(options: { accessToken: string }): Record<string, string> {
+	return {
+		Authorization: `Bearer ${options.accessToken}`,
+		Accept: "application/json",
+		"X-XAI-Token-Auth": "xai-grok-cli",
+	};
+}
+
 function parseXAIDeviceAuthorization(payload: unknown): XAIDeviceAuthorization {
 	if (!isRecord(payload)) {
 		throw new AIError.OAuthError("xAI device-code response was not a JSON object.", {
@@ -304,6 +429,7 @@ async function pollXAIDeviceToken(
 				client_id: XAI_OAUTH_CLIENT_ID,
 				device_code: deviceCode,
 			}),
+			redirect: "error",
 			signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
 		});
 	} catch (error) {
@@ -364,12 +490,13 @@ export async function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCredent
 	});
 	ctrl.onProgress?.("Waiting for xAI device authorization...");
 
-	return pollOAuthDeviceCodeFlow({
+	const credentials = await pollOAuthDeviceCodeFlow({
 		poll: () => pollXAIDeviceToken(discovery.token_endpoint, device.deviceCode, fetchImpl, ctrl.signal),
 		intervalSeconds: device.intervalSeconds,
 		expiresInSeconds: device.expiresInSeconds,
 		signal: ctrl.signal,
 	});
+	return withXAIOAuthIdentity(credentials, fetchImpl, ctrl.signal);
 }
 
 /**
@@ -400,6 +527,7 @@ export async function refreshXAIOAuthToken(refreshToken: string, fetchOverride?:
 			Accept: "application/json",
 		},
 		body,
+		redirect: "error",
 		signal: AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS),
 	});
 
@@ -426,5 +554,6 @@ export async function refreshXAIOAuthToken(refreshToken: string, fetchOverride?:
 			{ kind: "validation", provider: "xai", cause: error },
 		);
 	}
-	return parseXAITokenResponse(payload, "xAI token refresh response", refreshToken);
+	const credentials = parseXAITokenResponse(payload, "xAI token refresh response", refreshToken);
+	return withXAIOAuthIdentity(credentials, fetchImpl);
 }

package/src/usage/synthetic.ts

@@ -0,0 +1,180 @@
+import { isRecord } from "@oh-my-pi/pi-utils/type-guards";
+import type {
+	UsageAmount,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+	UsageStatus,
+	UsageWindow,
+} from "../usage";
+
+const QUOTAS_URL = "https://api.synthetic.new/v2/quotas";
+const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+function parseDollarAmount(value: unknown): number | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.replace(/^\$/, "").trim();
+	const parsed = Number(trimmed);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parseIsoMs(value: unknown): number | undefined {
+	if (typeof value !== "string" || !value) return undefined;
+	const ms = Date.parse(value);
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+function buildUsageAmount(args: {
+	used: number | undefined;
+	limit: number | undefined;
+	remaining: number | undefined;
+	usedFraction: number | undefined;
+	unit: UsageAmount["unit"];
+}): UsageAmount {
+	let usedFraction = args.usedFraction;
+	if (usedFraction === undefined && args.used !== undefined && args.limit !== undefined && args.limit > 0) {
+		usedFraction = Math.min(args.used / args.limit, 1);
+	}
+	const remainingFraction = usedFraction !== undefined ? Math.max(1 - usedFraction, 0) : undefined;
+	return {
+		...(args.used !== undefined ? { used: args.used } : {}),
+		...(args.limit !== undefined ? { limit: args.limit } : {}),
+		...(args.remaining !== undefined ? { remaining: args.remaining } : {}),
+		...(usedFraction !== undefined ? { usedFraction } : {}),
+		...(remainingFraction !== undefined ? { remainingFraction } : {}),
+		unit: args.unit,
+	};
+}
+
+function getUsageStatus(usedFraction: number | undefined): UsageStatus | undefined {
+	if (usedFraction === undefined) return undefined;
+	if (usedFraction >= 1) return "exhausted";
+	if (usedFraction >= 0.9) return "warning";
+	return "ok";
+}
+
+function parseRollingFiveHourLimit(raw: unknown, provider: UsageFetchParams["provider"]): UsageLimit | null {
+	if (!isRecord(raw)) return null;
+	const remaining = typeof raw.remaining === "number" ? raw.remaining : undefined;
+	const max = typeof raw.max === "number" ? raw.max : undefined;
+	const limited = raw.limited === true;
+	const nextTickAt = parseIsoMs(raw.nextTickAt);
+	const tickPercent = typeof raw.tickPercent === "number" ? raw.tickPercent : undefined;
+
+	if (remaining === undefined && max === undefined) return null;
+
+	const used = max !== undefined && remaining !== undefined ? max - remaining : undefined;
+	const regenPercent = tickPercent !== undefined ? Number((tickPercent * 100).toFixed(2)) : undefined;
+	const window: UsageWindow = {
+		id: "5h",
+		label: regenPercent !== undefined ? `5h · regen ${regenPercent}%/tick` : "5h",
+		durationMs: FIVE_HOUR_MS,
+		...(nextTickAt !== undefined ? { resetsAt: nextTickAt, resetLabel: "tick" } : {}),
+	};
+	const amount = buildUsageAmount({
+		used,
+		limit: max,
+		remaining,
+		usedFraction: undefined,
+		unit: "requests",
+	});
+	const status: UsageStatus = limited ? "exhausted" : (getUsageStatus(amount.usedFraction) ?? "ok");
+	return {
+		id: "synthetic:requests:5h",
+		label: "Synthetic Requests",
+		scope: { provider, windowId: "5h", shared: true },
+		window,
+		amount,
+		status,
+	};
+}
+
+function parseWeeklyTokenLimit(raw: unknown, provider: UsageFetchParams["provider"]): UsageLimit | null {
+	if (!isRecord(raw)) return null;
+	const remainingCredits = parseDollarAmount(raw.remainingCredits);
+	const maxCredits = parseDollarAmount(raw.maxCredits);
+	const percentRemaining = typeof raw.percentRemaining === "number" ? raw.percentRemaining : undefined;
+	const nextRegenAt = parseIsoMs(raw.nextRegenAt);
+
+	if (remainingCredits === undefined && maxCredits === undefined) return null;
+
+	const usedFraction =
+		percentRemaining !== undefined ? Math.min(Math.max(1 - percentRemaining / 100, 0), 1) : undefined;
+	const used = usedFraction !== undefined && maxCredits !== undefined ? usedFraction * maxCredits : undefined;
+	const nextRegenCredits = parseDollarAmount(raw.nextRegenCredits);
+	const window: UsageWindow = {
+		id: "7d",
+		label: nextRegenCredits !== undefined ? `7d · regen $${nextRegenCredits.toFixed(2)}/tick` : "7d",
+		durationMs: WEEK_MS,
+		...(nextRegenAt !== undefined ? { resetsAt: nextRegenAt, resetLabel: "regen" } : {}),
+	};
+	const amount = buildUsageAmount({
+		used,
+		limit: maxCredits,
+		remaining: remainingCredits,
+		usedFraction,
+		unit: "usd",
+	});
+	return {
+		id: "synthetic:usd:7d",
+		label: "Synthetic Credits",
+		scope: { provider, windowId: "7d", shared: true },
+		window,
+		amount,
+		status: getUsageStatus(amount.usedFraction),
+	};
+}
+
+async function fetchSyntheticUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+	if (params.provider !== "synthetic") return null;
+	const credential = params.credential;
+	if (credential.type !== "api_key" || !credential.apiKey) return null;
+
+	let payload: unknown = null;
+	try {
+		const response = await ctx.fetch(QUOTAS_URL, {
+			headers: {
+				Authorization: `Bearer ${credential.apiKey}`,
+				"Content-Type": "application/json",
+			},
+			signal: params.signal,
+		});
+		if (!response.ok) {
+			ctx.logger?.warn("Synthetic usage fetch failed", { status: response.status, statusText: response.statusText });
+			return null;
+		}
+		payload = await response.json();
+	} catch (error) {
+		ctx.logger?.warn("Synthetic usage fetch error", { error: String(error) });
+		return null;
+	}
+
+	if (!isRecord(payload)) return null;
+
+	const limits: UsageLimit[] = [];
+
+	const fiveHour = parseRollingFiveHourLimit(payload.rollingFiveHourLimit, params.provider);
+	if (fiveHour) limits.push(fiveHour);
+
+	const weekly = parseWeeklyTokenLimit(payload.weeklyTokenLimit, params.provider);
+	if (weekly) limits.push(weekly);
+
+	if (limits.length === 0) return null;
+
+	return {
+		provider: params.provider,
+		fetchedAt: Date.now(),
+		limits,
+		metadata: { endpoint: QUOTAS_URL },
+		raw: payload,
+	};
+}
+
+export const syntheticUsageProvider: UsageProvider = {
+	id: "synthetic",
+	fetchUsage: fetchSyntheticUsage,
+	supports: params => params.provider === "synthetic" && params.credential.type === "api_key",
+};

package/src/usage/xai-oauth.ts

@@ -0,0 +1,256 @@
+/**
+ * SuperGrok (`xai-oauth`) subscription usage provider.
+ *
+ * Reads weekly credit and product utilization from the Grok CLI billing
+ * endpoint. Only OAuth access credentials are accepted; paid API keys are a
+ * separate product and must never be sent here.
+ */
+
+import {
+	buildXAICliBillingUrl,
+	extractXAIAccessTokenSubject,
+	fetchXAIOAuthIdentity,
+	getXAICliBillingHeaders,
+} from "../registry/oauth/xai-oauth";
+import type {
+	UsageAmount,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+	UsageStatus,
+	UsageWindow,
+} from "../usage";
+import { isRecord } from "../utils";
+import { toNumber } from "./shared";
+
+const PROVIDER_ID = "xai-oauth";
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+interface XaiBillingPeriod {
+	start: string;
+	end: string;
+	type: string;
+}
+
+interface XaiProductUsage {
+	product: string;
+	usagePercent: number;
+}
+
+interface XaiBillingConfig {
+	currentPeriod: XaiBillingPeriod;
+	creditUsagePercent: number;
+	productUsage: XaiProductUsage[];
+	onDemandCap?: number;
+	onDemandUsed?: number;
+}
+
+function parseIsoMs(value: string): number | undefined {
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function parsePercent(value: unknown): number | undefined {
+	const percent = toNumber(value);
+	return percent !== undefined && percent >= 0 && percent <= 100 ? percent : undefined;
+}
+
+function parseOnDemandAmount(value: unknown): number | undefined {
+	if (!isRecord(value)) return undefined;
+	const amount = toNumber(value.val);
+	return amount !== undefined && amount >= 0 ? amount : undefined;
+}
+
+function buildPercentAmount(usagePercent: number): UsageAmount {
+	const usedFraction = usagePercent / 100;
+	return {
+		used: usagePercent,
+		limit: 100,
+		remaining: 100 - usagePercent,
+		usedFraction,
+		remainingFraction: 1 - usedFraction,
+		unit: "percent",
+	};
+}
+
+function buildUsageStatus(usedFraction: number): UsageStatus {
+	if (usedFraction >= 1) return "exhausted";
+	if (usedFraction >= 0.9) return "warning";
+	return "ok";
+}
+
+function slugifyProduct(product: string): string {
+	return product
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+function buildPeriodWindow(period: XaiBillingPeriod): UsageWindow {
+	return {
+		id: "1w",
+		label: "Weekly",
+		durationMs: WEEK_MS,
+		resetsAt: parseIsoMs(period.end),
+	};
+}
+
+function parseBillingConfig(payload: unknown): XaiBillingConfig | null {
+	if (!isRecord(payload) || !isRecord(payload.config)) return null;
+	const raw = payload.config;
+	if (!isRecord(raw.currentPeriod)) return null;
+
+	const start = typeof raw.currentPeriod.start === "string" ? parseIsoMs(raw.currentPeriod.start) : undefined;
+	const end = typeof raw.currentPeriod.end === "string" ? parseIsoMs(raw.currentPeriod.end) : undefined;
+	const type = typeof raw.currentPeriod.type === "string" ? raw.currentPeriod.type : "";
+	// Keep recently-ended weekly windows so /usage still renders across period
+	// rollover while the billing API is mid-refresh. Reject only inverted ranges
+	// and non-weekly period types.
+	if (start === undefined || end === undefined || end <= start || !type.toUpperCase().includes("WEEK")) {
+		return null;
+	}
+
+	const creditUsagePercent = parsePercent(raw.creditUsagePercent);
+	if (creditUsagePercent === undefined) return null;
+
+	const productUsage: XaiProductUsage[] = [];
+	if (raw.productUsage !== undefined) {
+		if (!Array.isArray(raw.productUsage)) return null;
+		for (const item of raw.productUsage) {
+			if (!isRecord(item)) continue;
+			const product = typeof item.product === "string" ? item.product.trim() : "";
+			const usagePercent = parsePercent(item.usagePercent);
+			if (!product || usagePercent === undefined) continue;
+			productUsage.push({ product, usagePercent });
+		}
+	}
+
+	return {
+		currentPeriod: {
+			start: raw.currentPeriod.start as string,
+			end: raw.currentPeriod.end as string,
+			type,
+		},
+		creditUsagePercent,
+		productUsage,
+		onDemandCap: parseOnDemandAmount(raw.onDemandCap),
+		onDemandUsed: parseOnDemandAmount(raw.onDemandUsed),
+	};
+}
+
+function buildLimits(config: XaiBillingConfig, accountId: string | undefined): UsageLimit[] {
+	const window = buildPeriodWindow(config.currentPeriod);
+	const scope = {
+		provider: PROVIDER_ID,
+		...(accountId ? { accountId } : {}),
+		windowId: window.id,
+		shared: true as const,
+	};
+	const overall = buildPercentAmount(config.creditUsagePercent);
+	const limits: UsageLimit[] = [
+		{
+			id: `${PROVIDER_ID}:credits:1w`,
+			label: "SuperGrok Weekly Credits",
+			scope,
+			window,
+			amount: overall,
+			status: buildUsageStatus(overall.usedFraction ?? 0),
+		},
+	];
+
+	for (const item of config.productUsage) {
+		const amount = buildPercentAmount(item.usagePercent);
+		const slug = slugifyProduct(item.product);
+		if (!slug) continue;
+		limits.push({
+			id: `${PROVIDER_ID}:product:${slug}:1w`,
+			label: `${item.product === "GrokBuild" ? "Grok Build" : item.product === "Api" ? "API" : item.product} (Weekly)`,
+			scope,
+			window,
+			amount,
+			status: buildUsageStatus(amount.usedFraction ?? 0),
+		});
+	}
+	if (config.onDemandCap !== undefined && config.onDemandCap > 0 && config.onDemandUsed !== undefined) {
+		const usedFraction = Math.min(config.onDemandUsed / config.onDemandCap, 1);
+		limits.push({
+			id: `${PROVIDER_ID}:on-demand`,
+			label: "On-demand",
+			scope: {
+				provider: PROVIDER_ID,
+				...(accountId ? { accountId } : {}),
+				shared: true,
+			},
+			amount: {
+				used: config.onDemandUsed,
+				limit: config.onDemandCap,
+				remaining: Math.max(0, config.onDemandCap - config.onDemandUsed),
+				usedFraction,
+				remainingFraction: 1 - usedFraction,
+				unit: "unknown",
+			},
+			status: buildUsageStatus(usedFraction),
+		});
+	}
+
+	return limits;
+}
+
+export const xaiOauthUsageProvider: UsageProvider = {
+	id: PROVIDER_ID,
+
+	supports(params: UsageFetchParams): boolean {
+		return params.provider === PROVIDER_ID && params.credential.type === "oauth" && !!params.credential.accessToken;
+	},
+
+	async fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+		if (params.provider !== PROVIDER_ID || params.credential.type !== "oauth") return null;
+		const accessToken = params.credential.accessToken?.trim();
+		if (!accessToken) return null;
+		if (params.credential.expiresAt !== undefined && params.credential.expiresAt <= Date.now()) return null;
+
+		let accountId = params.credential.accountId?.trim() || extractXAIAccessTokenSubject(accessToken);
+		let email = params.credential.email?.trim().toLowerCase();
+		if (!email) {
+			try {
+				const identity = await fetchXAIOAuthIdentity(accessToken, ctx.fetch, params.signal);
+				email = identity?.email?.trim().toLowerCase() || undefined;
+				accountId ??= identity?.accountId?.trim() || undefined;
+			} catch {
+				// Identity enrichment is best effort; billing remains authoritative.
+			}
+		}
+
+		const url = buildXAICliBillingUrl();
+		let payload: unknown;
+		try {
+			const response = await ctx.fetch(url, {
+				headers: getXAICliBillingHeaders({ accessToken }),
+				redirect: "error",
+				signal: params.signal,
+			});
+			if (!response.ok) return null;
+			payload = await response.json();
+		} catch {
+			return null;
+		}
+
+		const config = parseBillingConfig(payload);
+		if (!config) return null;
+		return {
+			provider: PROVIDER_ID,
+			fetchedAt: Date.now(),
+			limits: buildLimits(config, accountId),
+			metadata: {
+				endpoint: url,
+				source: "cli-chat-proxy.grok.com/v1/billing",
+				...(accountId ? { accountId } : {}),
+				...(email ? { email } : {}),
+			},
+			raw: payload,
+		};
+	},
+};

package/src/usage.ts

@@ -20,6 +20,12 @@ export interface UsageWindow {
 	durationMs?: number;
 	/** Absolute reset timestamp in milliseconds since epoch. */
 	resetsAt?: number;
+	/**
+	 * Verb rendered before the {@link resetsAt} countdown (e.g. "tick", "regen").
+	 * Defaults to "resets" — override for rolling windows where the timestamp is
+	 * an incremental regeneration step rather than a full window reset.
+	 */
+	resetLabel?: string;
 }
 
 /** Quantitative usage data. */
@@ -189,6 +195,7 @@ export const usageWindowSchema = type({
 	label: "string",
 	"durationMs?": "number",
 	"resetsAt?": "number",
+	"resetLabel?": "string",
 });
 
 export const usageAmountSchema = type({