@gajae-code/ai 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-06-15
+
+### Changed
+
+- Changed the Anthropic provider's default prompt-cache retention to `long` (`ttl: "1h"`) when a request and model omit `cacheRetention`. The previous default (~5m) was too fragile for long-running Codex/Gajae-Code subagent workflows, where the cached prefix was frequently evicted between turns. The 1h `ttl` marker is only emitted on the canonical Anthropic API (`api.anthropic.com`) for models advertising `supportsLongCacheRetention`; proxies, gateways, and models without that capability still fall back to the default ephemeral breakpoint (Anthropic services it at ~5m). Explicit request/model `cacheRetention` and the `GJC_CACHE_RETENTION`/`PI_CACHE_RETENTION` env overrides continue to win, and `resolveCacheRetention` now accepts a `fallback` argument (defaulting to `"short"`) so non-Anthropic providers are unaffected.
+
+## [0.5.1] - 2026-06-14
+
+### Fixed
+
+- Classified model/message limit exhaustion as persistent usage-limit errors so hosts fail fast or switch credentials instead of leaving sessions in an unbounded retry/working state.
+
 ## [0.5.0] - 2026-06-13
 
 ### Added

package/dist/types/index.d.ts

@@ -33,6 +33,7 @@ export * from "./usage/claude";
 export * from "./usage/gemini";
 export * from "./usage/github-copilot";
 export * from "./usage/google-antigravity";
+export * from "./usage/grok-cli";
 export * from "./usage/kimi";
 export * from "./usage/minimax-code";
 export * from "./usage/openai-codex";

package/dist/types/usage/grok-cli.d.ts

@@ -0,0 +1,10 @@
+import type { CredentialRankingStrategy, UsageProvider } from "../usage";
+interface BillingUsage {
+    monthlyLimit: number;
+    used: number;
+    billingPeriodEnd: string;
+}
+export declare function parseGrokCliBillingUsage(payload: unknown): BillingUsage;
+export declare const grokCliUsageProvider: UsageProvider;
+export declare const grokCliRankingStrategy: CredentialRankingStrategy;
+export {};

package/dist/types/utils/oauth/xai.d.ts

@@ -8,16 +8,23 @@ interface XaiDiscovery {
     authorizationEndpoint: string;
     tokenEndpoint: string;
 }
+export interface XaiOAuthFlowOptions {
+    extraAuthorizeParams?: Readonly<Record<string, string>>;
+}
+export interface XaiOAuthRefreshOptions {
+    signal?: AbortSignal;
+    extraTokenParams?: Readonly<Record<string, string>>;
+}
 export declare function discoverXaiOAuthEndpoints(signal?: AbortSignal): Promise<XaiDiscovery>;
 export declare class XaiOAuthFlow extends OAuthCallbackFlow {
     #private;
-    constructor(ctrl: OAuthController);
+    constructor(ctrl: OAuthController, options?: XaiOAuthFlowOptions);
     generateAuthUrl(state: string, redirectUri: string): Promise<{
         url: string;
         instructions?: string;
     }>;
     exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials>;
 }
-export declare function loginXai(ctrl: OAuthController): Promise<OAuthCredentials>;
-export declare function refreshXaiToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials>;
+export declare function loginXai(ctrl: OAuthController, options?: XaiOAuthFlowOptions): Promise<OAuthCredentials>;
+export declare function refreshXaiToken(refreshToken: string, options?: AbortSignal | XaiOAuthRefreshOptions): Promise<OAuthCredentials>;
 export {};

package/dist/types/utils.d.ts

@@ -22,7 +22,13 @@ export declare function getOpenAIResponsesHistoryPayload(providerPayload: Provid
 export declare function getOpenAIResponsesHistoryItems(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): Array<Record<string, unknown>> | undefined;
 /**
  * Resolve cache retention preference.
- * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
+ *
+ * Resolution order: explicit request value → `GJC_CACHE_RETENTION` →
+ * legacy `PI_CACHE_RETENTION` → `fallback`. Both env vars act as explicit
+ * opt-in (`"long"`) or opt-out (any other value) so a provider-specific
+ * `fallback` only applies when nothing else is configured. `fallback`
+ * defaults to `"short"` to preserve the historical behaviour for callers
+ * that don't pass one.
  */
-export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention, fallback?: CacheRetention): CacheRetention;
 export declare function isAnthropicOAuthToken(key: string): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.5.0",
+		"@gajae-code/utils": "0.5.2",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-storage.ts

@@ -27,6 +27,7 @@ import { claudeRankingStrategy, claudeUsageProvider } from "./usage/claude";
 import { googleGeminiCliUsageProvider } from "./usage/gemini";
 import { githubCopilotUsageProvider } from "./usage/github-copilot";
 import { antigravityUsageProvider } from "./usage/google-antigravity";
+import { grokCliRankingStrategy, grokCliUsageProvider } from "./usage/grok-cli";
 import { kimiUsageProvider } from "./usage/kimi";
 import { codexRankingStrategy, openaiCodexUsageProvider } from "./usage/openai-codex";
 import { zaiUsageProvider } from "./usage/zai";
@@ -370,6 +371,7 @@ const DEFAULT_USAGE_PROVIDERS: UsageProvider[] = [
 	claudeUsageProvider,
 	zaiUsageProvider,
 	githubCopilotUsageProvider,
+	grokCliUsageProvider,
 ];
 
 const DEFAULT_USAGE_PROVIDER_MAP = new Map<Provider, UsageProvider>(
@@ -498,6 +500,7 @@ function resolveDefaultUsageProvider(provider: Provider): UsageProvider | undefi
 const DEFAULT_RANKING_STRATEGIES = new Map<Provider, CredentialRankingStrategy>([
 	["openai-codex", codexRankingStrategy],
 	["anthropic", claudeRankingStrategy],
+	["grok-build", grokCliRankingStrategy],
 ]);
 
 function resolveDefaultRankingStrategy(provider: Provider): CredentialRankingStrategy | undefined {

package/src/index.ts

@@ -33,6 +33,7 @@ export * from "./usage/claude";
 export * from "./usage/gemini";
 export * from "./usage/github-copilot";
 export * from "./usage/google-antigravity";
+export * from "./usage/grok-cli";
 export * from "./usage/kimi";
 export * from "./usage/minimax-code";
 export * from "./usage/openai-codex";

package/src/models.json

@@ -71048,6 +71048,30 @@
 				"maxLevel": "xhigh"
 			}
 		},
+		"glm-5.2": {
+			"id": "glm-5.2",
+			"name": "GLM-5.2",
+			"api": "anthropic-messages",
+			"provider": "zai",
+			"baseUrl": "https://api.z.ai/api/anthropic",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 200000,
+			"maxTokens": 131072,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
+		},
 		"glm-5v-turbo": {
 			"id": "glm-5v-turbo",
 			"name": "GLM-5V-Turbo",

package/src/provider-models/descriptors.ts

@@ -280,7 +280,7 @@ export const PROVIDER_DESCRIPTORS: readonly ProviderDescriptor[] = [
 		config => zenmuxModelManagerOptions(config),
 		catalog("ZenMux", ["ZENMUX_API_KEY"]),
 	),
-	catalogDescriptor("zai", "glm-5.1", config => zaiModelManagerOptions(config), catalog("zAI", ["ZAI_API_KEY"])),
+	catalogDescriptor("zai", "glm-5.2", config => zaiModelManagerOptions(config), catalog("zAI", ["ZAI_API_KEY"])),
 	descriptor("github-copilot", "gpt-4o", config => githubCopilotModelManagerOptions(config)),
 	descriptor("google", "gemini-2.5-pro", config => googleModelManagerOptions(config)),
 	catalogDescriptor(

package/src/providers/anthropic.ts

@@ -353,10 +353,19 @@ function getCacheControl(
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
 ): { retention: CacheRetention; cacheControl?: AnthropicCacheControl } {
-	const retention = resolveCacheRetention(cacheRetention);
+	// Default Anthropic prompt caching to long (1h) retention. The provider
+	// default of ~5m is too fragile for long-running Codex/Gajae-Code subagent
+	// workflows, where the prefix is frequently evicted between turns. Explicit
+	// request/model `cacheRetention` and the GJC_CACHE_RETENTION /
+	// PI_CACHE_RETENTION env overrides still win.
+	const retention = resolveCacheRetention(cacheRetention, "long");
 	if (retention === "none") {
 		return { retention };
 	}
+	// `ttl: "1h"` is only honoured on the canonical Anthropic API for models
+	// that advertise long-cache support. Everywhere else (proxies, gateways,
+	// models without the capability) we fall back to the default ephemeral
+	// breakpoint, which Anthropic services at the standard ~5m TTL.
 	const ttl =
 		retention === "long" && isAnthropicApiBaseUrl(baseUrl) && getAnthropicCompat(model).supportsLongCacheRetention
 			? "1h"

package/src/rate-limit-utils.ts

@@ -45,7 +45,16 @@ export function parseRateLimitReason(errorMessage: string): RateLimitReason {
 		return "RATE_LIMIT_EXCEEDED";
 	}
 
-	if (lower.includes("exhausted") || lower.includes("quota") || lower.includes("usage limit")) {
+	if (
+		lower.includes("exhausted") ||
+		lower.includes("quota") ||
+		lower.includes("usage limit") ||
+		lower.includes("model limit") ||
+		lower.includes("model_limit") ||
+		lower.includes("message limit") ||
+		lower.includes("message_limit") ||
+		lower.includes("limit for this model")
+	) {
 		return "QUOTA_EXHAUSTED";
 	}
 
@@ -77,7 +86,7 @@ export function calculateRateLimitBackoffMs(reason: RateLimitReason): number {
 
 /** Detect usage/quota limit errors in error messages (persistent, requires credential switch). */
 const USAGE_LIMIT_PATTERN =
-	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?exceeded|resource.?exhausted/i;
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|model.?limit|model_limit_reached|message.?limit|message_limit_reached|limit for this model|quota.?exceeded|resource has been exhausted[^\n]*(?:quota|limit)/i;
 
 export function isUsageLimitError(errorMessage: string): boolean {
 	return USAGE_LIMIT_PATTERN.test(errorMessage);

package/src/usage/grok-cli.ts

@@ -0,0 +1,163 @@
+import type {
+	CredentialRankingStrategy,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+} from "../usage";
+
+interface BillingUsage {
+	monthlyLimit: number;
+	used: number;
+	billingPeriodEnd: string;
+}
+const DEFAULT_GROK_BUILD_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+const ALLOWED_GROK_BUILD_HOSTS = new Set(["cli-chat-proxy.grok.com"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object";
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function parseValNumber(value: unknown): number | undefined {
+	return isRecord(value) ? finiteNumber(value.val) : undefined;
+}
+
+export function parseGrokCliBillingUsage(payload: unknown): BillingUsage {
+	if (!isRecord(payload) || !isRecord(payload.config)) {
+		throw new Error("invalid Grok CLI billing payload");
+	}
+	const monthlyLimit = parseValNumber(payload.config.monthlyLimit);
+	const used = parseValNumber(payload.config.used);
+	const billingPeriodEnd = payload.config.billingPeriodEnd;
+	if (
+		monthlyLimit === undefined ||
+		used === undefined ||
+		typeof billingPeriodEnd !== "string" ||
+		!Number.isFinite(new Date(billingPeriodEnd).getTime())
+	) {
+		throw new Error("invalid Grok CLI billing payload");
+	}
+	return { monthlyLimit, used, billingPeriodEnd };
+}
+
+function isAllowedGrokCredentialHost(baseUrl: string): boolean {
+	try {
+		const url = new URL(baseUrl);
+		return url.protocol === "https:" && ALLOWED_GROK_BUILD_HOSTS.has(url.hostname.toLowerCase());
+	} catch {
+		return false;
+	}
+}
+
+function normalizeGrokBaseUrl(baseUrl?: string): string {
+	const normalized = (baseUrl?.trim() || DEFAULT_GROK_BUILD_BASE_URL).replace(/\/+$/, "");
+	return isAllowedGrokCredentialHost(normalized) ? normalized : DEFAULT_GROK_BUILD_BASE_URL;
+}
+function isUnsafeGrokBaseUrlOverride(baseUrl?: string): boolean {
+	const normalized = baseUrl?.trim().replace(/\/+$/, "");
+	return !!normalized && !isAllowedGrokCredentialHost(normalized);
+}
+
+function resolveAccessToken(params: UsageFetchParams): string | undefined {
+	const token = params.credential.accessToken ?? params.credential.apiKey ?? process.env.GROK_CLI_OAUTH_TOKEN;
+	return token?.trim() || undefined;
+}
+
+function buildMonthlyUsageLimit(usage: BillingUsage, nowMs: number): UsageLimit {
+	const usedFraction = usage.monthlyLimit > 0 ? usage.used / usage.monthlyLimit : 0;
+	const percent = usedFraction * 100;
+	const resetsAt = new Date(usage.billingPeriodEnd).getTime();
+	return {
+		id: "grok-build:7d",
+		label: "SuperGrok monthly credits",
+		scope: { provider: "grok-build", shared: true, windowId: "7d" },
+		window: {
+			id: "7d",
+			label: "Monthly credits",
+			resetsAt,
+		},
+		amount: {
+			unit: "percent",
+			used: percent,
+			limit: 100,
+			remaining: Math.max(0, 100 - percent),
+			usedFraction,
+			remainingFraction: Math.max(0, 1 - usedFraction),
+		},
+		status: percent >= 95 ? "exhausted" : percent >= 80 ? "warning" : "ok",
+		notes: [
+			`${usage.used}/${usage.monthlyLimit} credits used`,
+			`resets in ${Math.max(0, Math.round((resetsAt - nowMs) / 3_600_000))}h`,
+		],
+	};
+}
+
+export const grokCliUsageProvider: UsageProvider = {
+	id: "grok-build",
+
+	supports(params) {
+		return params.provider === "grok-build";
+	},
+
+	async fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+		const accessToken = resolveAccessToken(params);
+		if (!accessToken) {
+			ctx.logger?.warn("Grok Build usage: no access token", { provider: params.provider });
+			return null;
+		}
+
+		if (isUnsafeGrokBaseUrlOverride(params.baseUrl)) {
+			ctx.logger?.warn("Grok Build usage: ignoring unsafe base URL override for credential safety", {
+				provider: params.provider,
+			});
+		}
+		const billingBaseUrl = normalizeGrokBaseUrl(params.baseUrl);
+		const response = await ctx.fetch(`${billingBaseUrl}/billing`, {
+			headers: {
+				Authorization: `Bearer ${accessToken}`,
+				"x-xai-token-auth": "xai-grok-cli",
+				accept: "application/json",
+			},
+			signal: params.signal,
+		});
+		if (!response.ok) {
+			ctx.logger?.warn("Grok Build billing request failed", { status: response.status, provider: params.provider });
+			return null;
+		}
+
+		const payload = (await response.json()) as unknown;
+		let billing: BillingUsage;
+		try {
+			billing = parseGrokCliBillingUsage(payload);
+		} catch (error) {
+			ctx.logger?.warn("Grok Build billing parse failed", { error: String(error) });
+			return null;
+		}
+
+		const nowMs = Date.now();
+		return {
+			provider: "grok-build",
+			fetchedAt: nowMs,
+			limits: [buildMonthlyUsageLimit(billing, nowMs)],
+			metadata: {
+				email: params.credential.email,
+				accountId: params.credential.accountId,
+				subscription: true,
+			},
+			raw: payload,
+		};
+	},
+};
+
+export const grokCliRankingStrategy: CredentialRankingStrategy = {
+	findWindowLimits(report) {
+		const monthly = report.limits.find(limit => limit.id === "grok-build:7d");
+		return { secondary: monthly };
+	},
+	windowDefaults: { primaryMs: 5 * 60 * 60 * 1000, secondaryMs: 30 * 24 * 60 * 60 * 1000 },
+};

package/src/utils/oauth/xai.ts

@@ -30,6 +30,15 @@ interface XaiTokenPayload {
 	token_type?: unknown;
 }
 
+export interface XaiOAuthFlowOptions {
+	extraAuthorizeParams?: Readonly<Record<string, string>>;
+}
+
+export interface XaiOAuthRefreshOptions {
+	signal?: AbortSignal;
+	extraTokenParams?: Readonly<Record<string, string>>;
+}
+
 interface XaiJwtPayload {
 	sub?: unknown;
 	email?: unknown;
@@ -41,6 +50,28 @@ function requestSignal(signal: AbortSignal | undefined): AbortSignal {
 	return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
 }
 
+function addNonOverridingParams(
+	target: URLSearchParams | Record<string, string>,
+	params: Readonly<Record<string, string>>,
+): void {
+	for (const [key, value] of Object.entries(params)) {
+		if (key.length === 0 || value.length === 0) continue;
+		if (target instanceof URLSearchParams) {
+			if (!target.has(key)) target.set(key, value);
+		} else if (!(key in target)) {
+			target[key] = value;
+		}
+	}
+}
+
+function isAbortSignal(value: AbortSignal | XaiOAuthRefreshOptions | undefined): value is AbortSignal {
+	return value instanceof AbortSignal;
+}
+
+function resolveRefreshOptions(options: AbortSignal | XaiOAuthRefreshOptions | undefined): XaiOAuthRefreshOptions {
+	return isAbortSignal(options) ? { signal: options } : (options ?? {});
+}
+
 function validateXaiEndpoint(rawUrl: string): string {
 	const parsed = new URL(rawUrl);
 	const host = parsed.hostname.toLowerCase();
@@ -136,8 +167,9 @@ function credentialsFromTokenPayload(payload: XaiTokenPayload, refreshFallback =
 export class XaiOAuthFlow extends OAuthCallbackFlow {
 	#verifier = "";
 	#discovery: XaiDiscovery | undefined;
+	#extraAuthorizeParams: Readonly<Record<string, string>>;
 
-	constructor(ctrl: OAuthController) {
+	constructor(ctrl: OAuthController, options: XaiOAuthFlowOptions = {}) {
 		super(ctrl, {
 			preferredPort: XAI_OAUTH_CALLBACK_PORT,
 			callbackPath: XAI_OAUTH_CALLBACK_PATH,
@@ -145,6 +177,7 @@ export class XaiOAuthFlow extends OAuthCallbackFlow {
 			callbackBindHostname: "127.0.0.1",
 			redirectUri: `http://127.0.0.1:${XAI_OAUTH_CALLBACK_PORT}${XAI_OAUTH_CALLBACK_PATH}`,
 		} satisfies OAuthCallbackFlowOptions);
+		this.#extraAuthorizeParams = options.extraAuthorizeParams ?? {};
 	}
 
 	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
@@ -161,6 +194,7 @@ export class XaiOAuthFlow extends OAuthCallbackFlow {
 			state,
 			nonce: crypto.randomUUID(),
 		});
+		addNonOverridingParams(params, this.#extraAuthorizeParams);
 		return {
 			url: `${this.#discovery.authorizationEndpoint}?${params.toString()}`,
 			instructions:
@@ -188,23 +222,25 @@ export class XaiOAuthFlow extends OAuthCallbackFlow {
 	}
 }
 
-export async function loginXai(ctrl: OAuthController): Promise<OAuthCredentials> {
-	return new XaiOAuthFlow(ctrl).login();
+export async function loginXai(ctrl: OAuthController, options?: XaiOAuthFlowOptions): Promise<OAuthCredentials> {
+	return new XaiOAuthFlow(ctrl, options).login();
 }
 
-export async function refreshXaiToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+export async function refreshXaiToken(
+	refreshToken: string,
+	options?: AbortSignal | XaiOAuthRefreshOptions,
+): Promise<OAuthCredentials> {
 	if (!refreshToken) {
 		throw new Error("xAI credentials are expired and do not include a refresh token");
 	}
+	const { signal, extraTokenParams = {} } = resolveRefreshOptions(options);
 	const discovery = await discoverXaiOAuthEndpoints(signal);
-	const tokenPayload = await postXaiToken(
-		discovery.tokenEndpoint,
-		{
-			grant_type: "refresh_token",
-			client_id: XAI_OAUTH_CLIENT_ID,
-			refresh_token: refreshToken,
-		},
-		signal,
-	);
+	const body = {
+		grant_type: "refresh_token",
+		client_id: XAI_OAUTH_CLIENT_ID,
+		refresh_token: refreshToken,
+	};
+	addNonOverridingParams(body, extraTokenParams);
+	const tokenPayload = await postXaiToken(discovery.tokenEndpoint, body, signal);
 	return credentialsFromTokenPayload(tokenPayload, refreshToken);
 }

package/src/utils.ts

@@ -153,14 +153,24 @@ export function getOpenAIResponsesHistoryItems(
 
 /**
  * Resolve cache retention preference.
- * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
+ *
+ * Resolution order: explicit request value → `GJC_CACHE_RETENTION` →
+ * legacy `PI_CACHE_RETENTION` → `fallback`. Both env vars act as explicit
+ * opt-in (`"long"`) or opt-out (any other value) so a provider-specific
+ * `fallback` only applies when nothing else is configured. `fallback`
+ * defaults to `"short"` to preserve the historical behaviour for callers
+ * that don't pass one.
  */
-export function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention {
+export function resolveCacheRetention(
+	cacheRetention?: CacheRetention,
+	fallback: CacheRetention = "short",
+): CacheRetention {
 	if (cacheRetention) return cacheRetention;
 	if ($env.GJC_CACHE_RETENTION === "long") return "long";
 	if ($env.GJC_CACHE_RETENTION !== undefined) return "short";
 	if ($env.PI_CACHE_RETENTION === "long") return "long";
-	return "short";
+	if ($env.PI_CACHE_RETENTION !== undefined) return "short";
+	return fallback;
 }
 
 export function isAnthropicOAuthToken(key: string): boolean {