@gajae-code/ai 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [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
+
+- 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

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/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/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.1",
+	"version": "0.5.3",
 	"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.1",
+		"@gajae-code/utils": "0.5.3",
 		"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;
@@ -2453,6 +2473,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 +2543,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 +2564,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/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/providers/cursor.ts

@@ -136,6 +136,38 @@ export const CURSOR_CLIENT_VERSION = "cli-2026.01.09-231024f";
 const conversationStateCache = new Map<string, ConversationStateStructure>();
 const conversationBlobStores = new Map<string, Map<string, Uint8Array>>();
 
+// F15: bound the module-global conversation caches so long-lived / many-session use cannot
+// grow them without limit. LRU by conversation count + TTL on idle conversations.
+const CURSOR_MAX_CONVERSATIONS = 64;
+const CURSOR_CONVERSATION_TTL_MS = 60 * 60 * 1000;
+const conversationLastAccess = new Map<string, number>();
+
+/** Drop all cached state + blob bytes for a conversation (F15 bound + session-teardown hook). */
+export function disposeCursorConversation(conversationId: string): void {
+	conversationStateCache.delete(conversationId);
+	conversationBlobStores.delete(conversationId);
+	conversationLastAccess.delete(conversationId);
+}
+
+/** Refresh recency for a conversation and evict TTL-stale / LRU-overflow entries (F15). */
+function touchCursorConversation(conversationId: string): void {
+	const now = Date.now();
+	for (const [id, ts] of conversationLastAccess) {
+		if (id !== conversationId && now - ts > CURSOR_CONVERSATION_TTL_MS) disposeCursorConversation(id);
+	}
+	conversationLastAccess.set(conversationId, now);
+	const state = conversationStateCache.get(conversationId);
+	if (state !== undefined) {
+		conversationStateCache.delete(conversationId);
+		conversationStateCache.set(conversationId, state);
+	}
+	while (conversationStateCache.size > CURSOR_MAX_CONVERSATIONS) {
+		const oldest = conversationStateCache.keys().next().value;
+		if (oldest === undefined || oldest === conversationId) break;
+		disposeCursorConversation(oldest);
+	}
+}
+
 export interface CursorOptions extends StreamOptions {
 	customSystemPrompt?: string;
 	conversationId?: string;
@@ -349,6 +381,7 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 				conversationState: cachedState,
 			});
 			conversationStateCache.set(conversationId, conversationState);
+			touchCursorConversation(conversationId);
 			const requestContextTools = buildMcpToolDefinitions(context.tools);
 
 			const baseUrl = model.baseUrl || CURSOR_API_URL;
@@ -405,6 +438,7 @@ export const streamCursor: StreamFunction<"cursor-agent"> = (
 
 			const onConversationCheckpoint = (checkpoint: ConversationStateStructure) => {
 				conversationStateCache.set(conversationId, checkpoint);
+				touchCursorConversation(conversationId);
 			};
 
 			let resolveH2: (() => void) | undefined;

package/src/providers/openai-codex-responses.ts

@@ -96,6 +96,7 @@ const CODEX_WEBSOCKET_IDLE_TIMEOUT_MS = 300000;
 const CODEX_WEBSOCKET_FIRST_EVENT_TIMEOUT_MS = 15000;
 const CODEX_WEBSOCKET_RETRY_BUDGET = CODEX_MAX_RETRIES;
 const CODEX_WEBSOCKET_TRANSPORT_ERROR_PREFIX = "Codex websocket transport error";
+const CODEX_PREVIOUS_RESPONSE_STALE_CODES = new Set(["previous_response_not_found", "codex_previous_response_stale"]);
 const CODEX_RETRYABLE_EVENT_CODES = new Set(["model_error", "server_error", "internal_error"]);
 const CODEX_RETRYABLE_EVENT_MESSAGE =
 	/processing your request|retry your request|temporar(?:y|ily)|overloaded|service.?unavailable|internal error|server error/i;
@@ -170,7 +171,7 @@ interface CodexProviderSessionState extends ProviderSessionState {
 
 interface CodexRequestContext {
 	apiKey: string;
-	accountId: string;
+	accountId: string | undefined;
 	baseUrl: string;
 	url: string;
 	requestHeaders: Record<string, string>;
@@ -1475,7 +1476,11 @@ async function tryReconnectCodexWebSocketOnConnectionLimit(
 }
 
 function isCodexPreviousResponseNotFound(error: unknown): boolean {
-	return error instanceof CodexProviderStreamError && error.code === "previous_response_not_found";
+	return (
+		error instanceof CodexProviderStreamError &&
+		typeof error.code === "string" &&
+		CODEX_PREVIOUS_RESPONSE_STALE_CODES.has(error.code)
+	);
 }
 
 async function tryRecoverCodexPreviousResponseNotFound(
@@ -1801,12 +1806,12 @@ export async function prewarmOpenAICodexResponses(
 function getCodexWebSocketSessionKey(
 	sessionId: string | undefined,
 	model: Model<"openai-codex-responses">,
-	accountId: string,
+	accountId: string | undefined,
 	baseUrl: string,
 ): string | undefined {
 	const promptCacheKey = normalizeOpenAIResponsesPromptCacheKey(sessionId);
 	if (!promptCacheKey) return undefined;
-	return `${accountId}:${baseUrl}:${model.id}:${promptCacheKey}`;
+	return `${accountId ?? "opaque"}:${baseUrl}:${model.id}:${promptCacheKey}`;
 }
 
 function getCodexPublicSessionKey(
@@ -2335,7 +2340,7 @@ async function getOrCreateCodexWebSocketConnection(
 async function openCodexSseEventStream(
 	url: string,
 	requestHeaders: Record<string, string> | undefined,
-	accountId: string,
+	accountId: string | undefined,
 	apiKey: string,
 	sessionId: string | undefined,
 	body: RequestBody,
@@ -2400,7 +2405,7 @@ async function openCodexWebSocketEventStream(
 
 function createCodexHeaders(
 	initHeaders: Record<string, string> | undefined,
-	accountId: string,
+	accountId: string | undefined,
 	accessToken: string,
 	promptCacheKey?: string,
 	transport: CodexTransport = "sse",
@@ -2409,7 +2414,11 @@ function createCodexHeaders(
 	const headers = new Headers(initHeaders ?? {});
 	headers.delete("x-api-key");
 	headers.set("Authorization", `Bearer ${accessToken}`);
-	headers.set(OPENAI_HEADERS.ACCOUNT_ID, accountId);
+	if (accountId) {
+		headers.set(OPENAI_HEADERS.ACCOUNT_ID, accountId);
+	} else {
+		headers.delete(OPENAI_HEADERS.ACCOUNT_ID);
+	}
 	const betaHeader =
 		transport === "websocket"
 			? OPENAI_HEADER_VALUES.BETA_RESPONSES_WEBSOCKETS_V2
@@ -2482,12 +2491,8 @@ function resolveCodexResponsesUrl(baseUrl: string | undefined): string {
 	return `${normalized}/codex/responses`;
 }
 
-function getAccountId(accessToken: string): string {
-	const accountId = getCodexAccountId(accessToken);
-	if (!accountId) {
-		throw new Error("Failed to extract accountId from token");
-	}
-	return accountId;
+function getAccountId(accessToken: string): string | undefined {
+	return getCodexAccountId(accessToken);
 }
 
 function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput {
@@ -2669,6 +2674,22 @@ function getString(value: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
 
+function getCodexEventError(rawEvent: Record<string, unknown>): Record<string, unknown> | null {
+	const response = asRecord(rawEvent.response);
+	return asRecord(rawEvent.error) ?? (response ? asRecord(response.error) : null);
+}
+
+function getCodexEventErrorCode(rawEvent: Record<string, unknown>): string {
+	const error = getCodexEventError(rawEvent);
+	return getString(error?.code) ?? getString(error?.type) ?? getString(rawEvent.code) ?? "";
+}
+
+function getCodexEventErrorMessage(rawEvent: Record<string, unknown>): string {
+	const response = asRecord(rawEvent.response);
+	const error = getCodexEventError(rawEvent);
+	return getString(error?.message) ?? getString(rawEvent.message) ?? getString(response?.message) ?? "";
+}
+
 class CodexProviderStreamError extends Error {
 	readonly retryable: boolean;
 	readonly code?: string;
@@ -2682,19 +2703,17 @@ class CodexProviderStreamError extends Error {
 }
 
 function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean {
-	const response = asRecord(rawEvent.response);
-	const error = asRecord(rawEvent.error) ?? (response ? asRecord(response.error) : null);
-	const code = getString(error?.code) ?? getString(error?.type) ?? getString(rawEvent.code);
+	const code = getCodexEventErrorCode(rawEvent);
 	if (code && CODEX_RETRYABLE_EVENT_CODES.has(code.toLowerCase())) {
 		return true;
 	}
-	const message = getString(error?.message) ?? getString(rawEvent.message) ?? getString(response?.message);
+	const message = getCodexEventErrorMessage(rawEvent);
 	return !!message && CODEX_RETRYABLE_EVENT_MESSAGE.test(message);
 }
 
 function createCodexProviderStreamError(rawEvent: Record<string, unknown>): CodexProviderStreamError {
-	const code = getString(rawEvent.code) ?? "";
-	const message = getString(rawEvent.message) ?? "";
+	const code = getCodexEventErrorCode(rawEvent);
+	const message = getCodexEventErrorMessage(rawEvent);
 	const formattedMessage =
 		typeof rawEvent.type === "string" && rawEvent.type === "error"
 			? formatCodexErrorEvent(rawEvent, code, message)

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 {