@gajae-code/ai 0.18.11 → 0.18.12

package/src/stream.d.ts

@@ -1,7 +1,19 @@
 import type { Effort } from "./model-thinking";
 import type { AnthropicOptions } from "./providers/anthropic";
-import type { Api, AssistantMessage, Context, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types";
+import type { Api, AssistantMessage, Context, FetchImpl, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types";
 import { AssistantMessageEventStream } from "./utils/event-stream";
+export type EnvApiKeyCredentialSource = {
+    kind: "environment";
+    name: string;
+} | {
+    kind: "google-adc";
+    source: "explicit-file" | "default-file" | "metadata-server";
+} | {
+    kind: "aws";
+    source: "bearer-token" | "environment-credentials" | "profile" | "instance-profile";
+} | {
+    kind: "unknown";
+};
 /**
  * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
  *
@@ -9,6 +21,26 @@ import { AssistantMessageEventStream } from "./utils/event-stream";
  * loaded into $env for app/tool execution, but must not silently fund GJC model requests.
  */
 export declare function getEnvApiKey(provider: string): string | undefined;
+/**
+ * List configured environment variable names consulted for a provider's
+ * environment credential. Values are never returned. This intentionally uses
+ * the same credential-only environment reader as {@link getEnvApiKey}.
+ */
+export declare function getEnvApiKeyEnvNames(provider: string): string[];
+/** Describe the selected source without exposing credential values or unvalidated ADC files. */
+export declare function getEnvApiKeyCredentialSource(provider: string, options?: {
+    fetch?: FetchImpl;
+}): Promise<EnvApiKeyCredentialSource | undefined>;
+/** Enumerate usable credential candidates in provider dispatch precedence without exposing credentials. */
+export declare function getEnvApiKeyCredentialSources(provider: string, options?: {
+    fetch?: FetchImpl;
+}): Promise<EnvApiKeyCredentialSource[]>;
+/** Resolve Vertex ADC provenance, including metadata-server credentials, without acquiring a token. */
+export declare function getGoogleVertexCredentialSource(options?: {
+    fetch?: FetchImpl;
+}): Promise<EnvApiKeyCredentialSource | undefined>;
+/** Name of the environment variable whose value is selected by `getEnvApiKey`, when identifiable. */
+export declare function getEnvApiKeyEnvName(provider: string): Promise<string | undefined>;
 /**
  * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
  * Used by `gjc auth-broker migrate --include-env` to discover env-sourced keys

package/src/stream.ts

@@ -36,6 +36,7 @@ import {
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
 import {
+	hasAwsInstanceProfileCredentialSource,
 	hasResolvableAwsProfileSource,
 	isValidBedrockBearerToken,
 	readAwsStaticEnvironmentCredentials,
@@ -43,6 +44,7 @@ import {
 import type { CursorOptions } from "./providers/cursor";
 import type { DevinAcpOptions } from "./providers/devin-acp";
 import type { GoogleOptions } from "./providers/google";
+import { getVertexCredentialSource, isValidVertexLocation } from "./providers/google-auth";
 import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli";
 import type { GoogleVertexOptions } from "./providers/google-vertex";
 import type { KiroCodeWhispererOptions } from "./providers/kiro-codewhisperer";
@@ -73,6 +75,7 @@ import type {
 	AssistantMessageEvent,
 	AuthRetryCredential,
 	Context,
+	FetchImpl,
 	Model,
 	OptionsForApi,
 	SimpleStreamOptions,
@@ -83,8 +86,6 @@ import type {
 import { AssistantMessageEventStream } from "./utils/event-stream";
 import { isFoundryEnabled } from "./utils/foundry";
 
-let cachedVertexAdcCredentialsExists: boolean | null = null;
-
 function assertCustomApiRegistryActive(registry: CustomApiRegistry | undefined): void {
 	if (registry !== undefined) CustomApiRegistry.assertActive(registry);
 }
@@ -111,21 +112,19 @@ function isBuiltInApi(api: Api): boolean {
 }
 
 function hasVertexAdcCredentials(): boolean {
-	if (cachedVertexAdcCredentialsExists === null) {
-		const gacPath = $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
-		if (gacPath) {
-			cachedVertexAdcCredentialsExists = fs.existsSync(gacPath);
-		} else {
-			cachedVertexAdcCredentialsExists = fs.existsSync(
-				path.join(getTrustedHomeDir(), ".config", "gcloud", "application_default_credentials.json"),
-			);
-		}
-	}
-	return cachedVertexAdcCredentialsExists;
+	const gacPath = $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
+	if (gacPath) return fs.existsSync(gacPath);
+	return fs.existsSync(path.join(getTrustedHomeDir(), ".config", "gcloud", "application_default_credentials.json"));
 }
 
 type KeyResolver = string | (() => string | undefined);
 
+export type EnvApiKeyCredentialSource =
+	| { kind: "environment"; name: string }
+	| { kind: "google-adc"; source: "explicit-file" | "default-file" | "metadata-server" }
+	| { kind: "aws"; source: "bearer-token" | "environment-credentials" | "profile" | "instance-profile" }
+	| { kind: "unknown" };
+
 const serviceProviderMap: Record<string, KeyResolver> = {
 	"alibaba-token-plan": "ALIBABA_TOKEN_PLAN_API_KEY",
 	openai: () => $credentialEnv("OPENAI_API_KEY"),
@@ -223,6 +222,25 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	xiaomi: "XIAOMI_API_KEY",
 };
 
+const functionResolverEnvNames: Record<string, readonly string[]> = {
+	openai: ["OPENAI_API_KEY"],
+	kiro: ["KIRO_API_KEY", "AWS_BEARER_TOKEN_KIRO"],
+	"github-copilot": ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+	"google-vertex": ["GOOGLE_CLOUD_API_KEY"],
+	"amazon-bedrock": ["AWS_BEARER_TOKEN_BEDROCK"],
+	huggingface: ["HUGGINGFACE_HUB_TOKEN", "HF_TOKEN"],
+	"qwen-portal": ["QWEN_OAUTH_TOKEN", "QWEN_PORTAL_API_KEY"],
+};
+
+function getFunctionResolverEnvNames(provider: string): readonly string[] {
+	if (provider === "anthropic") {
+		return isFoundryEnabled()
+			? ["ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"]
+			: ["ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"];
+	}
+	return functionResolverEnvNames[provider] ?? [];
+}
+
 /**
  * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
  *
@@ -237,6 +255,82 @@ export function getEnvApiKey(provider: string): string | undefined {
 	return resolver?.();
 }
 
+/**
+ * List configured environment variable names consulted for a provider's
+ * environment credential. Values are never returned. This intentionally uses
+ * the same credential-only environment reader as {@link getEnvApiKey}.
+ */
+export function getEnvApiKeyEnvNames(provider: string): string[] {
+	const resolver = serviceProviderMap[provider];
+	const names = typeof resolver === "string" ? [resolver] : getFunctionResolverEnvNames(provider);
+	return names.filter(name => {
+		const value = $credentialEnv(name);
+		if (value === undefined) return false;
+		if (provider === "kiro" && name === "KIRO_API_KEY") {
+			return value.trim().startsWith("ksk_") && !/[\x00-\x1f\x7f]/.test(value);
+		}
+		if (provider === "amazon-bedrock" && name === "AWS_BEARER_TOKEN_BEDROCK") {
+			return isValidBedrockBearerToken(value);
+		}
+		return true;
+	});
+}
+
+/** Describe the selected source without exposing credential values or unvalidated ADC files. */
+export async function getEnvApiKeyCredentialSource(
+	provider: string,
+	options?: { fetch?: FetchImpl },
+): Promise<EnvApiKeyCredentialSource | undefined> {
+	return (await getEnvApiKeyCredentialSources(provider, options))[0];
+}
+
+/** Enumerate usable credential candidates in provider dispatch precedence without exposing credentials. */
+export async function getEnvApiKeyCredentialSources(
+	provider: string,
+	options?: { fetch?: FetchImpl },
+): Promise<EnvApiKeyCredentialSource[]> {
+	const sources: EnvApiKeyCredentialSource[] = getEnvApiKeyEnvNames(provider).map(
+		(name): EnvApiKeyCredentialSource =>
+			provider === "amazon-bedrock" && name === "AWS_BEARER_TOKEN_BEDROCK"
+				? { kind: "aws", source: "bearer-token" }
+				: { kind: "environment", name },
+	);
+
+	if (provider === "google-vertex") {
+		const project = $credentialEnv("GOOGLE_CLOUD_PROJECT") || $credentialEnv("GCLOUD_PROJECT");
+		const location = $credentialEnv("GOOGLE_CLOUD_LOCATION");
+		if (project && location && isValidVertexLocation(location)) {
+			const source = await getVertexCredentialSource({ fetch: options?.fetch });
+			if (source) sources.push({ kind: "google-adc", source });
+		}
+	} else if (provider === "amazon-bedrock") {
+		const bearerToken = $credentialEnv("AWS_BEARER_TOKEN_BEDROCK");
+		if (bearerToken && !isValidBedrockBearerToken(bearerToken)) return sources;
+		if (readAwsStaticEnvironmentCredentials()) {
+			sources.push({ kind: "aws", source: "environment-credentials" });
+		}
+		if (hasResolvableAwsProfileSource()) sources.push({ kind: "aws", source: "profile" });
+		if (await hasAwsInstanceProfileCredentialSource({ fetch: options?.fetch })) {
+			sources.push({ kind: "aws", source: "instance-profile" });
+		}
+	}
+
+	return sources;
+}
+
+/** Resolve Vertex ADC provenance, including metadata-server credentials, without acquiring a token. */
+export async function getGoogleVertexCredentialSource(options?: {
+	fetch?: FetchImpl;
+}): Promise<EnvApiKeyCredentialSource | undefined> {
+	return (await getEnvApiKeyCredentialSources("google-vertex", options))[0];
+}
+
+/** Name of the environment variable whose value is selected by `getEnvApiKey`, when identifiable. */
+export async function getEnvApiKeyEnvName(provider: string): Promise<string | undefined> {
+	const source = await getEnvApiKeyCredentialSource(provider);
+	return source?.kind === "environment" ? source.name : undefined;
+}
+
 /**
  * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
  * Used by `gjc auth-broker migrate --include-env` to discover env-sourced keys

package/src/types.d.ts

@@ -89,6 +89,8 @@ export interface ToolChoiceCompat {
     supportsToolChoice?: boolean;
     /** Legacy flag for forced tool_choice support. */
     supportsForcedToolChoice?: boolean;
+    /** Whether the provider supports OpenAI ultrafast service tier. Default: false. */
+    supportsUltrafastTier?: boolean;
 }
 export type CacheRetention = "none" | "short" | "long";
 /**
@@ -107,9 +109,11 @@ export type CacheRetention = "none" | "short" | "long";
  * - `"openai-only"` → `"priority"` on `openai` and `OpenAI code provider`; ignored elsewhere.
  * - `"Anthropic model-only"` → `"priority"` on direct `anthropic` (not Bedrock/Vertex Anthropic model).
  */
-export type ServiceTier = "auto" | "default" | "flex" | "scale" | "priority" | "openai-only" | "claude-only";
+export type ServiceTier = "auto" | "default" | "flex" | "scale" | "priority" | "ultrafast" | "openai-only" | "claude-only";
 /** Resolved tier — one of the values that providers actually consume on the wire. */
 export type ResolvedServiceTier = Exclude<ServiceTier, "openai-only" | "claude-only">;
+/** Parse a provider-reported service tier, leaving unknown response values for request fallback. */
+export declare function parseResolvedServiceTier(value: unknown): ResolvedServiceTier | undefined;
 /**
  * Resolves a possibly scoped `ServiceTier` to the effective tier for the
  * given provider. Scoped values match their target family and otherwise
@@ -119,13 +123,19 @@ export declare function resolveServiceTier(serviceTier: ServiceTier | null | und
 /**
  * True when the (possibly scoped) tier should be sent as an OpenAI-compatible
  * `service_tier` request field. Custom providers must explicitly opt in through
- * `compat.supportsServiceTier`; unknown providers remain fail-closed.
+ * `compat.supportsServiceTier` for the existing tiers or a model-specific
+ * `supportsUltrafastTier` capability for ultrafast; unknown providers remain fail-closed.
+ *
+ * Note: ultrafast has an additional gating requirement via `modelSupportsUltrafastTier`
+ * to ensure it is only sent to models that explicitly support it.
  */
-export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined, supportsServiceTier?: boolean): boolean;
+export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined, supportsServiceTier?: boolean, supportsUltrafastTier?: boolean): boolean;
 /**
  * True when a priority tier is realized as a fast-mode request on the provider's
  * wire protocol. Custom OpenAI-compatible proxies opt in explicitly rather than
  * inheriting support merely because their API shape resembles OpenAI.
+ *
+ * Note: ultrafast is distinct from priority and is not considered fast-mode.
  */
 export declare function isFastModeEffectiveForProvider(serviceTier: ServiceTier | null | undefined, provider: Provider | undefined, supportsServiceTier?: boolean): boolean;
 /**
@@ -611,6 +621,8 @@ export interface AssistantMessage {
     provider: Provider;
     model: string;
     responseId?: string;
+    /** Effective service tier reported by the provider, or the sent tier when the provider omits it. */
+    serviceTier?: ResolvedServiceTier;
     usage: Usage;
     stopReason: StopReason;
     errorMessage?: string;
@@ -905,6 +917,7 @@ export type AssistantMessageEvent = {
     contentIndex?: undefined;
     reason: Extract<StopReason, "aborted" | "error">;
     error: AssistantMessage;
+    partial?: AssistantMessage;
 } | {
     type: "toolChoiceIncapability";
     contentIndex?: undefined;
@@ -949,6 +962,12 @@ export interface OpenAICompat extends ToolChoiceCompat {
      * preserves or intentionally realizes OpenAI priority processing.
      */
     supportsServiceTier?: boolean;
+    /**
+     * Whether the model explicitly supports the ultrafast service tier.
+     * Only models that set this flag will send ultrafast tier to the API.
+     * Models: gpt-6-astra and gpt-6.1-sol.
+     */
+    supportsUltrafastTier?: boolean;
     /**
      * Tool names the provider reserves for its own built-ins and refuses to
      * accept as custom function declarations. A colliding tool is **dropped**
@@ -1170,6 +1189,8 @@ export interface Model<TApi extends Api = any> {
     requestTransform?: ModelRequestTransform;
     /** Default prompt-cache retention preference for this model when the request omits one. */
     cacheRetention?: CacheRetention;
+    /** Configured inter-event idle timeout for this model, in milliseconds. */
+    streamIdleTimeoutMs?: number;
     /** Provider-assigned priority value (lower = higher priority). */
     priority?: number;
     /** Canonical thinking capability metadata for this model. */
@@ -1194,3 +1215,5 @@ export interface Model<TApi extends Api = any> {
 }
 /** True when a model explicitly opts into OpenAI-compatible `service_tier` forwarding. */
 export declare function modelSupportsServiceTier(model: Pick<Model, "compat"> | undefined): boolean;
+/** True when a model explicitly opts into OpenAI ultrafast service tier support. */
+export declare function modelSupportsUltrafastTier(model: Pick<Model, "compat"> | undefined): boolean;

package/src/types.ts

@@ -237,6 +237,8 @@ export interface ToolChoiceCompat {
 	supportsToolChoice?: boolean;
 	/** Legacy flag for forced tool_choice support. */
 	supportsForcedToolChoice?: boolean;
+	/** Whether the provider supports OpenAI ultrafast service tier. Default: false. */
+	supportsUltrafastTier?: boolean;
 }
 
 // Base options all providers share
@@ -258,11 +260,34 @@ export type CacheRetention = "none" | "short" | "long";
  * - `"openai-only"` → `"priority"` on `openai` and `OpenAI code provider`; ignored elsewhere.
  * - `"Anthropic model-only"` → `"priority"` on direct `anthropic` (not Bedrock/Vertex Anthropic model).
  */
-export type ServiceTier = "auto" | "default" | "flex" | "scale" | "priority" | "openai-only" | "claude-only";
+export type ServiceTier =
+	| "auto"
+	| "default"
+	| "flex"
+	| "scale"
+	| "priority"
+	| "ultrafast"
+	| "openai-only"
+	| "claude-only";
 
 /** Resolved tier — one of the values that providers actually consume on the wire. */
 export type ResolvedServiceTier = Exclude<ServiceTier, "openai-only" | "claude-only">;
 
+/** Parse a provider-reported service tier, leaving unknown response values for request fallback. */
+export function parseResolvedServiceTier(value: unknown): ResolvedServiceTier | undefined {
+	switch (value) {
+		case "auto":
+		case "default":
+		case "flex":
+		case "scale":
+		case "priority":
+		case "ultrafast":
+			return value;
+		default:
+			return undefined;
+	}
+}
+
 /**
  * Resolves a possibly scoped `ServiceTier` to the effective tier for the
  * given provider. Scoped values match their target family and otherwise
@@ -286,15 +311,23 @@ export function resolveServiceTier(
 /**
  * True when the (possibly scoped) tier should be sent as an OpenAI-compatible
  * `service_tier` request field. Custom providers must explicitly opt in through
- * `compat.supportsServiceTier`; unknown providers remain fail-closed.
+ * `compat.supportsServiceTier` for the existing tiers or a model-specific
+ * `supportsUltrafastTier` capability for ultrafast; unknown providers remain fail-closed.
+ *
+ * Note: ultrafast has an additional gating requirement via `modelSupportsUltrafastTier`
+ * to ensure it is only sent to models that explicitly support it.
  */
 export function shouldSendServiceTier(
 	serviceTier: ServiceTier | null | undefined,
 	provider: Provider | undefined,
 	supportsServiceTier = false,
+	supportsUltrafastTier = false,
 ): boolean {
 	const resolved = resolveServiceTier(serviceTier, provider);
 	if (provider === "deepinfra") return resolved === "priority";
+	if (resolved === "ultrafast") {
+		return provider === "openai" || provider === "openai-codex" || supportsUltrafastTier;
+	}
 	if (provider !== "openai" && provider !== "openai-codex" && !supportsServiceTier) return false;
 	return resolved === "flex" || resolved === "scale" || resolved === "priority";
 }
@@ -303,6 +336,8 @@ export function shouldSendServiceTier(
  * True when a priority tier is realized as a fast-mode request on the provider's
  * wire protocol. Custom OpenAI-compatible proxies opt in explicitly rather than
  * inheriting support merely because their API shape resembles OpenAI.
+ *
+ * Note: ultrafast is distinct from priority and is not considered fast-mode.
  */
 export function isFastModeEffectiveForProvider(
 	serviceTier: ServiceTier | null | undefined,
@@ -856,6 +891,8 @@ export interface AssistantMessage {
 	provider: Provider;
 	model: string;
 	responseId?: string; // Provider-specific response/message identifier when the upstream API exposes one
+	/** Effective service tier reported by the provider, or the sent tier when the provider omits it. */
+	serviceTier?: ResolvedServiceTier;
 	usage: Usage;
 	stopReason: StopReason;
 	errorMessage?: string;
@@ -1143,6 +1180,7 @@ export type AssistantMessageEvent =
 			contentIndex?: undefined;
 			reason: Extract<StopReason, "aborted" | "error">;
 			error: AssistantMessage;
+			partial?: AssistantMessage;
 	  }
 	| {
 			type: "toolChoiceIncapability";
@@ -1189,6 +1227,12 @@ export interface OpenAICompat extends ToolChoiceCompat {
 	 * preserves or intentionally realizes OpenAI priority processing.
 	 */
 	supportsServiceTier?: boolean;
+	/**
+	 * Whether the model explicitly supports the ultrafast service tier.
+	 * Only models that set this flag will send ultrafast tier to the API.
+	 * Models: gpt-6-astra and gpt-6.1-sol.
+	 */
+	supportsUltrafastTier?: boolean;
 	/**
 	 * Tool names the provider reserves for its own built-ins and refuses to
 	 * accept as custom function declarations. A colliding tool is **dropped**
@@ -1420,6 +1464,8 @@ export interface Model<TApi extends Api = any> {
 	requestTransform?: ModelRequestTransform;
 	/** Default prompt-cache retention preference for this model when the request omits one. */
 	cacheRetention?: CacheRetention;
+	/** Configured inter-event idle timeout for this model, in milliseconds. */
+	streamIdleTimeoutMs?: number;
 	/** Provider-assigned priority value (lower = higher priority). */
 	priority?: number;
 	/** Canonical thinking capability metadata for this model. */
@@ -1460,3 +1506,10 @@ export interface Model<TApi extends Api = any> {
 export function modelSupportsServiceTier(model: Pick<Model, "compat"> | undefined): boolean {
 	return Boolean(model?.compat && "supportsServiceTier" in model.compat && model.compat.supportsServiceTier === true);
 }
+
+/** True when a model explicitly opts into OpenAI ultrafast service tier support. */
+export function modelSupportsUltrafastTier(model: Pick<Model, "compat"> | undefined): boolean {
+	return Boolean(
+		model?.compat && "supportsUltrafastTier" in model.compat && model.compat.supportsUltrafastTier === true,
+	);
+}

package/src/usage/claude.ts

@@ -357,7 +357,9 @@ async function fetchClaudeUsage(params: UsageFetchParams, ctx: UsageFetchContext
 
 	const payloadResult = await fetchUsagePayload(url, headers, ctx, params.signal);
 	if (!payloadResult || !isRecord(payloadResult.payload)) return null;
-	const { payload, orgId } = payloadResult;
+	const { payload } = payloadResult;
+	// Limits are per organization, and one account can sign in to several of them.
+	const orgId = payloadResult.orgId ?? credential.organizationId;
 
 	const fiveHour = parseBucket(payload.five_hour);
 	const sevenDay = parseBucket(payload.seven_day);
@@ -408,7 +410,7 @@ async function fetchClaudeUsage(params: UsageFetchParams, ctx: UsageFetchContext
 	].filter((limit): limit is UsageLimit => limit !== null);
 
 	if (limits.length === 0) return null;
-	const identity = extractUsageIdentity(payload, orgId);
+	const identity = extractUsageIdentity(payload, payloadResult.orgId);
 	let accountId = identity.accountId ?? credential.accountId;
 	let email = identity.email ?? credential.email;
 	if ((!accountId || !email) && !params.signal?.aborted) {

package/src/usage.ts

@@ -156,6 +156,9 @@ export interface UsageCredential {
 	email?: string;
 	enterpriseUrl?: string;
 	profileArn?: string;
+	/** Organization the OAuth token is scoped to; usage limits are per organization. */
+	organizationId?: string;
+	organizationName?: string;
 	mcpBinding?: UsageMCPOAuthBinding;
 	metadata?: Record<string, unknown>;
 }

package/src/utils/discovery/antigravity.ts

@@ -3,6 +3,14 @@ import { isRetiredModelKey } from "../../model-retirements";
 import { getAntigravityUserAgent } 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 +43,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 +95,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
@@ -182,6 +199,7 @@ 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 ?? getAntigravityUserAgent();
 	const endpoints = options.endpoint
 		? [trimTrailingSlashes(options.endpoint)]
 		: DEFAULT_ANTIGRAVITY_DISCOVERY_ENDPOINTS.map(trimTrailingSlashes);
@@ -194,7 +212,7 @@ export async function fetchAntigravityDiscoveryModels(
 				headers: {
 					Authorization: `Bearer ${options.token}`,
 					"Content-Type": "application/json",
-					"User-Agent": options.userAgent ?? getAntigravityUserAgent(),
+					"User-Agent": userAgent,
 				},
 				body: JSON.stringify({}),
 				signal,
@@ -228,15 +246,56 @@ 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">[] = [];
 
 		for (const [modelId, model] of Object.entries(parsed.models ?? {})) {
-			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId) || isRetiredModelKey(targetProvider, modelId)) {
+			if (ANTIGRAVITY_DISCOVERY_DENYLIST.has(modelId)) {
+				if (debugEnabled) {
+					filteredByDenylist.push(modelId);
+					filteredModelDetails[modelId] = { ...model, reason: "denylist" };
+				}
+				continue;
+			}
+			if (isRetiredModelKey(targetProvider, modelId)) {
+				if (debugEnabled) {
+					filteredByRetirement.push(modelId);
+					filteredModelDetails[modelId] = { ...model, reason: `retired-${targetProvider}` };
+				}
+				continue;
+			}
+			if (model.disabled === true) {
+				if (debugEnabled) {
+					filteredByDisabled.push(modelId);
+					filteredModelDetails[modelId] = { ...model, reason: "disabled" };
+				}
 				continue;
 			}
 			if (model.isInternal === true && !surfacedModelIds.has(modelId)) {
+				if (debugEnabled) {
+					filteredByInternal.push(modelId);
+					filteredModelDetails[modelId] = { ...model, reason: "internal-not-surfaced" };
+				}
 				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({
@@ -259,6 +318,89 @@ export async function fetchAntigravityDiscoveryModels(
 		}
 
 		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;
 	}