@vib-rato/ai 0.16.0

package/src/providers/openai-responses.ts

@@ -0,0 +1,989 @@
+import { $credentialEnv, extractHttpStatusFromError, logger, structuredCloneJSON } from "@vib-rato/utils";
+import OpenAI, { APIConnectionTimeoutError } from "openai";
+import type {
+	Tool as OpenAITool,
+	ResponseCreateParamsStreaming,
+	ResponseInput,
+} from "openai/resources/responses/responses";
+import packageJson from "../../package.json" with { type: "json" };
+import { getEnvApiKey } from "../stream";
+import {
+	type AssistantMessage,
+	type CacheRetention,
+	type Context,
+	type FetchImpl,
+	isKnownProvider,
+	type MessageAttribution,
+	type Model,
+	type OpenAICompat,
+	type ProviderSessionState,
+	type ServiceTier,
+	type StreamFunction,
+	type StreamOptions,
+	type Tool,
+	type ToolChoice,
+	type ToolResultMessage,
+} from "../types";
+import {
+	createOpenAIResponsesHistoryPayload,
+	getOpenAIResponsesHistoryItems,
+	getOpenAIResponsesHistoryPayload,
+	isInvalidPromptError,
+	neutralizeReservedControlTokens,
+	neutralizeResponsesInputControlTokens,
+	normalizeSystemPrompts,
+	resolveCacheRetention,
+	sanitizeOpenAIResponsesHistoryItemsForReplay,
+} from "../utils";
+import { createAbortSourceTracker } from "../utils/abort";
+import { AssistantMessageEventStream } from "../utils/event-stream";
+import { EMPTY_RESPONSE_PROVIDER_CODE, transportFailureFacts } from "../utils/fallback-transport";
+import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
+import {
+	FirstEventTimeoutError,
+	getOpenAIStreamIdleTimeoutMs,
+	getProviderFirstEventTimeoutFallbackMs,
+	getStreamFirstEventTimeoutMs,
+	iterateWithIdleTimeout,
+	resolveOpenAISdkRequestTimeoutMs,
+} from "../utils/idle-iterator";
+import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
+import { notifyProviderResponse } from "../utils/provider-response";
+import { callWithCopilotModelRetry } from "../utils/retry";
+import { resolveRetryBudget } from "../utils/retry-budget";
+import {
+	adaptSchemaForStrict,
+	flattenToolRootCombinators,
+	NO_STRICT,
+	sanitizeSchemaForOpenAIResponses,
+	toolWireSchema,
+} from "../utils/schema";
+import { wrapFetchForSseDebug } from "../utils/sse-debug";
+import { mapToOpenAIResponsesToolChoice, type OpenAIResponsesToolChoice } from "../utils/tool-choice";
+import {
+	isForcedToolChoiceUnsupportedError,
+	markToolChoiceIncapability,
+	resolveToolChoice,
+} from "../utils/tool-choice-capability";
+import { COMPOSER_EDIT_DISCIPLINE_PROMPT, isComposerHarnessModel } from "./composer-discipline";
+import { mergeDashScopeTokenPlanHeaders } from "./dashscope-token-plan-headers";
+import {
+	buildCopilotDynamicHeaders,
+	hasCopilotVisionInput,
+	resolveGitHubCopilotBaseUrl,
+} from "./github-copilot-headers";
+import { compactGrammarDefinition } from "./grammar";
+import { wrapOpenAIFetchForBoundedRateLimits } from "./openai-bounded-rate-limits";
+import {
+	applyOpenAIRequestTransformBody,
+	applyOpenAIRequestTransformHeaders,
+	wrapFetchForOpenAIRequestTransform,
+} from "./openai-request-transform";
+import {
+	appendResponsesToolResultMessages,
+	applyCommonResponsesSamplingParams,
+	applyResponsesReasoningParams,
+	collectCustomCallIds,
+	collectKnownCallIds,
+	convertResponsesAssistantMessage,
+	convertResponsesInputContent,
+	createInitialResponsesAssistantMessage,
+	isOpenAIResponsesProgressEvent,
+	normalizeResponsesToolCallIdForTransform,
+	processResponsesStream,
+	repairOrphanResponsesToolOutputs,
+} from "./openai-responses-shared";
+import { transformMessages } from "./transform-messages";
+
+/**
+ * Get prompt cache retention based on cacheRetention and base URL.
+ * Only applies to direct OpenAI API calls (api.openai.com).
+ */
+function getPromptCacheRetention(baseUrl: string | undefined, cacheRetention: CacheRetention): "24h" | undefined {
+	if (cacheRetention !== "long") {
+		return undefined;
+	}
+	if (baseUrl && isDefaultOpenAIBaseUrl(baseUrl)) {
+		return "24h";
+	}
+	return undefined;
+}
+
+export function normalizeOpenAIResponsesPromptCacheKey(sessionId: string | undefined): string | undefined {
+	if (!sessionId || sessionId.length === 0) return undefined;
+	const wellFormed = sessionId.toWellFormed();
+	if (wellFormed.length <= 64) return wellFormed;
+	return `pc_${Bun.hash(wellFormed).toString(36)}`;
+}
+
+// OpenAI Responses-specific options
+export interface OpenAIResponsesOptions extends StreamOptions {
+	reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+	reasoningSummary?: "auto" | "detailed" | "concise" | null;
+	serviceTier?: ServiceTier;
+	toolChoice?: ToolChoice;
+	/**
+	 * Enforce strict tool call/result pairing when building Responses API inputs.
+	 * Azure OpenAI and GitHub Copilot Responses paths require tool results to match prior tool calls.
+	 */
+	strictResponsesPairing?: boolean;
+}
+
+const OPENAI_RESPONSES_PROVIDER_SESSION_STATE_PREFIX = "openai-responses:";
+const OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE =
+	"OpenAI responses stream timed out while waiting for the first event";
+const OPENAI_DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const OPENAI_DEFAULT_BASE_URL_HOST = "api.openai.com";
+
+function isDefaultOpenAIBaseUrl(baseUrl: string): boolean {
+	try {
+		const url = new URL(baseUrl);
+		return url.hostname === OPENAI_DEFAULT_BASE_URL_HOST && (url.pathname === "" || url.pathname === "/v1");
+	} catch {
+		return baseUrl === OPENAI_DEFAULT_BASE_URL;
+	}
+}
+
+function isCanonicalOpenAIAffinityOrigin(baseUrl: string | undefined): boolean {
+	if (!baseUrl) return false;
+	try {
+		const url = new URL(baseUrl);
+		return (
+			url.origin === "https://api.openai.com" &&
+			url.username === "" &&
+			url.password === "" &&
+			(url.pathname === "" || url.pathname === "/" || url.pathname === "/v1") &&
+			url.search === "" &&
+			url.hash === ""
+		);
+	} catch {
+		return false;
+	}
+}
+/**
+ * Official OpenAI keeps its existing session-routing behavior even when prompt
+ * caching is disabled. Relay affinity is opt-in, cache-enabled, and limited to
+ * explicitly supported openai or unknown provider ids so known non-target
+ * transports cannot inherit the headers.
+ */
+
+function shouldSendOpenAIResponsesSessionHeaders(
+	model: Model<"openai-responses">,
+	baseUrl: string | undefined,
+	cacheRetention: CacheRetention,
+): boolean {
+	if (model.provider === "openai") {
+		if (isCanonicalOpenAIAffinityOrigin(baseUrl)) return true;
+		return cacheRetention !== "none" && model.compat?.supportsResponsesSessionAffinity === true;
+	}
+	if (cacheRetention === "none" || isKnownProvider(model.provider)) {
+		return false;
+	}
+	return (
+		Boolean(baseUrl?.trim()) &&
+		model.compat?.supportsResponsesSessionAffinity === true &&
+		!isCanonicalOpenAIAffinityOrigin(baseUrl)
+	);
+}
+
+function isOpenAIHostBaseUrl(baseUrl: string): boolean {
+	try {
+		const url = new URL(baseUrl);
+		return url.hostname === OPENAI_DEFAULT_BASE_URL_HOST;
+	} catch {
+		return baseUrl.toLowerCase().startsWith(OPENAI_DEFAULT_BASE_URL);
+	}
+}
+
+function resolveOpenAIProviderBaseUrl(
+	baseUrl: string | undefined,
+	authCredentialType: "api_key" | "oauth" | undefined,
+): string {
+	if (authCredentialType === "oauth") return OPENAI_DEFAULT_BASE_URL;
+	// Trusted sources only: this base URL becomes the request endpoint that carries
+	// the OpenAI credential, and `$env` merges the caller's `cwd/.env`, so reading it
+	// there would let repository content redirect authenticated traffic.
+	const envBaseUrl = $credentialEnv("OPENAI_BASE_URL");
+	const configuredBaseUrl = baseUrl?.trim();
+	if (envBaseUrl && (!configuredBaseUrl || isDefaultOpenAIBaseUrl(configuredBaseUrl))) {
+		return envBaseUrl;
+	}
+	return configuredBaseUrl || envBaseUrl || OPENAI_DEFAULT_BASE_URL;
+}
+
+/** Test seam: the provider base URL as resolved from trusted env. */
+export function resolveOpenAIProviderBaseUrlForTest(
+	baseUrl: string | undefined,
+	authCredentialType: "api_key" | "oauth" | undefined,
+): string {
+	return resolveOpenAIProviderBaseUrl(baseUrl, authCredentialType);
+}
+
+function appendUrlPath(baseUrl: string | undefined, path: string): string | undefined {
+	if (!baseUrl) return undefined;
+	const normalizedPath = path.replace(/^\/+/g, "");
+	try {
+		const parsed = new URL(baseUrl);
+		parsed.pathname = `${parsed.pathname.replace(/\/+$/g, "")}/${normalizedPath}`;
+		return parsed.toString();
+	} catch {
+		return `${baseUrl.replace(/\/+$/g, "")}/${normalizedPath}`;
+	}
+}
+
+type OpenAIResponsesQuery = string;
+
+function splitBaseUrlQuery(baseUrl: string | undefined): {
+	baseUrl: string | undefined;
+	query?: OpenAIResponsesQuery;
+} {
+	if (!baseUrl) return { baseUrl };
+	try {
+		const parsed = new URL(baseUrl);
+		if (!parsed.search) return { baseUrl };
+		const queryStart = baseUrl.indexOf("?");
+		const fragmentStart = baseUrl.indexOf("#", queryStart);
+		const query = baseUrl.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
+		if (!query) return { baseUrl };
+		parsed.search = "";
+		return {
+			baseUrl: parsed.toString(),
+			query,
+		};
+	} catch {
+		return { baseUrl };
+	}
+}
+
+function appendRawQuery(url: string, query: OpenAIResponsesQuery | undefined): string {
+	if (!query) return url;
+	const fragmentStart = url.indexOf("#");
+	const beforeFragment = fragmentStart === -1 ? url : url.slice(0, fragmentStart);
+	const fragment = fragmentStart === -1 ? "" : url.slice(fragmentStart);
+	return `${beforeFragment}${beforeFragment.includes("?") ? "&" : "?"}${query}${fragment}`;
+}
+
+function buildRequestUrl(baseUrl: string | undefined, path: string, query?: OpenAIResponsesQuery): string | undefined {
+	const url = appendUrlPath(baseUrl, path);
+	return url ? appendRawQuery(url, query) : undefined;
+}
+
+function appendQueryToRequest(input: string | URL | Request, query?: OpenAIResponsesQuery): string | URL | Request {
+	if (!query) return input;
+	const url = appendRawQuery(input instanceof Request ? input.url : String(input), query);
+	if (input instanceof Request) return new Request(url, input as unknown as RequestInit);
+	return url;
+}
+
+interface OpenAIResponsesProviderSessionState extends ProviderSessionState {
+	nativeHistoryReplayWarmed: boolean;
+}
+
+function createOpenAIResponsesProviderSessionState(): OpenAIResponsesProviderSessionState {
+	const state: OpenAIResponsesProviderSessionState = {
+		nativeHistoryReplayWarmed: false,
+		close: () => {
+			state.nativeHistoryReplayWarmed = false;
+		},
+	};
+	return state;
+}
+
+function getOpenAIResponsesProviderSessionStateKey(model: Model<"openai-responses">): string {
+	return `${OPENAI_RESPONSES_PROVIDER_SESSION_STATE_PREFIX}${model.provider}`;
+}
+
+function getOpenAIResponsesProviderSessionState(
+	model: Model<"openai-responses">,
+	providerSessionState: Map<string, ProviderSessionState> | undefined,
+): OpenAIResponsesProviderSessionState | undefined {
+	if (!providerSessionState) return undefined;
+	const key = getOpenAIResponsesProviderSessionStateKey(model);
+	const existing = providerSessionState.get(key) as OpenAIResponsesProviderSessionState | undefined;
+	if (existing) return existing;
+	const created = createOpenAIResponsesProviderSessionState();
+	providerSessionState.set(key, created);
+	return created;
+}
+
+function canReplayOpenAIResponsesNativeHistory(
+	providerSessionState: OpenAIResponsesProviderSessionState | undefined,
+): boolean {
+	return providerSessionState?.nativeHistoryReplayWarmed ?? true;
+}
+
+type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
+	top_p?: number;
+	top_k?: number;
+	min_p?: number;
+	presence_penalty?: number;
+	repetition_penalty?: number;
+	stream_options?: { include_obfuscation?: boolean };
+};
+
+export function isOpenCodeGoEmptyCompletedResponse(
+	model: Model<"openai-responses">,
+	output: AssistantMessage,
+	nativeOutputItemCount: number,
+): boolean {
+	return (
+		model.provider === "opencode-go" &&
+		typeof output.responseId === "string" &&
+		output.responseId.length > 0 &&
+		output.stopReason === "stop" &&
+		output.content.length === 0 &&
+		nativeOutputItemCount === 0 &&
+		output.usage.input === 0 &&
+		output.usage.output === 0 &&
+		output.usage.cacheRead === 0 &&
+		output.usage.cacheWrite === 0 &&
+		output.usage.totalTokens === 0
+	);
+}
+
+/**
+ * Generate function for OpenAI Responses API
+ */
+export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
+	model: Model<"openai-responses">,
+	context: Context,
+	options?: OpenAIResponsesOptions,
+): AssistantMessageEventStream => {
+	const stream = new AssistantMessageEventStream();
+
+	// Start async processing
+	(async () => {
+		const startTime = Date.now();
+		let firstTokenTime: number | undefined;
+		let streamConnected = false;
+
+		const output: AssistantMessage = createInitialResponsesAssistantMessage(
+			"openai-responses",
+			model.provider,
+			model.id,
+		);
+		let rawRequestDump: RawHttpRequestDump | undefined;
+		const abortTracker = createAbortSourceTracker(options?.signal);
+		const { requestAbortController, requestSignal } = abortTracker;
+
+		try {
+			// Keep request headers and prompt-cache routing on the same session-derived value.
+			const cacheSessionId = getOpenAIResponsesCacheSessionId(options);
+			const cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention);
+			const apiKey = options?.apiKey || getEnvApiKey(model.provider) || "";
+			const { client, copilotPremiumRequests, baseUrl, requestBaseUrl, requestQuery } = createClient(
+				model,
+				context,
+				apiKey,
+				options?.headers,
+				options?.initiatorOverride,
+				cacheSessionId,
+				cacheRetention,
+				options?.onSseEvent,
+				options?.fetch,
+				options?.authCredentialType,
+				options?.requestMaxRetries,
+				options?.maxRetryDelayMs,
+				options?.attemptScope,
+				options?.streamFirstEventTimeoutMs,
+			);
+			const premiumRequestsTotal = copilotPremiumRequests;
+			const providerSessionState = getOpenAIResponsesProviderSessionState(model, options?.providerSessionState);
+			const { params } = buildParams(model, context, options, providerSessionState, cacheRetention, baseUrl);
+			const idleTimeoutMs = options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs(model.provider, model.id);
+			options?.onPayload?.(params, undefined, options?.attemptScope);
+			rawRequestDump = {
+				provider: model.provider,
+				api: output.api,
+				model: model.id,
+				method: "POST",
+				url: buildRequestUrl(requestBaseUrl, "responses", requestQuery),
+				body: params,
+			};
+			const openaiStream = await callWithCopilotModelRetry(
+				async () => {
+					options?.onStreamCreated?.();
+					const { data, response, request_id } = await client.responses
+						.create(params, { signal: requestSignal })
+						.withResponse();
+					await notifyProviderResponse(options, response, model, request_id);
+					return data;
+				},
+				{
+					provider: model.provider,
+					signal: requestSignal,
+					fallbackManaged: options?.fallbackManaged,
+					requestMaxRetries: options?.requestMaxRetries,
+					disableProviderRetries: options?.disableProviderRetries,
+				},
+			).catch(async error => {
+				if (
+					options?.fallbackManaged ||
+					options?.disableProviderRetries ||
+					!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))
+				) {
+					throw error;
+				}
+				const reason = await finalizeErrorMessage(error, rawRequestDump);
+				markToolChoiceIncapability(model, "auto", reason);
+				const resolvedToolChoice = resolveToolChoice(model, options?.toolChoice);
+				stream.push({
+					type: "toolChoiceIncapability",
+					api: model.api,
+					provider: model.provider,
+					model: model.id,
+					requestedLevel: resolvedToolChoice.requestedLevel,
+					resolvedLevel: "auto",
+					reason,
+					registryKey: resolvedToolChoice.registryKey,
+				});
+				delete params.tool_choice;
+				if (rawRequestDump) rawRequestDump.body = params;
+				options?.onStreamCreated?.();
+				const { data, response, request_id } = await client.responses
+					.create(params, { signal: requestSignal })
+					.withResponse();
+				await notifyProviderResponse(options, response, model, request_id);
+				return data;
+			});
+			streamConnected = true;
+			const firstEventFallbackMs = getProviderFirstEventTimeoutFallbackMs(model.provider);
+			const firstEventTimeoutMs =
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs);
+			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
+			stream.push({ type: "start", partial: output });
+
+			const nativeOutputItems: Array<Record<string, unknown>> = [];
+			await processResponsesStream(
+				iterateWithIdleTimeout(openaiStream, {
+					idleTimeoutMs,
+					firstItemTimeoutMs: firstEventTimeoutMs,
+					firstItemErrorMessage: OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE,
+					errorMessage: "OpenAI responses stream stalled while waiting for the next event",
+					onIdle: () => requestAbortController.abort(),
+					onFirstItemTimeout: () => requestAbortController.abort(),
+					abortSignal: options?.signal,
+					isProgressItem: isOpenAIResponsesProgressEvent,
+				}),
+				output,
+				stream,
+				model,
+				{
+					onFirstToken: () => {
+						if (!firstTokenTime) firstTokenTime = Date.now();
+					},
+					onOutputItemDone: item => {
+						nativeOutputItems.push(structuredCloneJSON<unknown>(item) as unknown as Record<string, unknown>);
+					},
+				},
+			);
+			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
+
+			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
+			if (firstEventTimeoutError) {
+				throw firstEventTimeoutError;
+			}
+			if (abortTracker.wasCallerAbort()) {
+				throw new Error("Request was aborted");
+			}
+
+			if (output.stopReason === "aborted" || output.stopReason === "error") {
+				throw new Error(output.errorMessage ?? "An unknown error occurred");
+			}
+
+			output.providerPayload = createOpenAIResponsesHistoryPayload(model.provider, nativeOutputItems);
+			if (isOpenCodeGoEmptyCompletedResponse(model, output, nativeOutputItems.length)) {
+				output.stopReason = "error";
+				output.errorMessage = "Provider returned an empty response with zero token usage";
+				output.transportFailure = {
+					kind: "transport",
+					providerCode: EMPTY_RESPONSE_PROVIDER_CODE,
+				};
+			}
+			if (providerSessionState) providerSessionState.nativeHistoryReplayWarmed = true;
+
+			output.duration = Date.now() - startTime;
+			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
+			if (output.stopReason === "error") {
+				stream.push({ type: "error", reason: "error", error: output });
+			} else {
+				stream.push({ type: "done", reason: output.stopReason, message: output });
+			}
+			stream.end();
+		} catch (error) {
+			for (const block of output.content) delete (block as { index?: number }).index;
+			const localAbortReason = abortTracker.getLocalAbortReason();
+			const normalizedError =
+				!streamConnected && model.provider === "alibaba-token-plan" && error instanceof APIConnectionTimeoutError
+					? new FirstEventTimeoutError(OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE)
+					: error;
+			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
+			output.errorStatus = extractHttpStatusFromError(localAbortReason ?? normalizedError);
+			output.transportFailure = transportFailureFacts(localAbortReason ?? normalizedError);
+			output.errorMessage =
+				localAbortReason?.message ?? (await finalizeErrorMessage(normalizedError, rawRequestDump));
+			output.errorMessage = rewriteCopilotError(output.errorMessage, normalizedError, model.provider);
+			// Explicitly mark the poisoned-history rejection so the shared
+			// `invalid_prompt` contract is present even when the SDK error surfaces
+			// only a message (no structured code). This keeps the responses
+			// transport's classification uniform with the codex transport's
+			// non-retryable event set and lets the session-level circuit breaker
+			// key on one durable marker instead of per-transport string matching.
+			if (
+				output.stopReason === "error" &&
+				!output.transportFailure?.providerCode &&
+				(isInvalidPromptError(error) || isInvalidPromptError(output.errorMessage))
+			) {
+				output.transportFailure = {
+					...(output.transportFailure ?? { kind: "transport" }),
+					providerCode: "invalid_prompt",
+				};
+			}
+			output.duration = Date.now() - startTime;
+			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
+			stream.push({ type: "error", reason: output.stopReason, error: output });
+			stream.end();
+		}
+	})();
+
+	return stream;
+};
+
+function createClient(
+	model: Model<"openai-responses">,
+	context: Context,
+	apiKey?: string,
+	extraHeaders?: Record<string, string>,
+	initiatorOverride?: MessageAttribution,
+	sessionId?: string,
+	cacheRetention?: CacheRetention,
+	onSseEvent?: OpenAIResponsesOptions["onSseEvent"],
+	fetchOverride?: FetchImpl,
+	authCredentialType?: OpenAIResponsesOptions["authCredentialType"],
+	requestMaxRetries?: number,
+	maxRetryDelayMs?: number,
+	attemptScope?: import("../types.js").AttemptScopeRef,
+	streamFirstEventTimeoutOverride?: number,
+): {
+	client: OpenAI;
+	copilotPremiumRequests: number | undefined;
+	baseUrl: string | undefined;
+	requestBaseUrl: string | undefined;
+	requestQuery: OpenAIResponsesQuery | undefined;
+} {
+	if (!apiKey) {
+		apiKey = $credentialEnv("OPENAI_API_KEY");
+		if (!apiKey) {
+			throw new Error(
+				"OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass it as an argument.",
+			);
+		}
+	}
+	const rawApiKey = apiKey;
+
+	const baseHeaders =
+		model.provider === "alibaba-token-plan"
+			? // Emit Qwen Code's canonical DashScope request fingerprint (User-Agent /
+				// X-DashScope-CacheControl / X-DashScope-UserAgent / X-DashScope-AuthType)
+				// so DashScope treats the caller identically to upstream QwenLM/qwen-code.
+				// Canonical identity is the base; caller headers win per key (upstream
+				// `{...default, ...customHeaders}`). #3557.
+				mergeDashScopeTokenPlanHeaders({ ...(model.headers ?? {}), ...(extraHeaders ?? {}) })
+			: { ...(model.headers ?? {}), ...(extraHeaders ?? {}) };
+	let copilotPremiumRequests: number | undefined;
+
+	let baseUrl =
+		model.provider === "openai" ? resolveOpenAIProviderBaseUrl(model.baseUrl, authCredentialType) : model.baseUrl;
+	if (model.provider === "openai" && !baseUrl) {
+		baseUrl = OPENAI_DEFAULT_BASE_URL;
+	}
+	let headers = baseHeaders;
+	if (model.provider === "github-copilot") {
+		apiKey = parseGitHubCopilotApiKey(rawApiKey).accessToken;
+		const hasImages = hasCopilotVisionInput(context.messages);
+		const copilot = buildCopilotDynamicHeaders({
+			messages: context.messages,
+			hasImages,
+			premiumMultiplier: model.premiumMultiplier,
+			headers,
+			initiatorOverride,
+		});
+		Object.assign(headers, copilot.headers);
+		copilotPremiumRequests = copilot.premiumRequests;
+		baseUrl = resolveGitHubCopilotBaseUrl(model.baseUrl, rawApiKey) ?? model.baseUrl;
+	}
+	if (sessionId && shouldSendOpenAIResponsesSessionHeaders(model, baseUrl, cacheRetention ?? "short")) {
+		headers.session_id ??= sessionId;
+		headers["x-client-request-id"] ??= sessionId;
+	}
+	headers = applyOpenAIRequestTransformHeaders(headers, model.requestTransform, `Vibrato/${packageJson.version}`);
+	const { baseUrl: clientBaseUrl, query: endpointQuery } = splitBaseUrlQuery(baseUrl);
+	const baseFetch = fetchOverride ?? fetch;
+	const queryFetch = Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			return baseFetch(appendQueryToRequest(input, endpointQuery), init);
+		},
+		baseFetch.preconnect ? { preconnect: baseFetch.preconnect } : {},
+	);
+	const boundedFetch = wrapOpenAIFetchForBoundedRateLimits(queryFetch, maxRetryDelayMs);
+	const transformedFetch = wrapFetchForOpenAIRequestTransform(
+		boundedFetch,
+		model.requestTransform,
+		`Vibrato/${packageJson.version}`,
+	);
+	// Bound HTTP request timeout to the first-event window so a stalled-before-headers
+	// fetch cannot wait the SDK's 10-minute default before the transport watchdog arms.
+	const sdkTimeoutMs = resolveOpenAISdkRequestTimeoutMs(model.provider, streamFirstEventTimeoutOverride, model.id);
+	return {
+		client: new OpenAI({
+			apiKey,
+			baseURL: clientBaseUrl,
+			dangerouslyAllowBrowser: true,
+			maxRetries: resolveRetryBudget(requestMaxRetries, 5),
+			defaultHeaders: headers,
+			fetch: onSseEvent
+				? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model, attemptScope))
+				: transformedFetch,
+			...(sdkTimeoutMs !== undefined ? { timeout: sdkTimeoutMs } : {}),
+		}),
+		copilotPremiumRequests,
+		baseUrl,
+		requestBaseUrl: clientBaseUrl,
+		requestQuery: endpointQuery,
+	};
+}
+
+function getOpenAIResponsesCacheSessionId(
+	options: Pick<OpenAIResponsesOptions, "sessionId"> | undefined,
+): string | undefined {
+	return normalizeOpenAIResponsesPromptCacheKey(options?.sessionId);
+}
+
+function buildParams(
+	model: Model<"openai-responses">,
+	context: Context,
+	options: OpenAIResponsesOptions | undefined,
+	providerSessionState: OpenAIResponsesProviderSessionState | undefined,
+	cacheRetention: CacheRetention,
+	resolvedBaseUrl?: string,
+): { conversationMessages: ResponseInput; params: OpenAIResponsesSamplingParams } {
+	const strictResponsesPairing =
+		options?.strictResponsesPairing ??
+		(isAzureOpenAIBaseUrl(model.baseUrl ?? "") || model.provider === "github-copilot");
+	const conversationMessages = convertConversationMessages(
+		model,
+		context,
+		strictResponsesPairing,
+		providerSessionState,
+	);
+	const messages: ResponseInput = neutralizeResponsesInputControlTokens(conversationMessages);
+
+	// Neutralize leaked Harmony control tokens in the system prompt too: the
+	// `instructions` field and developer-role messages bypass the `input`
+	// request-boundary sanitizer above, and a poisoned system prompt (e.g.
+	// injected project context quoting `<|channel|>` markers) rejects EVERY
+	// turn with `Request blocked (code=invalid_prompt)` — unrepairable by the
+	// history circuit breaker.
+	const systemPrompts = normalizeSystemPrompts(context.systemPrompt).map(neutralizeReservedControlTokens);
+	if (isComposerHarnessModel(model.id)) {
+		systemPrompts.unshift(COMPOSER_EDIT_DISCIPLINE_PROMPT);
+	}
+	let systemInstructions: string | undefined;
+	if (systemPrompts.length > 0) {
+		const needsDeveloperRole =
+			model.reasoning &&
+			((model.provider === "openai" && !model.baseUrl) || supportsDeveloperRole(resolvedBaseUrl || model));
+		if (needsDeveloperRole) {
+			// Reasoning models on known OpenAI-compatible endpoints require the
+			// `developer` role. Send all system prompts inline in `input`.
+			messages.unshift(
+				...systemPrompts.map(systemPrompt => ({ role: "developer" as const, content: systemPrompt })),
+			);
+		} else {
+			// All other endpoints (including third-party /v1/responses proxies) use
+			// the canonical top-level `instructions` field so that proxies that
+			// reject `input[{role:"system"}]` work out of the box.
+			systemInstructions = systemPrompts.join("\n\n");
+		}
+	}
+
+	const promptCacheKey = getOpenAIResponsesCacheSessionId(options);
+	const params: OpenAIResponsesSamplingParams = {
+		model: model.wireModelId ?? model.id,
+		input: messages,
+		instructions: systemInstructions,
+		stream: true,
+		prompt_cache_key: promptCacheKey,
+		prompt_cache_retention: getPromptCacheRetention(resolvedBaseUrl || model.baseUrl, cacheRetention),
+		store: false,
+		stream_options: model.provider === "openai" ? { include_obfuscation: false } : undefined,
+	};
+
+	applyCommonResponsesSamplingParams(params, options, model.provider, model.compat?.supportsServiceTier === true);
+	// TODO: openai responses has no top-level `stop`/`stop_sequences`; surface via reasoning.stop?
+	// `StreamOptions.stopSequences` is intentionally dropped for this provider.
+	// TODO: openai responses has no top-level `frequency_penalty` field as of the current SDK;
+	// `StreamOptions.frequencyPenalty` is intentionally dropped for this provider.
+
+	if (context.tools) {
+		params.tools = convertTools(context.tools, supportsStrictMode(model), model);
+		if (options?.toolChoice) {
+			const toolChoice = resolveToolChoice(model, options.toolChoice);
+			if (toolChoice.degraded && toolChoice.supportSource === "runtime") {
+				logger.debug("openai-responses: degraded tool_choice after runtime capability discovery", {
+					model: model.id,
+					requestedLevel: toolChoice.requestedLevel,
+					resolvedLevel: toolChoice.resolvedLevel,
+					reason: toolChoice.reason,
+				});
+			}
+			params.tool_choice = mapOpenAIResponsesToolChoiceForTools(toolChoice.resolvedChoice, context.tools, model);
+		}
+		// The apply_patch spec §1 marks only `apply_patch` itself as
+		// `supports_parallel_tool_calls = false`. OpenAI's Responses API
+		// exposes `parallel_tool_calls` as a request-scoped flag, not a
+		// per-tool one, so when a custom grammar tool is in the list we
+		// disable parallelism for the whole turn. Slightly coarser than
+		// the spec requires — but the platform API offers no finer knob.
+		if (params.tools.some(t => (t as { type?: string }).type === "custom")) {
+			params.parallel_tool_calls = false;
+		}
+	}
+
+	applyResponsesReasoningParams(params, model, options, messages, effort =>
+		mapReasoningEffort(effort as NonNullable<OpenAIResponsesOptions["reasoning"]>, model.compat?.reasoningEffortMap),
+	);
+	applyOpenAIRequestTransformBody(params, model.requestTransform);
+
+	return { conversationMessages, params };
+}
+
+function mapReasoningEffort(
+	effort: NonNullable<OpenAIResponsesOptions["reasoning"]>,
+	reasoningEffortMap: OpenAICompat["reasoningEffortMap"] | undefined,
+): string {
+	return reasoningEffortMap?.[effort] ?? effort;
+}
+
+function isAzureOpenAIBaseUrl(baseUrl: string): boolean {
+	return baseUrl.includes(".openai.azure.com") || baseUrl.includes("azure.com/openai");
+}
+
+function supportsStrictMode(model: Model<"openai-responses">): boolean {
+	if (model.provider === "openai" || model.provider === "azure" || model.provider === "github-copilot") return true;
+
+	const baseUrl = model.baseUrl;
+	const lowerBaseUrl = baseUrl.toLowerCase();
+	return (
+		isDefaultOpenAIBaseUrl(baseUrl) ||
+		lowerBaseUrl.includes(".openai.azure.com") ||
+		lowerBaseUrl.includes("models.inference.ai.azure.com")
+	);
+}
+
+export function supportsDeveloperRole(modelOrBaseUrl: Pick<Model, "provider" | "baseUrl"> | string): boolean {
+	const baseUrl = typeof modelOrBaseUrl === "string" ? modelOrBaseUrl : (modelOrBaseUrl.baseUrl ?? "");
+	if (typeof modelOrBaseUrl !== "string" && modelOrBaseUrl.provider === "openai" && !baseUrl) {
+		return true;
+	}
+	const lowerBaseUrl = baseUrl.toLowerCase();
+	return (
+		isOpenAIHostBaseUrl(baseUrl) ||
+		lowerBaseUrl.includes(".openai.azure.com") ||
+		lowerBaseUrl.includes("azure.com/openai") ||
+		lowerBaseUrl.includes("models.inference.ai.azure.com") ||
+		lowerBaseUrl.includes("githubcopilot.com") ||
+		lowerBaseUrl.includes("copilot-api.")
+	);
+}
+
+function convertConversationMessages(
+	model: Model<"openai-responses">,
+	context: Context,
+	strictResponsesPairing: boolean,
+	providerSessionState: OpenAIResponsesProviderSessionState | undefined,
+): ResponseInput {
+	const messages: ResponseInput = [];
+	let knownCallIds = new Set<string>();
+	const customCallIds = new Set<string>();
+	const shouldReplayNativeHistory = canReplayOpenAIResponsesNativeHistory(providerSessionState);
+	const transformedMessages = transformMessages(context.messages, model, normalizeResponsesToolCallIdForTransform);
+
+	let msgIndex = 0;
+	// Consecutive tool results are batched into one append call so every output
+	// of the turn stays contiguous before the collected image user message;
+	// per-result image user messages interleave with sibling outputs and break
+	// tool_use→tool_result adjacency through Anthropic-translating proxies (#4807).
+	let pendingToolResults: ToolResultMessage[] = [];
+	const flushPendingToolResults = (): void => {
+		if (pendingToolResults.length === 0) return;
+		appendResponsesToolResultMessages(
+			messages,
+			pendingToolResults,
+			model,
+			strictResponsesPairing,
+			knownCallIds,
+			customCallIds,
+		);
+		pendingToolResults = [];
+	};
+	for (const msg of transformedMessages) {
+		if (msg.role === "toolResult") {
+			pendingToolResults.push(msg);
+			msgIndex++;
+			continue;
+		}
+		flushPendingToolResults();
+		if (msg.role === "user" || msg.role === "developer") {
+			const providerPayload = (msg as { providerPayload?: AssistantMessage["providerPayload"] }).providerPayload;
+			const historyItems = getOpenAIResponsesHistoryItems(providerPayload, model.provider);
+			const shouldReplayPayloadItems =
+				shouldReplayNativeHistory ||
+				(historyItems?.some(item => {
+					if (!item || typeof item !== "object") return false;
+					const candidate = item as { type?: unknown };
+					return candidate.type === "compaction" || candidate.type === "compaction_summary";
+				}) ??
+					false);
+			if (historyItems && shouldReplayPayloadItems) {
+				messages.push(...sanitizeOpenAIResponsesHistoryItemsForReplay(historyItems));
+				knownCallIds = collectKnownCallIds(messages);
+				for (const id of collectCustomCallIds(messages)) customCallIds.add(id);
+				msgIndex++;
+				continue;
+			}
+			const content = convertResponsesInputContent(msg.content, model.input.includes("image"));
+			if (!content) continue;
+			messages.push({ role: "user", content });
+		} else if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			const providerPayload = shouldReplayNativeHistory
+				? getOpenAIResponsesHistoryPayload(assistantMsg.providerPayload, model.provider, assistantMsg.provider)
+				: undefined;
+			const historyItems = providerPayload?.items;
+			if (historyItems) {
+				const sanitizedHistoryItems = sanitizeOpenAIResponsesHistoryItemsForReplay(historyItems);
+				if (providerPayload?.dt) {
+					messages.push(...sanitizedHistoryItems);
+				} else {
+					messages.splice(0, messages.length, ...sanitizedHistoryItems);
+				}
+				knownCallIds = collectKnownCallIds(messages);
+				for (const id of collectCustomCallIds(messages)) customCallIds.add(id);
+				msgIndex++;
+				continue;
+			}
+
+			const outputItems = convertResponsesAssistantMessage(
+				assistantMsg,
+				model,
+				msgIndex,
+				knownCallIds,
+				shouldReplayNativeHistory,
+				customCallIds,
+			);
+			if (outputItems.length === 0) continue;
+			messages.push(...outputItems);
+		}
+		msgIndex++;
+	}
+	flushPendingToolResults();
+
+	return repairOrphanResponsesToolOutputs(messages);
+}
+
+/**
+ * Whether this model should get the OpenAI custom-tool grammar variant
+ * for `apply_patch`. The generated model catalog sets
+ * `model.applyPatchToolType` for first-party GPT-5 Responses models; this
+ * runtime path only consumes that metadata.
+ * @internal Exported for tests.
+ */
+export function supportsFreeformApplyPatch(model: Model<"openai-responses">): boolean {
+	return model.applyPatchToolType === "freeform";
+}
+
+/** @internal Exported for tests. */
+export function mapOpenAIResponsesToolChoiceForTools(
+	choice: ToolChoice | undefined,
+	tools: Tool[],
+	model: Model<"openai-responses">,
+): OpenAIResponsesToolChoice {
+	const mapped = mapToOpenAIResponsesToolChoice(choice);
+	if (!mapped || typeof mapped === "string" || mapped.type !== "function" || !supportsFreeformApplyPatch(model)) {
+		return mapped;
+	}
+
+	const customTool = tools.find(
+		tool => tool.customFormat && (tool.name === mapped.name || tool.customWireName === mapped.name),
+	);
+	return customTool ? { type: "custom", name: customTool.customWireName ?? customTool.name } : mapped;
+}
+
+function isForcedOpenAIResponsesToolChoice(choice: unknown): boolean {
+	return !!choice && choice !== "none" && choice !== "auto";
+}
+
+/**
+ * Tool names an OpenAI-compatible endpoint reserves for its own built-ins and
+ * refuses as custom function declarations.
+ *
+ * OpenCode Zen/Go reject `web_search` with
+ * `invalid tools in request: custom function name "web_search" is reserved`.
+ * The rejection is request-scoped: one colliding declaration fails the WHOLE
+ * tools array before any token streams, so every agent carrying that tool is
+ * permanently broken on the provider rather than losing a single capability.
+ *
+ * The collision is dropped rather than renamed. A renamed function tool would
+ * come back as a `function_call` under the wire alias, and that path does not
+ * populate `Tool.customWireName`, so the agent-loop dispatcher could not route
+ * it — trading a loud 400 for a silent unresolvable call. Dropping leaves the
+ * agent in the same state as any provider that simply has no web search.
+ */
+const PROVIDER_RESERVED_TOOL_NAMES: Record<string, readonly string[]> = {
+	"opencode-go": ["web_search"],
+	"opencode-zen": ["web_search"],
+};
+
+/** @internal Exported for tests. */
+export function resolveReservedToolNames(model: Model<"openai-responses">): readonly string[] {
+	return model.compat?.reservedToolNames ?? PROVIDER_RESERVED_TOOL_NAMES[model.provider] ?? [];
+}
+/** @internal Exported for tests. */
+export function convertTools(tools: Tool[], strictMode: boolean, model: Model<"openai-responses">): OpenAITool[] {
+	const allowFreeform = supportsFreeformApplyPatch(model);
+	const reserved = resolveReservedToolNames(model);
+	const declarable = reserved.length === 0 ? tools : tools.filter(tool => !reserved.includes(tool.name));
+	const payloads = declarable.map(tool => {
+		if (allowFreeform && tool.customFormat) {
+			return {
+				type: "custom",
+				// Tool advertises its wire-level name (e.g. `apply_patch`) — the
+				// agent-loop dispatcher will match incoming calls by either the
+				// internal `name` or `customWireName`.
+				name: tool.customWireName ?? tool.name,
+				description: tool.description || "",
+				format: {
+					type: "grammar",
+					syntax: tool.customFormat.syntax,
+					definition: compactGrammarDefinition(tool.customFormat.syntax, tool.customFormat.definition),
+				},
+			} as unknown as OpenAITool;
+		}
+		const strict = !NO_STRICT && strictMode && tool.strict !== false;
+		const baseParameters = flattenToolRootCombinators(toolWireSchema(tool));
+		const responseParameters = sanitizeSchemaForOpenAIResponses(baseParameters);
+		const { schema: parameters, strict: effectiveStrict } = adaptSchemaForStrict(responseParameters, strict);
+		return {
+			type: "function",
+			name: tool.name,
+			description: tool.description || "",
+			parameters,
+			...(effectiveStrict && { strict: true }),
+		} as OpenAITool;
+	});
+	// Tool definitions bypass the `input`/`instructions` sanitizers, so a
+	// leaked Harmony marker in an MCP/skill tool description or schema string
+	// rejects every gpt-5.x request (`Request blocked`).
+	return neutralizeResponsesInputControlTokens(payloads);
+}