@gajae-code/ai 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [0.5.4] - 2026-06-17
+
+### Fixed
+
+- Made the "No API key for provider" error from `stream`/`complete` actionable for OpenCode Go/Zen subscription providers in headless runs (#755). The subscription is itself an API key (`OPENCODE_API_KEY`, created at https://opencode.ai/auth), not a separate OAuth/session token; the new `formatProviderCredentialHint` helper (composed into `formatMissingApiKeyError`) names the env var GJC reads, warns that a project `.env` is intentionally ignored for provider credentials, and points OpenCode users at the one-time interactive `gjc auth-broker login <provider>` credential capture to run before headless/print mode. No auth behavior changed.
+
+## [0.5.3] - 2026-06-16
+
+### Added
+
+- Added opt-in `AuthStorageOptions.credentialRankingMode` (`balanced` (default) | `earliest-reset`) for multi-account OAuth credential selection. `earliest-reset` ranks non-blocked credentials earliest-expiry-first — draining the soonest-to-reset account before its perishable tumbling-window quota (e.g. Claude 5h/7d) is lost at reset — keeping the existing drain-rate/used-fraction metrics as tiebreakers. `balanced` is byte-identical to prior behavior, and ranking only runs at session start (or when the session's preferred credential is blocked), so this never thrashes accounts mid-session.
+
+### Fixed
+
+- Allowed `openai-codex-responses` custom backends to use opaque `apiKey` bearer tokens by omitting `chatgpt-account-id` when the token does not expose a Codex account id.
+- Fixed OpenAI code websocket continuations to treat codex-lb's `codex_previous_response_stale` response failures as expired `previous_response_id` anchors and retry with full context instead of surfacing the transient failure.
+- Bounded the Cursor provider's conversation cache with an LRU(64) + 1h TTL and added `disposeCursorConversation`, so long-running sessions no longer retain Cursor conversation state without limit (#717).
+
 ## [0.5.2] - 2026-06-15
 
 ### Changed

package/dist/types/auth-storage.d.ts

@@ -229,9 +229,26 @@ export interface CredentialDisabledEvent {
     provider: string;
     disabledCause: string;
 }
+/**
+ * How {@link AuthStorage} orders multiple healthy OAuth credentials of the same
+ * provider:type pool when selecting one for a (new) session.
+ *
+ * - `balanced` (default): prefer the least-used / lowest-drain-rate account.
+ *   Spreads load across accounts and keeps burst headroom on every account.
+ * - `earliest-reset`: prefer the non-blocked account whose usage window resets
+ *   soonest (earliest-expiry-first). Tumbling-window quota is perishable —
+ *   unused quota is lost at reset — so draining the soonest-to-reset account
+ *   first minimizes wasted quota. Drain/used metrics remain tiebreakers.
+ *
+ * Only affects ranking, which the `shouldRank` guard already limits to session
+ * start (or when the session's preferred credential is blocked), so this never
+ * thrashes accounts mid-session / cold-starts the server-side prompt cache.
+ */
+export type CredentialRankingMode = "balanced" | "earliest-reset";
 export type AuthStorageOptions = {
     usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
     rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
+    credentialRankingMode?: CredentialRankingMode;
     usageFetch?: typeof fetch;
     usageRequestTimeoutMs?: number;
     usageLogger?: UsageLogger;

package/dist/types/provider-models/openai-compat.d.ts

@@ -1,5 +1,5 @@
 import type { ModelManagerOptions } from "../model-manager";
-import type { Api, Model } from "../types";
+import type { Api, FetchImpl, Model, Provider } from "../types";
 export interface ModelsDevModel {
     id?: string;
     name?: string;
@@ -161,10 +161,17 @@ export interface CloudflareAiGatewayModelManagerConfig {
     baseUrl?: string;
 }
 export declare function cloudflareAiGatewayModelManagerOptions(config?: CloudflareAiGatewayModelManagerConfig): ModelManagerOptions<"anthropic-messages">;
+/** Region codes for Xiaomi Token Plan clusters exposed as separate login providers. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
+/** Configures Xiaomi standard or regional Token Plan OpenAI-compatible model discovery. */
 export interface XiaomiModelManagerConfig {
     apiKey?: string;
     baseUrl?: string;
+    fetch?: FetchImpl;
+    providerId?: Provider;
+    tokenPlanRegion?: XiaomiTokenPlanRegion;
 }
+/** Builds a Xiaomi model manager, preserving Token Plan region provider ids during discovery. */
 export declare function xiaomiModelManagerOptions(config?: XiaomiModelManagerConfig): ModelManagerOptions<"openai-completions">;
 export interface LiteLLMModelManagerConfig {
     apiKey?: string;

package/dist/types/providers/cursor.d.ts

@@ -2,6 +2,8 @@ import { type JsonValue } from "@bufbuild/protobuf";
 import type { CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, Message, StreamFunction, StreamOptions, ToolResultMessage } from "../types";
 export declare const CURSOR_API_URL = "https://api2.cursor.sh";
 export declare const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
+/** Drop all cached state + blob bytes for a conversation (F15 bound + session-teardown hook). */
+export declare function disposeCursorConversation(conversationId: string): void;
 export interface CursorOptions extends StreamOptions {
     customSystemPrompt?: string;
     conversationId?: string;

package/dist/types/stream.d.ts

@@ -15,6 +15,25 @@ export declare function getEnvApiKey(provider: string): string | undefined;
  * that should be uploaded to the broker.
  */
 export declare function listProvidersWithEnvKey(): string[];
+/**
+ * Provider-specific credential guidance appended to "no credential" errors.
+ *
+ * Headless GJC has no interactive `/login` TUI, so a bare "No API key" /
+ * "No credentials" error left users — OpenCode Go subscribers especially
+ * (#755) — unsure what signal GJC actually reads. OpenCode subscriptions are
+ * themselves API keys, so this names the env var GJC reads for the provider,
+ * warns that a project `.env` is intentionally ignored for provider
+ * credentials, and points OpenCode users at one-time interactive CLI credential capture.
+ *
+ * Returns an empty string when the provider has no env-var key and no special
+ * handling, so callers can append it unconditionally.
+ */
+export declare function formatProviderCredentialHint(provider: string): string;
+/**
+ * Build an actionable "missing API key" error for a provider, used by the
+ * low-level `stream`/`complete` entry points (#755).
+ */
+export declare function formatMissingApiKeyError(provider: string): string;
 export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): AssistantMessageEventStream;
 export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): Promise<AssistantMessage>;
 export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;

package/dist/types/types.d.ts

@@ -48,7 +48,7 @@ export interface ThinkingConfig {
     /** Provider-specific transport used to encode the selected effort. */
     mode: ThinkingControlMode;
 }
-export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "azure-openai" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "zenmux" | "lm-studio";
+export type KnownProvider = "alibaba-coding-plan" | "amazon-bedrock" | "azure-openai" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "openai-codex" | "kimi-code" | "minimax-code" | "minimax-code-cn" | "github-copilot" | "fireworks" | "firepass" | "gitlab-duo" | "cursor" | "deepseek" | "xai" | "groq" | "cerebras" | "openrouter" | "kilo" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "opencode-go" | "opencode-zen" | "synthetic" | "cloudflare-ai-gateway" | "huggingface" | "litellm" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "qianfan" | "qwen-portal" | "together" | "venice" | "vllm" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "lm-studio";
 export type Provider = KnownProvider | string;
 import type { Effort } from "./model-thinking";
 /** Token budgets for each thinking level (token-based providers only) */

package/dist/types/utils/discovery/openai-compatible.d.ts

@@ -1,4 +1,4 @@
-import type { Api, Model, Provider } from "../../types";
+import type { Api, FetchImpl, Model, Provider } from "../../types";
 /**
  * Minimal OpenAI-style model entry shape consumed by discovery.
  *
@@ -51,7 +51,9 @@ export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
     /** Optional AbortSignal for request cancellation. */
     signal?: AbortSignal;
     /** Optional fetch implementation override for testing/custom runtimes. */
-    fetch?: typeof globalThis.fetch;
+    fetch?: FetchImpl;
+    /** Optional HTTP status predicate for provider-specific hard failures. */
+    throwOnStatus?: (response: Response) => Error | undefined;
     /**
      * Optional post-normalization filter.
      * Return false to skip a model.

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

@@ -7,7 +7,7 @@ export type OAuthCredentials = {
     email?: string;
     accountId?: string;
 };
-export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xai" | "xiaomi" | "zenmux" | "zai";
+export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xai" | "xiaomi" | "xiaomi-token-plan-sgp" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-cn" | "zenmux" | "zai";
 export type OAuthProviderId = OAuthProvider | (string & {});
 export type OAuthPrompt = {
     message: string;
@@ -29,6 +29,7 @@ export interface OAuthController {
     onManualCodeInput?(): Promise<string>;
     onPrompt?(prompt: OAuthPrompt): Promise<string>;
     signal?: AbortSignal;
+    fetch?: typeof globalThis.fetch;
 }
 export interface OAuthLoginCallbacks extends OAuthController {
     onAuth: (info: OAuthAuthInfo) => void;

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

@@ -4,12 +4,12 @@
  * Xiaomi MiMo provides OpenAI-compatible models via
  * https://api.xiaomimimo.com/v1.
  *
- * This is not OAuth - it's a simple API key flow:
- * 1. Open browser to Xiaomi MiMo API key console
- * 2. User copies their API key
- * 3. User pastes the API key into the CLI
+ * Standard Xiaomi login opens the pay-as-you-go API key console. Token Plan
+ * login opens plan management so users copy the regional `tp-...` key.
  */
 import type { OAuthController } from "./types";
+/** Region codes accepted by the Xiaomi Token Plan login flow. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
 /**
  * Login to Xiaomi MiMo.
  *
@@ -17,3 +17,9 @@ import type { OAuthController } from "./types";
  * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
  */
 export declare function loginXiaomi(options: OAuthController): Promise<string>;
+/**
+ * Login to a regional Xiaomi Token Plan endpoint.
+ *
+ * Prompts for a token-plan API key and validates it against the selected region.
+ */
+export declare function loginXiaomiTokenPlan(options: OAuthController, region: XiaomiTokenPlanRegion): Promise<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.5.2",
+	"version": "0.5.4",
 	"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.2",
+		"@gajae-code/utils": "0.5.4",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-storage.ts

@@ -288,9 +288,27 @@ export interface CredentialDisabledEvent {
 	disabledCause: string;
 }
 
+/**
+ * How {@link AuthStorage} orders multiple healthy OAuth credentials of the same
+ * provider:type pool when selecting one for a (new) session.
+ *
+ * - `balanced` (default): prefer the least-used / lowest-drain-rate account.
+ *   Spreads load across accounts and keeps burst headroom on every account.
+ * - `earliest-reset`: prefer the non-blocked account whose usage window resets
+ *   soonest (earliest-expiry-first). Tumbling-window quota is perishable —
+ *   unused quota is lost at reset — so draining the soonest-to-reset account
+ *   first minimizes wasted quota. Drain/used metrics remain tiebreakers.
+ *
+ * Only affects ranking, which the `shouldRank` guard already limits to session
+ * start (or when the session's preferred credential is blocked), so this never
+ * thrashes accounts mid-session / cold-starts the server-side prompt cache.
+ */
+export type CredentialRankingMode = "balanced" | "earliest-reset";
+
 export type AuthStorageOptions = {
 	usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
 	rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
+	credentialRankingMode?: CredentialRankingMode;
 	usageFetch?: typeof fetch;
 	usageRequestTimeoutMs?: number;
 	usageLogger?: UsageLogger;
@@ -655,6 +673,7 @@ export class AuthStorage {
 	#usageReportsInFlight: Map<string, Promise<UsageReport[] | null>> = new Map();
 	#usageFetch: typeof fetch;
 	#usageRequestTimeoutMs: number;
+	#credentialRankingMode: CredentialRankingMode = "balanced";
 	#usageLogger?: UsageLogger;
 	#fallbackResolver?: (provider: string) => string | undefined;
 	#store: AuthCredentialStore;
@@ -686,6 +705,7 @@ export class AuthStorage {
 		this.#usageCache = new AuthStorageUsageCache(this.#store);
 		this.#usageFetch = options.usageFetch ?? fetch;
 		this.#usageRequestTimeoutMs = options.usageRequestTimeoutMs ?? DEFAULT_USAGE_REQUEST_TIMEOUT_MS;
+		this.#credentialRankingMode = options.credentialRankingMode ?? "balanced";
 		this.#refreshOAuthCredentialOverride = options.refreshOAuthCredential;
 		this.#fetchUsageReportsOverride = options.fetchUsageReports;
 		this.#sourceLabel = options.sourceLabel;
@@ -1621,6 +1641,24 @@ export class AuthStorage {
 				await saveApiKeyCredential(apiKey);
 				return;
 			}
+			case "xiaomi-token-plan-sgp": {
+				const { loginXiaomiTokenPlan } = await import("./utils/oauth/xiaomi");
+				const apiKey = await loginXiaomiTokenPlan(ctrl, "sgp");
+				await saveApiKeyCredential(apiKey);
+				return;
+			}
+			case "xiaomi-token-plan-ams": {
+				const { loginXiaomiTokenPlan } = await import("./utils/oauth/xiaomi");
+				const apiKey = await loginXiaomiTokenPlan(ctrl, "ams");
+				await saveApiKeyCredential(apiKey);
+				return;
+			}
+			case "xiaomi-token-plan-cn": {
+				const { loginXiaomiTokenPlan } = await import("./utils/oauth/xiaomi");
+				const apiKey = await loginXiaomiTokenPlan(ctrl, "cn");
+				await saveApiKeyCredential(apiKey);
+				return;
+			}
 			case "zenmux": {
 				const { loginZenMux } = await import("./utils/oauth/zenmux");
 				const apiKey = await loginZenMux(ctrl);
@@ -2453,6 +2491,7 @@ export class AuthStorage {
 			secondaryDrainRate: number;
 			primaryUsed: number;
 			primaryDrainRate: number;
+			resetAtMs: number;
 			orderPos: number;
 		}> = [];
 		// Pre-fetch usage reports in parallel for non-blocked credentials.
@@ -2522,6 +2561,10 @@ export class AuthStorage {
 				),
 				primaryUsed: this.#normalizeUsageFraction(primary),
 				primaryDrainRate: this.#computeWindowDrainRate(primary, nowMs, strategy.windowDefaults.primaryMs),
+				resetAtMs:
+					this.#resolveWindowResetAt(primary?.window) ??
+					this.#resolveWindowResetAt(secondary?.window) ??
+					Number.POSITIVE_INFINITY,
 				orderPos,
 			});
 		}
@@ -2539,6 +2582,11 @@ export class AuthStorage {
 				if (leftPlanPriority !== rightPlanPriority) return leftPlanPriority - rightPlanPriority;
 			}
 			if (left.hasPriorityBoost !== right.hasPriorityBoost) return left.hasPriorityBoost ? -1 : 1;
+			if (this.#credentialRankingMode === "earliest-reset" && left.resetAtMs !== right.resetAtMs) {
+				// Earliest-expiry-first: drain the soonest-to-reset account before
+				// its perishable tumbling-window quota is lost at reset.
+				return left.resetAtMs - right.resetAtMs;
+			}
 			if (left.secondaryDrainRate !== right.secondaryDrainRate)
 				return left.secondaryDrainRate - right.secondaryDrainRate;
 			if (left.secondaryUsed !== right.secondaryUsed) return left.secondaryUsed - right.secondaryUsed;

package/src/model-manager.ts

@@ -1,5 +1,5 @@
 import { readModelCache, writeModelCache } from "./model-cache";
-import { enrichModelThinking } from "./model-thinking";
+import { applyGeneratedModelPolicies, enrichModelThinking } from "./model-thinking";
 import { type GeneratedProvider, getBundledModels } from "./models";
 import type { Api, Model, Provider } from "./types";
 import { isRecord } from "./utils";
@@ -90,6 +90,7 @@ function passModelList<TApi extends Api>(value: unknown): Model<TApi>[] {
 		}
 		out.push(enrichModelThinking(item as Model<TApi>));
 	}
+	applyGeneratedModelPolicies(out as Model<Api>[]);
 	return out;
 }
 
@@ -322,7 +323,7 @@ function mergeDynamicModel<TApi extends Api>(existingModel: Model<TApi>, dynamic
 	// (issue #489). Keep the existing api, and only take the dynamic baseUrl
 	// when the api matches (same transport, same URL shape).
 	const baseUrl = existingModel.api === dynamicModel.api ? dynamicModel.baseUrl : existingModel.baseUrl;
-	return enrichModelThinking({
+	const merged = enrichModelThinking({
 		...existingModel,
 		...dynamicModel,
 		api: existingModel.api,
@@ -342,6 +343,9 @@ function mergeDynamicModel<TApi extends Api>(existingModel: Model<TApi>, dynamic
 		compat: dynamicModel.compat ?? existingModel.compat,
 		contextPromotionTarget: dynamicModel.contextPromotionTarget ?? existingModel.contextPromotionTarget,
 	});
+	const policyModels = [merged as Model<Api>];
+	applyGeneratedModelPolicies(policyModels);
+	return policyModels[0] as Model<TApi>;
 }
 
 function preferDiscoveryCost(discoveryCost: number, fallbackCost: number): number {

package/src/model-thinking.ts

@@ -699,7 +699,7 @@ function parseAnthropicModel(modelId: string): AnthropicModel | null {
 }
 
 function parseOpenAIModel(modelId: string): OpenAIModel | null {
-	const match = /gpt-(\d+(?:\.\d+){0,2})(?:-(codex-spark|codex-mini|codex-max|codex|mini|max|nano))?\b/.exec(modelId);
+	const match = /gpt-(\d+(?:\.\d+){0,2})(?:-(codex-spark|codex-mini|codex-max|codex|mini|max|nano))?$/.exec(modelId);
 	if (!match) {
 		return null;
 	}