@gajae-code/ai 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-07-19
+
+### Fixed
+
+- `transportFailureFacts` now reduces transport headers to a plain record containing only the retained retry signals (`retry-after`, `retry-after-ms`). Providers attach these facts to error `AssistantMessage`s, and the previous shape carried the live fetch/SDK `Headers` instance — which is not structured-cloneable (`structuredClone` throws `DataCloneError`, "The object can not be cloned." under Bun) and not JSON-serializable (persisted as `{}` in session files, silently dropping the retry hint). Under a managed model fallback chain, snapshotting such an error message replaced the real provider failure with the local clone error and exhausted the whole chain. Normalization is idempotent (re-running facts on facts is structurally stable; errors carrying only unretained headers with no status/code now yield no facts instead of an empty facts object), Retry-After classification (`classifyFallbackTrigger`) is unchanged, and arbitrary response headers no longer reach persisted facts.
+
 ## [0.11.0] - 2026-07-15
 ### Added
 
@@ -13,6 +19,8 @@
 
 - Closed the remaining `Request blocked (code=invalid_prompt)` wedge on gpt-5.6 caused by header-form leaked Harmony markers. The reserved-control-token sanitizer only matched the simple `<|ident|>` shape, so a header-form marker carrying a recipient (e.g. `<|assistant to=functions.bash|>`) survived every sanitizer path (replay, request boundary, compaction) and kept re-poisoning history even after the earlier fixes. The pattern now also matches the scoped header grammar — a known Harmony role (`system`/`developer`/`user`/`assistant`/`tool`) plus a `to=<recipient>` assignment with unbounded recipient length — while leaving ordinary delimiter/pipe text untouched (arbitrary `<|foo bar=baz|>`, F# `value <| f |> g`, compact `sum<|a+b|>c`, and multi-line bodies never match). The simple branch remains a strict superset of the prior identifier-only pattern (#2267).
 
+- Made the `Request blocked (code=invalid_prompt)` classification explicit and shared across transports (#2282). `invalid_prompt` was only non-retryable by omission — it appeared in neither the codex retryable nor non-retryable event set, and the plain OpenAI Responses transport surfaced it as a generic error with no durable marker. It is now in the codex `CODEX_NON_RETRYABLE_EVENT_CODES` set (code and message forms), the Responses error path tags `transportFailure.providerCode = "invalid_prompt"`, and a new exported `isInvalidPromptError` predicate is the single contract both transports and the session-level circuit breaker key on. Ordinary control-token / pipe text (F# `value <| f |> g`, `sum<|a+b|>c`, `<|foo bar=baz|>`) is unaffected; genuinely transient errors (`server_error`, `model_error`) stay retryable.
+
 ## [0.10.2] - 2026-07-14
 
 ### Fixed

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

@@ -410,6 +410,8 @@ export declare class AuthStorage {
      * Remove a runtime API key override.
      */
     removeRuntimeApiKey(provider: string): void;
+    /** Whether a provider is currently authenticated by a runtime API-key override. */
+    hasRuntimeApiKey(provider: string): boolean;
     /**
      * Register a per-provider API key sourced from user configuration
      * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than

package/dist/types/model-cache.d.ts

@@ -12,6 +12,8 @@ interface CacheEntry<TApi extends Api = Api> {
      */
     staticFingerprint: string;
 }
+/** Close the shared cache only when it owns the exact requested database path. */
+export declare function closeModelCache(dbPath?: string): boolean;
 export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
 export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string): void;
 export {};

package/dist/types/model-manager.d.ts

@@ -30,6 +30,8 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
     modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
     /** Clock override for deterministic tests. */
     now?: () => number;
+    /** Optional guard that must permit cache publication. Default: writes are permitted. */
+    canPublishCache?: () => boolean;
 }
 /**
  * Resolution result.

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

@@ -1,5 +1,5 @@
 import Anthropic, { type ClientOptions as AnthropicSdkClientOptions } from "@anthropic-ai/sdk";
-import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
+import type { MessageCreateParamsStreaming, MessageParam } from "@anthropic-ai/sdk/resources/messages";
 import type { FetchImpl, Message, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types";
 export type AnthropicHeaderOptions = {
     apiKey: string;
@@ -181,6 +181,7 @@ type SystemBlockOptions = {
 export declare function buildAnthropicSystemBlocks(systemPrompt: readonly string[] | undefined, options?: SystemBlockOptions): AnthropicSystemBlock[] | undefined;
 export declare function normalizeExtraBetas(betas?: string[] | string): string[];
 export declare function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): AnthropicClientOptionsResult;
+export declare function normalizeCacheControlTtlOrdering(params: MessageCreateParamsStreaming): void;
 export declare function convertAnthropicMessages(messages: Message[], model: Model<"anthropic-messages">, isOAuthToken: boolean, options?: {
     repairLatestAssistantThinking?: boolean;
 }): MessageParam[];

package/dist/types/providers/openai-codex-responses.d.ts

@@ -45,8 +45,8 @@ export declare function getOpenAICodexTransportDetails(model: Model<"openai-code
     providerSessionState?: Map<string, ProviderSessionState>;
 }): OpenAICodexTransportDetails;
 declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput;
-/** @internal Exported for tests. */
-export { convertMessages as convertCodexResponsesMessages };
+/** @internal Exported for tests. `classifyCodexFailureEventRetryable` is the retry classification of a Codex failure event. */
+export { convertMessages as convertCodexResponsesMessages, isRetryableCodexFailureEvent as classifyCodexFailureEventRetryable, };
 type CodexToolPayload = {
     type: "function";
     name: string;
@@ -65,3 +65,4 @@ type CodexToolPayload = {
 };
 /** @internal Exported for tests. */
 export declare function convertOpenAICodexResponsesTools(tools: Tool[], model: Model<"openai-codex-responses">): CodexToolPayload[];
+declare function isRetryableCodexFailureEvent(rawEvent: Record<string, unknown>): boolean;

package/dist/types/providers/pi-native-server.d.ts

@@ -10,13 +10,12 @@
  * translations impose on first-class pi-ai fields (service tier, cache
  * markers, thinking budgets, tool-choice variants, …).
  *
- * The streaming wire is {@link AssistantMessageEvent} serialized verbatim and
- * SSE-framed. Same type pi-ai already produces internally; the client feeds
- * each parsed event straight into `AssistantMessageEventStream.push()` with
- * no translation. Including `partial: AssistantMessage` on every delta is
- * O(N²) in turn length on the wire — acceptable for the loopback / sidecar
- * topology this transport is designed for; provider latency dominates the
- * actual cost.
+ * The streaming wire is {@link AssistantMessageEvent} serialized as SSE. Public
+ * projections omit private raw reasoning and serialized Responses reasoning
+ * signatures while preserving provider-displayable summaries and genuine opaque
+ * signatures. Including `partial: AssistantMessage` on every delta is O(N²) in
+ * turn length on the wire — acceptable for the loopback / sidecar topology this
+ * transport is designed for; provider latency dominates the actual cost.
  *
  * Endpoint contract:
  *   POST /v1/pi/stream
@@ -45,16 +44,9 @@ export interface PiNativeParsedRequest {
  */
 export declare function parseRequest(body: unknown, _headers?: Headers): PiNativeParsedRequest;
 /**
- * Ship every {@link AssistantMessageEvent} verbatim, SSE-framed.
- *
- * No per-event re-shaping: the pi-native client is pi-ai itself, so the
- * canonical event type IS the wire type. Including the rolling
- * `partial: AssistantMessage` on every delta is quadratic in turn length
- * on the wire, but for the loopback / sidecar topology this transport
- * targets (containerized GJC → host gateway) the bandwidth cost is negligible
- * compared to provider latency —
- * and the client gets to feed the events straight into its existing
- * `AssistantMessageEventStream.push()` plumbing with zero translation.
+ * Ship only public-safe {@link AssistantMessageEvent} projections. Unknown
+ * thinking blocks remain buffered until their terminal partial establishes that
+ * the provider-native block is safe; raw and mixed blocks never reach SSE.
  */
 export declare function encodeStream(events: AssistantMessageEventStream): ReadableStream<Uint8Array>;
 /**

package/dist/types/types.d.ts

@@ -319,6 +319,9 @@ export interface ThinkingContent {
     thinking: string;
     thinkingSignature?: string;
     itemId?: string;
+    readonly provenance?: "summary" | "raw" | "mixed";
+    readonly summaryText?: string;
+    readonly rawText?: string;
 }
 export interface RedactedThinkingContent {
     type: "redactedThinking";
@@ -542,6 +545,16 @@ export interface Tool<TParameters extends TSchema = TSchema> {
      * calls route correctly. Absent for regular JSON function tools.
      */
     customWireName?: string;
+    /**
+     * Optional safe projection for tool arguments or results. Extensions use this
+     * only for explicitly opt-in, display-safe summaries.
+     */
+    safeSummary?: (kind: "args" | "result", value: unknown) => string | undefined;
+    /** Allowlisted argument/result field names for a safe fallback summary. */
+    safeSummaryFields?: {
+        args?: string[];
+        result?: string[];
+    };
 }
 export interface Context {
     systemPrompt?: string[];
@@ -580,6 +593,20 @@ export type AssistantMessageEvent = {
     contentIndex: number;
     content: string;
     partial: AssistantMessage;
+} | {
+    type: "reasoning_summary_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "reasoning_summary_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "reasoning_summary_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
 } | {
     type: "toolcall_start";
     contentIndex: number;
@@ -731,6 +758,12 @@ export interface AnthropicCompat extends ToolChoiceCompat {
     supportsForcedToolChoice?: boolean;
     /** Whether long prompt-cache retention (`ttl: "1h"`) is supported. Default: true for canonical Anthropic API. */
     supportsLongCacheRetention?: boolean;
+    /**
+     * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
+     * Canonical Anthropic defaults to `"automatic"`; noncanonical endpoints default
+     * to `"none"` and must explicitly opt into generated `"explicit"` markers.
+     */
+    promptCacheMode?: "none" | "explicit" | "automatic";
 }
 /**
  * OpenRouter provider routing preferences.

package/dist/types/utils/fallback-transport.d.ts

@@ -1,4 +1,4 @@
-export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
 export interface FallbackTrigger {
     class: FallbackTriggerClass;
     retryAfterMs?: number;
@@ -7,12 +7,23 @@ export type TransportHeaders = Headers | Record<string, string | undefined>;
 /**
  * Structured facts from an upstream HTTP or transport failure. Retry decisions
  * must use these facts rather than provider- or application-owned error text.
+ *
+ * `headers` is always a plain record limited to the retained retry-signal
+ * entries: facts travel on persisted `AssistantMessage`s and through
+ * `structuredClone` snapshots (managed fallback attempt staging), so they must
+ * never carry a live `Headers` instance — cloning one throws `DataCloneError`
+ * ("The object can not be cloned.") and masks the real provider failure.
  */
 export interface TransportFailureFacts {
     kind: "transport";
     status?: number;
+    /** Canonical provider error code used for fallback classification. */
     providerCode?: string;
-    headers?: TransportHeaders;
+    /** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
+    anthropicErrorType?: string;
+    /** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
+    openaiErrorCode?: string;
+    headers?: Record<string, string>;
 }
 /** Opaque per-invocation marker required by managed fallback transport calls. */
 export interface FallbackAttemptToken {

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

@@ -1,61 +1,11 @@
 import type { AssistantMessage } from "../types";
+import type { TransportFailureFacts } from "./fallback-transport";
+export declare function classifyContextOverflow(message: AssistantMessage, transportFailure?: TransportFailureFacts, contextWindow?: number): boolean;
 /**
  * Check if an assistant message represents a context overflow error.
  *
- * This handles three cases:
- * 1. Error-based overflow: Most providers return stopReason "error" with a
- *    specific error message pattern.
- * 2. Silent overflow: Some providers accept overflow requests and return
- *    successfully. For these, we check if usage.input exceeds the context window.
- * 3. Proxy-level overflow: Some proxies (e.g. LiteLLM) return a "successful"
- *    response with empty content and a fabricated near-zero usage when the
- *    upstream model's context window is exceeded.
- *
- * ## Reliability by Provider
- *
- * **Reliable detection (returns error with detectable message):**
- * - Anthropic: "prompt is too long: X tokens > Y maximum"
- * - OpenAI (Completions & Responses): "exceeds the context window"
- * - Google Gemini: "input token count exceeds the maximum"
- * - xAI (Grok): "maximum prompt length is X but request contains Y"
- * - Groq: "reduce the length of the messages"
- * - Cerebras: 400/413 status code (no body)
- * - Mistral: 400/413 status code (no body)
- * - HTTP 413 payload/entity-too-large variants
- * - OpenRouter (all backends): "maximum context length is X tokens"
- * - llama.cpp: "exceeds the available context size"
- * - LM Studio: "greater than the context length"
- * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
- * - Anthropic 413: "request_too_large" (request body exceeds size limit)
- * - HTTP 413: "Payload Too Large" / "Request Entity Too Large"
- *
- * **Unreliable detection:**
- * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
- *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
- * - Ollama: Silently truncates input without error. Cannot be detected via this function.
- * - LiteLLM proxy: Returns a "successful" response with empty content and a
- *   fabricated near-zero usage (e.g. input: 1, output: 1) when the upstream
- *   model's context window is exceeded. Detected via Case 3 (empty content +
- *   anomalously low usage). Note: the LiteLLM proxy's context limit may differ
- *   from the underlying model's advertised contextWindow (e.g. configured via
- *   `model_info.max_tokens` in LiteLLM's config.yaml), so Case 2 (which compares
- *   usage.input against contextWindow) may not catch it.
- *   The response will have usage.input < expected, but we don't know the expected value.
- *
- * ## Custom Providers
- *
- * If you've added custom models via settings.json, this function may not detect
- * overflow errors from those providers. To add support:
- *
- * 1. Send a request that exceeds the model's context window
- * 2. Check the errorMessage in the response
- * 3. Create a regex pattern that matches the error
- * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
- *    check the errorMessage yourself before calling this function
- *
- * @param message - The assistant message to check
- * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
- * @returns true if the message indicates a context overflow
+ * Callers with normalized transport facts should use {@link classifyContextOverflow}
+ * so typed provider codes take precedence over error prose.
  */
 export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
 /**

package/dist/types/utils.d.ts

@@ -47,6 +47,18 @@ export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Arra
  * every marker the old regex caught still matches.
  */
 export declare function neutralizeReservedControlTokens(text: string): string;
+/**
+ * Shape-tolerant classifier for the poisoned-history rejection that wedges
+ * gpt-5.6 sessions: `Request blocked (code=invalid_prompt)`. Accepts a raw
+ * provider error, an assistant message, or any object carrying a
+ * `providerCode` / `transportFailure` / `errorMessage` field, and returns true
+ * when the failure is the deterministic `invalid_prompt` content fault rather
+ * than a transient upstream error. This is the single shared contract the
+ * provider transports and the session-level circuit breaker key on so the
+ * classification is explicit (not inferred from a catch-all bucket) and
+ * uniformly testable across transports.
+ */
+export declare function isInvalidPromptError(input: unknown): boolean;
 /**
  * Neutralize leaked reserved control tokens across every string in an outgoing
  * Responses `input` array. This is the request-boundary complement to the

package/package.json

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

package/src/auth-storage.ts

@@ -775,7 +775,9 @@ export class AuthStorage {
 	 */
 	static async create(dbPath: string, options: AuthStorageOptions = {}): Promise<AuthStorage> {
 		const store = await SqliteAuthCredentialStore.open(dbPath);
-		return new AuthStorage(store, options);
+		const storage = new AuthStorage(store, options);
+		await storage.reload();
+		return storage;
 	}
 
 	/**
@@ -854,6 +856,7 @@ export class AuthStorage {
 	 */
 	setRuntimeApiKey(provider: string, apiKey: string): void {
 		this.#runtimeOverrides.set(provider, apiKey);
+		this.#bumpGeneration("set-runtime-api-key");
 	}
 
 	/**
@@ -877,7 +880,12 @@ export class AuthStorage {
 	 * Remove a runtime API key override.
 	 */
 	removeRuntimeApiKey(provider: string): void {
-		this.#runtimeOverrides.delete(provider);
+		if (this.#runtimeOverrides.delete(provider)) this.#bumpGeneration("remove-runtime-api-key");
+	}
+
+	/** Whether a provider is currently authenticated by a runtime API-key override. */
+	hasRuntimeApiKey(provider: string): boolean {
+		return Boolean(this.#runtimeOverrides.get(provider));
 	}
 
 	/**
@@ -892,13 +900,14 @@ export class AuthStorage {
 	 */
 	setConfigApiKey(provider: string, apiKey: string): void {
 		this.#configOverrides.set(provider, apiKey);
+		this.#bumpGeneration("set-config-api-key");
 	}
 
 	/**
 	 * Remove a single config-sourced API key override.
 	 */
 	removeConfigApiKey(provider: string): void {
-		this.#configOverrides.delete(provider);
+		if (this.#configOverrides.delete(provider)) this.#bumpGeneration("remove-config-api-key");
 	}
 
 	/**
@@ -906,7 +915,9 @@ export class AuthStorage {
 	 * re-parsing `models.yml` so removed entries actually disappear.
 	 */
 	clearConfigApiKeys(): void {
+		if (this.#configOverrides.size === 0) return;
 		this.#configOverrides.clear();
+		this.#bumpGeneration("clear-config-api-keys");
 	}
 
 	/**

package/src/model-cache.ts

@@ -66,6 +66,16 @@ function getDb(dbPath?: string): Database {
 	return db;
 }
 
+/** Close the shared cache only when it owns the exact requested database path. */
+export function closeModelCache(dbPath?: string): boolean {
+	const resolvedPath = dbPath ?? getModelDbPath();
+	if (!sharedDb || sharedDbPath !== resolvedPath) return false;
+	sharedDb.close();
+	sharedDb = null;
+	sharedDbPath = null;
+	return true;
+}
+
 function migrateCacheSchema(db: Database): void {
 	const columns = db.prepare("PRAGMA table_info(model_cache)").all() as TableInfoRow[];
 	if (!columns.some(column => column.name === "static_fingerprint")) {

package/src/model-manager.ts

@@ -41,6 +41,8 @@ export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload =
 	modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
 	/** Clock override for deterministic tests. */
 	now?: () => number;
+	/** Optional guard that must permit cache publication. Default: writes are permitted. */
+	canPublishCache?: () => boolean;
 }
 
 /**
@@ -148,7 +150,9 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 			return { models: cachedModels, stale: false };
 		}
 		const repairedModels = mergeDynamicModels(staticModels, cachedModels);
-		writeModelCache(options.providerId, now(), repairedModels, true, staticFingerprint, dbPath);
+		if (options.canPublishCache?.() ?? true) {
+			writeModelCache(options.providerId, now(), repairedModels, true, staticFingerprint, dbPath);
+		}
 		return { models: repairedModels, stale: false };
 	}
 
@@ -169,24 +173,28 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 			const snapshotModels = applyFinalCodexGpt56ContextCap(
 				mergeDynamicModels(mergeModelSources(staticModels, modelsDevModels), dynamicModels),
 			);
-			writeModelCache(options.providerId, now(), snapshotModels, true, staticFingerprint, dbPath);
+			if (options.canPublishCache?.() ?? true) {
+				writeModelCache(options.providerId, now(), snapshotModels, true, staticFingerprint, dbPath);
+			}
 		} else {
 			// Dynamic fetch failed — update cache with a non-authoritative snapshot so
 			// stale state remains visible while retry backoff still applies.
 			const latestCache = readModelCache<TApi>(options.providerId, ttlMs, now, dbPath);
-			writeModelCache(
-				options.providerId,
-				now(),
-				applyFinalCodexGpt56ContextCap(
-					mergeDynamicModels(
-						mergeModelSources(staticModels, modelsDevModels),
-						normalizeModelList<TApi>(latestCache?.models ?? cache?.models ?? []),
+			if (options.canPublishCache?.() ?? true) {
+				writeModelCache(
+					options.providerId,
+					now(),
+					applyFinalCodexGpt56ContextCap(
+						mergeDynamicModels(
+							mergeModelSources(staticModels, modelsDevModels),
+							normalizeModelList<TApi>(latestCache?.models ?? cache?.models ?? []),
+						),
 					),
-				),
-				false,
-				staticFingerprint,
-				dbPath,
-			);
+					false,
+					staticFingerprint,
+					dbPath,
+				);
+			}
 		}
 	}
 	return {