@oh-my-pi/pi-ai 17.0.3 → 17.0.5

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [17.0.5] - 2026-07-18
+
+### Changed
+
+- Changed Anthropic API-key requests to default to a 1-hour prompt-cache retention (using the extended-cache-ttl-2025-04-11 beta) to prevent cold-misses during idle sessions, with support for PI_CACHE_RETENTION values "short" and "none" to override this behavior.
+
+### Fixed
+
+- Fixed transient OpenAI stream truncations by retrying once before output becomes replay-unsafe, preventing recoverable transport errors from failing the turn.
+- Fixed native Kimi Code K3 thinking being disabled during named function selection by utilizing generic required tool choice.
+- Fixed /login moonshot validating China-platform API keys against the international host instead of honoring MOONSHOT_BASE_URL.
+- Fixed Anthropic session stickiness suppressing usage-based re-ranking indefinitely by gating stickiness on a 1-hour cache warmth window (configurable via ANTHROPIC_SESSION_STICKY_CACHE_WARM_MS) to restore proactive multi-account load balancing after long idle periods.
+- Fixed credential ranking where clockless Anthropic usage windows incorrectly outranked clocked sibling credentials.
+- Fixed tool request failures (HTTP 400) on local grammar-constrained OpenAI-compatible backends (such as llama.cpp, LM Studio, and vLLM) by widening bare boolean subschemas into a value-accepting primitive union.
+- Fixed custom OAuth Anthropic-compatible endpoints receiving generated Claude Code fingerprint headers even when explicit header overrides were provided.
+- Fixed active sessions for plan-gated OpenAI Codex models (Sol/Luna) silently re-routing to sibling OAuth accounts when usage headroom changed, ensuring session stickiness is preserved as long as the preferred credential remains usable and eligible.
+
+## [17.0.4] - 2026-07-18
+
+### Fixed
+
+- Fixed Kimi Code usage reports dropping the 5h window reset time (`omp usage` showed no "resets in …" for the 5h limit): the API returns `resetTime` on the limit `detail`, not on `window`, so the parsed row-level reset is now carried onto the window when the window itself has none.
+- Made Kimi device-id persistence best-effort: a missing or unwritable `~/.omp/agent` directory no longer throws during Kimi header construction, which silently nulled every `kimi-code` usage probe on fresh installs.
+- Coerced boolean tool-schema subschemas to MFJS object forms for native Moonshot/Kimi endpoints, preventing the task tool's `outputSchema` field from causing HTTP 400 responses ([#5952](https://github.com/can1357/oh-my-pi/issues/5952)).
+
 ## [17.0.3] - 2026-07-17
 
 ### Fixed

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

@@ -11,6 +11,8 @@ export type AnthropicHeaderOptions = {
     isCloudflareAiGateway?: boolean;
     claudeCodeSessionId?: string;
     claudeCodeBetas?: readonly string[];
+    /** Allow explicit fingerprint headers to replace OAuth defaults on non-official endpoints. */
+    allowAnthropicHeaderOverrides?: boolean;
 };
 export declare function normalizeAnthropicBaseUrl(baseUrl?: string): string | undefined;
 export declare function buildBetaHeader(baseBetas: readonly string[], extraBetas: readonly string[]): string;

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

@@ -155,6 +155,8 @@ export declare function getOpenAICodexTransportDetails(model: Model<"openai-code
     preferWebsockets?: boolean;
     providerSessionState?: Map<string, ProviderSessionState>;
 }): OpenAICodexTransportDetails;
+/** Resolve a Codex Responses endpoint exactly as the chat and compaction transports do. */
+export declare function resolveCodexResponsesUrl(baseUrl: string | undefined): string;
 declare function convertMessages(model: Model<"openai-codex-responses">, context: Context): ResponseInput;
 /** @internal Exported for tests. */
 export { convertMessages as convertCodexResponsesMessages };

package/dist/types/registry/api-key-login.d.ts

@@ -21,7 +21,7 @@ type AnthropicMessagesValidation = {
 type ModelsEndpointValidation = {
     kind: "models-endpoint";
     provider: string;
-    modelsUrl: string;
+    modelsUrl: string | (() => string);
     headers?: Record<string, string> | (() => Record<string, string> | undefined);
 };
 export type ApiKeyLoginConfig = {

package/dist/types/utils/schema/normalize.d.ts

@@ -2,8 +2,11 @@ import { type DescriptionSpillFormat } from "./spill.js";
 import { type JsonObject } from "./types.js";
 export type ResidualSchemaIncompatibility = "type-array" | "type-null" | "nullable" | "combiners" | "not";
 export interface NormalizeSchemaOptions {
-    /** Coerce JSON Schema boolean subschemas for providers whose wire cannot encode them. */
-    coerceBooleanSubschemas?: boolean;
+    /**
+     * Coerce boolean subschemas to object forms. `standard` preserves `false`
+     * with `not`; `permissive` uses `{}` when the provider cannot express it.
+     */
+    coerceBooleanSubschemas?: "standard" | "permissive";
     unsupportedFields: (key: string) => boolean;
     normalizeFieldNames: boolean;
     collapseNullFields: boolean;
@@ -62,6 +65,9 @@ export declare function normalizeSchemaForMCP(value: unknown): unknown;
  *    `default` and `description` are MFJS Meta Data fields and are preserved.
  *  - `additionalProperties` (boolean or schema) and `type: "null"` (incl.
  *    inside `anyOf`) are kept.
+ *  - Boolean subschemas are object-coerced; MFJS has no exact `false` schema,
+ *    so both values become the permissive empty schema while local tool
+ *    validation remains authoritative.
  *
  * Out of scope (absent from the built-in tool surface, spec-ambiguous to
  * rewrite blindly): `allOf` intersection merging, external/recursive `$ref`,
@@ -73,6 +79,21 @@ export declare function normalizeSchemaForMoonshot(value: unknown): unknown;
  * cannot unmarshal into its object-shaped `Schema` struct.
  */
 export declare function sanitizeSchemaForOllama(schema: JsonObject): JsonObject;
+/**
+ * Rewrites the one JSON Schema form that grammar-constrained OpenAI-compatible
+ * backends (llama.cpp, LM Studio, vLLM) cannot compile to GBNF: a bare boolean
+ * subschema. `toolWireSchema` normalizes `{}` open subschemas to boolean `true`
+ * (issue #1179); llama.cpp's `json-schema-to-grammar.cpp` `visit()` has no case
+ * for a boolean schema and throws `Unrecognized schema: true` → HTTP 400 before
+ * the model is consulted (issue #5914).
+ *
+ * Narrower than {@link sanitizeSchemaForOllama}: only genuine subschema slots
+ * are widened. Boolean `additionalProperties`/`unevaluatedProperties` stay
+ * intact because the converter reads those as closed/open-object grammar
+ * semantics, and dropping `additionalProperties: false` would silently reopen
+ * every declared object.
+ */
+export declare function sanitizeSchemaForGrammar(schema: JsonObject): JsonObject;
 /**
  * OpenAI Responses rejects `oneOf` in tool schemas even when strict mode is
  * disabled, and rejects every schema node with `type: "object"` unless it has

package/dist/types/utils.d.ts

@@ -33,7 +33,8 @@ export declare function createOpenAIResponsesHistoryPayload(provider: string, it
 export declare function getOpenAIResponsesHistoryPayload(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): OpenAIResponsesHistoryPayload | undefined;
 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.
+ * Resolve cache retention preference: explicit request option first, then the
+ * `PI_CACHE_RETENTION` env override (`long` | `short` | `none`), then the
+ * provider-supplied fallback.
  */
-export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention, fallback?: CacheRetention): CacheRetention;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.0.3",
+	"version": "17.0.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.0.3",
-		"@oh-my-pi/pi-utils": "17.0.3",
-		"@oh-my-pi/pi-wire": "17.0.3",
+		"@oh-my-pi/pi-catalog": "17.0.5",
+		"@oh-my-pi/pi-utils": "17.0.5",
+		"@oh-my-pi/pi-wire": "17.0.5",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-storage.ts

@@ -73,6 +73,15 @@ function fingerprintOAuthBearer(bearer: string): string {
 	return createHash("sha256").update(bearer).digest("base64url");
 }
 const SESSION_STICKY_CACHE_PREFIX = "session:sticky:";
+/**
+ * Anthropic-only idle window after which a session's pinned credential no
+ * longer suppresses usage-based re-ranking. Anthropic caps OAuth prompt-cache
+ * retention at `ttl: "1h"` (ephemeral ~5min otherwise), so after this long
+ * without an Anthropic resolve the conversation-prefix cache is no longer
+ * guaranteed warm. Other providers retain indefinite stickiness until their
+ * own cache lifetimes are verified.
+ */
+const ANTHROPIC_SESSION_STICKY_CACHE_WARM_MS = 60 * 60_000;
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Credential Types
@@ -1137,7 +1146,10 @@ export class AuthStorage {
 	/** Tracks next credential index per provider:type key for round-robin distribution (non-session use). */
 	#providerRoundRobinIndex: Map<string, number> = new Map();
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
-	#sessionLastCredential: Map<string, Map<string, { type: AuthCredential["type"]; index: number }>> = new Map();
+	#sessionLastCredential: Map<
+		string,
+		Map<string, { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number }>
+	> = new Map();
 	/** Recent bearer fingerprints resolved for each durable OAuth row; used only for delayed usage-limit attribution. */
 	#oauthBearerFingerprints: Map<string, Map<number, string[]>> = new Map();
 	/** Maps provider:type -> credentialIndex -> blockedUntilMs for temporary backoff. */
@@ -1685,17 +1697,18 @@ export class AuthStorage {
 		index: number,
 	): void {
 		if (!sessionId) return;
+		const nowMs = Date.now();
 		const sessionMap = this.#sessionLastCredential.get(provider) ?? new Map();
-		sessionMap.set(sessionId, { type, index });
+		sessionMap.set(sessionId, { type, index, lastUsedAtMs: nowMs });
 		this.#sessionLastCredential.set(provider, sessionMap);
 
 		try {
 			const credentialId = this.#getStoredCredentials(provider)[index]?.id;
 			if (credentialId !== undefined) {
 				const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
-				const cacheValue = JSON.stringify({ type, index, credentialId });
+				const cacheValue = JSON.stringify({ type, index, credentialId, lastUsedAtMs: nowMs });
 				// Expires in 30 days
-				const expiresAtSec = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
+				const expiresAtSec = Math.floor(nowMs / 1000) + 30 * 24 * 60 * 60;
 				this.#store.setCache(cacheKey, cacheValue, expiresAtSec);
 			}
 		} catch (err) {
@@ -1707,7 +1720,7 @@ export class AuthStorage {
 	#getSessionCredential(
 		provider: string,
 		sessionId: string | undefined,
-	): { type: AuthCredential["type"]; index: number } | undefined {
+	): { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number } | undefined {
 		if (!sessionId) return undefined;
 		let sessionMap = this.#sessionLastCredential.get(provider);
 		if (sessionMap?.has(sessionId)) {
@@ -1717,7 +1730,12 @@ export class AuthStorage {
 			const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
 			const raw = this.#store.getCache(cacheKey);
 			if (raw) {
-				const val = JSON.parse(raw) as { type: AuthCredential["type"]; index: number; credentialId?: number };
+				const val = JSON.parse(raw) as {
+					type: AuthCredential["type"];
+					index: number;
+					credentialId?: number;
+					lastUsedAtMs?: number;
+				};
 
 				if (val.credentialId !== undefined) {
 					const stored = this.#getStoredCredentials(provider);
@@ -1737,7 +1755,7 @@ export class AuthStorage {
 					sessionMap = new Map();
 					this.#sessionLastCredential.set(provider, sessionMap);
 				}
-				const sessionVal = { type: val.type, index: val.index };
+				const sessionVal = { type: val.type, index: val.index, lastUsedAtMs: val.lastUsedAtMs };
 				sessionMap.set(sessionId, sessionVal);
 				return sessionVal;
 			}
@@ -3886,16 +3904,15 @@ export class AuthStorage {
 	 * how fast the window's remaining quota must be consumed to fully use it
 	 * before it resets and expires. Higher = more headroom at risk of expiring
 	 * unused = ranked first, so selection chases quota that is about to be
-	 * wasted ("use it or lose it"). Without a reset clock the headroom
-	 * fraction alone is returned, degrading to most-headroom-first.
+	 * wasted ("use it or lose it"). Without a reset clock, the full window
+	 * duration is assumed to remain so clocked and clockless scores stay comparable.
 	 */
 	#computeWindowRequiredDrain(limit: UsageLimit | undefined, nowMs: number, fallbackDurationMs: number): number {
 		const headroom = 1 - this.#normalizeUsageFraction(limit);
 		if (headroom <= 0) return 0;
 		const resetAt = this.#resolveWindowResetAt(limit?.window);
-		if (resetAt === undefined) return headroom;
 		const durationMs = limit?.window?.durationMs ?? fallbackDurationMs;
-		let remainingMs = resetAt - nowMs;
+		let remainingMs = resetAt === undefined ? durationMs : resetAt - nowMs;
 		if (Number.isFinite(durationMs) && durationMs > 0) {
 			remainingMs = Math.min(remainingMs, durationMs);
 		}
@@ -4135,16 +4152,39 @@ export class AuthStorage {
 			sessionPreferredCredential !== undefined &&
 			(sessionPreferredCredential.refresh.trim().length > 0 ||
 				Date.now() + OAUTH_REFRESH_SKEW_MS < sessionPreferredCredential.expires);
-		// Skip ranking only when the session already has a working preferred credential — re-ranking
-		// mid-session causes account switches that cold-start the server-side prompt cache. New sessions
-		// (no preference) and sessions whose preferred is blocked still rank, so we pick the account
-		// with the most headroom proactively and fall back intelligently when rate-limited.
+		// Skip ranking when the session already has a working preferred credential and its prompt
+		// cache may still be warm. Only Anthropic has a verified idle boundary here; unverified
+		// providers retain indefinite stickiness rather than risk switching while their prompt cache
+		// remains warm. New Anthropic sessions (no preference), sessions whose preferred is blocked,
+		// and sessions idle past {@link ANTHROPIC_SESSION_STICKY_CACHE_WARM_MS} still rank. Legacy
+		// pins predating `lastUsedAtMs` count as warm until the next resolve rewrites the row.
+		const sessionPreferredLastUsedAtMs =
+			sessionCredential?.type === "oauth" ? sessionCredential.lastUsedAtMs : undefined;
+		const sessionPreferredIsWarm =
+			provider !== "anthropic" ||
+			sessionPreferredLastUsedAtMs === undefined ||
+			Date.now() - sessionPreferredLastUsedAtMs < ANTHROPIC_SESSION_STICKY_CACHE_WARM_MS;
 		const sessionPreferredIsAvailable =
 			sessionPreferredIndex !== undefined &&
 			sessionPreferredCanRefreshOrUse &&
 			!this.#isCredentialBlocked(provider, providerKey, sessionPreferredIndex, blockScope);
-		const shouldRank = checkUsage && (!sessionPreferredIsAvailable || hasPlanRequirement);
-		const rankingOrder = shouldRank && sessionId ? credentials.map((_credential, index) => index) : order;
+		const shouldRank = checkUsage && (!sessionPreferredIsAvailable || !sessionPreferredIsWarm || hasPlanRequirement);
+		// When ranking, seed the pinned credential first in the evaluation order so it wins genuine
+		// ties (the ranked comparator falls back to `orderPos`) without overriding a strictly-better
+		// sibling — this respects the residual value of a same-account shared static prefix that other
+		// workspace traffic may have kept warm, while still rotating away from a clearly-worse account.
+		const baseRankingOrder = credentials.map((_credential, index) => index);
+		let rankingOrder = shouldRank && sessionId ? baseRankingOrder : order;
+		const sessionPreferredRankingPos =
+			shouldRank && sessionId && sessionPreferredIndex !== undefined && !hasPlanRequirement
+				? credentials.findIndex(entry => entry.index === sessionPreferredIndex)
+				: -1;
+		if (sessionPreferredRankingPos > 0) {
+			rankingOrder = [
+				sessionPreferredRankingPos,
+				...baseRankingOrder.filter(index => index !== sessionPreferredRankingPos),
+			];
+		}
 		const candidates = shouldRank
 			? await this.#rankOAuthSelections({
 					providerKey,
@@ -4162,7 +4202,10 @@ export class AuthStorage {
 					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
 					.map(selection => ({ selection, usage: null, usageChecked: false }));
 
-		if (sessionPreferredIndex !== undefined && !hasPlanRequirement) {
+		// On the warm skip path the candidate list follows the round-robin `order`, not the pin, so
+		// hoist the pinned credential to the front to actually reuse it. When ranking ran, the pin is
+		// already a mere tie-break via `rankingOrder`; do not override the ranked result here.
+		if (!shouldRank && sessionPreferredIndex !== undefined && !hasPlanRequirement) {
 			const sessionPreferredCandidate = candidates.findIndex(
 				candidate =>
 					!this.#isCredentialBlocked(provider, providerKey, candidate.selection.index, blockScope) &&
@@ -4249,6 +4292,29 @@ export class AuthStorage {
 			hasPlanRequirement &&
 			candidates.some(candidate => getOpenAICodexPlanEligibility(candidate.usage, planRequirement) === true);
 
+		// Plan-gated Codex models rank on every resolve to re-verify account tiers,
+		// so the drain-urgency order can flip between two eligible accounts as their
+		// usage headroom shifts. Promote the session-preferred credential back to the
+		// front while it is unblocked and still plan-eligible (or the requirement is
+		// unenforced and the pin is not known-ineligible) so an active session never
+		// silently migrates accounts mid-conversation; blocked, exhausted, or
+		// known-ineligible pins still fall through to the ranked sibling.
+		if (hasPlanRequirement && sessionPreferredIndex !== undefined) {
+			const sessionPreferredCandidate = candidates.findIndex(
+				candidate =>
+					!this.#isCredentialBlocked(provider, providerKey, candidate.selection.index, blockScope) &&
+					candidate.selection.index === sessionPreferredIndex,
+			);
+			if (sessionPreferredCandidate > 0) {
+				const preferred = candidates[sessionPreferredCandidate]!;
+				const planEligibility = getOpenAICodexPlanEligibility(preferred.usage, planRequirement);
+				if (planEligibility === true || (!enforcePlanRequirement && planEligibility !== false)) {
+					candidates.splice(sessionPreferredCandidate, 1);
+					candidates.unshift(preferred);
+				}
+			}
+		}
+
 		const passes: Array<{ allowBlocked: boolean; enforcePlanRequirement: boolean }> = [
 			{ allowBlocked: false, enforcePlanRequirement },
 			{ allowBlocked: true, enforcePlanRequirement },

package/src/providers/__tests__/kimi-code-thinking.test.ts

@@ -157,6 +157,53 @@ describe("Kimi K3 thinking transport", () => {
 		expect(payload).toMatchObject({ thinking: { type: "enabled", effort: Effort.Low } });
 		expect(payload).not.toMatchObject({ thinking: { type: "disabled" } });
 	});
+
+	it("downgrades named tool choice to required for K3 thinking", async () => {
+		vi.spyOn(kimiOauth, "getKimiCommonHeaders").mockReturnValue(KIMI_HEADERS);
+		const bundledModel = getBundledModel<"openai-completions">("kimi-code", "k3");
+		expect(bundledModel.compat.thinkingFormat).toBe("zai");
+		let payload: unknown;
+		const capturePayload = async (
+			model: Model<"openai-completions">,
+			toolChoice: "required" | { type: "tool"; name: string },
+			tools = TITLE_CONTEXT.tools,
+		) => {
+			const stream = streamKimi(
+				model,
+				{ ...TITLE_CONTEXT, tools },
+				{
+					apiKey: "test-key",
+					format: "openai",
+					reasoning: Effort.Max,
+					toolChoice,
+					onPayload: body => {
+						payload = body;
+						throw new Error("stop after payload capture");
+					},
+				},
+			);
+			await stream.result();
+		};
+
+		for (const model of [K3_MODEL, bundledModel]) {
+			await capturePayload(model, { type: "tool", name: "set_title" });
+			expect(payload).toMatchObject({
+				thinking: { type: "enabled" },
+				tool_choice: "required",
+				tools: [{ type: "function", function: { name: "set_title" } }],
+			});
+
+			await capturePayload(model, "required");
+			expect(payload).toMatchObject({
+				thinking: { type: "enabled" },
+				tool_choice: "required",
+				tools: [{ type: "function", function: { name: "set_title" } }],
+			});
+		}
+
+		await capturePayload(K3_MODEL, { type: "tool", name: "missing_tool" }, []);
+		expect((payload as { tool_choice?: unknown }).tool_choice).toBeUndefined();
+	});
 });
 
 describe("Kimi K2.7 Code thinking policy", () => {

package/src/providers/amazon-bedrock.ts

@@ -334,7 +334,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				toolConfig,
 				additionalModelRequestFields,
 			};
-			options?.onPayload?.(commandInput);
+			options?.onPayload?.(commandInput, model);
 
 			const host = `bedrock-runtime.${region}.amazonaws.com`;
 			const url = `https://${host}/model/${encodeURIComponent(model.id)}/converse-stream`;

package/src/providers/anthropic.ts

@@ -100,6 +100,8 @@ export type AnthropicHeaderOptions = {
 	isCloudflareAiGateway?: boolean;
 	claudeCodeSessionId?: string;
 	claudeCodeBetas?: readonly string[];
+	/** Allow explicit fingerprint headers to replace OAuth defaults on non-official endpoints. */
+	allowAnthropicHeaderOverrides?: boolean;
 };
 
 export function normalizeAnthropicBaseUrl(baseUrl?: string): string | undefined {
@@ -144,7 +146,8 @@ const claudeCodeAgentBetaDefaults = [
 	midConversationSystemBeta,
 	"advanced-tool-use-2025-11-20",
 ] as const;
-const claudeCodeAgentPostEffortBetas = ["extended-cache-ttl-2025-04-11"] as const;
+const extendedCacheTtlBeta = "extended-cache-ttl-2025-04-11";
+const claudeCodeAgentPostEffortBetas = [extendedCacheTtlBeta] as const;
 const fineGrainedToolStreamingBeta = "fine-grained-tool-streaming-2025-05-14";
 const interleavedThinkingBeta = "interleaved-thinking-2025-05-14";
 // Asks the API to redact thinking blocks from responses. Only sent when the
@@ -225,22 +228,36 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 	const acceptHeader = oauthToken ? "application/json" : stream ? "text/event-stream" : "application/json";
 	const isCloudflare = options.isCloudflareAiGateway ?? false;
 	const honorAuthorization = !oauthToken && !isCloudflare;
+	const allowAnthropicHeaderOverrides =
+		oauthToken &&
+		options.allowAnthropicHeaderOverrides === true &&
+		!isCloudflare &&
+		!isOfficialAnthropicApiUrl(options.baseUrl);
 	const honorApiKey = !isCloudflare;
 	const modelHeaders: Record<string, string> = {};
+	const anthropicHeaderOverrides: Record<string, string> = {};
 	const filteredEnforcedKeys: string[] = [];
-	for (const [key, value] of Object.entries(options.modelHeaders ?? {})) {
-		const lowerKey = key.toLowerCase();
-		if (enforcedHeaderKeys.has(lowerKey)) {
-			// user-agent is always re-applied explicitly. authorization / x-api-key
-			// are silently re-applied in honoring branches and dropped + logged
-			// where the branch enforces its own credential.
-			if (lowerKey === "user-agent") continue;
-			if (lowerKey === "authorization" && honorAuthorization) continue;
-			if (lowerKey === "x-api-key" && honorApiKey) continue;
-			filteredEnforcedKeys.push(key);
-			continue;
+	const headerSource = options.modelHeaders;
+	if (headerSource) {
+		for (const key in headerSource) {
+			const value = headerSource[key];
+			const lowerKey = key.toLowerCase();
+			if (enforcedHeaderKeys.has(lowerKey)) {
+				if (allowAnthropicHeaderOverrides && overridableAnthropicHeaderKeys.has(lowerKey)) {
+					anthropicHeaderOverrides[key] = value;
+					continue;
+				}
+				// user-agent is always re-applied explicitly. authorization / x-api-key
+				// are silently re-applied in honoring branches and dropped + logged
+				// where the branch enforces its own credential.
+				if (lowerKey === "user-agent") continue;
+				if (lowerKey === "authorization" && honorAuthorization) continue;
+				if (lowerKey === "x-api-key" && honorApiKey) continue;
+				filteredEnforcedKeys.push(key);
+				continue;
+			}
+			modelHeaders[key] = value;
 		}
-		modelHeaders[key] = value;
 	}
 	if (filteredEnforcedKeys.length > 0) {
 		// Caller/env-supplied values (options.headers, ANTHROPIC_CUSTOM_HEADERS)
@@ -266,7 +283,7 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 		const userAgent = isClaudeCodeClientUserAgent(incomingUserAgent)
 			? incomingUserAgent
 			: `claude-cli/${claudeCodeVersion} (external, local-agent, agent-sdk/${claudeAgentSdkVersion})`;
-		return {
+		const headers = {
 			...modelHeaders,
 			...claudeCodeHeaders,
 			Accept: acceptHeader,
@@ -278,6 +295,7 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 			"User-Agent": userAgent,
 			...(incomingApiKey ? { "X-Api-Key": incomingApiKey } : {}),
 		};
+		return allowAnthropicHeaderOverrides ? mergeHeaders(headers, anthropicHeaderOverrides) : headers;
 	} else if (!isOfficialAnthropicApiUrl(options.baseUrl)) {
 		return {
 			...modelHeaders,
@@ -424,7 +442,15 @@ function getCacheControl(
 	cacheRetention: CacheRetention | undefined,
 	isOAuthToken: boolean,
 ): { retention: CacheRetention; cacheControl?: AnthropicCacheControl } {
-	const retention = cacheRetention ?? (isOAuthToken ? "long" : resolveCacheRetention(undefined));
+	// OAuth mirrors Claude Code and always defaults to 1h retention. API-key
+	// requests also default to 1h where the endpoint supports it (canonical
+	// Anthropic API, `compat.supportsLongCacheRetention`): agent sessions
+	// routinely idle past 5 minutes waiting on background jobs, and a 5m
+	// breakpoint cold-misses the entire prefix on resume. PI_CACHE_RETENTION
+	// still overrides the API-key default in either direction.
+	const retention = isOAuthToken
+		? (cacheRetention ?? "long")
+		: resolveCacheRetention(cacheRetention, model.compat.supportsLongCacheRetention ? "long" : "short");
 	if (retention === "none") {
 		return { retention };
 	}
@@ -512,6 +538,10 @@ const enforcedHeaderKeys = new Set(
 	].map(key => key.toLowerCase()),
 );
 
+const overridableAnthropicHeaderKeys = new Set(
+	[...Object.keys(claudeCodeHeaders), "anthropic-beta", "User-Agent", "x-app"].map(key => key.toLowerCase()),
+);
+
 const CLAUDE_BILLING_HEADER_PREFIX = "x-anthropic-billing-header:";
 
 function createClaudeBillingHeader(firstUserMessageText: string): string {
@@ -1853,6 +1883,17 @@ const streamAnthropicOnce = (
 				) {
 					extraBetas.push(contextManagementBeta);
 				}
+				// `ttl: "1h"` requires the extended-cache-ttl beta on API-key
+				// requests. OAuth requests never add it here: agent requests
+				// already carry it in the Claude Code beta list, and utility
+				// requests must not deviate from CC's header fingerprint.
+				if (
+					!(options?.isOAuth ?? isAnthropicOAuthToken(apiKey)) &&
+					getCacheControl(model, options?.cacheRetention, false).cacheControl?.ttl === "1h" &&
+					!extraBetas.includes(extendedCacheTtlBeta)
+				) {
+					extraBetas.push(extendedCacheTtlBeta);
+				}
 				// Server-side fallback beta chain: opt-in via `options.fallbacks`.
 				// Nested overrides (`speed`, `output_config.effort`,
 				// `output_config.task_budget`) reuse the same top-level betas
@@ -2791,6 +2832,7 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 			dynamicHeaders,
 		),
 		isCloudflareAiGateway: model.provider === "cloudflare-ai-gateway",
+		allowAnthropicHeaderOverrides: model.compat.allowAnthropicHeaderOverrides,
 		claudeCodeSessionId,
 		claudeCodeBetas: oauthToken
 			? buildClaudeCodeBetas(

package/src/providers/cursor.ts

@@ -2868,7 +2868,7 @@ function buildGrpcRequest(
 		conversationId: state.conversationId,
 	});
 
-	options?.onPayload?.(runRequest);
+	options?.onPayload?.(runRequest, model);
 
 	// Tools are sent later via requestContext (exec handshake)
 

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

@@ -3913,7 +3913,8 @@ function redactHeaders(headers: Headers): Record<string, string> {
 	return redacted;
 }
 
-function resolveCodexResponsesUrl(baseUrl: string | undefined): string {
+/** Resolve a Codex Responses endpoint exactly as the chat and compaction transports do. */
+export function resolveCodexResponsesUrl(baseUrl: string | undefined): string {
 	const raw = baseUrl && baseUrl.trim().length > 0 ? baseUrl : CODEX_BASE_URL;
 	const normalized = raw.replace(/\/+$/, "");
 	if (normalized.endsWith("/codex/responses")) return normalized;

package/src/providers/openai-completions.ts

@@ -42,7 +42,13 @@ import {
 import { OpenAIHttpError, postOpenAIStream } from "../utils/openai-http";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { callWithCopilotModelRetry } from "../utils/retry";
-import { adaptSchemaForStrict, NO_STRICT, normalizeSchemaForMoonshot, toolWireSchema } from "../utils/schema";
+import {
+	adaptSchemaForStrict,
+	NO_STRICT,
+	normalizeSchemaForMoonshot,
+	sanitizeSchemaForGrammar,
+	toolWireSchema,
+} from "../utils/schema";
 import {
 	type HealedToolCall,
 	StreamMarkupHealing,
@@ -671,7 +677,7 @@ const streamOpenAICompletionsOnce = (
 				}
 				activeReasoningEffortFallbackKey = reasoningEffortFallbackKey;
 				activeRequestParams = params;
-				options?.onPayload?.(params);
+				options?.onPayload?.(params, model);
 				rawRequestDump = {
 					provider: model.provider,
 					api: output.api,
@@ -1431,6 +1437,20 @@ function dropOpenRouterKimiForcedToolReasoning(
 	}
 }
 
+function hasActiveNativeKimiK3Reasoning(
+	model: Model<"openai-completions">,
+	options: OpenAICompletionsOptions | undefined,
+): boolean {
+	if (model.provider !== "kimi-code" || model.id.toLowerCase() !== "k3" || !model.reasoning) return false;
+	if (options?.reasoning === undefined || options.disableReasoning) return false;
+	try {
+		const url = new URL(model.baseUrl);
+		return url.hostname === "api.kimi.com" && (url.pathname === "/coding" || url.pathname.startsWith("/coding/"));
+	} catch {
+		return false;
+	}
+}
+
 function buildParams(
 	model: Model<"openai-completions">,
 	context: Context,
@@ -1518,6 +1538,20 @@ function buildParams(
 	) {
 		params.tool_choice = "required";
 	}
+	const forcedToolName =
+		typeof params.tool_choice === "object" && params.tool_choice !== null && "function" in params.tool_choice
+			? params.tool_choice.function.name
+			: undefined;
+	if (
+		forcedToolName !== undefined &&
+		Array.isArray(params.tools) &&
+		params.tools.some(tool => tool.type === "function" && tool.function.name === forcedToolName) &&
+		hasActiveNativeKimiK3Reasoning(model, options)
+	) {
+		// Native K3 reasoning is incompatible with selecting a specific function.
+		// Preserve the hard tool-use contract while letting K3 choose among tools.
+		params.tool_choice = "required";
+	}
 	if (isForcedToolChoice(params.tool_choice) && !initialCompat.supportsForcedToolChoice) {
 		// Some thinking-required OpenAI-compatible models reject forced
 		// `tool_choice` while still accepting tools with the default auto
@@ -1537,10 +1571,6 @@ function buildParams(
 		delete params.tool_choice;
 	}
 
-	const forcedToolName =
-		typeof params.tool_choice === "object" && params.tool_choice !== null && "function" in params.tool_choice
-			? params.tool_choice.function.name
-			: undefined;
 	if (
 		forcedToolName !== undefined &&
 		(!Array.isArray(params.tools) ||
@@ -2205,10 +2235,16 @@ function convertTools(
 					description: tool.description || "",
 					// Moonshot/Kimi native hosts validate against the stricter MFJS subset
 					// (const→enum, typed enums, no validators) and 400 otherwise.
+					// Grammar-constrained local backends (llama.cpp, LM Studio, vLLM)
+					// build a GBNF grammar from the schema and 400 with
+					// `Unrecognized schema: true` on the bare boolean subschema
+					// `toolWireSchema` emits for open fields (issue #5914).
 					parameters:
 						compat.toolSchemaFlavor === "moonshot-mfjs"
 							? (normalizeSchemaForMoonshot(wireParameters) as Record<string, unknown>)
-							: wireParameters,
+							: compat.toolSchemaFlavor === "grammar"
+								? sanitizeSchemaForGrammar(wireParameters)
+								: wireParameters,
 					// Only include strict if provider supports it. Some reject unknown fields.
 					...(includeStrict ? { strict: true } : includeExplicitFalse ? { strict: false } : {}),
 				},