@gajae-code/ai 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-06
+
+### Added
+
+- Added minimax-m3 model support across MiniMax providers.
+- Honored the `GJC_CACHE_RETENTION` environment variable and `cacheRetention` model config so hosts can control provider prompt-cache retention (#379/#381).
+- Added an Opus max reasoning preset to the model thinking presets (#372).
+- Refreshed the generated models schema for the new model/config surface (#382).
+
+### Changed
+
+- Pinned the OpenAI Codex provider default to GPT-5.5 at `xhigh` reasoning effort (#352). This changes the default model and effort for Codex users (latency/cost/quality impact) and is a behavior change, not an API break; pass an explicit model/effort to override.
+- Bumped the spoofed Gemini CLI user-agent version to 0.45.2 to track the upstream release.
+
 ## [0.3.0] - 2026-06-03
 
 ### Added

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

@@ -5,7 +5,8 @@ export declare const enum Effort {
     Low = "low",
     Medium = "medium",
     High = "high",
-    XHigh = "xhigh"
+    XHigh = "xhigh",
+    Max = "max"
 }
 export declare const THINKING_EFFORTS: readonly Effort[];
 /**

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

@@ -1,6 +1,6 @@
 import type { ServiceTier, StreamFunction, StreamOptions, ToolChoice } from "../types";
 export interface AzureOpenAIResponsesOptions extends StreamOptions {
-    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     reasoningSummary?: "auto" | "detailed" | "concise" | null;
     azureApiVersion?: string;
     azureResourceName?: string;

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

@@ -1,6 +1,6 @@
 import type { StreamFunction, StreamOptions, ToolChoice } from "../types";
 export interface OllamaChatOptions extends StreamOptions {
-    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     toolChoice?: ToolChoice;
 }
 export declare const streamOllama: StreamFunction<"ollama-chat">;

package/dist/types/providers/openai-chat-server-schema.d.ts

@@ -777,6 +777,7 @@ export declare const openaiChatRequestSchema: z.ZodObject<{
     reasoning_effort: z.ZodOptional<z.ZodEnum<{
         high: "high";
         low: "low";
+        max: "max";
         medium: "medium";
         minimal: "minimal";
         xhigh: "xhigh";

package/dist/types/providers/openai-codex/request-transformer.d.ts

@@ -1,6 +1,6 @@
 import type { Api, Model } from "../../types";
 export interface ReasoningConfig {
-    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     summary?: "auto" | "concise" | "detailed";
 }
 export interface CodexRequestOptions {

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

@@ -1,7 +1,7 @@
 import type { ResponseInput } from "openai/resources/responses/responses";
 import { type Context, type Model, type ProviderSessionState, type ServiceTier, type StreamFunction, type StreamOptions, type Tool, type ToolChoice } from "../types";
 export interface OpenAICodexResponsesOptions extends StreamOptions {
-    reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     reasoningSummary?: "auto" | "concise" | "detailed" | null;
     textVerbosity?: "low" | "medium" | "high";
     include?: string[];

package/dist/types/providers/openai-completions.d.ts

@@ -17,7 +17,7 @@ import { type ResolvedOpenAICompat } from "./openai-completions-compat";
 export declare function isOpenAICompletionsProgressChunk(chunk: unknown): boolean;
 export interface OpenAICompletionsOptions extends StreamOptions {
     toolChoice?: ToolChoice;
-    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     /** Force-disable reasoning where supported, or request the lowest effort on generic effort endpoints. */
     disableReasoning?: boolean;
     serviceTier?: ServiceTier;

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

@@ -3,7 +3,7 @@ import type { Model, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoic
 import { type OpenAIResponsesToolChoice } from "../utils/tool-choice";
 export declare function normalizeOpenAIResponsesPromptCacheKey(sessionId: string | undefined): string | undefined;
 export interface OpenAIResponsesOptions extends StreamOptions {
-    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
     reasoningSummary?: "auto" | "detailed" | "concise" | null;
     serviceTier?: ServiceTier;
     toolChoice?: ToolChoice;

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

@@ -4,7 +4,7 @@
  * Where the OpenAI / Anthropic / Responses route modules translate foreign
  * wire shapes through pi-ai's canonical {@link Context}, this module accepts
  * the canonical shape *directly* — for clients that already speak pi-ai
- * (containerized gjc, the swarm extension, robogjc's sidecar auth-gateway).
+ * (containerized gjc and robogjc's sidecar auth-gateway).
  * Skipping the wire-format → Context → wire-format round-trip cuts
  * per-request CPU but, more importantly, avoids the quantization that those
  * translations impose on first-class pi-ai fields (service tier, cache

package/dist/types/types.d.ts

@@ -751,6 +751,8 @@ export interface Model<TApi extends Api = any> {
     wireModelId?: string;
     /** Declarative request shaping for OpenAI-compatible proxy providers. */
     requestTransform?: ModelRequestTransform;
+    /** Default prompt-cache retention preference for this model when the request omits one. */
+    cacheRetention?: CacheRetention;
     /** Provider-assigned priority value (lower = higher priority). */
     priority?: number;
     /** Canonical thinking capability metadata for this model. */

package/dist/types/utils.d.ts

@@ -22,7 +22,7 @@ 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 PI_CACHE_RETENTION for backward compatibility.
+ * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
  */
 export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
 export declare function isAnthropicOAuthToken(key: string): boolean;

package/package.json

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

package/src/model-thinking.ts

@@ -8,6 +8,7 @@ export const enum Effort {
 	Medium = "medium",
 	High = "high",
 	XHigh = "xhigh",
+	Max = "max",
 }
 
 export const THINKING_EFFORTS: readonly Effort[] = [
@@ -16,6 +17,7 @@ export const THINKING_EFFORTS: readonly Effort[] = [
 	Effort.Medium,
 	Effort.High,
 	Effort.XHigh,
+	Effort.Max,
 ];
 
 const DEFAULT_REASONING_EFFORTS: readonly Effort[] = [Effort.Minimal, Effort.Low, Effort.Medium, Effort.High];
@@ -26,9 +28,26 @@ const DEFAULT_REASONING_EFFORTS_WITH_XHIGH: readonly Effort[] = [
 	Effort.High,
 	Effort.XHigh,
 ];
+const DEFAULT_REASONING_EFFORTS_WITH_MAX: readonly Effort[] = [
+	Effort.Minimal,
+	Effort.Low,
+	Effort.Medium,
+	Effort.High,
+	Effort.Max,
+];
+const DEFAULT_REASONING_EFFORTS_WITH_XHIGH_AND_MAX: readonly Effort[] = [
+	Effort.Minimal,
+	Effort.Low,
+	Effort.Medium,
+	Effort.High,
+	Effort.XHigh,
+	Effort.Max,
+];
 const GEMINI_3_PRO_EFFORTS: readonly Effort[] = [Effort.Low, Effort.High];
 const GEMINI_3_FLASH_EFFORTS: readonly Effort[] = [Effort.Minimal, Effort.Low, Effort.Medium, Effort.High];
 const GPT_5_2_PLUS_EFFORTS: readonly Effort[] = [Effort.Low, Effort.Medium, Effort.High, Effort.XHigh];
+const GPT_5_5_DEFAULT_EFFORT = Effort.XHigh;
+
 const GPT_5_1_CODEX_MINI_EFFORTS: readonly Effort[] = [Effort.Medium, Effort.High];
 const CLOUDFLARE_AI_GATEWAY_BASE_URL = "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic";
 
@@ -281,6 +300,7 @@ export function mapEffortToGoogleThinkingLevel<TApi extends Api>(
 			return "MEDIUM";
 		case Effort.High:
 		case Effort.XHigh:
+		case Effort.Max:
 			return "HIGH";
 	}
 }
@@ -299,10 +319,8 @@ export function mapEffortToAnthropicAdaptiveEffort<TApi extends Api>(
 		case Effort.High:
 			return "high";
 		case Effort.XHigh:
-			// Opus 4.7+ introduced a distinct "xhigh" effort level (between "high" and "max").
-			// The Anthropic docs scope this to the Messages API only, so Bedrock Converse and
-			// older adaptive-thinking Opus 4.6 models keep the legacy "max" alias.
-			return anthropicModelHasRealXHighEffort(model) ? "xhigh" : "max";
+		case Effort.Max:
+			return effort === Effort.XHigh ? "xhigh" : "max";
 	}
 }
 
@@ -433,6 +451,17 @@ function applyOpenAICatalogPolicy(model: ApiModel<Api>, parsedModel: OpenAIModel
 	}
 }
 
+function inferDefaultEffort<TApi extends Api>(model: ApiModel<TApi>, parsedModel: ParsedModel): Effort | undefined {
+	if (
+		parsedModel.family === "openai" &&
+		model.provider === "openai-codex" &&
+		semverEqual(parsedModel.version, "5.5")
+	) {
+		return GPT_5_5_DEFAULT_EFFORT;
+	}
+	return undefined;
+}
+
 function inferModelThinking<TApi extends Api>(model: ApiModel<TApi>): ThinkingConfig {
 	const parsedModel = parseKnownModel(model.id);
 	const efforts = inferSupportedEfforts(parsedModel, model);
@@ -446,6 +475,10 @@ function inferModelThinking<TApi extends Api>(model: ApiModel<TApi>): ThinkingCo
 		minLevel,
 		maxLevel,
 	};
+	const defaultLevel = inferDefaultEffort(model, parsedModel);
+	if (defaultLevel && efforts.includes(defaultLevel)) {
+		config.defaultLevel = defaultLevel;
+	}
 	// Encode explicit levels only when the inferred set has gaps the min..max range cannot represent.
 	const minIndex = THINKING_EFFORTS.indexOf(minLevel);
 	const maxIndex = THINKING_EFFORTS.indexOf(maxLevel);
@@ -466,7 +499,13 @@ function normalizeThinkingConfig(thinking: ThinkingConfig | undefined): Thinking
 function thinkingsEqual(left: ThinkingConfig | undefined, right: ThinkingConfig | undefined): boolean {
 	if (left === right) return true;
 	if (!left || !right) return false;
-	if (left.mode !== right.mode || left.minLevel !== right.minLevel || left.maxLevel !== right.maxLevel) return false;
+	if (
+		left.mode !== right.mode ||
+		left.minLevel !== right.minLevel ||
+		left.maxLevel !== right.maxLevel ||
+		left.defaultLevel !== right.defaultLevel
+	)
+		return false;
 	const leftLevels = left.levels;
 	const rightLevels = right.levels;
 	if (leftLevels === rightLevels) return true;
@@ -525,7 +564,10 @@ function inferAnthropicSupportedEfforts<TApi extends Api>(
 		(model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") &&
 		semverGte(parsedModel.version, "4.6")
 	) {
-		return parsedModel.kind === "opus" ? DEFAULT_REASONING_EFFORTS_WITH_XHIGH : DEFAULT_REASONING_EFFORTS;
+		if (parsedModel.kind !== "opus") return DEFAULT_REASONING_EFFORTS;
+		return anthropicModelHasRealXHighEffort(model)
+			? DEFAULT_REASONING_EFFORTS_WITH_XHIGH_AND_MAX
+			: DEFAULT_REASONING_EFFORTS_WITH_MAX;
 	}
 	return inferFallbackEfforts(model);
 }

package/src/models.json

@@ -34657,6 +34657,31 @@
 				"minLevel": "minimal",
 				"maxLevel": "xhigh"
 			}
+		},
+		"minimax-m3": {
+			"id": "minimax-m3",
+			"name": "MiniMax M3",
+			"api": "anthropic-messages",
+			"provider": "minimax",
+			"baseUrl": "https://api.minimax.io/anthropic",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 0.6,
+				"output": 2.4,
+				"cacheRead": 0.12,
+				"cacheWrite": 0
+			},
+			"contextWindow": 512000,
+			"maxTokens": 128000,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
 		}
 	},
 	"minimax-cn": {
@@ -34827,6 +34852,31 @@
 				"minLevel": "minimal",
 				"maxLevel": "xhigh"
 			}
+		},
+		"minimax-m3": {
+			"id": "minimax-m3",
+			"name": "MiniMax M3",
+			"api": "anthropic-messages",
+			"provider": "minimax-cn",
+			"baseUrl": "https://api.minimaxi.com/anthropic",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 0.6,
+				"output": 2.4,
+				"cacheRead": 0.12,
+				"cacheWrite": 0
+			},
+			"contextWindow": 512000,
+			"maxTokens": 128000,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
 		}
 	},
 	"minimax-code": {
@@ -35069,6 +35119,37 @@
 				"minLevel": "minimal",
 				"maxLevel": "high"
 			}
+		},
+		"minimax-m3": {
+			"id": "minimax-m3",
+			"name": "MiniMax M3",
+			"api": "openai-completions",
+			"provider": "minimax-code",
+			"baseUrl": "https://api.minimax.io/v1",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 512000,
+			"maxTokens": 128000,
+			"compat": {
+				"supportsStore": false,
+				"supportsDeveloperRole": false,
+				"supportsReasoningEffort": false,
+				"reasoningContentField": "reasoning_content"
+			},
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "high"
+			}
 		}
 	},
 	"minimax-code-cn": {
@@ -35311,6 +35392,37 @@
 				"minLevel": "minimal",
 				"maxLevel": "high"
 			}
+		},
+		"minimax-m3": {
+			"id": "minimax-m3",
+			"name": "MiniMax M3",
+			"api": "openai-completions",
+			"provider": "minimax-code-cn",
+			"baseUrl": "https://api.minimaxi.com/v1",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 512000,
+			"maxTokens": 128000,
+			"compat": {
+				"supportsStore": false,
+				"supportsDeveloperRole": false,
+				"supportsReasoningEffort": false,
+				"reasoningContentField": "reasoning_content"
+			},
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "high"
+			}
 		}
 	},
 	"mistral": {
@@ -53159,7 +53271,8 @@
 			"thinking": {
 				"mode": "effort",
 				"minLevel": "low",
-				"maxLevel": "xhigh"
+				"maxLevel": "xhigh",
+				"defaultLevel": "xhigh"
 			},
 			"applyPatchToolType": "freeform",
 			"contextPromotionTarget": "openai-codex/gpt-5.4"
@@ -74638,4 +74751,4 @@
 			}
 		}
 	}
-}
+}

package/src/provider-models/descriptors.ts

@@ -301,9 +301,9 @@ export const DEFAULT_MODEL_PER_PROVIDER: Record<KnownProvider, string> = {
 	"google-antigravity": "gemini-3-pro-high",
 	"google-gemini-cli": "gemini-2.5-pro",
 	"google-vertex": "gemini-3-pro-preview",
-	minimax: "MiniMax-M2.5",
-	"minimax-code": "MiniMax-M2.5",
-	"minimax-code-cn": "MiniMax-M2.5",
-	"openai-codex": "gpt-5.4",
+	minimax: "minimax-m3",
+	"minimax-code": "minimax-m3",
+	"minimax-code-cn": "minimax-m3",
+	"openai-codex": "gpt-5.5",
 	"gitlab-duo": "duo-chat-sonnet-4-5",
 } as Record<KnownProvider, string>;

package/src/provider-models/openai-compat.ts

@@ -2135,7 +2135,7 @@ const MODELS_DEV_PROVIDER_DESCRIPTORS_CORE: readonly ModelsDevProviderDescriptor
 			// sending unsupported effort strings.
 			supportsDeveloperRole: false,
 			supportsReasoningEffort: true,
-			reasoningEffortMap: { minimal: "high", low: "high", medium: "high", high: "high", xhigh: "max" },
+			reasoningEffortMap: { minimal: "high", low: "high", medium: "high", high: "high", xhigh: "max", max: "max" },
 			maxTokensField: "max_tokens",
 			// DeepSeek V4 thinking mode rejects the `tool_choice` control parameter.
 			// Tool calls still work without it; the API defaults to auto when tools exist.

package/src/providers/amazon-bedrock.ts

@@ -791,6 +791,7 @@ function buildAdditionalModelRequestFields(
 		medium: 8192,
 		high: 16384,
 		xhigh: 32768,
+		max: 32768,
 	};
 	const budget = options.thinkingBudgets?.[level] ?? defaultBudgets[level];
 

package/src/providers/anthropic.ts

@@ -2001,8 +2001,8 @@ function buildParams(
 				}
 				params.thinking = adaptive as typeof params.thinking;
 				if (effort) {
-					// SDK's OutputConfig.effort type is not yet widened to include the new "xhigh"
-					// level introduced with Anthropic model Opus 4.7. Cast until the SDK catches up.
+					// SDK OutputConfig.effort typings may lag Anthropic's adaptive effort literals.
+					// Cast so newly supported levels can pass through before the SDK catches up.
 					params.output_config = { effort } as typeof params.output_config;
 				}
 			} else {

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

@@ -70,7 +70,7 @@ function resolveDeploymentName(model: Model<"azure-openai-responses">, options?:
 
 // Azure OpenAI Responses-specific options
 export interface AzureOpenAIResponsesOptions extends StreamOptions {
-	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	reasoningSummary?: "auto" | "detailed" | "concise" | null;
 	azureApiVersion?: string;
 	azureResourceName?: string;

package/src/providers/google-gemini-headers.ts

@@ -4,7 +4,7 @@
  * GeminiCLI/VERSION/MODEL (PLATFORM; ARCH; SURFACE)
  */
 export function getGeminiCliUserAgent(modelId = "gemini-3.1-pro-preview"): string {
-	const version = process.env.PI_AI_GEMINI_CLI_VERSION || "0.44.1";
+	const version = process.env.PI_AI_GEMINI_CLI_VERSION || "0.45.2";
 	const platform = process.platform === "win32" ? "win32" : process.platform;
 	const arch = process.arch === "x64" ? "x64" : process.arch;
 	return `GeminiCLI/${version}/${modelId} (${platform}; ${arch}; terminal)`;

package/src/providers/ollama.ts

@@ -23,7 +23,7 @@ import { toolWireSchema } from "../utils/schema/wire";
 import { transformMessages } from "./transform-messages";
 
 export interface OllamaChatOptions extends StreamOptions {
-	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	toolChoice?: ToolChoice;
 }
 
@@ -95,6 +95,7 @@ function mapReasoning(reasoning: OllamaChatOptions["reasoning"]): boolean | "low
 			return "medium";
 		case "high":
 		case "xhigh":
+		case "max":
 			return "high";
 		default:
 			return undefined;

package/src/providers/openai-chat-server-schema.ts

@@ -210,7 +210,7 @@ export const openaiChatRequestSchema = z.object({
 	frequency_penalty: z.number().optional(),
 	logit_bias: z.record(z.string(), z.number()).optional(),
 	user: z.string().optional(),
-	reasoning_effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
+	reasoning_effort: z.enum(["minimal", "low", "medium", "high", "xhigh", "max"]).optional(),
 	parallel_tool_calls: z.boolean().optional(),
 	service_tier: z.enum(["auto", "default", "flex", "scale", "priority"]).optional(),
 	metadata: z.record(z.string(), z.unknown()).optional(),

package/src/providers/openai-chat-server.ts

@@ -33,7 +33,14 @@ export type { ParsedRequest };
 type ReasoningEffort = NonNullable<ParsedRequest["options"]["reasoning"]>;
 
 function isReasoningEffort(value: unknown): value is ReasoningEffort {
-	return value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh";
+	return (
+		value === "minimal" ||
+		value === "low" ||
+		value === "medium" ||
+		value === "high" ||
+		value === "xhigh" ||
+		value === "max"
+	);
 }
 
 function isServiceTier(value: unknown): value is ResolvedServiceTier {

package/src/providers/openai-codex/request-transformer.ts

@@ -3,7 +3,7 @@ import { requireSupportedEffort } from "../../model-thinking";
 import type { Api, Model } from "../../types";
 
 export interface ReasoningConfig {
-	effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+	effort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	summary?: "auto" | "concise" | "detailed";
 }
 

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

@@ -73,7 +73,7 @@ import {
 import { transformMessages } from "./transform-messages";
 
 export interface OpenAICodexResponsesOptions extends StreamOptions {
-	reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	reasoningSummary?: "auto" | "concise" | "detailed" | null;
 	textVerbosity?: "low" | "medium" | "high";
 	include?: string[];

package/src/providers/openai-completions-compat.ts

@@ -1,6 +1,6 @@
 import type { Model, OpenAICompat } from "../types";
 
-type OpenAIReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+type OpenAIReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type ResolvedToolStrictMode = NonNullable<OpenAICompat["toolStrictMode"]> | "mixed";
 
 export type ResolvedOpenAICompat = Required<
@@ -162,6 +162,7 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 					medium: "default",
 					high: "default",
 					xhigh: "default",
+					max: "default",
 				} satisfies Partial<Record<OpenAIReasoningEffort, string>>)
 			: isDeepseekFamily && model.reasoning
 				? ({
@@ -170,6 +171,7 @@ export function detectOpenAICompat(model: Model<"openai-completions">, resolvedB
 						medium: "high",
 						high: "high",
 						xhigh: "max",
+						max: "max",
 					} satisfies Partial<Record<OpenAIReasoningEffort, string>>)
 				: isFireworks
 					? ({

package/src/providers/openai-completions.ts

@@ -249,13 +249,13 @@ export function isOpenAICompletionsProgressChunk(chunk: unknown): boolean {
 
 export interface OpenAICompletionsOptions extends StreamOptions {
 	toolChoice?: ToolChoice;
-	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	/** Force-disable reasoning where supported, or request the lowest effort on generic effort endpoints. */
 	disableReasoning?: boolean;
 	serviceTier?: ServiceTier;
 }
 
-type OpenAICompletionsParams = OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming & {
+type OpenAICompletionsParams = Omit<OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming, "reasoning_effort"> & {
 	top_k?: number;
 	min_p?: number;
 	repetition_penalty?: number;
@@ -263,6 +263,7 @@ type OpenAICompletionsParams = OpenAI.Chat.Completions.ChatCompletionCreateParam
 	enable_thinking?: boolean;
 	chat_template_kwargs?: { enable_thinking: boolean };
 	reasoning?: { effort?: string } | { enabled: false };
+	reasoning_effort?: OpenAICompletionsOptions["reasoning"];
 	provider?: OpenAICompat["openRouterRouting"];
 	providerOptions?: { gateway?: { only?: string[]; order?: string[] } };
 };
@@ -479,7 +480,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					body: params,
 				};
 				const { data, response, request_id } = await client.chat.completions
-					.create(params, { signal: requestSignal })
+					.create(params as OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming, { signal: requestSignal })
 					.withResponse();
 				await notifyProviderResponse(options, response, model, request_id);
 				return data;

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

@@ -37,7 +37,14 @@ export type { ParsedRequest };
 // ─── narrow guards ──────────────────────────────────────────────────────────
 
 function isReasoningEffort(value: unknown): value is NonNullable<ParsedRequest["options"]["reasoning"]> {
-	return value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh";
+	return (
+		value === "minimal" ||
+		value === "low" ||
+		value === "medium" ||
+		value === "high" ||
+		value === "xhigh" ||
+		value === "max"
+	);
 }
 
 function isServiceTier(value: unknown): value is NonNullable<ParsedRequest["options"]["serviceTier"]> {

package/src/providers/openai-responses.ts

@@ -95,7 +95,7 @@ export function normalizeOpenAIResponsesPromptCacheKey(sessionId: string | undef
 
 // OpenAI Responses-specific options
 export interface OpenAIResponsesOptions extends StreamOptions {
-	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh";
+	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	reasoningSummary?: "auto" | "detailed" | "concise" | null;
 	serviceTier?: ServiceTier;
 	toolChoice?: ToolChoice;
@@ -425,11 +425,9 @@ function createClient(
 }
 
 function getOpenAIResponsesCacheSessionId(
-	options: Pick<OpenAIResponsesOptions, "cacheRetention" | "sessionId"> | undefined,
+	options: Pick<OpenAIResponsesOptions, "sessionId"> | undefined,
 ): string | undefined {
-	return resolveCacheRetention(options?.cacheRetention) === "none"
-		? undefined
-		: normalizeOpenAIResponsesPromptCacheKey(options?.sessionId);
+	return normalizeOpenAIResponsesPromptCacheKey(options?.sessionId);
 }
 
 function buildParams(
@@ -470,7 +468,7 @@ function buildParams(
 		}
 	}
 
-	const cacheRetention = resolveCacheRetention(options?.cacheRetention);
+	const cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention);
 	const promptCacheKey = getOpenAIResponsesCacheSessionId(options);
 	const params: OpenAIResponsesSamplingParams = {
 		model: model.wireModelId ?? model.id,
@@ -478,9 +476,7 @@ function buildParams(
 		instructions: systemInstructions,
 		stream: true,
 		prompt_cache_key: promptCacheKey,
-		prompt_cache_retention: promptCacheKey
-			? getPromptCacheRetention(resolvedBaseUrl || model.baseUrl, cacheRetention)
-			: undefined,
+		prompt_cache_retention: getPromptCacheRetention(resolvedBaseUrl || model.baseUrl, cacheRetention),
 		store: false,
 		stream_options: model.provider === "openai" ? { include_obfuscation: false } : undefined,
 	};

package/src/providers/pi-native-client.ts

@@ -11,9 +11,8 @@
  *
  * Activated when a {@link Model} has `transport: "pi-native"` set; the
  * dispatch hook lives in `streamSimple()` (see `../stream.ts`). Used by
- * containerized gjc deployments (robogjc slots, the swarm extension) that
- * route every LLM call through a credential-holding sidecar so the slot
- * itself stays credential-free.
+ * containerized gjc deployments (e.g. robogjc slots) that route every LLM call
+ * through a credential-holding sidecar so the slot itself stays credential-free.
  */
 import { readSseJson } from "@gajae-code/utils";
 import type {

package/src/providers/pi-native-server.ts

@@ -4,7 +4,7 @@
  * Where the OpenAI / Anthropic / Responses route modules translate foreign
  * wire shapes through pi-ai's canonical {@link Context}, this module accepts
  * the canonical shape *directly* — for clients that already speak pi-ai
- * (containerized gjc, the swarm extension, robogjc's sidecar auth-gateway).
+ * (containerized gjc and robogjc's sidecar auth-gateway).
  * Skipping the wire-format → Context → wire-format round-trip cuts
  * per-request CPU but, more importantly, avoids the quantization that those
  * translations impose on first-class pi-ai fields (service tier, cache

package/src/stream.ts

@@ -459,6 +459,7 @@ export const ANTHROPIC_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 32768,
+	max: 65536,
 };
 
 const GOOGLE_THINKING: Record<Effort, number> = {
@@ -467,6 +468,7 @@ const GOOGLE_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 24575,
+	max: 24575,
 };
 
 const BEDROCK_CLAUDE_THINKING: Record<Effort, number> = {
@@ -475,6 +477,7 @@ const BEDROCK_CLAUDE_THINKING: Record<Effort, number> = {
 	medium: 8192,
 	high: 16384,
 	xhigh: 16384,
+	max: 32768,
 };
 
 function resolveBedrockThinkingBudget(
@@ -559,7 +562,7 @@ function mapOptionsForApi<TApi extends Api>(
 		maxTokens: options?.maxTokens || Math.min(model.maxTokens, 32000),
 		signal: options?.signal,
 		apiKey: apiKey || options?.apiKey,
-		cacheRetention: options?.cacheRetention,
+		cacheRetention: options?.cacheRetention ?? model.cacheRetention,
 		headers: options?.headers,
 		initiatorOverride: options?.initiatorOverride,
 		maxRetryDelayMs: options?.maxRetryDelayMs,

package/src/types.ts

@@ -888,6 +888,8 @@ export interface Model<TApi extends Api = any> {
 	wireModelId?: string;
 	/** Declarative request shaping for OpenAI-compatible proxy providers. */
 	requestTransform?: ModelRequestTransform;
+	/** Default prompt-cache retention preference for this model when the request omits one. */
+	cacheRetention?: CacheRetention;
 	/** Provider-assigned priority value (lower = higher priority). */
 	priority?: number;
 	/** Canonical thinking capability metadata for this model. */

package/src/utils.ts

@@ -153,10 +153,12 @@ export function getOpenAIResponsesHistoryItems(
 
 /**
  * Resolve cache retention preference.
- * Defaults to "short" and uses PI_CACHE_RETENTION for backward compatibility.
+ * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
  */
 export function resolveCacheRetention(cacheRetention?: CacheRetention): 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";
 }