@demicodes/provider-grok-build 0.17.1 → 0.17.2

package/README.md

@@ -22,7 +22,7 @@ See [docs/provider-global-credentials.md](../../docs/provider-global-credentials
 
 ## Quota
 
-- **probe** (cost: `free`): `/v1/billing` + `/v1/user?include=subscription` on
+- **probe** (cost: `free`): `/v1/billing?format=credits` + `/v1/user?include=subscription` on
   cli-chat-proxy.
 - **observe**: short-window ratelimit headers on chat responses (separate from monthly).
 

package/dist/index.d.mts

@@ -11,8 +11,12 @@ interface GrokAuthEntry {
   oidc_client_id?: string;
   email?: string;
   first_name?: string;
+  last_name?: string;
   user_id?: string;
   team_id?: string;
+  principal_type?: string;
+  principal_id?: string;
+  organization_id?: string;
   [key: string]: unknown;
 }
 interface GrokResolvedAuth {
@@ -20,6 +24,9 @@ interface GrokResolvedAuth {
   refreshToken: string | null;
   expiresAt: Date | null;
   email: string | null;
+  userId: string | null;
+  principalType: string | null;
+  principalId: string | null;
   issuer: string | null;
   clientId: string | null;
   entryKey: string;
@@ -55,6 +62,8 @@ type GrokTokenRefresh = (input: {
   refreshToken: string;
   clientId: string;
   tokenEndpoint: string;
+  principalType?: string | null;
+  principalId?: string | null;
 }, signal?: AbortSignal) => Promise<GrokRefreshTokenResponse>;
 declare function grokBuildAuthStatus(options?: FileGrokAuthStoreOptions): Promise<ProviderAuthState>;
 //#endregion
@@ -101,7 +110,7 @@ interface GrokBuildQuotaOptions {
 /**
  * Active probe against cli-chat-proxy:
  * - GET /v1/user?include=subscription → tier
- * - GET /v1/billing → monthly used/limit
+ * - GET /v1/billing?format=credits → creditUsagePercent / currentPeriod
  *
  * Optional observation of short-window x-ratelimit-* headers from chat responses
  * (separate windows from monthly subscription quota).
@@ -137,6 +146,7 @@ declare function createGrokBuildCredentials(pool: FileCredentialPool, authStore:
 }): ProviderCredentials;
 //#endregion
 //#region src/device-login.d.ts
+type GrokLoginSurface = 'ui' | 'cli' | 'headless';
 interface GrokDeviceLoginPending {
   verificationUrl: string;
   userCode: string;
@@ -150,6 +160,7 @@ interface GrokDeviceLoginOptions {
   issuer?: string;
   clientId?: string;
   scope?: string;
+  surface?: GrokLoginSurface;
 }
 interface GrokDeviceLoginResult {
   entryKey: string;

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { delay, errorCode, errorMessage, isAbortError, isRecord, nonEmptyString, normalizeBaseUrl, numberOrNull, numberOrZero, parseJsonObject, parseJsonOrString, stringOrNull } from "@demicodes/utils";
-import { createProviderQuota, defineProvider, httpRequestFailedEvent, normalizeErrorCode, numberHeader, providerErrorFromUnknown, redactCredentialText, severityFromUsedPercent, toolResultContentToText, usedPercentFromRatio } from "@demicodes/provider";
+import { clampUsedPercent, createProviderQuota, defineProvider, httpRequestFailedEvent, normalizeErrorCode, numberHeader, providerErrorFromUnknown, redactCredentialText, severityFromUsedPercent, toolResultContentToText, usedPercentFromRatio } from "@demicodes/provider";
 import { Buffer } from "node:buffer";
 import { chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import process from "node:process";
+import process$1 from "node:process";
 import { zeroUsage } from "@demicodes/core";
-import { FileCredentialPool, credentialIdFromIdentity } from "@demicodes/provider/credentials-pool";
 import { readFileSync } from "node:fs";
+import { FileCredentialPool, credentialIdFromIdentity } from "@demicodes/provider/credentials-pool";
 //#region src/auth.ts
 /** Grok auth.json stores the access token under `key`; redact it alongside the standard fields. */
 const SECRET_FIELD_PATTERNS = ["\\bkey\\b"];
@@ -68,18 +68,18 @@ var FileGrokAuthStore = class {
 		if ((options.forceRefresh === true || expiresWithin(expiresAt, this.now(), REFRESH_EXPIRY_SKEW_MS)) && refreshToken && clientId) return this.refreshAndResolve(accessToken, entryKey, {
 			refreshToken,
 			clientId,
-			tokenEndpoint: tokenEndpointForIssuer(issuer)
+			tokenEndpoint: tokenEndpointForIssuer(issuer),
+			principalType: stringOrNull(entry.principal_type),
+			principalId: stringOrNull(entry.principal_id)
 		});
-		return {
-			accessToken,
+		return resolvedAuthFromEntry(entry, accessToken, {
 			refreshToken,
 			expiresAt,
-			email: stringOrNull(entry.email),
 			issuer,
 			clientId,
 			entryKey,
 			authFile: this.authFile
-		};
+		});
 	}
 	async refreshAndResolve(staleAccessToken, entryKey, refreshInput) {
 		return this.withAuthFileLock(async () => {
@@ -92,21 +92,21 @@ var FileGrokAuthStore = class {
 			const latestAccessToken = nonEmptyString(latestEntry.key);
 			if (latestAccessToken && latestAccessToken !== staleAccessToken) {
 				const latestExpiresAt = parseExpiresAt(latestEntry.expires_at) ?? parseJwtExpiration(latestAccessToken);
-				if (!expiresWithin(latestExpiresAt, this.now(), REFRESH_EXPIRY_SKEW_MS)) return {
-					accessToken: latestAccessToken,
+				if (!expiresWithin(latestExpiresAt, this.now(), REFRESH_EXPIRY_SKEW_MS)) return resolvedAuthFromEntry(latestEntry, latestAccessToken, {
 					refreshToken: nonEmptyString(latestEntry.refresh_token) ?? null,
 					expiresAt: latestExpiresAt,
-					email: stringOrNull(latestEntry.email),
 					issuer,
 					clientId,
 					entryKey,
 					authFile: this.authFile
-				};
+				});
 			}
 			const response = await this.refreshImpl({
 				refreshToken,
 				clientId,
-				tokenEndpoint: tokenEndpointForIssuer(issuer) || refreshInput.tokenEndpoint
+				tokenEndpoint: tokenEndpointForIssuer(issuer) || refreshInput.tokenEndpoint,
+				principalType: stringOrNull(latestEntry.principal_type) ?? refreshInput.principalType,
+				principalId: stringOrNull(latestEntry.principal_id) ?? refreshInput.principalId
 			});
 			const accessToken = nonEmptyString(response.access_token);
 			if (!accessToken) throw new GrokAuthError("auth_refresh_failed", "Grok token refresh returned no access_token");
@@ -122,16 +122,14 @@ var FileGrokAuthStore = class {
 				[entryKey]: nextEntry
 			};
 			await writeAuthJsonAtomic(this.authFile, nextFile);
-			return {
-				accessToken,
+			return resolvedAuthFromEntry(nextEntry, accessToken, {
 				refreshToken: nonEmptyString(nextEntry.refresh_token) ?? null,
 				expiresAt,
-				email: stringOrNull(nextEntry.email),
 				issuer,
 				clientId,
 				entryKey,
 				authFile: this.authFile
-			};
+			});
 		});
 	}
 	async readAuthFile() {
@@ -164,7 +162,7 @@ var FileGrokAuthStore = class {
 			await delay(this.lockRetryDelayMs);
 		}
 		try {
-			await writeFile(lockFile, `${process.pid}:${Math.floor(this.now().getTime() / 1e3)}`, { mode: 384 });
+			await writeFile(lockFile, `${process$1.pid}:${Math.floor(this.now().getTime() / 1e3)}`, { mode: 384 });
 			return await fn();
 		} finally {
 			const ownedIdentity = await handle.stat().then(toFileIdentity).catch(() => null);
@@ -182,7 +180,7 @@ var GrokAuthError = class extends Error {
 	}
 };
 function defaultGrokHome() {
-	const fromEnv = process.env.GROK_HOME;
+	const fromEnv = process$1.env.GROK_HOME;
 	return fromEnv && fromEnv.trim() ? fromEnv : join(homedir(), ".grok");
 }
 function selectAuthEntry(file) {
@@ -220,6 +218,8 @@ async function refreshGrokOidcToken(input, signal) {
 		refresh_token: input.refreshToken,
 		client_id: input.clientId
 	});
+	if (nonEmptyString(input.principalType)) body.set("principal_type", input.principalType);
+	if (nonEmptyString(input.principalId)) body.set("principal_id", input.principalId);
 	const response = await fetch(input.tokenEndpoint, {
 		method: "POST",
 		headers: {
@@ -232,8 +232,20 @@ async function refreshGrokOidcToken(input, signal) {
 	if (!response.ok) throw new GrokAuthError("auth_refresh_failed", `Grok token refresh failed with HTTP ${response.status}`);
 	return await response.json();
 }
+function peekGrokAccessTokenPrincipal(accessToken) {
+	const payload = decodeGrokJwtPayload(accessToken);
+	if (!payload) return null;
+	const principalType = nonEmptyString(payload.principal_type) ?? nonEmptyString(payload.principalType);
+	const principalId = nonEmptyString(payload.principal_id) ?? nonEmptyString(payload.principalId);
+	if (!principalType || !principalId) return null;
+	return {
+		principalType,
+		principalId,
+		teamId: nonEmptyString(payload.team_id) ?? null
+	};
+}
 function parseJwtExpiration(jwt) {
-	const exp = decodeJwtPayload(jwt)?.exp;
+	const exp = decodeGrokJwtPayload(jwt)?.exp;
 	return typeof exp === "number" ? /* @__PURE__ */ new Date(exp * 1e3) : null;
 }
 function tokenEndpointForIssuer(issuer) {
@@ -261,12 +273,12 @@ function expiresWithin(expiresAt, now, skewMs) {
 }
 async function writeAuthJsonAtomic(authFile, auth) {
 	await mkdir(dirname(authFile), { recursive: true });
-	const temp = `${authFile}.${process.pid}.${Date.now()}.tmp`;
+	const temp = `${authFile}.${process$1.pid}.${Date.now()}.tmp`;
 	await writeFile(temp, `${JSON.stringify(auth, null, 2)}\n`, { mode: 384 });
 	await chmod(temp, 384);
 	await rename(temp, authFile);
 }
-function decodeJwtPayload(jwt) {
+function decodeGrokJwtPayload(jwt) {
 	const parts = jwt.split(".");
 	if (parts.length !== 3 || !parts[1]) return null;
 	try {
@@ -277,6 +289,25 @@ function decodeJwtPayload(jwt) {
 		return null;
 	}
 }
+function resolveGrokUserId(entry, accessToken) {
+	return stringOrNull(entry.user_id) ?? peekGrokAccessTokenPrincipal(accessToken)?.principalId ?? stringOrNull(decodeGrokJwtPayload(accessToken)?.sub);
+}
+function resolvedAuthFromEntry(entry, accessToken, rest) {
+	const peeked = peekGrokAccessTokenPrincipal(accessToken);
+	return {
+		accessToken,
+		refreshToken: rest.refreshToken,
+		expiresAt: rest.expiresAt,
+		email: stringOrNull(entry.email),
+		userId: resolveGrokUserId(entry, accessToken),
+		principalType: stringOrNull(entry.principal_type) ?? peeked?.principalType ?? null,
+		principalId: stringOrNull(entry.principal_id) ?? peeked?.principalId ?? null,
+		issuer: rest.issuer,
+		clientId: rest.clientId,
+		entryKey: rest.entryKey,
+		authFile: rest.authFile
+	};
+}
 /** Grok CLI lock format is `pid:unix_seconds`. A valid live PID always owns its lock. */
 async function isAbandonedGrokAuthLock(lockFile, now, maxAgeMs = 3e4) {
 	try {
@@ -311,7 +342,7 @@ async function removeLockFileIfSame(lockFile, expected) {
 }
 function isProcessAlive(pid) {
 	try {
-		process.kill(pid, 0);
+		process$1.kill(pid, 0);
 		return true;
 	} catch (error) {
 		if (errorCode(error) === "EPERM") return true;
@@ -596,16 +627,75 @@ function grokUsage(usage) {
 	};
 }
 //#endregion
+//#region src/headers.ts
+const DEFAULT_GROK_BUILD_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+const GROK_CLI_TOKEN_AUTH = "xai-grok-cli";
+const GROK_AUTHENTICATE_RESPONSE = "authenticate-response";
+const GROK_CLIENT_IDENTIFIER = "grok-shell";
+const GROK_CLIENT_MODE = "interactive";
+/** Official Grok CLI crate version, used when no local `~/.grok/version.json` exists. */
+const DEFAULT_GROK_CLIENT_VERSION = "1.0.5";
+function buildGrokBuildHeaders(auth, request, options) {
+	const headers = new Headers(options?.extra);
+	headers.set("authorization", `Bearer ${auth.accessToken}`);
+	headers.set("X-XAI-Token-Auth", GROK_CLI_TOKEN_AUTH);
+	headers.set("x-authenticateresponse", GROK_AUTHENTICATE_RESPONSE);
+	headers.set("x-grok-client-version", resolveGrokClientVersion(options?.clientVersion, options?.grokHome));
+	headers.set("x-grok-client-identifier", nonEmptyString(process.env.GROK_CLIENT_NAME) ?? GROK_CLIENT_IDENTIFIER);
+	headers.set("x-grok-client-mode", GROK_CLIENT_MODE);
+	if (auth.userId) {
+		headers.set("x-userid", auth.userId);
+		headers.set("x-grok-user-id", auth.userId);
+	}
+	if (auth.email) headers.set("x-email", auth.email);
+	if (request?.modelId) headers.set("x-grok-model-override", request.modelId);
+	if (request?.sessionId) {
+		headers.set("x-grok-session-id", request.sessionId);
+		headers.set("x-grok-conv-id", request.sessionId);
+	}
+	if (request?.requestId) headers.set("x-grok-req-id", request.requestId);
+	if (request?.turnId) headers.set("x-grok-turn-idx", request.turnId);
+	return headers;
+}
+function resolveGrokClientVersion(explicit, grokHome) {
+	const fromExplicit = nonEmptyString(explicit);
+	if (fromExplicit) return fromExplicit;
+	return readGrokCliVersion(grokHome ?? defaultGrokHome()) ?? DEFAULT_GROK_CLIENT_VERSION;
+}
+function readGrokCliVersion(grokHome) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(grokHome, "version.json"), "utf8"));
+		if (!isRecord(parsed)) return null;
+		return nonEmptyString(parsed.version) ?? null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/device-login.ts
 const GROK_ISSUER = "https://auth.x.ai";
 const GROK_CLI_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
-const GROK_LOGIN_SCOPE = "openid profile email offline_access grok-cli:access";
+const GROK_LOGIN_SCOPE = "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write workspaces:read workspaces:write";
+const GROK_LOGIN_REFERRER = "grok-build";
 const GROK_LOGIN_FALLBACK_INTERVAL_S = 5;
-const GROK_LOGIN_FALLBACK_EXPIRES_S = 900;
-async function postForm(fetchImpl, url, params, signal) {
+const GROK_LOGIN_MIN_EXPIRES_S = 600;
+const TEAM_PRINCIPAL = "Team";
+const ORGANIZATION_PRINCIPAL = "Organization";
+function resolveLoginSurface(options) {
+	if (options.surface) return options.surface;
+	return options.onPending ? "ui" : "headless";
+}
+function oauthHeaders(surface) {
+	return {
+		"content-type": "application/x-www-form-urlencoded",
+		"x-grok-client-version": resolveGrokClientVersion(),
+		"x-grok-client-surface": surface
+	};
+}
+async function postForm(fetchImpl, url, params, surface, signal) {
 	return fetchImpl(url, {
 		method: "POST",
-		headers: { "content-type": "application/x-www-form-urlencoded" },
+		headers: oauthHeaders(surface),
 		body: new URLSearchParams(params).toString(),
 		signal
 	});
@@ -615,17 +705,37 @@ async function jsonBody(response, what) {
 	if (!isRecord(body)) throw new GrokAuthError("auth_invalid", `${what} response is not a JSON object`);
 	return body;
 }
-async function requestDeviceCode(fetchImpl, issuer, clientId, scope, signal) {
+function assertUserCode(userCode) {
+	if (![...userCode].every((ch) => /[A-Za-z0-9-]/.test(ch))) throw new GrokAuthError("auth_invalid", "Grok device code response has an invalid user_code");
+}
+function assertVerificationUri(uri) {
+	if ([...uri].some((ch) => ch.charCodeAt(0) < 32)) throw new GrokAuthError("auth_invalid", "Grok device code response has an invalid verification URI");
+	let parsed;
+	try {
+		parsed = new URL(uri);
+	} catch {
+		throw new GrokAuthError("auth_invalid", "Grok device code response has an invalid verification URI");
+	}
+	if (parsed.protocol === "https:") return;
+	if (parsed.protocol === "http:" && (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1")) return;
+	throw new GrokAuthError("auth_invalid", "Grok device code response has an unsupported verification URI scheme");
+}
+async function requestDeviceCode(fetchImpl, issuer, clientId, scope, surface, signal) {
 	const response = await postForm(fetchImpl, `${issuer}/oauth2/device/code`, {
 		client_id: clientId,
-		scope
-	}, signal);
+		scope,
+		referrer: GROK_LOGIN_REFERRER
+	}, surface, signal);
 	if (!response.ok) throw new GrokAuthError("auth_invalid", `Grok device code request failed with HTTP ${response.status}`);
 	const body = await jsonBody(response, "Grok device code");
 	const deviceCode = nonEmptyString(body.device_code);
 	const userCode = nonEmptyString(body.user_code);
 	const verificationUrl = nonEmptyString(body.verification_uri_complete) ?? nonEmptyString(body.verification_uri);
+	const verificationUri = nonEmptyString(body.verification_uri);
 	if (!deviceCode || !userCode || !verificationUrl) throw new GrokAuthError("auth_invalid", "Grok device code response is missing device_code, user_code, or verification_uri");
+	assertUserCode(userCode);
+	if (verificationUri) assertVerificationUri(verificationUri);
+	if (nonEmptyString(body.verification_uri_complete)) assertVerificationUri(nonEmptyString(body.verification_uri_complete));
 	const interval = Number(body.interval);
 	const expiresIn = Number(body.expires_in);
 	return {
@@ -633,18 +743,20 @@ async function requestDeviceCode(fetchImpl, issuer, clientId, scope, signal) {
 		userCode,
 		verificationUrl,
 		intervalSeconds: Number.isFinite(interval) && interval >= 0 ? interval : GROK_LOGIN_FALLBACK_INTERVAL_S,
-		expiresAt: Date.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : GROK_LOGIN_FALLBACK_EXPIRES_S) * 1e3
+		expiresAt: Date.now() + Math.max(Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 0, GROK_LOGIN_MIN_EXPIRES_S) * 1e3
 	};
 }
-async function pollForTokens(fetchImpl, issuer, clientId, device, signal) {
-	let intervalSeconds = device.intervalSeconds;
+async function pollForTokens(fetchImpl, issuer, clientId, device, surface, signal) {
+	let intervalSeconds = Math.max(device.intervalSeconds, 1);
 	for (;;) {
 		signal?.throwIfAborted();
+		await delay(intervalSeconds * 1e3);
+		if (Date.now() >= device.expiresAt) throw new GrokAuthError("auth_invalid", "Grok device login timed out before the user confirmed");
 		const response = await postForm(fetchImpl, `${issuer}/oauth2/token`, {
 			grant_type: "urn:ietf:params:oauth:grant-type:device_code",
 			device_code: device.deviceCode,
 			client_id: clientId
-		}, signal);
+		}, surface, signal);
 		const body = await jsonBody(response, "Grok device token");
 		if (response.ok) {
 			const accessToken = nonEmptyString(body.access_token);
@@ -653,49 +765,103 @@ async function pollForTokens(fetchImpl, issuer, clientId, device, signal) {
 			return {
 				accessToken,
 				refreshToken: nonEmptyString(body.refresh_token) ?? null,
-				expiresIn: Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : null
+				expiresIn: Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : null,
+				idToken: nonEmptyString(body.id_token) ?? null
 			};
 		}
 		const error = nonEmptyString(body.error);
 		if (error === "slow_down") intervalSeconds += 5;
 		else if (error !== "authorization_pending") throw new GrokAuthError("auth_invalid", `Grok device login failed: ${error ?? `HTTP ${response.status}`}`);
-		if (Date.now() >= device.expiresAt) throw new GrokAuthError("auth_invalid", "Grok device login timed out before the user confirmed");
-		await delay(intervalSeconds * 1e3);
 	}
 }
-async function fetchUserinfo(fetchImpl, issuer, accessToken, signal) {
-	const response = await fetchImpl(`${issuer}/oauth2/userinfo`, {
-		headers: { authorization: `Bearer ${accessToken}` },
-		signal
-	});
-	if (!response.ok) return {};
-	const body = await response.json().catch(() => null);
-	return isRecord(body) ? body : {};
+async function fetchUserEnrichment(fetchImpl, accessToken, signal) {
+	try {
+		const response = await fetchImpl(`${DEFAULT_GROK_BUILD_BASE_URL}/user`, {
+			headers: {
+				authorization: `Bearer ${accessToken}`,
+				"X-XAI-Token-Auth": GROK_CLI_TOKEN_AUTH,
+				"x-grok-client-version": resolveGrokClientVersion(),
+				"x-grok-client-mode": "interactive"
+			},
+			signal
+		});
+		if (!response.ok) return null;
+		const body = await response.json().catch(() => null);
+		if (!isRecord(body)) return null;
+		if (!nonEmptyString(body.userId) && !nonEmptyString(body.user_id)) return null;
+		return body;
+	} catch {
+		return null;
+	}
+}
+function applyUserInfoEnrichment(entry, user) {
+	const userId = nonEmptyString(user.userId) ?? nonEmptyString(user.user_id);
+	if (userId) entry.user_id = userId;
+	const firstName = nonEmptyString(user.firstName) ?? nonEmptyString(user.first_name);
+	if (firstName) entry.first_name = firstName;
+	const lastName = nonEmptyString(user.lastName) ?? nonEmptyString(user.last_name);
+	if (lastName) entry.last_name = lastName;
+	const principalType = nonEmptyString(user.principalType) ?? nonEmptyString(user.principal_type);
+	if (principalType) entry.principal_type = principalType;
+	const principalId = nonEmptyString(user.principalId) ?? nonEmptyString(user.principal_id);
+	if (principalId) entry.principal_id = principalId;
+	const teamId = nonEmptyString(user.teamId) ?? nonEmptyString(user.team_id);
+	if (teamId) entry.team_id = teamId;
+	const organizationId = nonEmptyString(user.organizationId) ?? nonEmptyString(user.organization_id);
+	if (organizationId) entry.organization_id = organizationId;
+	const email = nonEmptyString(user.email);
+	if (email) entry.email = email;
+}
+async function assembleAuthEntry(fetchImpl, issuer, clientId, tokens, signal) {
+	const idClaims = tokens.idToken ? decodeGrokJwtPayload(tokens.idToken) : null;
+	let userId = nonEmptyString(idClaims?.sub) ?? "";
+	let email = nonEmptyString(idClaims?.email) ?? null;
+	const peeked = peekGrokAccessTokenPrincipal(tokens.accessToken);
+	const principalType = peeked?.principalType ?? null;
+	const principalId = peeked?.principalId ?? null;
+	let teamId = peeked?.teamId ?? null;
+	let organizationId = null;
+	if (principalType === TEAM_PRINCIPAL && principalId) {
+		userId = principalId;
+		email = null;
+		teamId = principalId;
+	} else if (principalType === ORGANIZATION_PRINCIPAL && principalId) {
+		userId = principalId;
+		email = null;
+		organizationId = principalId;
+	}
+	const entry = {
+		key: tokens.accessToken,
+		auth_mode: "oidc",
+		...tokens.refreshToken ? { refresh_token: tokens.refreshToken } : {},
+		...tokens.expiresIn ? { expires_at: new Date(Date.now() + tokens.expiresIn * 1e3).toISOString() } : {},
+		oidc_issuer: issuer,
+		oidc_client_id: clientId,
+		...email ? { email } : {},
+		...userId ? { user_id: userId } : {},
+		...principalType ? { principal_type: principalType } : {},
+		...principalId ? { principal_id: principalId } : {},
+		...teamId ? { team_id: teamId } : {},
+		...organizationId ? { organization_id: organizationId } : {}
+	};
+	const enriched = await fetchUserEnrichment(fetchImpl, tokens.accessToken, signal);
+	if (enriched) applyUserInfoEnrichment(entry, enriched);
+	return entry;
 }
 /** Runs the full device flow and returns a vendor-shaped auth.json entry keyed like the Grok CLI. */
 async function runGrokDeviceLogin(options = {}) {
 	const fetchImpl = options.fetch ?? fetch;
 	const issuer = (options.issuer ?? GROK_ISSUER).replace(/\/+$/, "");
 	const clientId = options.clientId ?? GROK_CLI_CLIENT_ID;
-	const device = await requestDeviceCode(fetchImpl, issuer, clientId, options.scope ?? GROK_LOGIN_SCOPE, options.signal);
+	const scope = options.scope ?? GROK_LOGIN_SCOPE;
+	const surface = resolveLoginSurface(options);
+	const device = await requestDeviceCode(fetchImpl, issuer, clientId, scope, surface, options.signal);
 	options.onPending?.({
 		verificationUrl: device.verificationUrl,
 		userCode: device.userCode,
 		expiresAt: new Date(device.expiresAt).toISOString()
 	});
-	const tokens = await pollForTokens(fetchImpl, issuer, clientId, device, options.signal);
-	const userinfo = await fetchUserinfo(fetchImpl, issuer, tokens.accessToken, options.signal);
-	const entry = {
-		key: tokens.accessToken,
-		auth_mode: "oidc",
-		...tokens.refreshToken ? { refresh_token: tokens.refreshToken } : {},
-		...tokens.expiresIn ? { expires_at: new Date(Date.now() + tokens.expiresIn * 1e3).toISOString() } : {},
-		oidc_issuer: issuer,
-		oidc_client_id: clientId,
-		...nonEmptyString(userinfo.email) ? { email: nonEmptyString(userinfo.email) } : {},
-		...nonEmptyString(userinfo.given_name) ? { first_name: nonEmptyString(userinfo.given_name) } : {},
-		...nonEmptyString(userinfo.sub) ? { user_id: nonEmptyString(userinfo.sub) } : {}
-	};
+	const entry = await assembleAuthEntry(fetchImpl, issuer, clientId, await pollForTokens(fetchImpl, issuer, clientId, device, surface, options.signal), options.signal);
 	return {
 		entryKey: `${issuer}::${clientId}`,
 		entry
@@ -815,7 +981,8 @@ function createGrokBuildCredentials(pool, authStore, options = {}) {
 				const { entryKey, entry } = await runGrokDeviceLogin({
 					signal: loginOptions?.signal,
 					onPending: loginOptions?.onPending,
-					fetch: options.loginFetch
+					fetch: options.loginFetch,
+					surface: "ui"
 				});
 				return {
 					status: "completed",
@@ -869,33 +1036,6 @@ function createGrokBuildCredentials(pool, authStore, options = {}) {
 		}
 	};
 }
-const GROK_CLI_TOKEN_AUTH = "xai-grok-cli";
-const GROK_CLIENT_SURFACE = "grok-build";
-function buildGrokBuildHeaders(auth, request, options) {
-	const headers = new Headers(options?.extra);
-	headers.set("authorization", `Bearer ${auth.accessToken}`);
-	headers.set("X-XAI-Token-Auth", GROK_CLI_TOKEN_AUTH);
-	headers.set("x-grok-client-surface", GROK_CLIENT_SURFACE);
-	headers.set("x-grok-client-version", resolveGrokClientVersion(options?.clientVersion, options?.grokHome));
-	if (request?.modelId) headers.set("x-grok-model-override", request.modelId);
-	if (request?.sessionId) headers.set("x-grok-session-id", request.sessionId);
-	if (request?.requestId) headers.set("x-grok-req-id", request.requestId);
-	return headers;
-}
-function resolveGrokClientVersion(explicit, grokHome) {
-	const fromExplicit = nonEmptyString(explicit);
-	if (fromExplicit) return fromExplicit;
-	return readGrokCliVersion(grokHome ?? defaultGrokHome()) ?? "0.1.202";
-}
-function readGrokCliVersion(grokHome) {
-	try {
-		const parsed = JSON.parse(readFileSync(join(grokHome, "version.json"), "utf8"));
-		if (!isRecord(parsed)) return null;
-		return nonEmptyString(parsed.version) ?? null;
-	} catch {
-		return null;
-	}
-}
 //#endregion
 //#region src/models.ts
 const FALLBACK_SOURCE_FETCHED_AT = "1970-01-01T00:00:00.000Z";
@@ -1023,7 +1163,7 @@ function positiveOrDefault(value, fallback) {
 /**
 * Active probe against cli-chat-proxy:
 * - GET /v1/user?include=subscription → tier
-* - GET /v1/billing → monthly used/limit
+* - GET /v1/billing?format=credits → creditUsagePercent / currentPeriod
 *
 * Optional observation of short-window x-ratelimit-* headers from chat responses
 * (separate windows from monthly subscription quota).
@@ -1046,7 +1186,7 @@ function createGrokBuildQuota(options = {}) {
 			const [user, billing] = await Promise.all([fetchJson(fetchImpl, `${baseUrl}/user?include=subscription`, auth, {
 				grokHome,
 				clientVersion
-			}, signal), fetchJson(fetchImpl, `${baseUrl}/billing`, auth, {
+			}, signal), fetchJson(fetchImpl, `${baseUrl}/billing?format=credits`, auth, {
 				grokHome,
 				clientVersion
 			}, signal)]);
@@ -1059,18 +1199,21 @@ function mapGrokQuotaProbe(user, billing, auth) {
 	const userRecord = isRecord(user) ? user : {};
 	const billingRecord = isRecord(billing) ? billing : {};
 	const config = isRecord(billingRecord.config) ? billingRecord.config : {};
+	const period = isRecord(config.currentPeriod) ? config.currentPeriod : null;
+	const isWeekly = stringOrNull(period?.type) === "USAGE_PERIOD_TYPE_WEEKLY";
+	const resetsAt = stringOrNull(period?.end) ?? stringOrNull(config.billingPeriodEnd);
 	const monthlyLimit = moneyVal(config.monthlyLimit);
 	const used = moneyVal(config.used);
 	const onDemandCap = moneyVal(config.onDemandCap);
-	const usedPercent = usedPercentFromRatio(used, monthlyLimit);
+	const usedPercent = clampUsedPercent(config.creditUsagePercent) ?? usedPercentFromRatio(used, monthlyLimit);
 	const windows = [{
-		id: "monthly",
-		label: "Monthly credits",
+		id: isWeekly ? "weekly" : "monthly",
+		label: isWeekly ? "Weekly credits" : "Monthly credits",
 		usedPercent,
 		used,
 		limit: monthlyLimit,
 		unit: "credits",
-		resetsAt: stringOrNull(config.billingPeriodEnd),
+		resetsAt,
 		severity: severityFromUsedPercent(usedPercent)
 	}];
 	if (onDemandCap != null && onDemandCap > 0) windows.push({
@@ -1080,7 +1223,7 @@ function mapGrokQuotaProbe(user, billing, auth) {
 		used: null,
 		limit: onDemandCap,
 		unit: "credits",
-		resetsAt: stringOrNull(config.billingPeriodEnd)
+		resetsAt
 	});
 	const tier = stringOrNull(userRecord.subscriptionTier);
 	return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/provider-grok-build",
   "description": "Grok Build provider adapter for Demi (reuses ~/.grok OAuth session).",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -11,9 +11,9 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.17.1",
-    "@demicodes/provider": "^0.17.1",
-    "@demicodes/utils": "^0.17.1"
+    "@demicodes/core": "^0.17.2",
+    "@demicodes/provider": "^0.17.2",
+    "@demicodes/utils": "^0.17.2"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",