@warlock.js/ai-openai 5.26.0 → 5.28.0

package/cjs/index.cjs

@@ -31,6 +31,224 @@ openai = __toESM(openai, 1);
 let _warlock_js_ai = require("@warlock.js/ai");
 let _warlock_js_logger = require("@warlock.js/logger");
 
+//#region ../ai-openai/src/utils/build-usage.ts
+/**
+* Build the neutral `Usage` from extracted counts. The optional detail
+* counters are emitted only when the provider reports a positive value, so
+* non-reasoning / uncached calls keep the lean `{ input, output, total }`
+* shape. Shared by the Chat Completions and Responses adapters so both
+* apply the same rule.
+*/
+function buildUsage(counts) {
+	const { input, output, total, cachedTokens, reasoningTokens, cacheWriteTokens } = counts;
+	return {
+		input,
+		output,
+		total,
+		...cachedTokens !== void 0 && cachedTokens > 0 ? { cachedTokens } : {},
+		...reasoningTokens !== void 0 && reasoningTokens > 0 ? { reasoningTokens } : {},
+		...cacheWriteTokens !== void 0 && cacheWriteTokens > 0 ? { cacheWriteTokens } : {}
+	};
+}
+
+//#endregion
+//#region ../ai-openai/src/utils/wrap-openai-error.ts
+/**
+* Wrap any thrown value caught inside the OpenAI adapter into the
+* appropriate `@warlock.js/ai` `AIError` subclass.
+*
+* **Dispatch strategy.** Prefers `APIError.code` when present (stable
+* machine identifier across SDK versions), falls back to `status` when
+* `code` is missing (common with proxied deployments that strip the
+* field). Name-based detection (`APIConnectionTimeoutError`) catches
+* transport-layer errors that never produced an HTTP response.
+*
+* `AIError` instances are returned unchanged — callers can pass the
+* error through `try/catch/throw wrap(e)` pipelines without accidental
+* double-wrapping.
+*
+* @example
+* try {
+*   return await this.client.chat.completions.create(...);
+* } catch (thrown) {
+*   throw wrapOpenAIError(thrown);
+* }
+*/
+function wrapOpenAIError(thrown) {
+	if (thrown instanceof _warlock_js_ai.AIError) return thrown;
+	const shape = toShape(thrown);
+	const context = buildContext(thrown, shape);
+	const message = shape.message ?? (thrown instanceof Error ? thrown.message : String(thrown));
+	if (isTimeout(thrown, shape)) return new _warlock_js_ai.ProviderTimeoutError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.status === 401 || shape.code === "invalid_api_key") return new _warlock_js_ai.ProviderAuthError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.code === "insufficient_quota") return new _warlock_js_ai.QuotaExceededError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.status === 429 || shape.code === "rate_limit_exceeded") return new _warlock_js_ai.ProviderRateLimitError(message, {
+		cause: thrown,
+		context,
+		retryAfter: parseRetryAfter(shape.headers)
+	});
+	if (shape.code === "context_length_exceeded") return new _warlock_js_ai.ContextLengthExceededError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.code === "content_filter") return new _warlock_js_ai.ContentFilterError(message, {
+		cause: thrown,
+		context,
+		reason: message
+	});
+	if (typeof shape.status === "number" && shape.status >= 400 && shape.status < 500) return new _warlock_js_ai.InvalidRequestError(message, {
+		cause: thrown,
+		context
+	});
+	return new _warlock_js_ai.ProviderError(message, {
+		cause: thrown,
+		context
+	});
+}
+/**
+* Read the raw error shape without depending on `instanceof APIError`
+* — some consumers wrap the SDK, and proxies sometimes strip the
+* prototype chain. Duck-typing on the visible fields is resilient to
+* both.
+*/
+function toShape(thrown) {
+	if (thrown instanceof openai.default.APIError) return {
+		status: thrown.status,
+		code: thrown.code,
+		message: thrown.message,
+		type: thrown.type,
+		param: thrown.param,
+		headers: thrown.headers,
+		name: thrown.name
+	};
+	if (typeof thrown === "object" && thrown !== null) {
+		const raw = thrown;
+		return {
+			status: typeof raw.status === "number" ? raw.status : void 0,
+			code: typeof raw.code === "string" ? raw.code : void 0,
+			message: typeof raw.message === "string" ? raw.message : void 0,
+			type: typeof raw.type === "string" ? raw.type : void 0,
+			param: typeof raw.param === "string" ? raw.param : void 0,
+			headers: typeof raw.headers === "object" && raw.headers !== null ? raw.headers : void 0,
+			name: typeof raw.name === "string" ? raw.name : void 0
+		};
+	}
+	return {};
+}
+/**
+* Decide whether the thrown value represents a timeout. OpenAI's SDK
+* throws `APIConnectionTimeoutError` for transport-level timeouts, and
+* Node surfaces `ETIMEDOUT` / `ECONNABORTED` on the lower socket
+* layer. Either signal counts.
+*/
+function isTimeout(thrown, shape) {
+	if (thrown instanceof openai.default.APIConnectionTimeoutError) return true;
+	if (shape.name === "APIConnectionTimeoutError") return true;
+	if (shape.code === "ETIMEDOUT" || shape.code === "ECONNABORTED") return true;
+	return false;
+}
+/**
+* Attach the raw diagnostic fields to `error.context` so consumers
+* have everything the provider surfaced without each subclass having
+* to redeclare them. Never includes `cause` — that lives on
+* `error.cause`.
+*/
+function buildContext(thrown, shape) {
+	const context = {};
+	if (shape.status !== void 0) context.status = shape.status;
+	if (shape.code) context.code = shape.code;
+	if (shape.type) context.type = shape.type;
+	if (shape.param) context.param = shape.param;
+	const requestId = readRequestId(thrown);
+	if (requestId) context.requestId = requestId;
+	return context;
+}
+/**
+* The request id OpenAI returned. Current SDKs expose it as
+* `APIError.requestID`; older ones and hand-rolled errors use
+* `request_id` / `requestId`. Extract defensively.
+*/
+function readRequestId(thrown) {
+	if (typeof thrown !== "object" || thrown === null) return;
+	const raw = thrown;
+	if (typeof raw.request_id === "string") return raw.request_id;
+	if (typeof raw.requestId === "string") return raw.requestId;
+	if (typeof raw.requestID === "string") return raw.requestID;
+}
+/**
+* Parse the `Retry-After` response header (seconds per HTTP spec)
+* into milliseconds so consumers can feed it straight to `setTimeout`.
+* Returns `undefined` when missing or unparseable.
+*/
+function parseRetryAfter(headers) {
+	if (!headers) return;
+	const raw = headers["retry-after"] ?? headers["Retry-After"];
+	if (!raw) return;
+	const seconds = Number(raw);
+	if (!Number.isFinite(seconds) || seconds < 0) return;
+	return Math.round(seconds * 1e3);
+}
+
+//#endregion
+//#region ../ai-openai/src/utils/map-responses-status.ts
+/**
+* Derive our `FinishReason` from a Responses terminal state. Responses has
+* no `finish_reason`, so it comes from `status`, `incomplete_details` and the
+* output items (design section 2, decision 5):
+*
+* - `completed` with a function call -> `tool_calls`; without -> `stop`
+*   (a refusal is ordinary text and also `stop`).
+* - `incomplete` / `max_output_tokens` and `max_messages` -> `length`.
+* - `incomplete` / `content_filter` and `steered` (or an unknown / missing
+*   reason) -> `error`. There is no neutral `content_filter` value.
+* - `cancelled`, `queued`, `in_progress` at a terminal read -> `error`.
+* - `failed` is not mapped here: callers throw it via {@link toResponseFailure}.
+*
+* A missing `status` is treated as `completed` (the SDK types it optional).
+*/
+function mapResponsesFinishReason(state) {
+	const status = state.status ?? "completed";
+	if (status === "completed") return state.hasToolCalls ? "tool_calls" : "stop";
+	if (status === "incomplete") {
+		const reason = state.incomplete_details?.reason;
+		return reason === "max_output_tokens" || reason === "max_messages" ? "length" : "error";
+	}
+	return "error";
+}
+/**
+* Turn a `failed` Responses payload into the same typed `AIError` the Chat
+* path throws for a provider failure, by running it through
+* `wrapOpenAIError` (so `rate_limit_exceeded` becomes a
+* `ProviderRateLimitError`, everything else a `ProviderError`, with `code`
+* and request id kept on `context`). The response id and model are added so
+* the failure is traceable.
+*/
+function toResponseFailure(response, model) {
+	const error = response.error;
+	const requestId = response._request_id;
+	const wrapped = wrapOpenAIError({
+		code: error?.code,
+		message: error?.message ?? "OpenAI response failed without an error object.",
+		...requestId ? { request_id: requestId } : {}
+	});
+	if (wrapped.context) Object.assign(wrapped.context, {
+		provider: "openai",
+		model,
+		responseId: response.id
+	});
+	return wrapped;
+}
+
+//#endregion
 //#region ../ai-openai/src/utils/map-finish-reason.ts
 const finishReasonMap = {
 	stop: "stop",
@@ -50,6 +268,219 @@ function mapFinishReason(raw) {
 	return finishReasonMap[raw ?? ""] ?? "error";
 }
 
+//#endregion
+//#region ../ai-openai/src/utils/prompt-cache-params.ts
+/**
+* Build the OpenAI-only prompt-cache request fields from the model config.
+* Returns nothing for any provider label other than `"openai"`: wrapper
+* endpoints use the same transport but may reject these OpenAI-only fields.
+*/
+function buildPromptCacheParams(provider, config) {
+	if (provider !== "openai") return {};
+	return {
+		...config.promptCacheKey !== void 0 ? { prompt_cache_key: config.promptCacheKey } : {},
+		...config.promptCacheRetention !== void 0 ? { prompt_cache_retention: config.promptCacheRetention } : {}
+	};
+}
+
+//#endregion
+//#region ../ai-openai/src/utils/reasoning-effort.ts
+/**
+* The installed OpenAI SDK 7.23.0 declares `reasoning_effort` as
+* `none | minimal | low | medium | high | xhigh | max` in
+* `openai/src/resources/shared.ts:367`. Its type notes that model support
+* varies but does not provide a model-family-specific accepted set, so map by
+* that union alone. This exhaustive record makes a future core level a
+* typecheck failure until its OpenAI clamp is consciously selected.
+*
+* Both the Chat Completions adapter (`reasoning_effort`) and the Responses
+* adapter (`reasoning.effort`) read this one table, so the two can never
+* disagree on how a neutral level reaches the wire.
+*/
+const EFFORT_TO_OPENAI_EFFORT = {
+	none: "none",
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max"
+};
+/**
+* Map a neutral `ReasoningEffort` to the value OpenAI accepts.
+*
+* @example
+* toOpenAIReasoningEffort("high"); // "high"
+*/
+function toOpenAIReasoningEffort(effort) {
+	return EFFORT_TO_OPENAI_EFFORT[effort];
+}
+
+//#endregion
+//#region ../ai-openai/src/utils/structured-output.ts
+/**
+* Map an explicit `responseFormat` override to the default
+* `structuredOutput` capability. Loose wire modes (`"json_object"`,
+* `"text"`) don't enforce shape, so the agent needs to see the soft
+* schema hint in the system prompt — that only happens when the
+* capability is `false`. Default (no override) stays `true` to
+* preserve the prior assumption that OpenAI models support strict
+* structured output.
+*/
+function inferStructuredOutput(responseFormat) {
+	if (responseFormat === "json_object" || responseFormat === "text") return false;
+	return true;
+}
+/**
+* Decide the structured-output mode for a call.
+*
+* When `override` (the `responseFormat` config) is set, it wins: `"text"`
+* emits nothing, `"json_object"` always picks the loose mode, and
+* `"json_schema"` picks strict mode (with the same strict-compatibility
+* safety check - a malformed schema still degrades to `json_object` rather
+* than 400). The override exists because some targets (older OpenAI models,
+* OpenRouter routes, Ollama OpenAI-compat) reject strict `json_schema`
+* outright.
+*
+* When the override is omitted, strict `json_schema` mode (token-level
+* enforcement) is used only when the schema is a proper root-object JSON
+* Schema whose every object lists all of its properties in `required`. For
+* anything else it falls back to loose `json_object` mode. Client-side
+* Standard Schema `validate()` still enforces the full shape.
+*/
+function planStructuredOutput(responseSchema, override) {
+	if (!responseSchema || override === "text") return { mode: "none" };
+	if (override === "json_object") return { mode: "json_object" };
+	if (isStrictCompatible(responseSchema)) return {
+		mode: "json_schema",
+		schema: responseSchema
+	};
+	return { mode: "json_object" };
+}
+/**
+* OpenAI strict `json_schema` mode requires the root to be a JSON Schema
+* object type (`{ type: "object", properties: ... }`). Anything else
+* (top-level arrays, primitives, unknown shapes) is rejected with a 400
+* before a token is sampled. Checked structurally here so the first call
+* doesn't crash on a malformed extraction.
+*/
+function isStrictCompatible(schema) {
+	return schema.type === "object" && typeof schema.properties === "object" && schema.properties !== null && isStrictSafeNode(schema);
+}
+/**
+* Recursively check the one strict-mode rule schemas most often trip on:
+* every object must list ALL of its `properties` in `required` (OpenAI
+* strict has no notion of optional - optional fields must be expressed as
+* nullable, e.g. `type: ["string", "null"]`, and still appear in
+* `required`). A schema that violates this anywhere in the tree is NOT sent
+* in strict mode, so a hand-built or optional-bearing schema can't 400 the
+* call ("'required' ... must include every key in properties").
+*/
+function isStrictSafeNode(node) {
+	if (!node || typeof node !== "object") return true;
+	const record = node;
+	if (record.type === "object" && record.properties && typeof record.properties === "object") {
+		const properties = record.properties;
+		const keys = Object.keys(properties);
+		const required = Array.isArray(record.required) ? record.required : [];
+		if (keys.some((key) => !required.includes(key))) return false;
+		for (const key of keys) if (!isStrictSafeNode(properties[key])) return false;
+	}
+	if (record.items !== void 0 && !isStrictSafeNode(record.items)) return false;
+	for (const branch of [
+		"anyOf",
+		"allOf",
+		"oneOf"
+	]) {
+		const value = record[branch];
+		if (Array.isArray(value) && value.some((sub) => !isStrictSafeNode(sub))) return false;
+	}
+	return true;
+}
+
+//#endregion
+//#region ../ai-openai/src/utils/reasoning-replay.ts
+/**
+* Key under `ModelToolCallRequest.providerMetadata` owned by the Responses
+* adapter. This name and the shape below are PERSISTED in users' conversation
+* memory, so they are part of the public contract: do not rename.
+*/
+const RESPONSES_METADATA_KEY = "openaiResponses";
+/**
+* Keep only the reasoning items that can actually be replayed. With
+* `store: false` the server keeps nothing, so an item without
+* `encrypted_content` has nothing to restore and replaying its bare `id`
+* would be rejected as an unknown item.
+*/
+function pickReplayableReasoning(items) {
+	return items.filter((item) => typeof item.encrypted_content === "string" && item.encrypted_content !== "");
+}
+/**
+* Attach the turn's reasoning items to the FIRST tool call only (parallel
+* calls do not each repeat the blobs). Returns the calls unchanged when
+* there is nothing to replay or no tool call to ride on (a text-only turn is
+* deliberately not replayed, decision 2). Does not mutate its input.
+*/
+function attachReasoningReplay(toolCalls, model, reasoningItems) {
+	const replayable = pickReplayableReasoning(reasoningItems);
+	const [first, ...rest] = toolCalls;
+	if (first === void 0 || replayable.length === 0) return [...toolCalls];
+	const metadata = {
+		model,
+		reasoningItems: replayable
+	};
+	return [{
+		...first,
+		providerMetadata: {
+			...first.providerMetadata,
+			[RESPONSES_METADATA_KEY]: metadata
+		}
+	}, ...rest];
+}
+/**
+* Read the stored reasoning items off an assistant turn's tool calls, for
+* replay on `model`. Returns `[]` when the key is absent or malformed, or
+* when the stored `model` differs from `model` (encrypted blobs are not
+* portable across models, design section 4). De-duplicates by item `id`.
+*/
+function readReasoningReplay(toolCalls, model) {
+	const seen = /* @__PURE__ */ new Set();
+	const items = [];
+	for (const call of toolCalls) {
+		const stored = call.providerMetadata?.[RESPONSES_METADATA_KEY];
+		if (!isReplayMetadata(stored) || stored.model !== model) continue;
+		for (const item of stored.reasoningItems) {
+			if (item?.type !== "reasoning" || seen.has(item.id)) continue;
+			seen.add(item.id);
+			items.push(item);
+		}
+	}
+	return items;
+}
+/**
+* Shape a stored reasoning item for the next request. Sends the four fields
+* a stateless replay needs (`type`, `id`, `summary`, `encrypted_content`) and
+* drops the response-only `status` and the optional raw `content`.
+*
+* UNVERIFIED: the SDK types accept the full item as input (`ResponseInputItem`
+* includes `ResponseReasoningItem`) and do not say which fields the API
+* refuses on replay with `store: false`. This is the conservative guess; a
+* live probe settles it.
+*/
+function toReplayReasoningItem(item) {
+	return {
+		type: "reasoning",
+		id: item.id,
+		summary: Array.isArray(item.summary) ? item.summary : [],
+		encrypted_content: item.encrypted_content
+	};
+}
+function isReplayMetadata(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.model === "string" && Array.isArray(candidate.reasoningItems);
+}
+
 //#endregion
 //#region ../ai-openai/src/utils/to-openai-messages.ts
 /**
@@ -178,7 +609,7 @@ function toOpenAIContentPart(part) {
 	};
 	if (part.type === "image") return {
 		type: "image_url",
-		image_url: { url: "url" in part.source ? part.source.url : `data:${part.source.mediaType};base64,${part.source.base64}` }
+		image_url: { url: toImageUrl(part.source) }
 	};
 	if (part.type === "pdf") {
 		if ("url" in part.source) throw new _warlock_js_ai.InvalidRequestError("OpenAI chat completions cannot fetch a remote-URL PDF; supply base64 document bytes instead.");
@@ -200,6 +631,13 @@ function toOpenAIContentPart(part) {
 	};
 }
 /**
+* Render an image source as a URL: a remote URL passes through, inlined
+* base64 bytes become a `data:` URL. Shared with the Responses adapter.
+*/
+function toImageUrl(source) {
+	return "url" in source ? source.url : `data:${source.mediaType};base64,${source.base64}`;
+}
+/**
 * Narrow a neutral audio media type to the two formats OpenAI's
 * `input_audio` accepts (`wav` / `mp3`). An unsupported type raises a
 * typed `InvalidRequestError` up front rather than a provider 400.
@@ -228,7 +666,7 @@ function toOpenAITools(tools) {
 		function: {
 			name: tool.name,
 			description: tool.description,
-			parameters: toParameters(tool.input)
+			parameters: toToolParameters(tool.input)
 		}
 	}));
 }
@@ -238,165 +676,171 @@ function toOpenAITools(tools) {
 * failed extraction) degrades to an empty-object schema so the tool
 * still registers and the model simply sees no parameters.
 */
-function toParameters(input) {
-	const schema = (0, _warlock_js_ai.extractJsonSchema)(input);
-	if (schema && schema.type === "object") return schema;
-	return {
-		type: "object",
-		properties: {}
-	};
-}
-
-//#endregion
-//#region ../ai-openai/src/utils/wrap-openai-error.ts
-/**
-* Wrap any thrown value caught inside the OpenAI adapter into the
-* appropriate `@warlock.js/ai` `AIError` subclass.
-*
-* **Dispatch strategy.** Prefers `APIError.code` when present (stable
-* machine identifier across SDK versions), falls back to `status` when
-* `code` is missing (common with proxied deployments that strip the
-* field). Name-based detection (`APIConnectionTimeoutError`) catches
-* transport-layer errors that never produced an HTTP response.
-*
-* `AIError` instances are returned unchanged — callers can pass the
-* error through `try/catch/throw wrap(e)` pipelines without accidental
-* double-wrapping.
-*
-* @example
-* try {
-*   return await this.client.chat.completions.create(...);
-* } catch (thrown) {
-*   throw wrapOpenAIError(thrown);
-* }
-*/
-function wrapOpenAIError(thrown) {
-	if (thrown instanceof _warlock_js_ai.AIError) return thrown;
-	const shape = toShape(thrown);
-	const context = buildContext(thrown, shape);
-	const message = shape.message ?? (thrown instanceof Error ? thrown.message : String(thrown));
-	if (isTimeout(thrown, shape)) return new _warlock_js_ai.ProviderTimeoutError(message, {
-		cause: thrown,
-		context
-	});
-	if (shape.status === 401 || shape.code === "invalid_api_key") return new _warlock_js_ai.ProviderAuthError(message, {
-		cause: thrown,
-		context
-	});
-	if (shape.code === "insufficient_quota") return new _warlock_js_ai.QuotaExceededError(message, {
-		cause: thrown,
-		context
-	});
-	if (shape.status === 429 || shape.code === "rate_limit_exceeded") return new _warlock_js_ai.ProviderRateLimitError(message, {
-		cause: thrown,
-		context,
-		retryAfter: parseRetryAfter(shape.headers)
-	});
-	if (shape.code === "context_length_exceeded") return new _warlock_js_ai.ContextLengthExceededError(message, {
-		cause: thrown,
-		context
-	});
-	if (shape.code === "content_filter") return new _warlock_js_ai.ContentFilterError(message, {
-		cause: thrown,
-		context,
-		reason: message
-	});
-	if (typeof shape.status === "number" && shape.status >= 400 && shape.status < 500) return new _warlock_js_ai.InvalidRequestError(message, {
-		cause: thrown,
-		context
-	});
-	return new _warlock_js_ai.ProviderError(message, {
-		cause: thrown,
-		context
-	});
-}
-/**
-* Read the raw error shape without depending on `instanceof APIError`
-* — some consumers wrap the SDK, and proxies sometimes strip the
-* prototype chain. Duck-typing on the visible fields is resilient to
-* both.
-*/
-function toShape(thrown) {
-	if (thrown instanceof openai.default.APIError) return {
-		status: thrown.status,
-		code: thrown.code,
-		message: thrown.message,
-		type: thrown.type,
-		param: thrown.param,
-		headers: thrown.headers,
-		name: thrown.name
-	};
-	if (typeof thrown === "object" && thrown !== null) {
-		const raw = thrown;
-		return {
-			status: typeof raw.status === "number" ? raw.status : void 0,
-			code: typeof raw.code === "string" ? raw.code : void 0,
-			message: typeof raw.message === "string" ? raw.message : void 0,
-			type: typeof raw.type === "string" ? raw.type : void 0,
-			param: typeof raw.param === "string" ? raw.param : void 0,
-			headers: typeof raw.headers === "object" && raw.headers !== null ? raw.headers : void 0,
-			name: typeof raw.name === "string" ? raw.name : void 0
-		};
-	}
-	return {};
-}
-/**
-* Decide whether the thrown value represents a timeout. OpenAI's SDK
-* throws `APIConnectionTimeoutError` for transport-level timeouts, and
-* Node surfaces `ETIMEDOUT` / `ECONNABORTED` on the lower socket
-* layer. Either signal counts.
-*/
-function isTimeout(thrown, shape) {
-	if (thrown instanceof openai.default.APIConnectionTimeoutError) return true;
-	if (shape.name === "APIConnectionTimeoutError") return true;
-	if (shape.code === "ETIMEDOUT" || shape.code === "ECONNABORTED") return true;
-	return false;
+function toToolParameters(input) {
+	const schema = (0, _warlock_js_ai.extractJsonSchema)(input);
+	if (schema && schema.type === "object") return schema;
+	return {
+		type: "object",
+		properties: {}
+	};
 }
+
+//#endregion
+//#region ../ai-openai/src/utils/to-responses-input.ts
 /**
-* Attach the raw diagnostic fields to `error.context` so consumers
-* have everything the provider surfaced without each subclass having
-* to redeclare them. Never includes `cause` — that lives on
-* `error.cause`.
+* Convert vendor-neutral `Message[]` into the Responses request pieces.
+*
+* - The FIRST system message becomes `instructions` (decision 9: it avoids
+*   the `system` vs `developer` role question on reasoning models). Any
+*   later system message stays inline as a `system` role item.
+* - `user` / `assistant` text becomes an `EasyInputMessage` (`{ role,
+*   content }`). Multipart user content becomes `input_text` / `input_image`
+*   parts; images always carry `detail: "auto"` because `ResponseInputImage.detail`
+*   is required by the SDK types.
+* - An assistant message that requested tools becomes its text (when
+*   non-empty) followed by one top-level `function_call` item per call; our
+*   `ModelToolCallRequest.id` is the wire `call_id`. No item `id` is sent:
+*   with `store: false` nothing was persisted for it to refer to.
+* - When `model` is given, reasoning items stored on the turn's tool calls
+*   (`providerMetadata.openaiResponses`, see `reasoning-replay.ts`) are
+*   emitted BEFORE the turn's text and `function_call` items (the order the
+*   API produced them), only if they were produced by that same model.
+*   Without `model` nothing is replayed.
+* - A `tool` message becomes a top-level `function_call_output` item.
+*
+* PDF and audio parts are rejected with a typed `InvalidRequestError`: the
+* Responses adapter declares those capabilities off, so they only arrive
+* here if a caller bypasses the agent's capability gate.
+*
+* @example
+* toResponsesInput([
+*   { role: "system", content: "Be brief." },
+*   { role: "user", content: "Hi" },
+* ]);
+* // { instructions: "Be brief.", input: [{ role: "user", content: "Hi" }] }
 */
-function buildContext(thrown, shape) {
-	const context = {};
-	if (shape.status !== void 0) context.status = shape.status;
-	if (shape.code) context.code = shape.code;
-	if (shape.type) context.type = shape.type;
-	if (shape.param) context.param = shape.param;
-	const requestId = readRequestId(thrown);
-	if (requestId) context.requestId = requestId;
-	return context;
+function toResponsesInput(messages, model) {
+	const input = [];
+	let instructions;
+	let instructionsTaken = false;
+	for (const message of messages) {
+		if (message.role === "system") {
+			const text = stringifyContent(message.content);
+			if (!instructionsTaken) {
+				instructionsTaken = true;
+				instructions = text === "" ? void 0 : text;
+				continue;
+			}
+			input.push({
+				role: "system",
+				content: text
+			});
+			continue;
+		}
+		if (message.role === "tool") {
+			input.push({
+				type: "function_call_output",
+				call_id: message.toolCallId ?? "",
+				output: stringifyContent(message.content)
+			});
+			continue;
+		}
+		if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {
+			const text = stringifyContent(message.content);
+			if (model !== void 0) for (const item of readReasoningReplay(message.toolCalls, model)) input.push(toReplayReasoningItem(item));
+			if (text !== "") input.push({
+				role: "assistant",
+				content: text
+			});
+			for (const call of message.toolCalls) input.push({
+				type: "function_call",
+				call_id: call.id,
+				name: call.name,
+				arguments: JSON.stringify(call.input ?? {})
+			});
+			continue;
+		}
+		if (message.role === "user" && Array.isArray(message.content)) {
+			input.push({
+				role: "user",
+				content: message.content.map(toResponsesContentPart)
+			});
+			continue;
+		}
+		input.push({
+			role: message.role,
+			content: stringifyContent(message.content)
+		});
+	}
+	return {
+		...instructions !== void 0 ? { instructions } : {},
+		input
+	};
+}
+/** Map a resolved `ContentPart` to a Responses input content part (text and images only). */
+function toResponsesContentPart(part) {
+	if (part.type === "text") return {
+		type: "input_text",
+		text: part.text
+	};
+	if (part.type === "image") return {
+		type: "input_image",
+		image_url: toImageUrl(part.source),
+		detail: "auto"
+	};
+	throw new _warlock_js_ai.InvalidRequestError(`OpenAI api: "responses" does not accept ${part.type} input in this adapter; use api: "chat" for ${part.type} attachments.`);
 }
+
+//#endregion
+//#region ../ai-openai/src/utils/to-responses-tools.ts
 /**
-* The request id OpenAI returned. Current SDKs expose it as
-* `APIError.requestID`; older ones and hand-rolled errors use
-* `request_id` / `requestId`. Extract defensively.
+* Convert vendor-neutral `ToolConfig[]` to Responses function tools.
+*
+* Responses tools are FLAT (`name` / `description` / `parameters` sit beside
+* `type`, not under a nested `function` object) and `strict` is required by
+* the SDK type (`FunctionTool.strict: boolean | null`). The Chat path never
+* sets `strict` (non-strict is the OpenAI default there), so every tool is
+* sent with `strict: false` to keep the same behavior.
+*
+* @example
+* toResponsesTools([weatherTool]);
+* // [{ type: "function", name: "getWeather", description: "...", parameters: {...}, strict: false }]
 */
-function readRequestId(thrown) {
-	if (typeof thrown !== "object" || thrown === null) return;
-	const raw = thrown;
-	if (typeof raw.request_id === "string") return raw.request_id;
-	if (typeof raw.requestId === "string") return raw.requestId;
-	if (typeof raw.requestID === "string") return raw.requestID;
+function toResponsesTools(tools) {
+	if (!tools || tools.length === 0) return;
+	return tools.map((tool) => ({
+		type: "function",
+		name: tool.name,
+		description: tool.description,
+		parameters: toToolParameters(tool.input),
+		strict: false
+	}));
 }
 /**
-* Parse the `Retry-After` response header (seconds per HTTP spec)
-* into milliseconds so consumers can feed it straight to `setTimeout`.
-* Returns `undefined` when missing or unparseable.
+* Read an optional `toolChoice` call option into the Responses `tool_choice`.
+*
+* `ModelCallOptions` does not declare `toolChoice` today (it only arrives
+* through the open index signature), so the value is validated here rather
+* than trusted. Accepted: `"none" | "auto" | "required"`, or a forced
+* function as `{ name }` / `{ type: "function", name }` (the Chat-style
+* nested `{ type: "function", function: { name } }` is also accepted). The
+* Responses form is flat: `{ type: "function", name }`. Anything else yields
+* `undefined`, leaving the provider default.
 */
-function parseRetryAfter(headers) {
-	if (!headers) return;
-	const raw = headers["retry-after"] ?? headers["Retry-After"];
-	if (!raw) return;
-	const seconds = Number(raw);
-	if (!Number.isFinite(seconds) || seconds < 0) return;
-	return Math.round(seconds * 1e3);
+function toResponsesToolChoice(toolChoice) {
+	if (toolChoice === "none" || toolChoice === "auto" || toolChoice === "required") return toolChoice;
+	if (typeof toolChoice !== "object" || toolChoice === null) return;
+	const record = toolChoice;
+	const name = typeof record.name === "string" ? record.name : record.function?.name;
+	if (typeof name === "string" && name !== "") return {
+		type: "function",
+		name
+	};
 }
 
 //#endregion
 //#region ../ai-openai/src/embedder.ts
-const LOG_MODULE$4 = "ai.openai";
+const LOG_MODULE$5 = "ai.openai";
 /**
 * OpenAI-backed implementation of `EmbedderContract`.
 *
@@ -461,7 +905,7 @@ var OpenAIEmbedder = class {
 	* plus a camelCase usage object for the caller to shape.
 	*/
 	async request(input) {
-		this.logger.debug(LOG_MODULE$4, "embedder.request", "embeddings.create", {
+		this.logger.debug(LOG_MODULE$5, "embedder.request", "embeddings.create", {
 			model: this.name,
 			batch: Array.isArray(input),
 			count: Array.isArray(input) ? input.length : 1
@@ -475,13 +919,13 @@ var OpenAIEmbedder = class {
 			});
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$4, "embedder.error", wrapped.message, {
+			this.logger.error(LOG_MODULE$5, "embedder.error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
 			throw wrapped;
 		}
-		this.logger.debug(LOG_MODULE$4, "embedder.response", "embeddings.create returned", {
+		this.logger.debug(LOG_MODULE$5, "embedder.response", "embeddings.create returned", {
 			dimensions: response.data[0]?.embedding.length,
 			usage: {
 				promptTokens: response.usage.prompt_tokens,
@@ -505,7 +949,7 @@ var OpenAIEmbedder = class {
 
 //#endregion
 //#region ../ai-openai/src/image.ts
-const LOG_MODULE$3 = "ai.openai";
+const LOG_MODULE$4 = "ai.openai";
 /** Map a neutral output container to its IANA media type. */
 function mediaTypeFor(format) {
 	switch (format) {
@@ -564,7 +1008,7 @@ var OpenAIImageModel = class {
 		if (!isGptImage && responseFormat) body.response_format = responseFormat;
 		if (isGptImage && options?.format !== void 0) body.output_format = options.format;
 		if (options?.background !== void 0) body.background = options.background;
-		this.logger.debug(LOG_MODULE$3, "image.request", "images.generate", {
+		this.logger.debug(LOG_MODULE$4, "image.request", "images.generate", {
 			model: this.name,
 			count: options?.count ?? 1
 		});
@@ -573,7 +1017,7 @@ var OpenAIImageModel = class {
 			response = await this.client.images.generate(body, options?.signal ? { signal: options.signal } : void 0);
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$3, "image.error", wrapped.message, {
+			this.logger.error(LOG_MODULE$4, "image.error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
@@ -589,7 +1033,7 @@ var OpenAIImageModel = class {
 			output: 0,
 			total: 0
 		};
-		this.logger.debug(LOG_MODULE$3, "image.response", "images.generate succeeded", {
+		this.logger.debug(LOG_MODULE$4, "image.response", "images.generate succeeded", {
 			images: images.length,
 			usage
 		});
@@ -708,37 +1152,7 @@ function inferVisionCapability(modelName) {
 
 //#endregion
 //#region ../ai-openai/src/model.ts
-const LOG_MODULE$2 = "ai.openai";
-/**
-* The installed OpenAI SDK 7.23.0 declares `reasoning_effort` as
-* `none | minimal | low | medium | high | xhigh | max` in
-* `openai/src/resources/shared.ts:367`. Its type notes that model support
-* varies but does not provide a model-family-specific accepted set, so map by
-* that union alone. This exhaustive record makes a future core level a
-* typecheck failure until its OpenAI clamp is consciously selected.
-*/
-const EFFORT_TO_OPENAI_EFFORT = {
-	none: "none",
-	minimal: "minimal",
-	low: "low",
-	medium: "medium",
-	high: "high",
-	xhigh: "xhigh",
-	max: "max"
-};
-/**
-* Map an explicit `responseFormat` override to the default
-* `structuredOutput` capability. Loose wire modes (`"json_object"`,
-* `"text"`) don't enforce shape, so the agent needs to see the soft
-* schema hint in the system prompt — that only happens when the
-* capability is `false`. Default (no override) stays `true` to
-* preserve the prior assumption that OpenAI models support strict
-* structured output.
-*/
-function inferStructuredOutput(responseFormat) {
-	if (responseFormat === "json_object" || responseFormat === "text") return false;
-	return true;
-}
+const LOG_MODULE$3 = "ai.openai";
 /**
 * OpenAI-backed implementation of `ModelContract`.
 *
@@ -779,6 +1193,11 @@ function inferStructuredOutput(responseFormat) {
 var OpenAIModel = class {
 	constructor(client, config, provider = "openai") {
 		this.logger = _warlock_js_logger.log;
+		if (config.api === "responses") throw new _warlock_js_ai.InvalidRequestError("OpenAIModel speaks Chat Completions only and cannot serve api: \"responses\". Use OpenAISDK.model({ api: \"responses\" }) on the direct OpenAI provider.", { context: {
+			provider,
+			model: config.name,
+			api: config.api
+		} });
 		this.client = client;
 		this.config = config;
 		this.name = config.name;
@@ -800,7 +1219,7 @@ var OpenAIModel = class {
 	* instance's `ModelConfig` defaults for this call only.
 	*/
 	async complete(messages, options) {
-		this.logger.debug(LOG_MODULE$2, "request", "Starting call to chat.completions", {
+		this.logger.debug(LOG_MODULE$3, "request", "Starting call to chat.completions", {
 			model: this.name,
 			messageCount: messages.length,
 			streaming: false,
@@ -812,14 +1231,14 @@ var OpenAIModel = class {
 				model: this.name,
 				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
 				...this.buildSamplingParams(options),
-				...this.buildPromptCacheParams(),
+				...buildPromptCacheParams(this.provider, this.config),
 				tools: toOpenAITools(options?.tools),
 				...this.buildResponseFormat(options?.responseSchema),
 				...this.buildReasoningParams(options?.reasoning, Boolean(options?.tools?.length))
 			}, options?.signal ? { signal: options.signal } : void 0);
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$3, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
@@ -833,7 +1252,7 @@ var OpenAIModel = class {
 		} });
 		const finishReason = mapFinishReason(choice.finish_reason);
 		const usage = this.extractUsage(response.usage);
-		this.logger.debug(LOG_MODULE$2, "response", "call to chat.completions succeeded", {
+		this.logger.debug(LOG_MODULE$3, "response", "call to chat.completions succeeded", {
 			finishReason,
 			usage
 		});
@@ -851,7 +1270,7 @@ var OpenAIModel = class {
 	* Callers consume it with `for await`.
 	*/
 	async *stream(messages, options) {
-		this.logger.debug(LOG_MODULE$2, "request", "Starting streaming call to chat.completions", {
+		this.logger.debug(LOG_MODULE$3, "request", "Starting streaming call to chat.completions", {
 			model: this.name,
 			messageCount: messages.length,
 			streaming: true,
@@ -863,7 +1282,7 @@ var OpenAIModel = class {
 				model: this.name,
 				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
 				...this.buildSamplingParams(options),
-				...this.buildPromptCacheParams(),
+				...buildPromptCacheParams(this.provider, this.config),
 				tools: toOpenAITools(options?.tools),
 				stream: true,
 				stream_options: { include_usage: true },
@@ -872,7 +1291,7 @@ var OpenAIModel = class {
 			}, options?.signal ? { signal: options.signal } : void 0);
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$3, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
@@ -927,14 +1346,14 @@ var OpenAIModel = class {
 			}
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$3, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
 			throw wrapped;
 		}
 		const finishReason = mapFinishReason(rawFinishReason);
-		this.logger.debug(LOG_MODULE$2, "response", "Streaming call to chat.completions succeeded", {
+		this.logger.debug(LOG_MODULE$3, "response", "Streaming call to chat.completions succeeded", {
 			finishReason,
 			usage
 		});
@@ -944,101 +1363,31 @@ var OpenAIModel = class {
 			usage
 		};
 	}
-	/** OpenAI-only request fields; wrappers use the same transport but not this wire extension. */
-	buildPromptCacheParams() {
-		if (this.provider !== "openai") return {};
-		return {
-			...this.config.promptCacheKey !== void 0 ? { prompt_cache_key: this.config.promptCacheKey } : {},
-			...this.config.promptCacheRetention !== void 0 ? { prompt_cache_retention: this.config.promptCacheRetention } : {}
-		};
-	}
 	/** Map the neutral cache hint only for the direct OpenAI provider. */
 	promptCacheBreakpoints(options) {
 		return this.provider === "openai" ? options?.cacheControl?.breakpoints ?? 0 : 0;
 	}
 	/**
 	* Translate the neutral `responseSchema` option into OpenAI's
-	* `response_format` parameter.
-	*
-	* When `config.responseFormat` is set, it wins: `"text"` emits no
-	* `response_format` at all, `"json_object"` always picks the loose
-	* mode, and `"json_schema"` picks strict mode (with the same
-	* `isStrictCompatible` safety check — a malformed schema still
-	* degrades to `json_object` rather than 400). The override exists
-	* because some targets (older OpenAI models, OpenRouter routes,
-	* Ollama OpenAI-compat) reject strict `json_schema` outright.
-	*
-	* When the override is omitted, uses strict `json_schema` mode
-	* (token-level enforcement) only when the schema is a proper
-	* root-object JSON Schema (`{ type: "object", properties: ... }`).
-	* For anything else — malformed extractor output, non-object
-	* schemas, or future shapes we haven't tested — falls back to loose
-	* `json_object` mode, which guarantees *some* valid JSON without
-	* enforcing shape. The agent's soft instruction already embeds the
-	* schema text in the system prompt when the model declares no
-	* native structured-output capability, so shape validation still
-	* runs client-side via the Standard Schema `validate()` call.
+	* `response_format` parameter. The mode decision (override handling,
+	* strict-compatibility downgrade to `json_object`) lives in
+	* `planStructuredOutput`, shared with the Responses adapter.
 	*
 	* Returns an empty spread when no schema was supplied, so the caller
 	* can unconditionally `...buildResponseFormat(...)` into the request.
 	*/
 	buildResponseFormat(responseSchema) {
-		if (!responseSchema) return {};
-		const override = this.config.responseFormat;
-		if (override === "text") return {};
-		if (override === "json_object") return { response_format: { type: "json_object" } };
-		if (this.isStrictCompatible(responseSchema)) return { response_format: {
+		const plan = planStructuredOutput(responseSchema, this.config.responseFormat);
+		if (plan.mode === "json_schema") return { response_format: {
 			type: "json_schema",
 			json_schema: {
 				name: "response",
-				schema: responseSchema,
+				schema: plan.schema,
 				strict: true
 			}
 		} };
-		return { response_format: { type: "json_object" } };
-	}
-	/**
-	* OpenAI strict `json_schema` mode requires the root to be a JSON
-	* Schema object type (`{ type: "object", properties: ... }`). Anything
-	* else (top-level arrays, primitives, unknown shapes) is rejected with
-	* a 400 before a token is sampled. We check structurally here so the
-	* first call doesn't crash on a malformed extraction — loose
-	* `json_object` mode is a safe degradation.
-	*/
-	isStrictCompatible(schema) {
-		return schema.type === "object" && typeof schema.properties === "object" && schema.properties !== null && this.isStrictSafeNode(schema);
-	}
-	/**
-	* Recursively check the one strict-mode rule schemas most often trip on:
-	* every object must list ALL of its `properties` in `required` (OpenAI
-	* strict has no notion of optional — optional fields must be expressed
-	* as nullable, e.g. `type: ["string", "null"]`, and still appear in
-	* `required`). A schema that violates this anywhere in the tree is NOT
-	* sent in strict `json_schema` mode — it degrades to loose
-	* `json_object` so a hand-built or optional-bearing schema can't 400
-	* the call ("'required' ... must include every key in properties").
-	* Client-side `validate()` still enforces the full shape.
-	*/
-	isStrictSafeNode(node) {
-		if (!node || typeof node !== "object") return true;
-		const record = node;
-		if (record.type === "object" && record.properties && typeof record.properties === "object") {
-			const properties = record.properties;
-			const keys = Object.keys(properties);
-			const required = Array.isArray(record.required) ? record.required : [];
-			if (keys.some((key) => !required.includes(key))) return false;
-			for (const key of keys) if (!this.isStrictSafeNode(properties[key])) return false;
-		}
-		if (record.items !== void 0 && !this.isStrictSafeNode(record.items)) return false;
-		for (const branch of [
-			"anyOf",
-			"allOf",
-			"oneOf"
-		]) {
-			const value = record[branch];
-			if (Array.isArray(value) && value.some((sub) => !this.isStrictSafeNode(sub))) return false;
-		}
-		return true;
+		if (plan.mode === "json_object") return { response_format: { type: "json_object" } };
+		return {};
 	}
 	/**
 	* Normalize OpenAI's `usage` block (which may be absent on some responses
@@ -1060,15 +1409,13 @@ var OpenAIModel = class {
 			output: 0,
 			total: 0
 		};
-		const cachedTokens = raw.prompt_tokens_details?.cached_tokens;
-		const reasoningTokens = raw.completion_tokens_details?.reasoning_tokens;
-		return {
+		return buildUsage({
 			input: raw.prompt_tokens,
 			output: raw.completion_tokens,
 			total: raw.total_tokens,
-			...cachedTokens !== void 0 && cachedTokens > 0 ? { cachedTokens } : {},
-			...reasoningTokens !== void 0 && reasoningTokens > 0 ? { reasoningTokens } : {}
-		};
+			cachedTokens: raw.prompt_tokens_details?.cached_tokens,
+			reasoningTokens: raw.completion_tokens_details?.reasoning_tokens
+		});
 	}
 	/**
 	* Translate the neutral `ModelCallOptions.reasoning` hint into OpenAI's
@@ -1125,7 +1472,7 @@ var OpenAIModel = class {
 	buildReasoningParams(reasoning, hasTools) {
 		if (!this.capabilities.reasoning) return {};
 		if (!reasoning?.effort) return hasTools ? { reasoning_effort: "none" } : {};
-		return { reasoning_effort: EFFORT_TO_OPENAI_EFFORT[reasoning.effort] };
+		return { reasoning_effort: toOpenAIReasoningEffort(reasoning.effort) };
 	}
 	/**
 	* Reshape OpenAI's `tool_calls` array into the neutral
@@ -1145,6 +1492,318 @@ var OpenAIModel = class {
 	}
 };
 
+//#endregion
+//#region ../ai-openai/src/responses-model.ts
+const LOG_MODULE$2 = "ai.openai";
+/**
+* OpenAI Responses API implementation of `ModelContract` (`api: "responses"`).
+*
+* **Role.** A sibling of `OpenAIModel` that speaks `POST /v1/responses`
+* instead of Chat Completions. Its point is letting a tool-using agent run a
+* reasoning model with reasoning ON: the Chat path has to force
+* `reasoning_effort: "none"` whenever tools are attached, Responses does not.
+*
+* **Why a separate class.** Only `OpenAISDK.model()` constructs it, and only
+* for the direct `"openai"` provider. The wrapper packages (deepseek, groq,
+* xai, mistral) build `OpenAIModel` and cannot reach this class, so an
+* endpoint that does not implement `/v1/responses` is never sent there. The
+* constructor re-checks the provider label as a second lock.
+*
+* **Stateless.** Every request sends `store: false`; nothing is kept on the
+* server and no `previous_response_id` is used. Full history is re-sent each
+* call, exactly like the Chat path.
+*
+* **Reasoning replay.** Every request asks for
+* `include: ["reasoning.encrypted_content"]`. The `reasoning` items of a
+* tool-calling turn are stored on the FIRST tool call as
+* `providerMetadata.openaiResponses = { model, reasoningItems }` and sent back
+* before that turn's `function_call` items on the next request (only when the
+* stored model equals the current one). Text-only turns are not replayed.
+*
+* **Streaming.** `stream()` uses `responses.create({ stream: true })` and yields
+* the same chunk sequence as the Chat path: text `delta`s, then the
+* `tool-call`s, then one `done`.
+*/
+var OpenAIResponsesModel = class {
+	constructor(client, config, provider = "openai") {
+		this.logger = _warlock_js_logger.log;
+		if (provider !== "openai") throw new _warlock_js_ai.InvalidRequestError(`api: "responses" is supported only on the direct "openai" provider; got provider "${provider}".`, { context: {
+			provider,
+			model: config.name,
+			api: "responses"
+		} });
+		this.client = client;
+		this.config = config;
+		this.name = config.name;
+		this.provider = provider;
+		this.pricing = config.pricing;
+		this.capabilities = {
+			structuredOutput: config.structuredOutput ?? inferStructuredOutput(config.responseFormat),
+			vision: config.vision ?? inferVisionCapability(config.name),
+			reasoning: config.reasoning ?? inferReasoningCapability(config.name),
+			promptCaching: true,
+			pdf: false,
+			audio: false
+		};
+	}
+	/**
+	* Single-shot completion against `client.responses.create`. Sends the full
+	* history as Responses `input` items, walks `response.output`, and reshapes
+	* it into a vendor-neutral `ModelResponse`. Per-call `options` override the
+	* instance defaults for this call only.
+	*/
+	async complete(messages, options) {
+		this.logger.debug(LOG_MODULE$2, "request", "Starting call to responses.create", {
+			model: this.name,
+			messageCount: messages.length,
+			streaming: false,
+			toolCount: options?.tools?.length ?? 0
+		});
+		let response;
+		try {
+			response = await this.client.responses.create(this.buildRequest(messages, options), options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			throw this.logAndWrap(thrown);
+		}
+		if (response.status === "failed") throw this.logAndWrap(toResponseFailure(response, this.name));
+		const output = Array.isArray(response.output) ? response.output : [];
+		const { content, toolCalls } = this.readOutput(output);
+		const finishReason = mapResponsesFinishReason({
+			status: response.status,
+			incomplete_details: response.incomplete_details,
+			hasToolCalls: toolCalls !== void 0
+		});
+		const usage = this.extractUsage(response.usage);
+		this.logger.debug(LOG_MODULE$2, "response", "call to responses.create succeeded", {
+			finishReason,
+			usage
+		});
+		return {
+			content,
+			finishReason,
+			usage,
+			...toolCalls ? { toolCalls } : {}
+		};
+	}
+	/**
+	* Incremental streaming completion via `responses.create({ stream: true })`
+	* (the SDK's `Stream<ResponseStreamEvent>`, `responses.d.ts:55`). Yields the
+	* same neutral `ModelStreamChunk` sequence as the Chat path:
+	*
+	* - `response.output_text.delta` / `response.refusal.delta` -> `delta`.
+	* - `response.output_item.done` with a completed `function_call` item ->
+	*   buffered; `reasoning` items are captured for replay. The `done` copy is
+	*   used because the `added` copy may be incomplete (`responses.d.ts:5711`).
+	* - After the loop: the buffered `tool-call`s (the first carries the
+	*   replay metadata), then a single `done` with the finish reason and usage
+	*   from `response.completed` / `response.incomplete`.
+	* - `response.failed` and `error` events throw a typed `AIError`; a stream
+	*   that ends with no terminal event throws `ProviderError`.
+	* - Abort goes through the request `signal`; the SDK rejects the read and
+	*   the error is wrapped like any other.
+	*/
+	async *stream(messages, options) {
+		this.logger.debug(LOG_MODULE$2, "request", "Starting streaming call to responses.create", {
+			model: this.name,
+			messageCount: messages.length,
+			streaming: true,
+			toolCount: options?.tools?.length ?? 0
+		});
+		let events;
+		try {
+			events = await this.client.responses.create({
+				...this.buildRequest(messages, options),
+				stream: true
+			}, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			throw this.logAndWrap(thrown);
+		}
+		const toolCalls = [];
+		const reasoningItems = [];
+		let terminal;
+		try {
+			for await (const event of events) {
+				if (event.type === "response.output_text.delta" || event.type === "response.refusal.delta") {
+					if (event.delta) yield {
+						type: "delta",
+						content: event.delta
+					};
+					continue;
+				}
+				if (event.type === "response.output_item.done") {
+					const { item } = event;
+					if (item.type === "reasoning") reasoningItems.push(item);
+					else if (item.type === "function_call" && item.status !== "incomplete") toolCalls.push(this.toToolCall(item));
+					continue;
+				}
+				if (event.type === "response.completed" || event.type === "response.incomplete") {
+					terminal = event.response;
+					continue;
+				}
+				if (event.type === "response.failed") throw toResponseFailure(event.response, this.name);
+				if (event.type === "error") throw wrapOpenAIError({
+					code: event.code,
+					message: event.message,
+					param: event.param
+				});
+			}
+			if (terminal === void 0) throw new _warlock_js_ai.ProviderError("OpenAI Responses stream ended before response.completed.", { context: {
+				provider: this.provider,
+				model: this.name
+			} });
+		} catch (thrown) {
+			throw this.logAndWrap(thrown);
+		}
+		for (const call of attachReasoningReplay(toolCalls, this.name, reasoningItems)) yield {
+			type: "tool-call",
+			id: call.id,
+			name: call.name,
+			input: call.input,
+			...call.providerMetadata ? { providerMetadata: call.providerMetadata } : {}
+		};
+		const finishReason = mapResponsesFinishReason({
+			status: terminal.status,
+			incomplete_details: terminal.incomplete_details,
+			hasToolCalls: toolCalls.length > 0
+		});
+		const usage = this.extractUsage(terminal.usage);
+		this.logger.debug(LOG_MODULE$2, "response", "Streaming call to responses.create succeeded", {
+			finishReason,
+			usage
+		});
+		yield {
+			type: "done",
+			finishReason,
+			usage
+		};
+	}
+	/**
+	* Assemble the `responses.create` body.
+	*
+	* - System prompt -> `instructions`; history -> `input` items.
+	* - `store: false` always (the API default is `true` when omitted), plus
+	*   `include: ["reasoning.encrypted_content"]` for stateless reasoning replay.
+	* - `max_output_tokens` caps reasoning and visible output together.
+	* - `temperature` only for non-reasoning models (same rule as Chat).
+	* - `tools` flat with `strict: false`; `tool_choice` only with tools.
+	* - `reasoning.effort` only when the caller gave one, through the same
+	*   clamp table as Chat. With no explicit effort the provider default
+	*   applies EVEN with tools attached - that is the point of this API.
+	*/
+	buildRequest(messages, options) {
+		const { instructions, input } = toResponsesInput(messages, this.name);
+		const tools = toResponsesTools(options?.tools);
+		const toolChoice = tools ? toResponsesToolChoice(options?.toolChoice) : void 0;
+		const maxTokens = options?.maxTokens ?? this.config.maxTokens;
+		const temperature = options?.temperature ?? this.config.temperature;
+		return {
+			model: this.name,
+			...instructions !== void 0 ? { instructions } : {},
+			input,
+			store: false,
+			include: ["reasoning.encrypted_content"],
+			...maxTokens !== void 0 ? { max_output_tokens: maxTokens } : {},
+			...!this.capabilities.reasoning && temperature !== void 0 ? { temperature } : {},
+			...tools ? { tools } : {},
+			...toolChoice !== void 0 ? { tool_choice: toolChoice } : {},
+			...this.buildTextFormat(options?.responseSchema),
+			...this.buildReasoningParams(options?.reasoning),
+			...buildPromptCacheParams(this.provider, this.config)
+		};
+	}
+	/**
+	* Structured output on Responses lives in `text.format`, and `name` /
+	* `schema` / `strict` sit directly on the format object (Chat nests them
+	* under `json_schema`). The strict-or-downgrade decision is the shared
+	* `planStructuredOutput`.
+	*/
+	buildTextFormat(responseSchema) {
+		const plan = planStructuredOutput(responseSchema, this.config.responseFormat);
+		if (plan.mode === "json_schema") return { text: { format: {
+			type: "json_schema",
+			name: "response",
+			schema: plan.schema,
+			strict: true
+		} } };
+		if (plan.mode === "json_object") return { text: { format: { type: "json_object" } } };
+		return {};
+	}
+	/** `reasoning.effort` for reasoning-capable models, only when the caller set one. */
+	buildReasoningParams(reasoning) {
+		if (!this.capabilities.reasoning || !reasoning?.effort) return {};
+		return { reasoning: { effort: toOpenAIReasoningEffort(reasoning.effort) } };
+	}
+	/**
+	* Walk `response.output`: `message` items contribute their `output_text`
+	* text and any `refusal` text (surfaced as ordinary content, decision 5);
+	* each completed `function_call` item becomes one tool call with
+	* `id = call_id`. `reasoning` items carry no visible content and are
+	* not content. A `function_call` the API marked `incomplete` (truncated
+	* arguments) is skipped rather than dispatched with empty input.
+	* `reasoning` items are captured and attached to the first tool call for
+	* replay (see `attachReasoningReplay`).
+	*/
+	readOutput(output) {
+		let content = "";
+		const toolCalls = [];
+		const reasoningItems = [];
+		for (const item of output) {
+			if (item.type === "reasoning") {
+				reasoningItems.push(item);
+				continue;
+			}
+			if (item.type === "message") {
+				for (const part of item.content) content += part.type === "refusal" ? part.refusal : part.text;
+				continue;
+			}
+			if (item.type === "function_call" && item.status !== "incomplete") toolCalls.push(this.toToolCall(item));
+		}
+		return {
+			content,
+			toolCalls: toolCalls.length > 0 ? attachReasoningReplay(toolCalls, this.name, reasoningItems) : void 0
+		};
+	}
+	/** One completed `function_call` item as a neutral tool call (`call_id` -> `id`). */
+	toToolCall(item) {
+		return {
+			id: item.call_id,
+			name: item.name,
+			input: (0, _warlock_js_ai.safeJsonParse)(item.arguments, {})
+		};
+	}
+	/**
+	* Normalize `usage` (absent on some partials) into the neutral `Usage`.
+	* `input_tokens_details.cached_tokens` -> `cachedTokens`,
+	* `cache_write_tokens` -> `cacheWriteTokens`,
+	* `output_tokens_details.reasoning_tokens` -> `reasoningTokens`. The
+	* detail blocks are typed non-optional but read defensively.
+	*/
+	extractUsage(raw) {
+		if (!raw) return {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		return buildUsage({
+			input: raw.input_tokens,
+			output: raw.output_tokens,
+			total: raw.total_tokens,
+			cachedTokens: raw.input_tokens_details?.cached_tokens,
+			cacheWriteTokens: raw.input_tokens_details?.cache_write_tokens,
+			reasoningTokens: raw.output_tokens_details?.reasoning_tokens
+		});
+	}
+	/** Wrap (idempotently), log and return a failure for the caller to throw. */
+	logAndWrap(thrown) {
+		const wrapped = wrapOpenAIError(thrown);
+		this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
+			code: wrapped.code,
+			context: wrapped.context
+		});
+		return wrapped;
+	}
+};
+
 //#endregion
 //#region ../ai-openai/src/speech.ts
 const LOG_MODULE$1 = "ai.openai";
@@ -1357,13 +2016,32 @@ var OpenAISDK = class {
 	* Pricing resolution: per-model `config.pricing` wins; otherwise the
 	* SDK-level registry entry keyed by `config.name`; otherwise
 	* `undefined` (no cost computed).
+	*
+	* `config.api` selects the wire API. Omitted or `"chat"` builds the Chat
+	* Completions `OpenAIModel`. `"responses"` builds `OpenAIResponsesModel`
+	* and is accepted ONLY when this SDK's provider label is `"openai"`: any
+	* other label (the wrapper packages deepseek / groq / xai / mistral, or a
+	* custom gateway label) throws, so an endpoint not known to implement
+	* `/v1/responses` is never sent there.
 	*/
 	model(config) {
+		const api = config.api;
+		if (api !== void 0 && api !== "chat" && api !== "responses") throw new _warlock_js_ai.InvalidRequestError(`Unknown OpenAI api "${String(api)}"; expected "chat" or "responses".`, { context: {
+			provider: this.provider,
+			model: config.name,
+			api
+		} });
+		if (api === "responses" && this.provider !== "openai") throw new _warlock_js_ai.InvalidRequestError(`api: "responses" is supported only on the direct "openai" provider; this SDK is labeled "${this.provider}". Use the default api: "chat".`, { context: {
+			provider: this.provider,
+			model: config.name,
+			api
+		} });
 		const resolvedPricing = config.pricing ?? this.pricing?.[config.name];
 		const resolvedConfig = resolvedPricing === config.pricing ? config : {
 			...config,
 			pricing: resolvedPricing
 		};
+		if (api === "responses") return new OpenAIResponsesModel(this.client, resolvedConfig, this.provider);
 		return new OpenAIModel(this.client, resolvedConfig, this.provider);
 	}
 	/**