@gajae-code/ai 0.18.11 → 0.19.0

package/src/utils/discovery/antigravity.ts

@@ -1,8 +1,17 @@
+import { logger } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { isRetiredModelKey } from "../../model-retirements";
-import { getAntigravityUserAgent } from "../../providers/google-gemini-headers";
+import { getAntigravityUserAgent, getGeminiCliUserAgent } from "../../providers/google-gemini-headers";
 import type { Model } from "../../types";
 
+/**
+ * Returns the default Antigravity discovery User-Agent.
+ * Can be overridden via PI_AI_ANTIGRAVITY_USER_AGENT environment variable.
+ */
+export function getDefaultAntigravityUserAgent(): string {
+	return getAntigravityUserAgent();
+}
+
 const DEFAULT_ANTIGRAVITY_DISCOVERY_ENDPOINTS = [
 	"https://daily-cloudcode-pa.googleapis.com",
 	"https://daily-cloudcode-pa.sandbox.googleapis.com",
@@ -35,6 +44,12 @@ export interface AntigravityDiscoveryApiModel {
 	modelProvider?: string;
 	isInternal?: boolean;
 	supportsVideo?: boolean;
+	/** Account-specific entitlement status */
+	entitlement?: string;
+	/** Whether the model is disabled for this account */
+	disabled?: boolean;
+	/** Per-account quota/tier information */
+	quota?: string;
 }
 
 /**
@@ -81,6 +96,9 @@ const AntigravityDiscoveryApiModelSchema: z.ZodType<AntigravityDiscoveryApiModel
 		modelProvider: z.preprocess(value => (typeof value === "string" ? value : undefined), z.string().optional()),
 		isInternal: z.preprocess(value => (typeof value === "boolean" ? value : undefined), z.boolean().optional()),
 		supportsVideo: z.preprocess(value => (typeof value === "boolean" ? value : undefined), z.boolean().optional()),
+		entitlement: z.preprocess(value => (typeof value === "string" ? value : undefined), z.string().optional()),
+		disabled: z.preprocess(value => (typeof value === "boolean" ? value : undefined), z.boolean().optional()),
+		quota: z.preprocess(value => (typeof value === "string" ? value : undefined), z.string().optional()),
 	})
 	.loose();
 const AntigravityDiscoveryAgentModelGroupSchema: z.ZodType<AntigravityDiscoveryAgentModelGroup> = z
@@ -154,7 +172,7 @@ export interface FetchAntigravityDiscoveryModelsOptions {
 	token: string;
 	/** Optional endpoint override. Defaults to Antigravity fallback endpoints. */
 	endpoint?: string;
-	/** Deprecated and ignored for antigravity discovery parity. */
+	/** Optional Google Cloud project ID for tier-gated model discovery. */
 	project?: string;
 	/** Optional user agent override. */
 	userAgent?: string;
@@ -168,6 +186,8 @@ export interface FetchAntigravityDiscoveryModelsOptions {
 	 * Default: `google-antigravity`.
 	 */
 	targetProvider?: "google-antigravity" | "google-gemini-cli";
+	/** Optional logger for debug diagnostics. */
+	logger?: Pick<typeof logger, "debug">;
 }
 
 /**
@@ -182,27 +202,40 @@ export async function fetchAntigravityDiscoveryModels(
 	const fetcher = options.fetcher ?? fetch;
 	const signal = options.signal ?? AbortSignal.timeout(5_000);
 	const targetProvider = options.targetProvider ?? "google-antigravity";
+	const userAgent = options.userAgent ?? getAntigravityDiscoveryUserAgent();
 	const endpoints = options.endpoint
 		? [trimTrailingSlashes(options.endpoint)]
 		: DEFAULT_ANTIGRAVITY_DISCOVERY_ENDPOINTS.map(trimTrailingSlashes);
+	const debugLogger = options.logger ?? logger;
 
 	for (const endpoint of endpoints) {
+		const redactedEndpoint = redactAntigravityEndpoint(endpoint);
 		let response: Response;
 		try {
+			const requestBody: Record<string, unknown> = {};
+			if (options.project) {
+				requestBody.project = options.project;
+			}
 			response = await fetcher(`${endpoint}${FETCH_AVAILABLE_MODELS_PATH}`, {
 				method: "POST",
 				headers: {
 					Authorization: `Bearer ${options.token}`,
 					"Content-Type": "application/json",
-					"User-Agent": options.userAgent ?? getAntigravityUserAgent(),
+					"User-Agent": userAgent,
 				},
-				body: JSON.stringify({}),
+				body: JSON.stringify(requestBody),
 				signal,
 			});
 		} catch {
 			continue;
 		}
 
+		debugLogger.debug("Antigravity discovery endpoint response", {
+			endpoint: redactedEndpoint,
+			status: response.status,
+			statusText: response.statusText,
+		});
+
 		if (!response.ok) {
 			continue;
 		}
@@ -228,15 +261,60 @@ export async function fetchAntigravityDiscoveryModels(
 			}
 		}
 
+		const debugEnabled = process.env.GJC_DEBUG_ANTIGRAVITY_DISCOVERY === "1";
+		const keptModelIds: string[] = [];
+		const filteredByDenylist: string[] = [];
+		const filteredByRetirement: string[] = [];
+		const filteredByInternal: string[] = [];
+		const filteredByDisabled: string[] = [];
+		const keptModelDetails: Record<string, Partial<AntigravityDiscoveryApiModel>> = {};
+		const filteredModelDetails: Record<string, Partial<AntigravityDiscoveryApiModel> & { reason: string }> = {};
+
 		const models: Model<"google-gemini-cli">[] = [];
+		const modelDropReasons: Record<string, string> = {};
 
 		for (const [modelId, model] of Object.entries(parsed.models ?? {})) {
-			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId) || isRetiredModelKey(targetProvider, modelId)) {
-				continue;
+			let dropReason: string | undefined;
+
+			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId)) {
+				dropReason = "denylist";
+			} else if (isRetiredModelKey(targetProvider, modelId)) {
+				dropReason = "retired";
+			} else if (model.disabled === true) {
+				dropReason = "disabled";
+			} else if (model.isInternal === true && !surfacedModelIds.has(modelId)) {
+				dropReason = "isInternal-not-surfaced";
 			}
-			if (model.isInternal === true && !surfacedModelIds.has(modelId)) {
+
+			if (dropReason) {
+				modelDropReasons[modelId] = dropReason;
+				if (debugEnabled) {
+					if (dropReason === "denylist") filteredByDenylist.push(modelId);
+					else if (dropReason === "retired") filteredByRetirement.push(modelId);
+					else if (dropReason === "disabled") filteredByDisabled.push(modelId);
+					else filteredByInternal.push(modelId);
+					filteredModelDetails[modelId] = {
+						...model,
+						reason:
+							dropReason === "retired"
+								? `retired-${targetProvider}`
+								: dropReason === "isInternal-not-surfaced"
+									? "internal-not-surfaced"
+									: dropReason,
+					};
+				}
 				continue;
 			}
+			if (debugEnabled) {
+				keptModelIds.push(modelId);
+				keptModelDetails[modelId] = {
+					displayName: model.displayName,
+					isInternal: model.isInternal,
+					entitlement: model.entitlement,
+					disabled: model.disabled,
+					quota: model.quota,
+				};
+			}
 
 			const supportsImages = model.supportsImages === true;
 			models.push({
@@ -258,7 +336,102 @@ export async function fetchAntigravityDiscoveryModels(
 			});
 		}
 
+		if (Object.keys(modelDropReasons).length > 0) {
+			debugLogger.debug("Antigravity discovery dropped models", {
+				endpoint: redactedEndpoint,
+				dropReasons: modelDropReasons,
+			});
+		}
+
+		debugLogger.debug("Antigravity discovery kept models", {
+			endpoint: redactedEndpoint,
+			keptModelIds: models.map(m => m.id),
+		});
+
 		models.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+
+		if (debugEnabled) {
+			const allRawModelIds = Object.keys(parsed.models ?? {}).sort();
+			console.error("[GJC_DEBUG_ANTIGRAVITY_DISCOVERY]");
+			console.error(`  HTTP Status: ${response.status}`);
+			console.error(`  User-Agent: ${userAgent}`);
+			console.error(`  Endpoint: ${endpoint}`);
+			console.error(`  Total raw models from response: ${allRawModelIds.length}`);
+			console.error("\n  === KEPT MODELS ===");
+			console.error(`  Count: ${keptModelIds.length}`);
+			for (const modelId of keptModelIds) {
+				const details = keptModelDetails[modelId];
+				const attrs = [];
+				if (details?.entitlement) attrs.push(`entitlement=${details.entitlement}`);
+				if (details?.disabled === true) attrs.push("disabled=true");
+				if (details?.quota) attrs.push(`quota=${details.quota}`);
+				if (details?.isInternal === true) attrs.push("isInternal=true");
+				const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+				console.error(`    ${modelId}${attrStr}`);
+			}
+			if (filteredByDenylist.length > 0) {
+				console.error(`\n  === FILTERED BY DENYLIST ===`);
+				console.error(`  Count: ${filteredByDenylist.length}`);
+				for (const modelId of filteredByDenylist) {
+					const details = filteredModelDetails[modelId];
+					const attrs = [];
+					if (details?.entitlement) attrs.push(`entitlement=${details.entitlement}`);
+					if (details?.disabled === true) attrs.push("disabled=true");
+					if (details?.quota) attrs.push(`quota=${details.quota}`);
+					if (details?.isInternal === true) attrs.push("isInternal=true");
+					const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+					console.error(`    ${modelId}${attrStr}`);
+				}
+			}
+			if (filteredByRetirement.length > 0) {
+				console.error(`\n  === FILTERED BY RETIREMENT (${targetProvider}) ===`);
+				console.error(`  Count: ${filteredByRetirement.length}`);
+				for (const modelId of filteredByRetirement) {
+					const details = filteredModelDetails[modelId];
+					const attrs = [];
+					if (details?.entitlement) attrs.push(`entitlement=${details.entitlement}`);
+					if (details?.disabled === true) attrs.push("disabled=true");
+					if (details?.quota) attrs.push(`quota=${details.quota}`);
+					if (details?.isInternal === true) attrs.push("isInternal=true");
+					const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+					console.error(`    ${modelId}${attrStr}`);
+				}
+			}
+			if (filteredByDisabled.length > 0) {
+				console.error(`\n  === FILTERED (disabled) ===`);
+				console.error(`  Count: ${filteredByDisabled.length}`);
+				for (const modelId of filteredByDisabled) {
+					const details = filteredModelDetails[modelId];
+					const attrs = [];
+					if (details?.entitlement) attrs.push(`entitlement=${details.entitlement}`);
+					if (details?.disabled === true) attrs.push("disabled=true");
+					if (details?.quota) attrs.push(`quota=${details.quota}`);
+					if (details?.isInternal === true) attrs.push("isInternal=true");
+					const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+					console.error(`    ${modelId}${attrStr}`);
+				}
+			}
+			if (filteredByInternal.length > 0) {
+				console.error(`\n  === FILTERED (internal, not surfaced) ===`);
+				console.error(`  Count: ${filteredByInternal.length}`);
+				for (const modelId of filteredByInternal) {
+					const details = filteredModelDetails[modelId];
+					const attrs = [];
+					if (details?.entitlement) attrs.push(`entitlement=${details.entitlement}`);
+					if (details?.disabled === true) attrs.push("disabled=true");
+					if (details?.quota) attrs.push(`quota=${details.quota}`);
+					if (details?.isInternal === true) attrs.push("isInternal=true");
+					const attrStr = attrs.length > 0 ? ` [${attrs.join(", ")}]` : "";
+					console.error(`    ${modelId}${attrStr}`);
+				}
+			}
+			console.error(`\n  === SURFACE INFO ===`);
+			console.error(`  agentModelSorts surfaced: ${surfacedModelIds.size}`);
+			if (surfacedModelIds.size > 0) {
+				console.error(`    ${Array.from(surfacedModelIds).sort().join(", ")}`);
+			}
+		}
+
 		return models;
 	}
 
@@ -283,3 +456,15 @@ function toPositiveNumber(value: unknown, fallback: number): number {
 function trimTrailingSlashes(value: string): string {
 	return value.replace(/\/+$/, "");
 }
+
+export function getAntigravityDiscoveryUserAgent(): string {
+	return process.env.PI_AI_ANTIGRAVITY_USER_AGENT ? getAntigravityUserAgent() : getGeminiCliUserAgent();
+}
+
+function redactAntigravityEndpoint(value: string): string {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return "invalid endpoint";
+	}
+}

package/src/utils/idle-iterator.d.ts

@@ -23,11 +23,12 @@ export declare function getStreamIdleTimeoutRemediationMs(): number;
  * Returns the idle timeout used for OpenAI-family streaming transports.
  *
  * Honors `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` first (`PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is the legacy alias). Set `=0` to disable.
+ * A configured model timeout takes precedence over the built-in provider/model floors; environment overrides win over it.
  * When `provider` is given, long-reasoning hosts (xAI Grok and Grok Build) use that floor instead of the 120s default.
  * Grok models reached through other OpenAI-compatible hosts (`openrouter/x-ai/grok-*`, kilo, litellm, …) get the
  * same floor keyed on the model id, because long-reasoning silence is a property of the model (#4797).
  */
-export declare function getOpenAIStreamIdleTimeoutMs(provider?: string, modelId?: string): number | undefined;
+export declare function getOpenAIStreamIdleTimeoutMs(provider?: string, modelId?: string, configuredTimeoutMs?: number): number | undefined;
 /**
  * Returns the timeout used while waiting for the first stream event.
  * The first token can legitimately take longer than later inter-event gaps,
@@ -57,7 +58,7 @@ export declare function getStreamFirstEventTimeoutMs(idleTimeoutMs?: number, fal
  *   window so a short post-connect first-event budget cannot kill legitimate
  *   slow setup.
  */
-export declare function resolveOpenAISdkRequestTimeoutMs(provider: string, streamFirstEventTimeoutOverride?: number, modelId?: string): number | undefined;
+export declare function resolveOpenAISdkRequestTimeoutMs(provider: string, streamFirstEventTimeoutOverride?: number, modelId?: string, configuredIdleTimeoutMs?: number, effectiveIdleTimeoutOverride?: number): number | undefined;
 /**
  * Resolves the Anthropic SDK client `timeout` so stalled-before-headers requests
  * are bounded. The Anthropic first-event watchdog deliberately arms only once

package/src/utils/idle-iterator.ts

@@ -46,7 +46,7 @@ export function getProviderFirstEventTimeoutFallbackMs(provider: string): number
 	return provider === "kimi-code" ? KIMI_CODE_FIRST_EVENT_TIMEOUT_MS : undefined;
 }
 
-function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): number | undefined {
+function normalizeIdleTimeoutMs(value: string | undefined, fallback: number | undefined): number | undefined {
 	if (value === undefined) return fallback;
 	const parsed = Number(value);
 	if (!Number.isFinite(parsed)) return fallback;
@@ -86,16 +86,29 @@ export function getStreamIdleTimeoutRemediationMs(): number {
  * Returns the idle timeout used for OpenAI-family streaming transports.
  *
  * Honors `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` first (`PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is the legacy alias). Set `=0` to disable.
+ * A configured model timeout takes precedence over the built-in provider/model floors; environment overrides win over it.
  * When `provider` is given, long-reasoning hosts (xAI Grok and Grok Build) use that floor instead of the 120s default.
  * Grok models reached through other OpenAI-compatible hosts (`openrouter/x-ai/grok-*`, kilo, litellm, …) get the
  * same floor keyed on the model id, because long-reasoning silence is a property of the model (#4797).
  */
-export function getOpenAIStreamIdleTimeoutMs(provider?: string, modelId?: string): number | undefined {
+export function getOpenAIStreamIdleTimeoutMs(
+	provider?: string,
+	modelId?: string,
+	configuredTimeoutMs?: number,
+): number | undefined {
+	const builtInFallback =
+		getProviderStreamIdleTimeoutFallbackMs(provider ?? "") ??
+		(isGrokModelId(modelId) ? LONG_REASONING_STREAM_IDLE_TIMEOUT_MS : undefined) ??
+		DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+	let configuredFallback: number | undefined = builtInFallback;
+	if (configuredTimeoutMs === 0) {
+		configuredFallback = undefined;
+	} else if (configuredTimeoutMs !== undefined && Number.isFinite(configuredTimeoutMs) && configuredTimeoutMs > 0) {
+		configuredFallback = Math.max(1, Math.trunc(configuredTimeoutMs));
+	}
 	return normalizeIdleTimeoutMs(
 		$env.GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS,
-		getProviderStreamIdleTimeoutFallbackMs(provider ?? "") ??
-			(isGrokModelId(modelId) ? LONG_REASONING_STREAM_IDLE_TIMEOUT_MS : undefined) ??
-			DEFAULT_STREAM_IDLE_TIMEOUT_MS,
+		configuredFallback,
 	);
 }
 
@@ -139,19 +152,26 @@ export function resolveOpenAISdkRequestTimeoutMs(
 	provider: string,
 	streamFirstEventTimeoutOverride?: number,
 	modelId?: string,
+	configuredIdleTimeoutMs?: number,
+	effectiveIdleTimeoutOverride?: number,
 ): number | undefined {
 	const providerFirstEventFallbackMs = getProviderFirstEventTimeoutFallbackMs(provider);
 	const envSdkTimeoutMs = getStreamFirstEventTimeoutMs(
-		getOpenAIStreamIdleTimeoutMs(provider, modelId),
+		effectiveIdleTimeoutOverride ?? getOpenAIStreamIdleTimeoutMs(provider, modelId, configuredIdleTimeoutMs),
 		providerFirstEventFallbackMs,
 	);
 	if (streamFirstEventTimeoutOverride === 0) return undefined;
+	let sdkTimeoutMs: number | undefined;
 	if (streamFirstEventTimeoutOverride !== undefined) {
-		return providerFirstEventFallbackMs !== undefined
-			? streamFirstEventTimeoutOverride
-			: Math.max(envSdkTimeoutMs ?? 0, streamFirstEventTimeoutOverride);
+		sdkTimeoutMs =
+			providerFirstEventFallbackMs !== undefined
+				? streamFirstEventTimeoutOverride
+				: Math.max(envSdkTimeoutMs ?? 0, streamFirstEventTimeoutOverride);
+	} else {
+		sdkTimeoutMs = envSdkTimeoutMs;
 	}
-	return envSdkTimeoutMs;
+	if (sdkTimeoutMs === undefined || !Number.isFinite(sdkTimeoutMs) || sdkTimeoutMs <= 0) return undefined;
+	return Math.min(Math.trunc(sdkTimeoutMs), MAX_TIMER_DELAY_MS);
 }
 
 /**

package/src/utils/oauth/anthropic.ts

@@ -62,15 +62,16 @@ async function postJson(url: string, body: Record<string, string | number>): Pro
 /**
  * Decoded shape of Anthropic's `/v1/oauth/token` response (both
  * `authorization_code` exchange and `refresh_token` refresh return the same
- * envelope). The `account` block is inlined alongside the tokens, so we can
- * surface `accountId` / `email` on {@link OAuthCredentials} without a separate
- * `/api/oauth/profile` round-trip.
+ * envelope). The `account` and `organization` blocks are inlined alongside the
+ * tokens, so we can surface `accountId` / `email` / `organizationId` on
+ * {@link OAuthCredentials} without a separate `/api/oauth/profile` round-trip.
  */
 interface AnthropicTokenResponse {
 	access_token: string;
 	refresh_token: string;
 	expires_in: number;
 	account?: { uuid?: string; email_address?: string };
+	organization?: { uuid?: string; name?: string };
 }
 
 function parseOAuthTokenResponse(responseBody: string, operation: string): AnthropicTokenResponse {
@@ -83,22 +84,26 @@ function parseOAuthTokenResponse(responseBody: string, operation: string): Anthr
 	}
 }
 
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
 /**
- * Lift the OAuth response's `account: { uuid, email_address }` block onto
- * {@link OAuthCredentials} so downstream identity propagation (e.g.
- * `metadata.user_id.account_uuid`, usage tracking) works without a separate
- * `/api/oauth/profile` round-trip. Returns `undefined` for either field when
- * the response omits it or carries a non-string / empty value.
+ * Lift the OAuth response's `account: { uuid, email_address }` and
+ * `organization: { uuid, name }` blocks onto {@link OAuthCredentials} so
+ * downstream identity propagation (e.g. `metadata.user_id.account_uuid`, usage
+ * tracking, one stored credential per organization) works without a separate
+ * `/api/oauth/profile` round-trip. Returns `undefined` for any field the
+ * response omits or carries as a non-string / empty value.
  */
-function extractAccountFromTokenResponse(data: AnthropicTokenResponse): {
-	accountId?: string;
-	email?: string;
-} {
-	const accountUuid = data.account?.uuid;
-	const emailAddress = data.account?.email_address;
+function extractIdentityFromTokenResponse(
+	data: AnthropicTokenResponse,
+): Pick<OAuthCredentials, "accountId" | "email" | "organizationId" | "organizationName"> {
 	return {
-		accountId: typeof accountUuid === "string" && accountUuid.length > 0 ? accountUuid : undefined,
-		email: typeof emailAddress === "string" && emailAddress.length > 0 ? emailAddress : undefined,
+		accountId: nonEmptyString(data.account?.uuid),
+		email: nonEmptyString(data.account?.email_address),
+		organizationId: nonEmptyString(data.organization?.uuid),
+		organizationName: nonEmptyString(data.organization?.name),
 	};
 }
 
@@ -182,14 +187,12 @@ export class AnthropicOAuthFlow extends OAuthCallbackFlow {
 		}
 
 		const tokenData = parseOAuthTokenResponse(responseBody, "token exchange");
-		const { accountId, email } = extractAccountFromTokenResponse(tokenData);
 
 		return {
 			refresh: tokenData.refresh_token,
 			access: tokenData.access_token,
 			expires: Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000,
-			accountId,
-			email,
+			...extractIdentityFromTokenResponse(tokenData),
 		};
 	}
 }
@@ -221,13 +224,11 @@ export async function refreshAnthropicToken(refreshToken: string): Promise<OAuth
 	}
 
 	const data = parseOAuthTokenResponse(responseBody, "token refresh");
-	const { accountId, email } = extractAccountFromTokenResponse(data);
 
 	return {
 		refresh: data.refresh_token || refreshToken,
 		access: data.access_token,
 		expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
-		accountId,
-		email,
+		...extractIdentityFromTokenResponse(data),
 	};
 }

package/src/utils/oauth/api-key-validation.ts

@@ -193,19 +193,42 @@ export async function validateOpenAICompatibleApiKey(options: OpenAICompatibleVa
 				typeof parsed === "object" && parsed !== null && "choices" in parsed
 					? (parsed as { choices?: unknown }).choices
 					: undefined;
-			const firstChoice = Array.isArray(choices) ? choices[0] : undefined;
-			const message =
-				typeof firstChoice === "object" &&
-				firstChoice !== null &&
-				"message" in firstChoice &&
-				typeof (firstChoice as { message?: unknown }).message === "object" &&
-				!Array.isArray((firstChoice as { message?: unknown }).message)
-					? (firstChoice as { message: Record<string, unknown> }).message
-					: undefined;
-			const content = message?.content;
-			if (!(typeof content === "string" && content.trim().length > 0)) {
+			if (!Array.isArray(choices) || choices.length === 0) {
 				throw validationFailure(options.provider, options.apiKey, "the inference probe returned no choices");
 			}
+			const firstChoice: unknown = choices[0];
+			if (
+				typeof firstChoice !== "object" ||
+				firstChoice === null ||
+				Array.isArray(firstChoice) ||
+				!("message" in firstChoice)
+			) {
+				throw validationFailure(
+					options.provider,
+					options.apiKey,
+					"the inference probe returned choices without a valid message",
+				);
+			}
+			const choice = firstChoice as Record<string, unknown>;
+			const rawMessage = choice.message;
+			if (typeof rawMessage !== "object" || rawMessage === null || Array.isArray(rawMessage)) {
+				throw validationFailure(
+					options.provider,
+					options.apiKey,
+					"the inference probe returned choices without a valid message",
+				);
+			}
+			const message = rawMessage as Record<string, unknown>;
+			const hasContent = typeof message.content === "string" && message.content.trim().length > 0;
+			const hasReasoningContent =
+				typeof message.reasoning_content === "string" && message.reasoning_content.trim().length > 0;
+			if (!hasContent && !hasReasoningContent && choice.finish_reason !== "length") {
+				throw validationFailure(
+					options.provider,
+					options.apiKey,
+					"the inference probe returned choices with empty content",
+				);
+			}
 		}
 		return;
 	}

package/src/utils/oauth/glm-zcode.d.ts

@@ -1,33 +1,3 @@
-/**
- * GLM ZCode OAuth flow (UNOFFICIAL, opt-in).
- *
- * Replicates how the ZCode desktop app turns a Z.AI login into usable GLM model
- * access. This is NOT an official Z.AI OAuth client: it reuses ZCode's authorize
- * page, broker, and a custom-protocol redirect. It may break at any time and may
- * violate ZCode/Z.AI Terms of Service. Endpoints/client id are overridable via
- * `ZCODE_OAUTH_*` environment variables.
- *
- * Verified end-to-end against the ZCode host bundle (`resolveZaiApiKey` /
- * `resolveBizApiKey`) and live traffic:
- *   1. Authorize: GET {authorize}?redirect_uri=zcode://oauth/callback&response_type=code&client_id=...&state=...
- *      (custom-protocol redirect → a CLI cannot catch it, so the user pastes the code/redirect URL)
- *   2. Broker:    POST {broker} { provider:"zai", code, redirect_uri, state }
- *                  → { data: { token: <ZCode JWT>, zai: { access_token: <upstream Z.AI token> } } }
- *   3. Business:  POST {z/login} { token: <upstream Z.AI token> } → { data: { access_token: <business token> } }
- *   4. Provision: with the business token, GET getCustomerInfo → default org/project,
- *      GET/POST .../api_keys (find/create a key named "zcode-api-key"),
- *      GET .../api_keys/copy/{id} → secretKey ⇒ a real Z.AI API key "{id}.{secret}".
- *
- * Credential mapping:
- *   - `access`  = the provisioned **Z.AI API key** ("{id}.{secret}"). Model requests go to
- *                 `https://api.z.ai/api/anthropic/v1/messages` with `Authorization: Bearer <key>`
- *                 (exactly like a dashboard key) — NO zcode.z.ai gateway, NO captcha.
- *   - `refresh` = the upstream Z.AI OAuth access token (used to re-provision the key).
- * The API key is long-lived, so `expires` is set far in the future.
- *
- * This provider must NEVER force `isOAuth=true`: the key is a plain Z.AI API key, and
- * api.z.ai is not api.anthropic.com, so the Anthropic path already emits a plain bearer.
- */
 import { OAuthCallbackFlow } from "./callback-server";
 import type { OAuthController, OAuthCredentials } from "./types";
 export declare const GLM_ZCODE_REFRESH_SKEW_MS: number;

package/src/utils/oauth/glm-zcode.ts

@@ -4,8 +4,9 @@
  * Replicates how the ZCode desktop app turns a Z.AI login into usable GLM model
  * access. This is NOT an official Z.AI OAuth client: it reuses ZCode's authorize
  * page, broker, and a custom-protocol redirect. It may break at any time and may
- * violate ZCode/Z.AI Terms of Service. Endpoints/client id are overridable via
- * `ZCODE_OAUTH_*` environment variables.
+ * violate ZCode/Z.AI Terms of Service. Endpoints and the client id are
+ * overridable via `ZCODE_OAUTH_*` from the launching shell or user-owned env
+ * files. A project `.env` is not a trusted source for those values.
  *
  * Verified end-to-end against the ZCode host bundle (`resolveZaiApiKey` /
  * `resolveBizApiKey`) and live traffic:
@@ -28,6 +29,7 @@
  * This provider must NEVER force `isOAuth=true`: the key is a plain Z.AI API key, and
  * api.z.ai is not api.anthropic.com, so the Anthropic path already emits a plain bearer.
  */
+import { $credentialEnv } from "@gajae-code/utils";
 import { OAuthCallbackFlow, type OAuthCallbackFlowOptions, parseCallbackInput } from "./callback-server";
 import type { OAuthController, OAuthCredentials } from "./types";
 
@@ -52,9 +54,18 @@ export const GLM_ZCODE_ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic";
 
 type FetchImpl = typeof globalThis.fetch;
 
+/**
+ * Trusted override for one `ZCODE_OAUTH_*` name.
+ *
+ * These values choose where the authorization code and upstream token are sent.
+ * `$credentialEnv` keeps the launching shell and user-owned env files and skips
+ * a project `.env`. A shell value is also skipped when it repeats that file
+ * or the project declaration is dynamic, and when no other trusted source
+ * sets the name an empty value still uses the built-in endpoint.
+ */
 function envOr(name: string, fallback: string): string {
-	const value = process.env[name];
-	return value && value.trim().length > 0 ? value.trim() : fallback;
+	const value = $credentialEnv(name)?.trim();
+	return value ? value : fallback;
 }
 
 function resolveAuthorizeUrl(): string {

package/src/utils/oauth/openai-codex.ts

@@ -63,6 +63,41 @@ interface PKCE {
 	challenge: string;
 }
 
+/**
+ * Extract a readable error message from OpenAI OAuth error response.
+ * Handles both string errors (error + error_description) and object errors (code/type + message).
+ */
+function extractOpenAIErrorMessage(body: unknown): string {
+	if (typeof body !== "object" || body === null) return "";
+
+	const obj = body as Record<string, unknown>;
+	const error = obj.error;
+
+	if (typeof error === "string") {
+		// String error: "invalid_grant", optionally explained by error_description.
+		// Parts are joined so an empty error string never leaves a dangling separator.
+		const desc = obj.error_description;
+		const parts = desc !== undefined && typeof desc === "string" && desc.length > 0 ? [error, desc] : [error];
+		return parts.filter(part => part.length > 0).join(": ");
+	}
+
+	if (typeof error === "object" && error !== null) {
+		// Object error: {message, type, code}. `code` wins over `type`, but only when
+		// it is a usable string — a numeric or empty code must fall back to the type
+		// rather than silently dropping both.
+		const err = error as Record<string, unknown>;
+		const code = typeof err.code === "string" && err.code.length > 0 ? err.code : err.type;
+		const msg = err.message;
+
+		const parts: string[] = [];
+		if (typeof code === "string" && code.length > 0) parts.push(code);
+		if (typeof msg === "string" && msg.length > 0) parts.push(msg);
+		return parts.join(": ");
+	}
+
+	return "";
+}
+
 class OpenAICodexOAuthFlow extends OAuthCallbackFlow {
 	constructor(
 		ctrl: OAuthController,
@@ -120,9 +155,9 @@ async function exchangeCodeForToken(code: string, verifier: string, redirectUri:
 	if (!tokenResponse.ok) {
 		let detail = `${tokenResponse.status}`;
 		try {
-			const body = (await tokenResponse.json()) as { error?: string; error_description?: string };
-			if (body.error)
-				detail = `${tokenResponse.status} ${body.error}${body.error_description ? `: ${body.error_description}` : ""}`;
+			const body = await tokenResponse.json();
+			const errorMsg = extractOpenAIErrorMessage(body);
+			if (errorMsg) detail = `${tokenResponse.status} ${errorMsg}`;
 		} catch {}
 		throw new Error(`Token exchange failed: ${detail}`);
 	}
@@ -272,9 +307,9 @@ export async function refreshOpenAICodexToken(refreshToken: string): Promise<OAu
 	if (!response.ok) {
 		let detail = `${response.status}`;
 		try {
-			const body = (await response.json()) as { error?: string; error_description?: string };
-			if (body.error)
-				detail = `${response.status} ${body.error}${body.error_description ? `: ${body.error_description}` : ""}`;
+			const body = await response.json();
+			const errorMsg = extractOpenAIErrorMessage(body);
+			if (errorMsg) detail = `${response.status} ${errorMsg}`;
 		} catch {}
 		throw new Error(`OpenAI Codex token refresh failed: ${detail}`);
 	}