@oh-my-pi/pi-ai 16.1.0 → 16.1.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [16.1.2] - 2026-06-19
+
+### Added
+
+- Added improved JSON repair capabilities for Anthropic tool arguments
+- Added authentication broker discovery to sync credentials between local SQLite and remote state
+
+### Fixed
+
+- Improved error feedback and transparency for malformed Anthropic tool call arguments
+- Added automatic fallback for unsupported OpenAI reasoning effort levels
+- Improved reliability when handling invalid reasoning parameter errors across OpenAI-compatible APIs
+- Fixed OpenAI-compatible Chat Completions, Responses, and Azure Responses requests to retry once with the nearest provider-supported reasoning effort when an endpoint rejects `xhigh`/`minimal`-style effort values.
+
 ## [16.1.0] - 2026-06-19
 
 ### Added
@@ -3920,4 +3934,4 @@ _Dedicated to Peter's shoulder ([@steipete](https://twitter.com/steipete))_
 
 ## [0.9.4] - 2025-11-26
 
-Initial release with multi-provider LLM support.
+Initial release with multi-provider LLM support.

package/dist/types/auth-broker/discover.d.ts

@@ -0,0 +1,35 @@
+import { AuthStorage } from "../auth-storage";
+export interface AuthBrokerClientConfig {
+    url: string;
+    token: string;
+}
+export interface ResolveAuthBrokerConfigOptions {
+    agentDir?: string;
+    configValueResolver?: (config: string) => Promise<string | undefined>;
+}
+export interface DiscoverAuthStorageOptions {
+    agentDir?: string;
+    configValueResolver?: (config: string) => Promise<string | undefined>;
+    cachePath?: string;
+    sourceLabel?: string;
+}
+/** Path to the local bearer token file. Created by `omp auth-broker token`. */
+export declare function getAuthBrokerTokenFilePath(): string;
+/**
+ * Resolve broker connection configuration using the same precedence as the TUI:
+ *
+ * 1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
+ * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml`.
+ * 3. `<config-root>/auth-broker.token` file (paired with a URL from env/config).
+ *
+ * Returns `null` when no broker URL is configured — callers should fall back to
+ * the local SQLite store. Throws when a URL is configured but no token is
+ * available, matching the TUI behavior.
+ */
+export declare function resolveAuthBrokerConfig(options?: ResolveAuthBrokerConfigOptions): Promise<AuthBrokerClientConfig | null>;
+/**
+ * Create an AuthStorage instance, using the broker when configured and falling
+ * back to the local SQLite store otherwise. This is the single source of truth
+ * for the TUI and the catalog generator.
+ */
+export declare function discoverAuthStorage(options?: DiscoverAuthStorageOptions): Promise<AuthStorage>;

package/dist/types/auth-broker/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./client";
+export * from "./discover";
 export * from "./refresher";
 export * from "./remote-store";
 export * from "./server";

package/dist/types/providers/openai-reasoning-fallback.d.ts

@@ -0,0 +1,25 @@
+import type { CapturedHttpErrorResponse } from "../utils/http-inspector";
+/** @internal */
+export type OpenAIReasoningEffortFallback = string | null;
+/** @internal */
+export interface OpenAIReasoningEffortFallbackState {
+    reasoningEffortFallbacks: Map<string, OpenAIReasoningEffortFallback>;
+}
+/** @internal */
+export declare function createOpenAIReasoningEffortFallbackState(): OpenAIReasoningEffortFallbackState;
+/** @internal */
+export declare function clearOpenAIReasoningEffortFallbackState(state: OpenAIReasoningEffortFallbackState): void;
+/** @internal */
+export declare function getOpenAIReasoningEffortFallback(state: OpenAIReasoningEffortFallbackState | undefined, key: string): OpenAIReasoningEffortFallback | undefined;
+/** @internal */
+export declare function rememberOpenAIReasoningEffortFallback(state: OpenAIReasoningEffortFallbackState | undefined, key: string, fallback: OpenAIReasoningEffortFallback): void;
+/** @internal */
+export declare function createOpenAIReasoningEffortFallbackKey(endpoint: "chat-completions" | "responses" | "azure-responses", baseUrl: string | undefined, wireModelId: string | undefined): string;
+/** @internal */
+export declare function readOpenAIReasoningEffort(params: unknown): string | undefined;
+/** @internal */
+export declare function applyOpenAIReasoningEffortFallback(params: unknown, fallback: OpenAIReasoningEffortFallback): boolean;
+/** @internal */
+export declare function resolveOpenAIReasoningEffortFallback(error: unknown, captured: CapturedHttpErrorResponse | undefined, params: unknown, options?: {
+    explicitDisable?: boolean;
+}): OpenAIReasoningEffortFallback | undefined;

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

@@ -1,5 +1,6 @@
 import type { Context, Model, OpenAICompat, ProviderSessionState, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types";
 import { type OpenAIResponsesToolChoice } from "../utils/tool-choice";
+import { type OpenAIReasoningEffortFallbackState } from "./openai-reasoning-fallback";
 import type { Tool as OpenAITool, ResponseCreateParamsStreaming, ResponseInput } from "./openai-responses-wire";
 import { type OpenAIStrictToolsScope, type OpenAIStrictToolsState } from "./openai-shared";
 export interface OpenAIResponsesOptions extends StreamOptions {
@@ -55,7 +56,7 @@ export interface OpenAIResponsesOptions extends StreamOptions {
      */
     extraBody?: Record<string, unknown>;
 }
-interface OpenAIResponsesProviderSessionState extends ProviderSessionState, OpenAIStrictToolsState {
+interface OpenAIResponsesProviderSessionState extends ProviderSessionState, OpenAIStrictToolsState, OpenAIReasoningEffortFallbackState {
     nativeHistoryReplayWarmed: boolean;
     /** Stateful `previous_response_id` chain baselines, keyed by baseUrl/model/session. */
     chains: Map<string, OpenAIResponsesChainState>;

package/dist/types/types.d.ts

@@ -549,8 +549,8 @@ export interface Tool<TParameters extends TSchema = TSchema> {
      * Illustrative calls/notes; the AI layer renders them into an `<examples>`
      * block in the model's native tool-call syntax and appends to the wire
      * description. Author `call`/`bad`/`good` as plain argument objects WITHOUT
-     * `_i` — when intent tracing injects `_i` into the schema, the renderer adds
-     * a placeholder `_i` automatically. Type each tool's `examples` against its
+     * `i` — when intent tracing injects `i` into the schema, the renderer adds
+     * a placeholder `i` automatically. Type each tool's `examples` against its
      * own schema (e.g. `readonly ToolExample<typeof schema["type"]>[]`).
      */
     examples?: readonly ToolExample[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.1.0",
+	"version": "16.1.2",
 	"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.0",
-		"@oh-my-pi/pi-catalog": "16.1.0",
-		"@oh-my-pi/pi-utils": "16.1.0",
-		"@oh-my-pi/pi-wire": "16.1.0",
+		"@oh-my-pi/pi-catalog": "16.1.2",
+		"@oh-my-pi/pi-utils": "16.1.2",
+		"@oh-my-pi/pi-wire": "16.1.2",
 		"arktype": "^2.2.0",
 		"partial-json": "^0.1.7",
 		"zod": "^4"

package/src/auth-broker/discover.ts

@@ -0,0 +1,217 @@
+/**
+ * Broker-aware auth-storage discovery used by both the coding-agent runtime and
+ * the catalog model generator. Keeps the precedence logic (env → config.yml →
+ * token file → local SQLite) in one place so build-time tooling sees the same
+ * credentials as the TUI.
+ */
+import * as path from "node:path";
+import {
+	getAgentDbPath,
+	getAgentDir,
+	getAuthBrokerSnapshotCachePath,
+	getConfigRootDir,
+	isEnoent,
+	logger,
+} from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import { AuthStorage } from "../auth-storage";
+import { AuthBrokerClient } from "./client";
+import { RemoteAuthCredentialStore } from "./remote-store";
+import { readAuthBrokerSnapshotCache, writeAuthBrokerSnapshotCache } from "./snapshot-cache";
+import { DEFAULT_SNAPSHOT_CACHE_TTL_MS, type SnapshotResponse } from "./types";
+
+export interface AuthBrokerClientConfig {
+	url: string;
+	token: string;
+}
+
+export interface ResolveAuthBrokerConfigOptions {
+	agentDir?: string;
+	configValueResolver?: (config: string) => Promise<string | undefined>;
+}
+
+export interface DiscoverAuthStorageOptions {
+	agentDir?: string;
+	configValueResolver?: (config: string) => Promise<string | undefined>;
+	cachePath?: string;
+	sourceLabel?: string;
+}
+
+/** Path to the local bearer token file. Created by `omp auth-broker token`. */
+export function getAuthBrokerTokenFilePath(): string {
+	return path.join(getConfigRootDir(), "auth-broker.token");
+}
+
+/**
+ * Default resolver for config values: checks `process.env` first, then treats
+ * the value as a literal. Does NOT execute `!command` syntax; such values are
+ * left unresolved so the caller can fall back to the token file.
+ */
+async function defaultResolveConfigValue(config: string): Promise<string | undefined> {
+	if (config.startsWith("!")) return undefined;
+	const envValue = process.env[config];
+	return envValue || config;
+}
+
+async function readTokenFile(): Promise<string | null> {
+	try {
+		const raw = await Bun.file(getAuthBrokerTokenFilePath()).text();
+		const trimmed = raw.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch (err) {
+		if (isEnoent(err)) return null;
+		logger.warn("auth-broker token file unreadable", { error: String(err) });
+		return null;
+	}
+}
+
+interface ConfigSnapshot {
+	url?: string;
+	token?: string;
+}
+
+async function readConfigYaml(agentDir: string): Promise<ConfigSnapshot> {
+	const configPath = path.join(agentDir, "config.yml");
+	try {
+		const raw = await Bun.file(configPath).text();
+		const parsed = YAML.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		const record = parsed as Record<string, unknown>;
+		const url = typeof record["auth.broker.url"] === "string" ? (record["auth.broker.url"] as string) : undefined;
+		const token =
+			typeof record["auth.broker.token"] === "string" ? (record["auth.broker.token"] as string) : undefined;
+		return { url, token };
+	} catch (err) {
+		if (isEnoent(err)) return {};
+		logger.warn("auth-broker config.yml unreadable", { error: String(err) });
+		return {};
+	}
+}
+
+function resolveSnapshotTtlMs(): number {
+	const raw = process.env.OMP_AUTH_BROKER_SNAPSHOT_TTL_MS;
+	if (raw === undefined) return DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+	const value = raw.trim();
+	if (value === "") return DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+	const ttlMs = Number(value);
+	if (Number.isFinite(ttlMs) && ttlMs >= 0) return ttlMs;
+	logger.warn("Invalid OMP_AUTH_BROKER_SNAPSHOT_TTL_MS; using default", { value: raw });
+	return DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+}
+
+/**
+ * Resolve broker connection configuration using the same precedence as the TUI:
+ *
+ * 1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
+ * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml`.
+ * 3. `<config-root>/auth-broker.token` file (paired with a URL from env/config).
+ *
+ * Returns `null` when no broker URL is configured — callers should fall back to
+ * the local SQLite store. Throws when a URL is configured but no token is
+ * available, matching the TUI behavior.
+ */
+export async function resolveAuthBrokerConfig(
+	options: ResolveAuthBrokerConfigOptions = {},
+): Promise<AuthBrokerClientConfig | null> {
+	const agentDir = options.agentDir ?? getAgentDir();
+	const resolveConfig = options.configValueResolver ?? defaultResolveConfigValue;
+
+	const envUrl = process.env.OMP_AUTH_BROKER_URL;
+	const envToken = process.env.OMP_AUTH_BROKER_TOKEN;
+
+	let url = envUrl && envUrl.length > 0 ? envUrl : undefined;
+	let configToken: string | undefined;
+	if (!url || !envToken) {
+		const fromConfig = await readConfigYaml(agentDir);
+		if (!url && fromConfig.url) {
+			const resolved = await resolveConfig(fromConfig.url);
+			if (resolved && resolved.length > 0) url = resolved;
+		}
+		if (fromConfig.token) {
+			const resolved = await resolveConfig(fromConfig.token);
+			if (resolved && resolved.length > 0) configToken = resolved;
+		}
+	}
+	if (!url) return null;
+
+	const token =
+		(envToken && envToken.length > 0 ? envToken : undefined) ?? configToken ?? (await readTokenFile()) ?? undefined;
+	if (!token) {
+		throw new Error(
+			`OMP_AUTH_BROKER_URL is set (${url}) but no bearer token is available. ` +
+				`Set OMP_AUTH_BROKER_TOKEN, the \`auth.broker.token\` config entry, or place one at ${getAuthBrokerTokenFilePath()}.`,
+		);
+	}
+	return { url, token };
+}
+
+/**
+ * Create an AuthStorage instance, using the broker when configured and falling
+ * back to the local SQLite store otherwise. This is the single source of truth
+ * for the TUI and the catalog generator.
+ */
+export async function discoverAuthStorage(options: DiscoverAuthStorageOptions = {}): Promise<AuthStorage> {
+	const agentDir = options.agentDir ?? getAgentDir();
+	const brokerConfig = await resolveAuthBrokerConfig({
+		agentDir,
+		configValueResolver: options.configValueResolver,
+	});
+
+	if (brokerConfig) {
+		const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
+		const cachePath = options.cachePath ?? getAuthBrokerSnapshotCachePath();
+		const ttlMs = resolveSnapshotTtlMs();
+		const persist =
+			ttlMs > 0
+				? (snapshot: SnapshotResponse): void => {
+						void writeAuthBrokerSnapshotCache({
+							path: cachePath,
+							token: brokerConfig.token,
+							url: brokerConfig.url,
+							snapshot,
+						}).catch(error => {
+							logger.debug("auth-broker snapshot cache write failed", { error: String(error) });
+						});
+					}
+				: undefined;
+
+		let initialSnapshot: SnapshotResponse | undefined;
+		if (ttlMs > 0) {
+			initialSnapshot =
+				(await readAuthBrokerSnapshotCache({
+					path: cachePath,
+					token: brokerConfig.token,
+					url: brokerConfig.url,
+					ttlMs,
+				}).catch(error => {
+					logger.debug("auth-broker snapshot cache read failed", { error: String(error) });
+					return null;
+				})) ?? undefined;
+		}
+		if (!initialSnapshot) {
+			const initialResult = await client.fetchSnapshot();
+			if (initialResult.status !== 200) throw new Error("Auth broker returned no initial snapshot");
+			initialSnapshot = initialResult.snapshot;
+			persist?.(initialSnapshot);
+		}
+		const store = new RemoteAuthCredentialStore({
+			client,
+			initialSnapshot,
+			onSnapshot: persist,
+		});
+		const storage = new AuthStorage(store, {
+			configValueResolver: options.configValueResolver,
+			sourceLabel: options.sourceLabel ?? `broker ${brokerConfig.url}`,
+		});
+		await storage.reload();
+		return storage;
+	}
+
+	const dbPath = getAgentDbPath(agentDir);
+	const storage = await AuthStorage.create(dbPath, {
+		configValueResolver: options.configValueResolver,
+		sourceLabel: options.sourceLabel ?? `local ${dbPath}`,
+	});
+	await storage.reload();
+	return storage;
+}

package/src/auth-broker/index.ts

@@ -1,4 +1,5 @@
 export * from "./client";
+export * from "./discover";
 export * from "./refresher";
 export * from "./remote-store";
 export * from "./server";

package/src/dialect/examples.ts

@@ -9,7 +9,7 @@ export function renderToolExamples(tool: InbandTool, dialect: Dialect, intentFie
 	if (!examples?.length) return "";
 	const definition = getDialectDefinition(dialect);
 	const renderCall = (args: Record<string, unknown>): string => {
-		// When intent tracing injects `_i` into the schema, examples must show a
+		// When intent tracing injects `i` into the schema, examples must show a
 		// placeholder so the model learns to emit it. Keep it first, matching the
 		// schema injection order.
 		const finalArgs = intentField ? { [intentField]: INTENT_PLACEHOLDER, ...args } : args;

package/src/dialect/pi.md

@@ -23,7 +23,7 @@ Call with a verbatim body — everything between `«` and `»` is taken literall
 
 Argument values:
 
-- Strings are written bare and verbatim (`path=src/a.ts`). Quote with `"…"` only when the value contains spaces or starts with `"`, `[`, or `{` (`_i="run the tests"`).
+- Strings are written bare and verbatim (`path=src/a.ts`). Quote with `"…"` only when the value contains spaces or starts with `"`, `[`, or `{` (`i="run the tests"`).
 - Numbers, booleans, and `null` are JSON literals (`offset=50`, `force=true`).
 - Arrays and objects are inline JSON (`paths=["src","test"]`).
 - The body fence holds the call's first long/multi-line string parameter; its key is implied, never written.

package/src/providers/anthropic.ts

@@ -50,7 +50,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { isFoundryEnabled } from "../utils/foundry";
 import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
 import { getStreamFirstEventTimeoutMs, getStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
-import { parseStreamingJsonThrottled } from "../utils/json-parse";
+import { parseJsonWithRepair, parseStreamingJsonThrottled } from "../utils/json-parse";
 import { notifyProviderResponse } from "../utils/provider-response";
 import { isCopilotTransientModelError } from "../utils/retry";
 import { COMBINATOR_KEYS, NO_STRICT, toolWireSchema } from "../utils/schema";
@@ -1752,14 +1752,25 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					const finalJson =
 						block.partialJson.length > 0 ? block.partialJson : JSON.stringify(block.arguments ?? {});
 					try {
-						block.arguments = JSON.parse(finalJson) as ToolCall["arguments"];
+						block.arguments = parseJsonWithRepair(finalJson) as ToolCall["arguments"];
 					} catch (parseError) {
 						// Non-fatal: keep the best-effort arguments recovered by the throttled streaming
 						// parser instead of failing the turn on malformed/truncated tool-argument JSON.
 						reportAnthropicEnvelopeAnomaly(
 							`tool_use ${block.id} arguments are not valid JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
 						);
-						block.arguments = (block.arguments ?? {}) as ToolCall["arguments"];
+						const recoveredKeys = Object.keys(block.arguments ?? {});
+						if (recoveredKeys.length === 0) {
+							const maxLen = 512;
+							const truncatedJson =
+								finalJson.length <= maxLen
+									? finalJson
+									: `${finalJson.slice(0, maxLen)}… [truncated ${finalJson.length - maxLen} chars]`;
+							block.arguments = {
+								__parseError: parseError instanceof Error ? parseError.message : String(parseError),
+								__rawJson: truncatedJson,
+							};
+						}
 					}
 					delete (block as { partialJson?: string }).partialJson;
 					delete (block as { lastParseLen?: number }).lastParseLen;

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

@@ -18,9 +18,15 @@ import {
 	getOpenAIStreamIdleTimeoutMs,
 	iterateWithIdleTimeout,
 } from "../utils/idle-iterator";
-import { postOpenAIStream } from "../utils/openai-http";
+import { OpenAIHttpError, postOpenAIStream } from "../utils/openai-http";
 import { sanitizeSchemaForOpenAIResponses, toolWireSchema } from "../utils/schema";
 import { mapToOpenAIResponsesToolChoice } from "../utils/tool-choice";
+import {
+	applyOpenAIReasoningEffortFallback,
+	createOpenAIReasoningEffortFallbackKey,
+	type OpenAIReasoningEffortFallback,
+	resolveOpenAIReasoningEffortFallback,
+} from "./openai-reasoning-fallback";
 import type { ResponseCreateParamsStreaming, ResponseStreamEvent } from "./openai-responses-wire";
 import {
 	applyCommonResponsesSamplingParams,
@@ -135,29 +141,52 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 				url,
 				body: params,
 			};
-			let requestTimeout: NodeJS.Timeout | undefined;
-			if (requestTimeoutMs !== undefined) {
-				requestTimeout = setTimeout(() => abortTracker.abortLocally(firstEventTimeoutAbortError), requestTimeoutMs);
-			}
+			const reasoningEffortFallbackKey = createOpenAIReasoningEffortFallbackKey(
+				"azure-responses",
+				url,
+				typeof params.model === "string" ? params.model : model.id,
+			);
+			const attemptedReasoningEffortFallbacks = new Set<string>();
 			let openaiStream: AsyncIterable<ResponseStreamEvent>;
-			try {
-				const headersWithTimeout = { ...headers };
+			while (true) {
+				let requestTimeout: NodeJS.Timeout | undefined;
 				if (requestTimeoutMs !== undefined) {
-					headersWithTimeout["X-Stainless-Timeout"] = Math.floor(requestTimeoutMs / 1000).toString();
+					requestTimeout = setTimeout(
+						() => abortTracker.abortLocally(firstEventTimeoutAbortError),
+						requestTimeoutMs,
+					);
+				}
+				try {
+					const headersWithTimeout = { ...headers };
+					if (requestTimeoutMs !== undefined) {
+						headersWithTimeout["X-Stainless-Timeout"] = Math.floor(requestTimeoutMs / 1000).toString();
+					}
+					const handle = await postOpenAIStream<ResponseStreamEvent>({
+						url,
+						headers: headersWithTimeout,
+						body: params,
+						signal: requestSignal,
+						fetch: options?.fetch,
+						// Watchdog armed → no retries, so they cannot silently extend the deadline.
+						maxAttempts: requestTimeoutMs !== undefined ? 1 : undefined,
+						onSseEvent: rawSseObserver,
+					});
+					openaiStream = handle.events;
+					break;
+				} catch (error) {
+					const capturedErrorResponse = error instanceof OpenAIHttpError ? error.captured : undefined;
+					const reasoningEffortFallback: OpenAIReasoningEffortFallback | undefined = !requestSignal.aborted
+						? resolveOpenAIReasoningEffortFallback(error, capturedErrorResponse, params)
+						: undefined;
+					if (reasoningEffortFallback === undefined) throw error;
+					const retryMarker = `${reasoningEffortFallbackKey}:${String(reasoningEffortFallback)}`;
+					if (attemptedReasoningEffortFallbacks.has(retryMarker)) throw error;
+					attemptedReasoningEffortFallbacks.add(retryMarker);
+					applyOpenAIReasoningEffortFallback(params, reasoningEffortFallback);
+					rawRequestDump.body = params;
+				} finally {
+					if (requestTimeout !== undefined) clearTimeout(requestTimeout);
 				}
-				const handle = await postOpenAIStream<ResponseStreamEvent>({
-					url,
-					headers: headersWithTimeout,
-					body: params,
-					signal: requestSignal,
-					fetch: options?.fetch,
-					// Watchdog armed → no retries, so they cannot silently extend the deadline.
-					maxAttempts: requestTimeoutMs !== undefined ? 1 : undefined,
-					onSseEvent: rawSseObserver,
-				});
-				openaiStream = handle.events;
-			} finally {
-				if (requestTimeout !== undefined) clearTimeout(requestTimeout);
 			}
 			stream.push({ type: "start", partial: output });
 

package/src/providers/openai-completions.ts

@@ -56,6 +56,17 @@ import type {
 	ChatCompletionTool,
 	ChatCompletionToolMessageParam,
 } from "./openai-chat-wire";
+import {
+	applyOpenAIReasoningEffortFallback,
+	clearOpenAIReasoningEffortFallbackState,
+	createOpenAIReasoningEffortFallbackKey,
+	createOpenAIReasoningEffortFallbackState,
+	getOpenAIReasoningEffortFallback,
+	type OpenAIReasoningEffortFallback,
+	type OpenAIReasoningEffortFallbackState,
+	rememberOpenAIReasoningEffortFallback,
+	resolveOpenAIReasoningEffortFallback,
+} from "./openai-reasoning-fallback";
 import {
 	applyChatCompletionsCompatPolicy,
 	applyChatCompletionsToolStream,
@@ -444,14 +455,19 @@ type BuiltOpenAICompletionTools = {
 
 const OPENAI_COMPLETIONS_PROVIDER_SESSION_STATE_PREFIX = "openai-completions:";
 
-type OpenAICompletionsProviderSessionState = ProviderSessionState & OpenAIStrictToolsState;
+type OpenAICompletionsProviderSessionState = ProviderSessionState &
+	OpenAIStrictToolsState &
+	OpenAIReasoningEffortFallbackState;
 
 function createOpenAICompletionsProviderSessionState(): OpenAICompletionsProviderSessionState {
 	const strictToolsState = createOpenAIStrictToolsState();
+	const reasoningEffortFallbackState = createOpenAIReasoningEffortFallbackState();
 	const state: OpenAICompletionsProviderSessionState = {
 		...strictToolsState,
+		...reasoningEffortFallbackState,
 		close: () => {
 			clearOpenAIStrictToolsState(state);
+			clearOpenAIReasoningEffortFallbackState(state);
 		},
 	};
 	return state;
@@ -581,6 +597,10 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			let appliedStrictTools = false;
+			const requestReasoningEffortFallbacks = new Map<string, OpenAIReasoningEffortFallback>();
+			const attemptedReasoningEffortFallbacks = new Set<string>();
+			let activeReasoningEffortFallbackKey: string | undefined;
+			let activeRequestParams: OpenAICompletionsParams | undefined;
 			const providerSessionState = getOpenAICompletionsProviderSessionState(
 				model,
 				baseUrl,
@@ -601,6 +621,19 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					effectiveToolStrictModeOverride,
 				);
 				appliedStrictTools = strictToolsApplied;
+				const reasoningEffortFallbackKey = createOpenAIReasoningEffortFallbackKey(
+					"chat-completions",
+					trimmedBaseUrl,
+					params.model,
+				);
+				const requestReasoningEffortFallback = requestReasoningEffortFallbacks.has(reasoningEffortFallbackKey)
+					? requestReasoningEffortFallbacks.get(reasoningEffortFallbackKey)
+					: getOpenAIReasoningEffortFallback(providerSessionState, reasoningEffortFallbackKey);
+				if (requestReasoningEffortFallback !== undefined) {
+					applyOpenAIReasoningEffortFallback(params, requestReasoningEffortFallback);
+				}
+				activeReasoningEffortFallbackKey = reasoningEffortFallbackKey;
+				activeRequestParams = params;
 				options?.onPayload?.(params);
 				rawRequestDump = {
 					provider: model.provider,
@@ -650,7 +683,24 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				});
 			} catch (error) {
 				const capturedErrorResponse = error instanceof OpenAIHttpError ? error.captured : undefined;
-				if (
+				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);
+					openaiStream = await createCompletionsStream();
+					rememberOpenAIReasoningEffortFallback(
+						providerSessionState,
+						activeReasoningEffortFallbackKey,
+						reasoningEffortFallback,
+					);
+				} else if (
 					isOpenRouterAnthropicModel(model) &&
 					!disableStrictTools &&
 					isCompiledGrammarTooLargeStrictError(error, capturedErrorResponse)

package/src/providers/openai-reasoning-fallback.ts

@@ -0,0 +1,269 @@
+import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
+import type { CapturedHttpErrorResponse } from "../utils/http-inspector";
+
+/** @internal */
+export type OpenAIReasoningEffortFallback = string | null;
+
+/** @internal */
+export interface OpenAIReasoningEffortFallbackState {
+	reasoningEffortFallbacks: Map<string, OpenAIReasoningEffortFallback>;
+}
+
+const ENABLED_REASONING_VALUES = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const KNOWN_REASONING_VALUE: Readonly<Record<string, true>> = {
+	none: true,
+	minimal: true,
+	low: true,
+	medium: true,
+	high: true,
+	xhigh: true,
+	max: true,
+};
+const REASONING_VALUE_RANK: Readonly<Record<string, number>> = {
+	minimal: 0,
+	low: 1,
+	medium: 2,
+	high: 3,
+	xhigh: 4,
+	max: 5,
+};
+
+/** @internal */
+export function createOpenAIReasoningEffortFallbackState(): OpenAIReasoningEffortFallbackState {
+	return { reasoningEffortFallbacks: new Map() };
+}
+
+/** @internal */
+export function clearOpenAIReasoningEffortFallbackState(state: OpenAIReasoningEffortFallbackState): void {
+	state.reasoningEffortFallbacks.clear();
+}
+
+/** @internal */
+export function getOpenAIReasoningEffortFallback(
+	state: OpenAIReasoningEffortFallbackState | undefined,
+	key: string,
+): OpenAIReasoningEffortFallback | undefined {
+	return state?.reasoningEffortFallbacks.get(key);
+}
+
+/** @internal */
+export function rememberOpenAIReasoningEffortFallback(
+	state: OpenAIReasoningEffortFallbackState | undefined,
+	key: string,
+	fallback: OpenAIReasoningEffortFallback,
+): void {
+	state?.reasoningEffortFallbacks.set(key, fallback);
+}
+
+/** @internal */
+export function createOpenAIReasoningEffortFallbackKey(
+	endpoint: "chat-completions" | "responses" | "azure-responses",
+	baseUrl: string | undefined,
+	wireModelId: string | undefined,
+): string {
+	return `${endpoint}:${baseUrl ?? ""}:${wireModelId ?? ""}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @internal */
+export function readOpenAIReasoningEffort(params: unknown): string | undefined {
+	if (!isRecord(params)) return undefined;
+	if (typeof params.reasoning_effort === "string") return params.reasoning_effort;
+	const reasoning = params.reasoning;
+	return isRecord(reasoning) && typeof reasoning.effort === "string" ? reasoning.effort : undefined;
+}
+
+function deleteReasoningEffort(reasoning: Record<string, unknown>, parent: Record<string, unknown>): boolean {
+	if (typeof reasoning.effort !== "string") return false;
+	delete reasoning.effort;
+	for (const key in reasoning) {
+		if (key !== "effort") return true;
+	}
+	delete parent.reasoning;
+	return true;
+}
+
+/** @internal */
+export function applyOpenAIReasoningEffortFallback(params: unknown, fallback: OpenAIReasoningEffortFallback): boolean {
+	if (!isRecord(params)) return false;
+	let changed = false;
+	if (typeof params.reasoning_effort === "string") {
+		if (fallback === null) {
+			delete params.reasoning_effort;
+		} else {
+			params.reasoning_effort = fallback;
+		}
+		changed = true;
+	}
+	const reasoning = params.reasoning;
+	if (isRecord(reasoning) && typeof reasoning.effort === "string") {
+		if (fallback === null) {
+			changed = deleteReasoningEffort(reasoning, params) || changed;
+		} else {
+			reasoning.effort = fallback;
+			changed = true;
+		}
+	}
+	return changed;
+}
+
+function capturedStringField(
+	captured: CapturedHttpErrorResponse | undefined,
+	field: "code" | "message" | "param" | "type",
+) {
+	const body = isRecord(captured?.bodyJson) ? captured.bodyJson : undefined;
+	const error = isRecord(body?.error) ? body.error : undefined;
+	if (typeof error?.[field] === "string") return error[field];
+	return typeof body?.[field] === "string" ? body[field] : undefined;
+}
+
+function collectMessageParts(error: unknown, captured: CapturedHttpErrorResponse | undefined): string {
+	const parts = [
+		error instanceof Error ? error.message : undefined,
+		capturedStringField(captured, "message"),
+		capturedStringField(captured, "param"),
+		capturedStringField(captured, "code"),
+		capturedStringField(captured, "type"),
+		captured?.bodyText,
+	].filter((value): value is string => typeof value === "string" && value.trim().length > 0);
+	return parts.join("\n");
+}
+
+const REASONING_EFFORT_FIELD_PATTERN = /reasoning[_. ]effort|reasoning value/i;
+
+function mentionsReasoningEffort(error: unknown, captured: CapturedHttpErrorResponse | undefined): boolean {
+	const param = capturedStringField(captured, "param");
+	const code = capturedStringField(captured, "code");
+	const type = capturedStringField(captured, "type");
+	const message = collectMessageParts(error, captured);
+	return (
+		REASONING_EFFORT_FIELD_PATTERN.test(param ?? "") ||
+		REASONING_EFFORT_FIELD_PATTERN.test(code ?? "") ||
+		REASONING_EFFORT_FIELD_PATTERN.test(type ?? "") ||
+		REASONING_EFFORT_FIELD_PATTERN.test(message)
+	);
+}
+
+function isInvalidReasoningEffortError(
+	error: unknown,
+	captured: CapturedHttpErrorResponse | undefined,
+	currentEffort: string,
+): boolean {
+	const status = extractHttpStatusFromError(error) ?? captured?.status;
+	if (status !== 400 && status !== 422) return false;
+	if (!mentionsReasoningEffort(error, captured)) return false;
+	const message = collectMessageParts(error, captured);
+	if (/reasoning[_ ]content/i.test(message) && !REASONING_EFFORT_FIELD_PATTERN.test(message)) return false;
+	if (/invalid[^\n]*(?:reasoning[_. ]effort|reasoning value)/i.test(message)) return true;
+	if (
+		/(?:reasoning[_. ]effort|reasoning value)[^\n]*(?:invalid|unsupported|not supported|must be|expected)/i.test(
+			message,
+		)
+	) {
+		return true;
+	}
+	if (/(?:unsupported|not supported)[^\n]*(?:reasoning[_. ]effort|reasoning value)/i.test(message)) {
+		return true;
+	}
+	return new RegExp(
+		`(?:invalid|unsupported|not supported)[^\\n]*["'\`]${escapeRegExp(currentEffort)}["'\`]`,
+		"i",
+	).test(message);
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseKnownReasoningValues(text: string): Set<string> {
+	const values = new Set<string>();
+	const quotedPattern = /["'`](none|minimal|low|medium|high|xhigh|max)["'`]/gi;
+	let quotedMatch = quotedPattern.exec(text);
+	while (quotedMatch !== null) {
+		values.add(quotedMatch[1]!.toLowerCase());
+		quotedMatch = quotedPattern.exec(text);
+	}
+	const allowedMatch = /(?:must be|one of|allowed values?|supported values?(?: are)?|expected)([^.\n]+)/i.exec(text);
+	if (allowedMatch) {
+		const allowedText = allowedMatch[1]!;
+		const barePattern = /\b(none|minimal|low|medium|high|xhigh|max)\b/gi;
+		let bareMatch = barePattern.exec(allowedText);
+		while (bareMatch !== null) {
+			values.add(bareMatch[1]!.toLowerCase());
+			bareMatch = barePattern.exec(allowedText);
+		}
+	}
+	return values;
+}
+
+function parseAllowedReasoningValues(message: string, currentEffort: string): Set<string> | undefined {
+	const values = parseKnownReasoningValues(message);
+	const hasAllowedCue = /must be|one of|allowed values?|supported values?|expected/i.test(message);
+	values.delete(currentEffort.toLowerCase());
+	if (!hasAllowedCue && values.size === 0) return undefined;
+	return values;
+}
+
+function orderedEnabledAllowedValues(allowed: Set<string>): string[] {
+	return ENABLED_REASONING_VALUES.filter(value => allowed.has(value));
+}
+
+function lowestEnabledAllowedValue(allowed: Set<string>): string | undefined {
+	for (const value of ENABLED_REASONING_VALUES) {
+		if (allowed.has(value)) return value;
+	}
+	return undefined;
+}
+
+function nearestEnabledReasoningFallback(currentEffort: string, allowed: Set<string>): string | undefined {
+	const current = currentEffort.toLowerCase();
+	const allowedEnabled = orderedEnabledAllowedValues(allowed);
+	if (allowedEnabled.length === 0) return undefined;
+	if (current === "minimal" && allowedEnabled.includes("low")) return "low";
+	if (current === "xhigh" && allowedEnabled.includes("max")) return "max";
+	if (current === "xhigh" && allowedEnabled.includes("high")) return "high";
+	if (current === "max" && allowedEnabled.includes("xhigh")) return "xhigh";
+	const currentRank = REASONING_VALUE_RANK[current];
+	if (currentRank === undefined) return undefined;
+	let best: string | undefined;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	let bestRank = Number.NEGATIVE_INFINITY;
+	for (const candidate of allowedEnabled) {
+		if (candidate === current) continue;
+		const candidateRank = REASONING_VALUE_RANK[candidate];
+		if (candidateRank === undefined) continue;
+		const distance = Math.abs(candidateRank - currentRank);
+		if (distance < bestDistance || (distance === bestDistance && candidateRank > bestRank)) {
+			best = candidate;
+			bestDistance = distance;
+			bestRank = candidateRank;
+		}
+	}
+	return best;
+}
+
+/** @internal */
+export function resolveOpenAIReasoningEffortFallback(
+	error: unknown,
+	captured: CapturedHttpErrorResponse | undefined,
+	params: unknown,
+	options?: { explicitDisable?: boolean },
+): OpenAIReasoningEffortFallback | undefined {
+	const currentEffort = readOpenAIReasoningEffort(params);
+	if (!currentEffort || !KNOWN_REASONING_VALUE[currentEffort.toLowerCase()]) return undefined;
+	if (!isInvalidReasoningEffortError(error, captured, currentEffort)) return undefined;
+	const message = collectMessageParts(error, captured);
+	const allowed = parseAllowedReasoningValues(message, currentEffort);
+	const normalizedCurrent = currentEffort.toLowerCase();
+	if (allowed === undefined) return null;
+	if (options?.explicitDisable) {
+		if (normalizedCurrent !== "none" && allowed.has("none")) return "none";
+		const fallback = lowestEnabledAllowedValue(allowed);
+		return fallback && fallback !== normalizedCurrent ? fallback : null;
+	}
+	if (normalizedCurrent === "none") return null;
+	return nearestEnabledReasoningFallback(normalizedCurrent, allowed) ?? null;
+}

package/src/providers/openai-responses.ts

@@ -44,6 +44,17 @@ import {
 	type OpenAIResponsesToolChoice,
 } from "../utils/tool-choice";
 import { compactGrammarDefinition } from "./grammar";
+import {
+	applyOpenAIReasoningEffortFallback,
+	clearOpenAIReasoningEffortFallbackState,
+	createOpenAIReasoningEffortFallbackKey,
+	createOpenAIReasoningEffortFallbackState,
+	getOpenAIReasoningEffortFallback,
+	type OpenAIReasoningEffortFallback,
+	type OpenAIReasoningEffortFallbackState,
+	rememberOpenAIReasoningEffortFallback,
+	resolveOpenAIReasoningEffortFallback,
+} from "./openai-reasoning-fallback";
 import type {
 	Tool as OpenAITool,
 	ResponseCreateParamsStreaming,
@@ -140,7 +151,10 @@ const OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE =
 /** Consecutive stale-previous-response failures before chaining is disabled for the session. */
 const OPENAI_RESPONSES_CHAIN_STALE_FAILURE_LIMIT = 3;
 
-interface OpenAIResponsesProviderSessionState extends ProviderSessionState, OpenAIStrictToolsState {
+interface OpenAIResponsesProviderSessionState
+	extends ProviderSessionState,
+		OpenAIStrictToolsState,
+		OpenAIReasoningEffortFallbackState {
 	nativeHistoryReplayWarmed: boolean;
 	/** Stateful `previous_response_id` chain baselines, keyed by baseUrl/model/session. */
 	chains: Map<string, OpenAIResponsesChainState>;
@@ -164,14 +178,17 @@ interface OpenAIResponsesChainState {
 
 function createOpenAIResponsesProviderSessionState(): OpenAIResponsesProviderSessionState {
 	const strictToolsState = createOpenAIStrictToolsState();
+	const reasoningEffortFallbackState = createOpenAIReasoningEffortFallbackState();
 	const state: OpenAIResponsesProviderSessionState = {
 		...strictToolsState,
+		...reasoningEffortFallbackState,
 		nativeHistoryReplayWarmed: false,
 		chains: new Map(),
 		close: () => {
 			state.nativeHistoryReplayWarmed = false;
 			state.chains.clear();
 			clearOpenAIStrictToolsState(state);
+			clearOpenAIReasoningEffortFallbackState(state);
 		},
 	};
 	return state;
@@ -385,6 +402,26 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			const { trailingScaffoldingItems } = builtParams;
 			let activeParams = params;
 			let activeTrailingScaffoldingItems = trailingScaffoldingItems;
+			const resolvedBaseUrl = (baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+			const requestReasoningEffortFallbacks = new Map<string, OpenAIReasoningEffortFallback>();
+			const attemptedReasoningEffortFallbacks = new Set<string>();
+			let pendingReasoningEffortFallback: { key: string; fallback: OpenAIReasoningEffortFallback } | undefined;
+			let activeReasoningEffortFallbackKey: string | undefined;
+			let activeRequestParams: OpenAIResponsesSamplingParams | undefined;
+			const applyReasoningEffortFallbackForRequest = (requestParams: OpenAIResponsesSamplingParams): string => {
+				const fallbackKey = createOpenAIReasoningEffortFallbackKey(
+					"responses",
+					resolvedBaseUrl,
+					typeof requestParams.model === "string" ? requestParams.model : model.id,
+				);
+				const requestReasoningEffortFallback = requestReasoningEffortFallbacks.has(fallbackKey)
+					? requestReasoningEffortFallbacks.get(fallbackKey)
+					: getOpenAIReasoningEffortFallback(providerSessionState, fallbackKey);
+				if (requestReasoningEffortFallback !== undefined) {
+					applyOpenAIReasoningEffortFallback(requestParams, requestReasoningEffortFallback);
+				}
+				return fallbackKey;
+			};
 			if (isOpenAIResponsesStatefulEnabled(options, baseUrl) && routingSessionId && providerSessionState) {
 				chainState = getOpenAIResponsesChainState(providerSessionState, model, baseUrl, routingSessionId);
 				if (!chainState.disabled) {
@@ -392,6 +429,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 					params.store = true;
 				}
 			}
+			applyReasoningEffortFallbackForRequest(params);
 			let chained: OpenAIResponsesChainedParams =
 				chainState && !chainState.disabled
 					? buildOpenAIResponsesChainedParams(params, trailingScaffoldingItems, chainState)
@@ -402,12 +440,13 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				options?.streamFirstEventTimeoutMs ?? getOpenAIStreamFirstEventTimeoutMs(idleTimeoutMs);
 			const requestTimeoutMs =
 				firstEventTimeoutMs !== undefined && firstEventTimeoutMs > 0 ? firstEventTimeoutMs : undefined;
-			const requestUrl = `${(baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/responses`;
+			const requestUrl = `${resolvedBaseUrl}/responses`;
 			const applyPayloadReplacement = async (requestParams: OpenAIResponsesSamplingParams) => {
 				const replacementPayload = await options?.onPayload?.(requestParams, model);
-				return replacementPayload !== undefined
-					? (replacementPayload as OpenAIResponsesSamplingParams)
-					: requestParams;
+				const payload =
+					replacementPayload !== undefined ? (replacementPayload as OpenAIResponsesSamplingParams) : requestParams;
+				applyReasoningEffortFallbackForRequest(payload);
+				return payload;
 			};
 			chained = { ...chained, params: await applyPayloadReplacement(chained.params) };
 			rawRequestDump = {
@@ -418,8 +457,14 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				url: requestUrl,
 				body: chained.params,
 			};
-			const openResponsesStream = (requestParams: OpenAIResponsesSamplingParams) =>
-				callWithCopilotModelRetry(
+			const openResponsesStream = (requestParams: OpenAIResponsesSamplingParams) => {
+				activeReasoningEffortFallbackKey = createOpenAIReasoningEffortFallbackKey(
+					"responses",
+					resolvedBaseUrl,
+					typeof requestParams.model === "string" ? requestParams.model : model.id,
+				);
+				activeRequestParams = requestParams;
+				return callWithCopilotModelRetry(
 					async () => {
 						let requestTimeout: NodeJS.Timeout | undefined;
 						if (requestTimeoutMs !== undefined) {
@@ -458,6 +503,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 					},
 					{ provider: model.provider, signal: requestSignal },
 				);
+			};
 			let openaiStream: AsyncIterable<ResponseStreamEvent>;
 			let strictRetryAvailable = true;
 			let activeStrictToolsApplied = builtParams.strictToolsApplied;
@@ -465,9 +511,37 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			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);

package/src/types.ts

@@ -656,8 +656,8 @@ export interface Tool<TParameters extends TSchema = TSchema> {
 	 * Illustrative calls/notes; the AI layer renders them into an `<examples>`
 	 * block in the model's native tool-call syntax and appends to the wire
 	 * description. Author `call`/`bad`/`good` as plain argument objects WITHOUT
-	 * `_i` — when intent tracing injects `_i` into the schema, the renderer adds
-	 * a placeholder `_i` automatically. Type each tool's `examples` against its
+	 * `i` — when intent tracing injects `i` into the schema, the renderer adds
+	 * a placeholder `i` automatically. Type each tool's `examples` against its
 	 * own schema (e.g. `readonly ToolExample<typeof schema["type"]>[]`).
 	 */
 	examples?: readonly ToolExample[];

package/src/utils/validation.ts

@@ -1291,6 +1291,18 @@ function truncateArgsForError(value: unknown): unknown {
  */
 export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall["arguments"] {
 	const originalArgs = toolCall.arguments;
+	if (originalArgs && typeof originalArgs === "object" && "__parseError" in originalArgs) {
+		const parseError = originalArgs.__parseError;
+		const rawJson = String(originalArgs.__rawJson ?? "");
+		const maxLen = 512;
+		const truncatedRawJson =
+			rawJson.length <= maxLen
+				? rawJson
+				: `${rawJson.slice(0, maxLen)}… [truncated ${rawJson.length - maxLen} chars]`;
+		throw new Error(
+			`Validation failed for tool "${toolCall.name}": Tool call arguments are not valid JSON.\nParse Error: ${parseError}\nRaw JSON:\n${truncatedRawJson}`,
+		);
+	}
 	const ctx = getValidationContext(tool);
 	const { json } = ctx;