jeopi-ai 16.2.13

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

@@ -0,0 +1,269 @@
+import { extractHttpStatusFromError } from "jeopi-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-reasoning-suppression.md

@@ -0,0 +1 @@
+Keep internal reasoning brief. Continue following the task and use tools normally.

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

@@ -0,0 +1,282 @@
+/**
+ * ArkType schemas for the OpenAI Responses API request shape we accept on the
+ * gateway. Mirrors https://platform.openai.com/docs/api-reference/responses.
+ *
+ * Unsupported / opaque controls (background/include/metadata/prompt/…) are
+ * accepted as `"unknown"` optional so we silently ignore rather than 400.
+ * Real clients (codex, openai-python, llm-git) routinely send these and a 400
+ * is a worse outcome than dropping them on the floor.
+ */
+
+import { type } from "arktype";
+import type {
+	EasyInputMessage,
+	ResponseCreateParams,
+	ResponseFunctionToolCall,
+	ResponseInputContent,
+	ResponseInputItem,
+	ResponseOutputMessage,
+	ResponseReasoningItem,
+	Tool as ResponsesTool,
+} from "./openai-responses-wire";
+
+// ─── Input content blocks ───────────────────────────────────────────────────
+
+const inputTextSchema = type({
+	type: "'input_text'",
+	text: "string",
+});
+
+const plainTextSchema = type({
+	type: "'text'",
+	text: "string",
+});
+
+const inputImageBlockSchema = type({
+	type: "'input_image'",
+	"detail?": "'auto' | 'low' | 'high'",
+	"image_url?": "string",
+	"file_id?": "string",
+}).narrow((v, ctx) => {
+	return (
+		typeof v.image_url === "string" ||
+		typeof v.file_id === "string" ||
+		ctx.mustBe("at least one of `image_url` or `file_id` for input_image")
+	);
+});
+
+const inputFileBlockSchema = type({
+	type: "'input_file'",
+	"file_id?": "string",
+	"filename?": "string",
+	"file_data?": "string",
+});
+
+const outputTextSchema = type({
+	type: "'output_text'",
+	text: "string",
+});
+
+const outputRefusalSchema = type({
+	type: "'refusal'",
+	refusal: "string",
+});
+
+const summaryTextSchema = type({
+	type: "'summary_text'",
+	text: "string",
+});
+
+const reasoningTextSchema = type({
+	type: "'reasoning_text'",
+	text: "string",
+});
+
+const inputContentBlockSchema = inputTextSchema.or(plainTextSchema).or(inputImageBlockSchema).or(inputFileBlockSchema);
+
+const outputContentBlockSchema = outputTextSchema.or(plainTextSchema).or(outputRefusalSchema);
+
+// ─── Input items ────────────────────────────────────────────────────────────
+
+const userMessageItemSchema = type({
+	"type?": "'message'",
+	role: "'user' | 'developer'",
+	"content?": type("string").or(inputContentBlockSchema.array()),
+});
+
+const systemMessageItemSchema = type({
+	"type?": "'message'",
+	role: "'system'",
+	"content?": type("string").or(inputContentBlockSchema.array()),
+});
+
+const assistantMessageItemSchema = type({
+	"type?": "'message'",
+	"id?": "string",
+	role: "'assistant'",
+	"content?": type("string").or(outputContentBlockSchema.array()),
+	"status?": "'in_progress' | 'completed' | 'incomplete'",
+	"phase?": "'commentary' | 'final_answer' | null",
+});
+
+const reasoningItemSchema = type({
+	type: "'reasoning'",
+	"id?": "string",
+	"summary?": summaryTextSchema.array(),
+	"content?": reasoningTextSchema.array(),
+});
+
+const functionCallItemSchema = type({
+	type: "'function_call'",
+	"id?": "string",
+	call_id: "string >= 1",
+	name: "string >= 1",
+	"arguments?": "string",
+});
+
+const functionCallOutputItemSchema = type({
+	type: "'function_call_output'",
+	call_id: "string >= 1",
+	// Codex CLI replays multimodal tool results in array form (text + refusal).
+	"output?": type("string").or(outputContentBlockSchema.array()),
+});
+
+const customToolCallItemSchema = type({
+	type: "'custom_tool_call'",
+	"id?": "string",
+	call_id: "string >= 1",
+	name: "string >= 1",
+	// Raw input string — NOT JSON.stringified. apply_patch flow streams a
+	// freeform body and reading it as JSON would corrupt it.
+	input: "string",
+});
+
+const customToolCallOutputItemSchema = type({
+	type: "'custom_tool_call_output'",
+	call_id: "string >= 1",
+	output: "string",
+});
+
+/**
+ * Direct mapping to standard types.
+ */
+export const inputItemSchema = userMessageItemSchema
+	.or(systemMessageItemSchema)
+	.or(assistantMessageItemSchema)
+	.or(reasoningItemSchema)
+	.or(functionCallItemSchema)
+	.or(functionCallOutputItemSchema)
+	.or(customToolCallItemSchema)
+	.or(customToolCallOutputItemSchema)
+	// Tolerated but not bridged (file_search_call, web_search_call, …).
+	.or(type({ type: "string" }));
+
+// Variant types alias the canonical SDK union members so the walker can
+// narrow them cleanly. The convenience "message" shape (no `type` field) maps
+// to EasyInputMessage; the explicit form maps to ResponseInputItem.Message.
+export type OpenAIResponsesUserItem = EasyInputMessage | ResponseInputItem.Message;
+export type OpenAIResponsesSystemItem = EasyInputMessage | ResponseInputItem.Message;
+export type OpenAIResponsesAssistantItem = EasyInputMessage | ResponseOutputMessage;
+export type OpenAIResponsesReasoningItem = ResponseReasoningItem;
+export type OpenAIResponsesFunctionCallItem = ResponseFunctionToolCall;
+export type OpenAIResponsesFunctionCallOutputItem = ResponseInputItem.FunctionCallOutput;
+
+/** Inferred shape of the custom tool call input item (no canonical SDK alias). */
+export type OpenAIResponsesCustomToolCallItem = typeof customToolCallItemSchema.infer;
+export type OpenAIResponsesCustomToolCallOutputItem = typeof customToolCallOutputItemSchema.infer;
+export type OpenAIResponsesInputImageBlock = typeof inputImageBlockSchema.infer;
+export type OpenAIResponsesInputFileBlock = typeof inputFileBlockSchema.infer;
+export type OpenAIResponsesOutputRefusalBlock = typeof outputRefusalSchema.infer;
+
+// ─── Tools ──────────────────────────────────────────────────────────────────
+
+export const toolSchema = type({
+	type: "'function'",
+	name: "string >= 1",
+	"description?": "string",
+	"parameters?": type({ "[string]": "unknown" }),
+	"strict?": "boolean",
+});
+
+// Built-in / hosted tool entries (web_search_preview, file_search, …) — accepted
+// but skipped by the walker.
+const builtinToolSchema = type({
+	type: "string",
+});
+
+// ─── Tool choice ────────────────────────────────────────────────────────────
+
+const hostedToolType = type(
+	"'web_search_preview' | 'file_search' | 'computer_use_preview' | 'code_interpreter' | 'image_generation' | 'mcp'",
+);
+
+const allowedToolEntrySchema = type({
+	type: "string",
+	"name?": "string",
+});
+
+export const toolChoiceSchema = type("'auto' | 'none' | 'required'")
+	.or(
+		type({
+			type: "'function'",
+			name: "string >= 1",
+		}),
+	)
+	.or(
+		type({
+			type: "'custom'",
+			name: "string >= 1",
+		}),
+	)
+	.or(
+		type({
+			type: hostedToolType,
+		}),
+	)
+	.or(
+		type({
+			type: "'allowed_tools'",
+			mode: "'auto' | 'required'",
+			tools: allowedToolEntrySchema.array(),
+		}),
+	);
+
+// ─── Reasoning config ───────────────────────────────────────────────────────
+
+export const reasoningConfigSchema = type({
+	"effort?": "string",
+	// `none` maps to hideThinkingSummary; auto/concise/detailed mean "show
+	// summary". pi-ai has no per-level plumbing for the latter — walker logs
+	// once and treats them as default.
+	"summary?": "'auto' | 'concise' | 'detailed' | 'none'",
+});
+
+// ─── Stop ───────────────────────────────────────────────────────────────────
+
+export const stopSchema = type("string | string[] | null");
+
+// ─── Top-level request ──────────────────────────────────────────────────────
+
+export const openaiResponsesRequestSchema = type({
+	model: "string >= 1",
+	"input?": type("string").or(inputItemSchema.array()),
+	"instructions?": "string | null",
+	"tools?": toolSchema.or(builtinToolSchema).array(),
+	"tool_choice?": toolChoiceSchema,
+	"max_output_tokens?": "number",
+	"temperature?": "number",
+	"top_p?": "number",
+	"stop?": stopSchema,
+	"stream?": "boolean",
+	"reasoning?": reasoningConfigSchema,
+	"store?": "boolean",
+	"previous_response_id?": "string",
+	"parallel_tool_calls?": "boolean",
+	"prompt_cache_key?": "string",
+	"metadata?": "unknown",
+	"user?": "string",
+	"service_tier?": "string",
+	"presence_penalty?": "number",
+	"frequency_penalty?": "number",
+	// Accepted-but-ignored: include `reasoning.encrypted_content` is the canonical
+	// way to request reasoning replay — silently accept and drop.
+	"background?": "unknown",
+	"include?": "unknown",
+	"prompt?": "unknown",
+	"safety_identifier?": "unknown",
+	"text?": "unknown",
+	"top_logprobs?": "unknown",
+	"truncation?": "unknown",
+});
+
+/**
+ * Public types are sourced from the OpenAI SDK so the gateway stays in
+ * lock-step with the canonical API surface; the schemas above are runtime
+ * validators for the subset we actually accept.
+ */
+export type OpenAIResponsesRequest = ResponseCreateParams;
+export type OpenAIResponsesInputItem = ResponseInputItem;
+export type OpenAIResponsesTool = ResponsesTool;
+export type OpenAIResponsesToolChoice = NonNullable<ResponseCreateParams["tool_choice"]>;
+export type OpenAIResponsesInputContent = ResponseInputContent;
+export type OpenAIResponsesOutputContent = ResponseOutputMessage["content"][number];