@warlock.js/ai-openai 5.24.0 → 5.26.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@warlock.js/ai-openai` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.26.0 - 2026-09-30
+
+### Changed
+
+- `reasoning.effort` now accepts every OpenAI SDK 7.23.0 `reasoning_effort` level: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
+- OpenAI-labelled Chat Completions models now support explicit prompt caching: `promptCacheKey`, `promptCacheRetention`, and `cacheControl.breakpoints` map to the OpenAI SDK's request fields. These fields are deliberately omitted for OpenAI-compatible wrapper providers.
+- Capability inference now recognizes the GPT-6 family as reasoning- and vision-capable, plus GPT-5 and o4 as vision-capable.
+- **Behaviour change:** requests send `max_completion_tokens` and never the legacy `max_tokens`, which current OpenAI models (the gpt-5 family and later) reject with `400 unsupported_parameter`. `maxTokens` in config and call options is unchanged.
+- Reasoning-capable models (o-series, gpt-5 family) no longer receive `temperature`; they accept only the default value and reject any other.
+
+### Fixed
+
+- A provider error now keeps the parameter OpenAI rejected (`context.param`) and the request id (`context.requestId`, read from the SDK's `requestID`), next to the status and code.
+
+## 5.25.0 - 2026-09-28
+
+### Changed
+
+- Lockstep release; package APIs are unchanged.
+
 ## 5.24.0 - 2026-09-27
 
 ### Changed

package/cjs/index.cjs

@@ -76,8 +76,8 @@ function mapFinishReason(raw) {
 *   ]},
 * ]);
 */
-function toOpenAIMessages(messages) {
-	return messages.map((m) => {
+function toOpenAIMessages(messages, cacheBreakpoints = 0) {
+	return addPromptCacheBreakpoints(messages.map((m) => {
 		if (m.role === "tool") return {
 			role: "tool",
 			content: stringifyContent(m.content),
@@ -103,7 +103,44 @@ function toOpenAIMessages(messages) {
 			role: m.role,
 			content: stringifyContent(m.content)
 		};
-	});
+	}), cacheBreakpoints);
+}
+/** Place explicit markers on the last requested user-content parts (maximum four). */
+function addPromptCacheBreakpoints(messages, requested) {
+	let remaining = Math.min(4, Math.max(0, Math.floor(requested)));
+	if (remaining === 0) return messages;
+	const marked = [...messages];
+	for (let index = marked.length - 1; index >= 0 && remaining > 0; index--) {
+		const message = marked[index];
+		if (message === void 0 || message.role !== "user") continue;
+		if (typeof message.content === "string") {
+			marked[index] = {
+				...message,
+				content: [{
+					type: "text",
+					text: message.content,
+					prompt_cache_breakpoint: { mode: "explicit" }
+				}]
+			};
+			remaining--;
+			continue;
+		}
+		const content = [...message.content];
+		for (let partIndex = content.length - 1; partIndex >= 0 && remaining > 0; partIndex--) {
+			const part = content[partIndex];
+			if (part === void 0) continue;
+			content[partIndex] = {
+				...part,
+				prompt_cache_breakpoint: { mode: "explicit" }
+			};
+			remaining--;
+		}
+		marked[index] = {
+			...message,
+			content
+		};
+	}
+	return marked;
 }
 /**
 * Multipart content is only meaningful on user messages — for any other
@@ -285,6 +322,7 @@ function toShape(thrown) {
 		code: thrown.code,
 		message: thrown.message,
 		type: thrown.type,
+		param: thrown.param,
 		headers: thrown.headers,
 		name: thrown.name
 	};
@@ -295,6 +333,7 @@ function toShape(thrown) {
 			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
 		};
@@ -324,19 +363,22 @@ function buildContext(thrown, shape) {
 	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;
 }
 /**
-* OpenAI puts the request id on `APIError.request_id`. Extract
-* defensively — both camel and snake keys exist across SDK versions.
+* 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)
@@ -599,11 +641,12 @@ const REASONING_CAPABLE_PREFIXES = [
 	"o1",
 	"o3",
 	"o4",
-	"gpt-5"
+	"gpt-5",
+	"gpt-6"
 ];
 /**
 * Infer whether a given OpenAI model name is a reasoning model (o-series
-* and the gpt-5 family) based on the known-prefix list. Unknown models
+* and the gpt-5 / gpt-6 families) based on the known-prefix list. Unknown models
 * default to `false` so the adapter never forwards an unsupported
 * `reasoning_effort` param to a non-reasoning model (which would 400).
 *
@@ -611,6 +654,7 @@ const REASONING_CAPABLE_PREFIXES = [
 * inferReasoningCapability("o3-mini");          // → true
 * inferReasoningCapability("o4-mini");          // → true
 * inferReasoningCapability("gpt-5-pro");        // → true
+* inferReasoningCapability("gpt-6-astra");      // → true
 * inferReasoningCapability("gpt-4o");           // → false
 * inferReasoningCapability("custom-llm");       // → false
 */
@@ -638,8 +682,11 @@ const VISION_CAPABLE_PREFIXES = [
 	"gpt-4o",
 	"gpt-4-turbo",
 	"gpt-4.1",
+	"gpt-5",
+	"gpt-6",
 	"o1",
 	"o3",
+	"o4",
 	"chatgpt-4o"
 ];
 /**
@@ -663,6 +710,23 @@ function inferVisionCapability(modelName) {
 //#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
@@ -724,7 +788,7 @@ var OpenAIModel = class {
 			structuredOutput: config.structuredOutput ?? inferStructuredOutput(config.responseFormat),
 			vision: config.vision ?? inferVisionCapability(config.name),
 			reasoning: config.reasoning ?? inferReasoningCapability(config.name),
-			promptCaching: true,
+			promptCaching: this.provider === "openai",
 			pdf: config.pdf ?? false,
 			audio: config.audio ?? false
 		};
@@ -746,9 +810,9 @@ var OpenAIModel = class {
 		try {
 			response = await this.client.chat.completions.create({
 				model: this.name,
-				messages: toOpenAIMessages(messages),
-				temperature: options?.temperature ?? this.config.temperature,
-				max_tokens: options?.maxTokens ?? this.config.maxTokens,
+				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
+				...this.buildSamplingParams(options),
+				...this.buildPromptCacheParams(),
 				tools: toOpenAITools(options?.tools),
 				...this.buildResponseFormat(options?.responseSchema),
 				...this.buildReasoningParams(options?.reasoning, Boolean(options?.tools?.length))
@@ -797,9 +861,9 @@ var OpenAIModel = class {
 		try {
 			stream = await this.client.chat.completions.create({
 				model: this.name,
-				messages: toOpenAIMessages(messages),
-				temperature: options?.temperature ?? this.config.temperature,
-				max_tokens: options?.maxTokens ?? this.config.maxTokens,
+				messages: toOpenAIMessages(messages, this.promptCacheBreakpoints(options)),
+				...this.buildSamplingParams(options),
+				...this.buildPromptCacheParams(),
 				tools: toOpenAITools(options?.tools),
 				stream: true,
 				stream_options: { include_usage: true },
@@ -880,6 +944,18 @@ 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.
@@ -1029,10 +1105,27 @@ var OpenAIModel = class {
 	* Returns an empty spread when nothing applies, so the caller can
 	* unconditionally `...buildReasoningParams(...)` into the request.
 	*/
+	/**
+	* Output-length and sampling params, in current Chat Completions shapes only.
+	*
+	* - `max_completion_tokens`, never the legacy `max_tokens`: current
+	*   models (the gpt-5 family and later) answer `400 unsupported_parameter`
+	*   to `max_tokens`, and `max_completion_tokens` is accepted everywhere.
+	* - No `temperature` for a reasoning-capable model: those accept only the
+	*   default value and reject any other with a 400.
+	*/
+	buildSamplingParams(options) {
+		const maxTokens = options?.maxTokens ?? this.config.maxTokens;
+		const temperature = options?.temperature ?? this.config.temperature;
+		return {
+			max_completion_tokens: maxTokens,
+			...!this.capabilities.reasoning && { temperature }
+		};
+	}
 	buildReasoningParams(reasoning, hasTools) {
 		if (!this.capabilities.reasoning) return {};
 		if (!reasoning?.effort) return hasTools ? { reasoning_effort: "none" } : {};
-		return { reasoning_effort: reasoning.effort };
+		return { reasoning_effort: EFFORT_TO_OPENAI_EFFORT[reasoning.effort] };
 	}
 	/**
 	* Reshape OpenAI's `tool_calls` array into the neutral