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

package/src/providers/openai-responses.ts

@@ -1,3 +1,4 @@
+import { scheduler } from "node:timers/promises";
 import { hostMatchesUrl } from "@oh-my-pi/pi-catalog/hosts";
 import { $flag, logger, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import * as AIError from "../error";
@@ -155,6 +156,33 @@ const OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE =
 	"OpenAI responses stream timed out while waiting for the first event";
 /** Consecutive stale-previous-response failures before chaining is disabled for the session. */
 const OPENAI_RESPONSES_CHAIN_STALE_FAILURE_LIMIT = 3;
+const OPENAI_RESPONSES_MAX_TRANSIENT_STREAM_RETRIES = 1;
+const OPENAI_RESPONSES_TRANSIENT_STREAM_RETRY_DELAY_MS = 500;
+
+function isOpenAIResponsesReplayUnsafeEvent(event: ResponseStreamEvent): boolean {
+	switch (event.type) {
+		case "response.output_text.delta":
+		case "response.refusal.delta":
+		case "response.reasoning_summary_text.delta":
+		case "response.reasoning_text.delta":
+		case "response.function_call_arguments.delta":
+		case "response.custom_tool_call_input.delta":
+			return typeof event.delta === "string" && event.delta.length > 0;
+		case "response.reasoning_summary_part.done":
+			return true;
+		case "response.output_item.done":
+			return true;
+		default:
+			return false;
+	}
+}
+
+function isRetryableOpenAIResponsesStreamFailure(error: unknown): boolean {
+	return (
+		AIError.isTransientStreamParseError(error) ||
+		(error instanceof AIError.ProviderResponseError && error.kind === "incomplete-stream")
+	);
+}
 
 interface OpenAIResponsesProviderSessionState
 	extends ProviderSessionState,
@@ -453,7 +481,7 @@ const streamOpenAIResponsesOnce = (
 				return payload;
 			};
 			chained = { ...chained, params: await applyPayloadReplacement(chained.params) };
-			rawRequestDump = {
+			const activeRawRequestDump: RawHttpRequestDump = {
 				provider: model.provider,
 				api: output.api,
 				model: model.id,
@@ -461,6 +489,7 @@ const streamOpenAIResponsesOnce = (
 				url: requestUrl,
 				body: chained.params,
 			};
+			rawRequestDump = activeRawRequestDump;
 			const openResponsesStream = (requestParams: OpenAIResponsesSamplingParams) => {
 				activeReasoningEffortFallbackKey = createOpenAIReasoningEffortFallbackKey(
 					"responses",
@@ -508,187 +537,257 @@ const streamOpenAIResponsesOnce = (
 					{ provider: model.provider, signal: requestSignal },
 				);
 			};
-			let openaiStream: AsyncIterable<ResponseStreamEvent>;
 			let strictRetryAvailable = true;
 			let activeStrictToolsApplied = builtParams.strictToolsApplied;
 			let forceDisableStrictTools = false;
-			while (true) {
-				try {
-					openaiStream = await openResponsesStream(chained.params);
-					if (pendingReasoningEffortFallback) {
-						rememberOpenAIReasoningEffortFallback(
-							providerSessionState,
-							pendingReasoningEffortFallback.key,
-							pendingReasoningEffortFallback.fallback,
-						);
-						pendingReasoningEffortFallback = undefined;
-					}
-					break;
-				} catch (error) {
-					const capturedErrorResponse = error instanceof OpenAIHttpError ? error.captured : undefined;
-					const reasoningEffortFallback =
-						activeReasoningEffortFallbackKey && activeRequestParams && !requestSignal.aborted
-							? resolveOpenAIReasoningEffortFallback(error, capturedErrorResponse, activeRequestParams, {
-									explicitDisable: options?.disableReasoning === true && options.reasoning === undefined,
-								})
-							: undefined;
-					if (reasoningEffortFallback !== undefined && activeReasoningEffortFallbackKey) {
-						const retryMarker = `${activeReasoningEffortFallbackKey}:${String(reasoningEffortFallback)}`;
-						if (attemptedReasoningEffortFallbacks.has(retryMarker)) throw error;
-						attemptedReasoningEffortFallbacks.add(retryMarker);
-						requestReasoningEffortFallbacks.set(activeReasoningEffortFallbackKey, reasoningEffortFallback);
-						applyOpenAIReasoningEffortFallback(chained.params, reasoningEffortFallback);
-						applyOpenAIReasoningEffortFallback(activeParams, reasoningEffortFallback);
-						rawRequestDump.body = chained.params;
-						pendingReasoningEffortFallback = {
-							key: activeReasoningEffortFallbackKey,
-							fallback: reasoningEffortFallback,
-						};
-						continue;
-					}
-					const compiledGrammarTooLarge =
-						isOpenRouterAnthropicModel(model) &&
-						isCompiledGrammarTooLargeStrictError(error, capturedErrorResponse);
-					const canRetryWithoutStrictTools =
-						strictRetryAvailable &&
-						!requestSignal.aborted &&
-						(compiledGrammarTooLarge ||
-							shouldRetryWithoutStrictTools(
-								error,
-								capturedErrorResponse,
-								activeStrictToolsApplied,
-								context.tools,
-							));
-					if (canRetryWithoutStrictTools) {
-						strictRetryAvailable = false;
-						forceDisableStrictTools = true;
-						disableStrictToolsForScope(providerSessionState, strictToolsScope);
-						const fallbackBuilt = buildParams(
+			const openResponsesStreamWithFallbacks = async (): Promise<AsyncIterable<ResponseStreamEvent>> => {
+				let openaiStream: AsyncIterable<ResponseStreamEvent>;
+				while (true) {
+					try {
+						openaiStream = await openResponsesStream(chained.params);
+						if (pendingReasoningEffortFallback) {
+							rememberOpenAIReasoningEffortFallback(
+								providerSessionState,
+								pendingReasoningEffortFallback.key,
+								pendingReasoningEffortFallback.fallback,
+							);
+							pendingReasoningEffortFallback = undefined;
+						}
+						break;
+					} catch (error) {
+						const capturedErrorResponse = error instanceof OpenAIHttpError ? error.captured : undefined;
+						const reasoningEffortFallback =
+							activeReasoningEffortFallbackKey && activeRequestParams && !requestSignal.aborted
+								? resolveOpenAIReasoningEffortFallback(error, capturedErrorResponse, activeRequestParams, {
+										explicitDisable: options?.disableReasoning === true && options.reasoning === undefined,
+									})
+								: undefined;
+						if (reasoningEffortFallback !== undefined && activeReasoningEffortFallbackKey) {
+							const retryMarker = `${activeReasoningEffortFallbackKey}:${String(reasoningEffortFallback)}`;
+							if (attemptedReasoningEffortFallbacks.has(retryMarker)) throw error;
+							attemptedReasoningEffortFallbacks.add(retryMarker);
+							requestReasoningEffortFallbacks.set(activeReasoningEffortFallbackKey, reasoningEffortFallback);
+							applyOpenAIReasoningEffortFallback(chained.params, reasoningEffortFallback);
+							applyOpenAIReasoningEffortFallback(activeParams, reasoningEffortFallback);
+							activeRawRequestDump.body = chained.params;
+							pendingReasoningEffortFallback = {
+								key: activeReasoningEffortFallbackKey,
+								fallback: reasoningEffortFallback,
+							};
+							continue;
+						}
+						const compiledGrammarTooLarge =
+							isOpenRouterAnthropicModel(model) &&
+							isCompiledGrammarTooLargeStrictError(error, capturedErrorResponse);
+						const canRetryWithoutStrictTools =
+							strictRetryAvailable &&
+							!requestSignal.aborted &&
+							(compiledGrammarTooLarge ||
+								shouldRetryWithoutStrictTools(
+									error,
+									capturedErrorResponse,
+									activeStrictToolsApplied,
+									context.tools,
+								));
+						if (canRetryWithoutStrictTools) {
+							strictRetryAvailable = false;
+							forceDisableStrictTools = true;
+							disableStrictToolsForScope(providerSessionState, strictToolsScope);
+							const fallbackBuilt = buildParams(
+								model,
+								context,
+								options,
+								providerSessionState,
+								strictToolsScope,
+								true,
+							);
+							const fallbackParams = fallbackBuilt.params;
+							if (chainState && !chainState.disabled) fallbackParams.store = true;
+							let fallbackChained: OpenAIResponsesChainedParams =
+								chainState && !chainState.disabled
+									? buildOpenAIResponsesChainedParams(fallbackParams, chainState)
+									: { params: fallbackParams };
+							sentPreviousResponseId = fallbackChained.previousResponseId;
+							fallbackChained = {
+								...fallbackChained,
+								params: await applyPayloadReplacement(fallbackChained.params),
+							};
+							chained = fallbackChained;
+							activeRawRequestDump.body = chained.params;
+							activeParams = fallbackParams;
+							activeStrictToolsApplied = fallbackBuilt.strictToolsApplied;
+							continue;
+						}
+						if (!chainState || !sentPreviousResponseId || requestSignal.aborted) {
+							throw error;
+						}
+						const zdrRejection =
+							error instanceof Error &&
+							/previous[ _]?response/i.test(error.message) &&
+							/zero[ _-]?data[ _-]?retention/i.test(error.message);
+						const isPromptBlocked =
+							error instanceof Error &&
+							((error as { code?: string }).code === "invalid_prompt" ||
+								/invalid_prompt|Request blocked/i.test(error.message));
+						if (!zdrRejection && !isPromptBlocked && !isOpenAIResponsesStalePreviousResponseError(error)) {
+							throw error;
+						}
+						// Server rejected the chain baseline: reset, count the failure (or
+						// disable categorically on ZDR), and retry once with the full
+						// transcript. Structurally cannot loop — the retry carries no
+						// previous_response_id.
+						if (zdrRejection) {
+							markOpenAIResponsesChainZeroDataRetention(chainState, error);
+							// ZDR orgs cannot store responses; the retry uses `store: false`.
+						} else {
+							registerOpenAIResponsesChainStaleFailure(chainState, error);
+						}
+						sentPreviousResponseId = undefined;
+						const currentBuilt = buildParams(
 							model,
 							context,
 							options,
 							providerSessionState,
 							strictToolsScope,
-							true,
+							forceDisableStrictTools,
 						);
-						const fallbackParams = fallbackBuilt.params;
-						if (chainState && !chainState.disabled) fallbackParams.store = true;
-						let fallbackChained: OpenAIResponsesChainedParams =
-							chainState && !chainState.disabled
-								? buildOpenAIResponsesChainedParams(fallbackParams, chainState)
-								: { params: fallbackParams };
-						sentPreviousResponseId = fallbackChained.previousResponseId;
-						fallbackChained = {
-							...fallbackChained,
-							params: await applyPayloadReplacement(fallbackChained.params),
-						};
-						chained = fallbackChained;
-						rawRequestDump.body = chained.params;
-						activeParams = fallbackParams;
-						activeStrictToolsApplied = fallbackBuilt.strictToolsApplied;
-						continue;
-					}
-					if (!chainState || !sentPreviousResponseId || requestSignal.aborted) {
-						throw error;
+						const currentParams = currentBuilt.params;
+						// Only ZDR forces `store: false` (the org never persists responses). A
+						// non-ZDR stale baseline is transient, so keep storing: the full-context
+						// retry must be chainable next turn, and the consecutive stale-failure
+						// breaker only trips when each retry stores and the next turn re-chains.
+						currentParams.store = !zdrRejection;
+						const retryParams = await applyPayloadReplacement(currentParams);
+						chained = { params: retryParams };
+						activeRawRequestDump.body = retryParams;
+						activeParams = currentParams;
+						activeStrictToolsApplied = currentBuilt.strictToolsApplied;
 					}
-					const zdrRejection =
-						error instanceof Error &&
-						/previous[ _]?response/i.test(error.message) &&
-						/zero[ _-]?data[ _-]?retention/i.test(error.message);
-					const isPromptBlocked =
-						error instanceof Error &&
-						((error as { code?: string }).code === "invalid_prompt" ||
-							/invalid_prompt|Request blocked/i.test(error.message));
-					if (!zdrRejection && !isPromptBlocked && !isOpenAIResponsesStalePreviousResponseError(error)) {
-						throw error;
-					}
-					// Server rejected the chain baseline: reset, count the failure (or
-					// disable categorically on ZDR), and retry once with the full
-					// transcript. Structurally cannot loop — the retry carries no
-					// previous_response_id.
-					if (zdrRejection) {
-						markOpenAIResponsesChainZeroDataRetention(chainState, error);
-						// ZDR orgs cannot store responses; the retry uses `store: false`.
-					} else {
-						registerOpenAIResponsesChainStaleFailure(chainState, error);
-					}
-					sentPreviousResponseId = undefined;
-					const currentBuilt = buildParams(
-						model,
-						context,
-						options,
-						providerSessionState,
-						strictToolsScope,
-						forceDisableStrictTools,
-					);
-					const currentParams = currentBuilt.params;
-					// Only ZDR forces `store: false` (the org never persists responses). A
-					// non-ZDR stale baseline is transient, so keep storing: the full-context
-					// retry must be chainable next turn, and the consecutive stale-failure
-					// breaker only trips when each retry stores and the next turn re-chains.
-					currentParams.store = !zdrRejection;
-					const retryParams = await applyPayloadReplacement(currentParams);
-					chained = { params: retryParams };
-					rawRequestDump.body = retryParams;
-					activeParams = currentParams;
-					activeStrictToolsApplied = currentBuilt.strictToolsApplied;
 				}
-			}
+				return openaiStream;
+			};
+			let openaiStream = await openResponsesStreamWithFallbacks();
 			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
 			stream.push({ type: "start", partial: output });
 
 			const nativeOutputItems: Array<Record<string, unknown>> = [];
-			let sawTerminalResponseEvent = false;
-			const timedOpenaiStream = iterateWithIdleTimeout(openaiStream, {
-				idleTimeoutMs,
-				firstItemTimeoutMs: firstEventTimeoutMs,
-				firstItemErrorMessage: OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE,
-				errorMessage: "OpenAI responses stream stalled while waiting for the next event",
-				onFirstItemTimeout: () => abortTracker.abortLocally(firstEventTimeoutAbortError),
-				onIdle: () => requestAbortController.abort(),
-				abortSignal: options?.signal,
-				isProgressItem: isOpenAIResponsesProgressEvent,
-			});
-			await processResponsesStream(timedOpenaiStream, output, stream, model, {
-				onFirstToken: () => {
-					if (!firstTokenTime) firstTokenTime = performance.now();
-				},
-				onOutputItemDone: item => {
-					// `processResponsesStream` hands over a private clone already; no
-					// second deep copy needed (reasoning items carry multi-KB blobs).
-					nativeOutputItems.push(item as unknown as Record<string, unknown>);
-				},
-				onCompleted: () => {
-					sawTerminalResponseEvent = true;
-				},
-				requestServiceTier: options?.serviceTier,
-			});
+			let transientStreamRetryAttempt = 0;
+			while (true) {
+				let sawReplayUnsafeOutput = false;
+				let sawTerminalResponseEvent = false;
+				const attemptStream = new AssistantMessageEventStream();
+				let forwardAttemptLive = false;
+				const forwardAttemptEvents = () => {
+					for (const event of attemptStream.queue) stream.push(event);
+					attemptStream.queue.length = 0;
+				};
+				nativeOutputItems.length = 0;
+				const timedOpenaiStream = iterateWithIdleTimeout(openaiStream, {
+					idleTimeoutMs,
+					firstItemTimeoutMs: firstEventTimeoutMs,
+					firstItemErrorMessage: OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE,
+					errorMessage: "OpenAI responses stream stalled while waiting for the next event",
+					onFirstItemTimeout: () => abortTracker.abortLocally(firstEventTimeoutAbortError),
+					onIdle: () => requestAbortController.abort(),
+					abortSignal: options?.signal,
+					isProgressItem: isOpenAIResponsesProgressEvent,
+				});
+				const observedOpenaiStream = (async function* (): AsyncGenerator<ResponseStreamEvent> {
+					for await (const event of timedOpenaiStream) {
+						if (isOpenAIResponsesReplayUnsafeEvent(event)) {
+							sawReplayUnsafeOutput = true;
+							if (!forwardAttemptLive) {
+								forwardAttemptEvents();
+								forwardAttemptLive = true;
+							}
+						}
+						yield event;
+						if (forwardAttemptLive) forwardAttemptEvents();
+					}
+				})();
 
-			const localAbortReason = abortTracker.getLocalAbortReason();
-			if (localAbortReason) {
-				throw localAbortReason;
-			}
-			if (abortTracker.wasCallerAbort()) {
-				throw new AIError.AbortError();
-			}
+				try {
+					await processResponsesStream(observedOpenaiStream, output, attemptStream, model, {
+						onFirstToken: () => {
+							if (!firstTokenTime) firstTokenTime = performance.now();
+						},
+						onOutputItemDone: item => {
+							// `processResponsesStream` hands over a private clone already; no
+							// second deep copy needed (reasoning items carry multi-KB blobs).
+							nativeOutputItems.push(item as unknown as Record<string, unknown>);
+						},
+						onCompleted: () => {
+							sawTerminalResponseEvent = true;
+						},
+						requestServiceTier: options?.serviceTier,
+					});
 
-			// Detect premature stream closure: the HTTP stream ended without the
-			// provider sending a recognized terminal response event.
-			// Custom/proxy providers may drop the connection mid-stream; without
-			// this guard the incomplete output is silently surfaced as a successful
-			// "stop".
-			if (!sawTerminalResponseEvent) {
-				throw new AIError.ProviderResponseError(
-					"OpenAI responses stream closed before a terminal response event was received",
-					{ provider: model.provider, kind: "incomplete-stream" },
-				);
-			}
+					const localAbortReason = abortTracker.getLocalAbortReason();
+					if (localAbortReason) throw localAbortReason;
+					if (abortTracker.wasCallerAbort()) throw new AIError.AbortError();
 
-			if (output.stopReason === "aborted" || output.stopReason === "error") {
-				throw new AIError.ProviderResponseError(output.errorMessage ?? "An unknown error occurred", {
-					provider: model.provider,
-					kind: "runtime",
-				});
+					// Detect premature stream closure: the HTTP stream ended without the
+					// provider sending a recognized terminal response event.
+					if (!sawTerminalResponseEvent) {
+						throw new AIError.ProviderResponseError(
+							"OpenAI responses stream closed before a terminal response event was received",
+							{ provider: model.provider, kind: "incomplete-stream" },
+						);
+					}
+
+					if (output.stopReason === "aborted" || output.stopReason === "error") {
+						throw new AIError.ProviderResponseError(output.errorMessage ?? "An unknown error occurred", {
+							provider: model.provider,
+							kind: "runtime",
+						});
+					}
+					forwardAttemptEvents();
+					break;
+				} catch (error) {
+					const streamFailure = abortTracker.getLocalAbortReason() ?? error;
+					const canRetry =
+						!sawReplayUnsafeOutput &&
+						!requestSignal.aborted &&
+						!abortTracker.wasCallerAbort() &&
+						transientStreamRetryAttempt < OPENAI_RESPONSES_MAX_TRANSIENT_STREAM_RETRIES &&
+						isRetryableOpenAIResponsesStreamFailure(streamFailure);
+					if (!canRetry) {
+						forwardAttemptEvents();
+						throw streamFailure;
+					}
+
+					transientStreamRetryAttempt++;
+					logger.debug("OpenAI responses stream ended before replay-unsafe output; retrying", {
+						provider: model.provider,
+						model: model.id,
+						attempt: transientStreamRetryAttempt,
+						error: streamFailure instanceof Error ? streamFailure.message : String(streamFailure),
+					});
+					const retryOutput = createInitialResponsesAssistantMessage(model.api, model.provider, model.id);
+					output.content.length = 0;
+					output.responseId = undefined;
+					output.upstreamProvider = undefined;
+					output.errorMessage = undefined;
+					output.errorStatus = undefined;
+					output.errorId = undefined;
+					output.stopDetails = undefined;
+					output.providerPayload = undefined;
+					output.usage = retryOutput.usage;
+					if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
+					output.stopReason = "stop";
+					output.duration = undefined;
+					output.ttft = undefined;
+					firstTokenTime = undefined;
+					nativeOutputItems.length = 0;
+
+					if (options?.providerRetryWait) {
+						await options.providerRetryWait(OPENAI_RESPONSES_TRANSIENT_STREAM_RETRY_DELAY_MS, options.signal);
+					} else {
+						await scheduler.wait(OPENAI_RESPONSES_TRANSIENT_STREAM_RETRY_DELAY_MS, { signal: options?.signal });
+					}
+					if (abortTracker.wasCallerAbort()) throw new AIError.AbortError();
+					openaiStream = await openResponsesStreamWithFallbacks();
+				}
 			}
 
 			output.providerPayload = createOpenAIResponsesHistoryPayload(model.provider, nativeOutputItems);

package/src/registry/api-key-login.ts

@@ -31,7 +31,7 @@ type AnthropicMessagesValidation = {
 type ModelsEndpointValidation = {
 	kind: "models-endpoint";
 	provider: string;
-	modelsUrl: string;
+	modelsUrl: string | (() => string);
 	headers?: Record<string, string> | (() => Record<string, string> | undefined);
 };
 
@@ -99,7 +99,10 @@ export function createApiKeyLogin(config: ApiKeyLoginConfig): (options: OAuthCon
 				await validateApiKeyAgainstModelsEndpoint({
 					provider: config.validation.provider,
 					apiKey: trimmed,
-					modelsUrl: config.validation.modelsUrl,
+					modelsUrl:
+						typeof config.validation.modelsUrl === "function"
+							? config.validation.modelsUrl()
+							: config.validation.modelsUrl,
 					headers: config.validation.headers,
 					signal: options.signal,
 					fetch: options.fetch,

package/src/registry/moonshot.ts

@@ -1,7 +1,13 @@
+import { $env } from "@oh-my-pi/pi-utils";
 import { createApiKeyLogin } from "./api-key-login";
 import type { OAuthLoginCallbacks } from "./oauth/types";
 import type { ProviderDefinition } from "./types";
 
+function resolveMoonshotModelsUrl(): string {
+	const baseUrl = $env.MOONSHOT_BASE_URL?.trim() || "https://api.moonshot.ai/v1";
+	return `${baseUrl.replace(/\/+$/, "")}/models`;
+}
+
 export const loginMoonshot = createApiKeyLogin({
 	providerLabel: "Moonshot",
 	authUrl: "https://platform.moonshot.ai/console/api-keys",
@@ -11,7 +17,7 @@ export const loginMoonshot = createApiKeyLogin({
 	validation: {
 		kind: "models-endpoint",
 		provider: "moonshot",
-		modelsUrl: "https://api.moonshot.ai/v1/models",
+		modelsUrl: resolveMoonshotModelsUrl,
 	},
 });
 

package/src/utils/schema/normalize.ts

@@ -1133,18 +1133,19 @@ const OLLAMA_SCHEMA_VALUE_KEYS = new Set([
 ]);
 
 /**
- * Widened stand-in for a `true` / `{}` subschema in an Ollama-bound tool.
+ * Widened stand-in for a `true` / `{}` open subschema on a tool bound for a
+ * backend whose wire cannot encode a bare boolean subschema.
  *
  * `toolWireSchema()` normalizes empty schemas to boolean `true` upstream so
- * grammar-constrained samplers (llama.cpp, etc.) don't treat `{}` as
- * "generate an empty object" (issue #1179). Ollama's Go tool parser can't
- * unmarshal a boolean into its object-shaped `Schema` struct, so this
- * sanitizer replaces every open subschema with an explicit union of every
- * primitive JSON type. Both invariants survive: the wire has no boolean
- * subschema (Go accepts it), and llama.cpp's grammar sees a real value
- * union rather than a closed empty object.
+ * grammar-constrained samplers don't treat `{}` as "generate an empty object"
+ * (issue #1179). Two backends then choke on the bare boolean: Ollama's Go tool
+ * parser can't unmarshal it into its object-shaped `Schema` struct, and
+ * llama.cpp's JSON-schema→GBNF converter has no case for a boolean schema
+ * (issue #5914). Both sanitizers replace the open subschema with an explicit
+ * union of every primitive JSON type — the wire has no boolean subschema, and
+ * a grammar sampler sees a real value union rather than a closed empty object.
  */
-const OLLAMA_OPEN_SUBSCHEMA_WIDENING = Object.freeze({
+const OPEN_SUBSCHEMA_WIDENING = Object.freeze({
 	anyOf: [
 		{ type: "string" },
 		{ type: "number" },
@@ -1161,8 +1162,8 @@ const OLLAMA_OPEN_SUBSCHEMA_WIDENING = Object.freeze({
  */
 export function sanitizeSchemaForOllama(schema: JsonObject): JsonObject {
 	const normalizeNode = (value: unknown): unknown => {
-		if (value === true) return OLLAMA_OPEN_SUBSCHEMA_WIDENING;
-		if (value === false) return { not: OLLAMA_OPEN_SUBSCHEMA_WIDENING };
+		if (value === true) return OPEN_SUBSCHEMA_WIDENING;
+		if (value === false) return { not: OPEN_SUBSCHEMA_WIDENING };
 		if (!isJsonObject(value)) {
 			if (!Array.isArray(value)) return value;
 			let changed = false;
@@ -1235,6 +1236,97 @@ export function sanitizeSchemaForOllama(schema: JsonObject): JsonObject {
 	return normalizeNode(schema) as JsonObject;
 }
 
+/**
+ * Schema-valued keywords whose bare boolean value must be widened for a
+ * grammar-constrained backend. Excludes `additionalProperties` and
+ * `unevaluatedProperties`: llama.cpp's `_build_object_rule` reads their boolean
+ * form as meaningful closed/open-object semantics, and `additionalProperties:
+ * false` is exactly what `toolWireSchema` emits to pin a strict object shape.
+ */
+const GRAMMAR_SCHEMA_VALUE_KEYS: Record<string, true> = {
+	items: true,
+	additionalItems: true,
+	contains: true,
+	contentSchema: true,
+	propertyNames: true,
+	if: true,
+	// biome-ignore lint/suspicious/noThenProperty: JSON Schema keyword
+	then: true,
+	else: true,
+	not: true,
+	unevaluatedItems: true,
+};
+
+/**
+ * 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 function sanitizeSchemaForGrammar(schema: JsonObject): JsonObject {
+	const normalizeNode = (value: unknown, isSubschema: boolean): unknown => {
+		if (value === true) return isSubschema ? OPEN_SUBSCHEMA_WIDENING : value;
+		if (value === false) return isSubschema ? { not: OPEN_SUBSCHEMA_WIDENING } : value;
+		if (Array.isArray(value)) {
+			let changed = false;
+			const output = value.map(item => {
+				const next = normalizeNode(item, isSubschema);
+				if (next !== item) changed = true;
+				return next;
+			});
+			return changed ? output : value;
+		}
+		if (!isJsonObject(value)) return value;
+
+		let changed = false;
+		const output: JsonObject = {};
+		for (const key in value) {
+			if (!Object.hasOwn(value, key)) continue;
+			const child = value[key];
+			let next = child;
+			if (Object.hasOwn(SUBSCHEMA_MAP_KEYS, key) && isJsonObject(child)) {
+				let mapChanged = false;
+				const mapOutput: JsonObject = {};
+				for (const childKey in child) {
+					if (!Object.hasOwn(child, childKey)) continue;
+					const mapChild = child[childKey];
+					const normalizedChild = normalizeNode(mapChild, true);
+					if (normalizedChild !== mapChild) mapChanged = true;
+					mapOutput[childKey] = normalizedChild;
+				}
+				next = mapChanged ? mapOutput : child;
+			} else if (Object.hasOwn(SUBSCHEMA_ARRAY_KEYS, key) && Array.isArray(child)) {
+				let arrayChanged = false;
+				const arrayOutput = child.map(item => {
+					const normalizedItem = normalizeNode(item, true);
+					if (normalizedItem !== item) arrayChanged = true;
+					return normalizedItem;
+				});
+				next = arrayChanged ? arrayOutput : child;
+			} else if (Object.hasOwn(GRAMMAR_SCHEMA_VALUE_KEYS, key)) {
+				next = normalizeNode(child, true);
+			} else if ((key === "additionalProperties" || key === "unevaluatedProperties") && typeof child !== "boolean") {
+				// Boolean form is meaningful closed/open-object grammar semantics and
+				// stays intact; the object form is a genuine subschema whose interior
+				// may still hold bare booleans emitted by `toolWireSchema`.
+				next = normalizeNode(child, true);
+			}
+			if (next !== child) changed = true;
+			output[key] = next;
+		}
+		return changed ? output : value;
+	};
+	return normalizeNode(schema, true) as JsonObject;
+}
+
 // ---------------------------------------------------------------------------
 // OpenAI Responses — schema-valued normalization
 // ---------------------------------------------------------------------------