@rulvar/openai 1.17.0 → 1.19.0

package/dist/index.d.ts

@@ -7,6 +7,14 @@ interface OpenAiModelInfo {
   api: "responses" | "chat";
   /** Reasoning models reject non-default sampling parameters. */
   reasoning: boolean;
+  /**
+  * The model accepts wire `reasoning.effort: "max"` (GPT-5.6 Sol per
+  * the official model docs). When false, canonical max downmaps to
+  * wire xhigh; the downmap is recorded in providerMetadata and the
+  * journal identity keeps max, so caps accept the full canonical set
+  * either way.
+  */
+  wireMaxEffort: boolean;
 }
 /** Static seed table of the current model set. */
 declare const OPENAI_MODELS: Record<string, OpenAiModelInfo>;
@@ -111,12 +119,15 @@ declare class OpenAiIdMap {
   wireFor(canonicalId: CanonicalId): string;
 }
 /**
-* Canonical-to-wire effort: low through
-* xhigh pass through; canonical max downmaps to xhigh (documented lossy;
-* recorded in providerMetadata); provider 'none' is reachable only via
-* providerOptions.openai.reasoningEffort.
+* Canonical-to-wire effort: low through xhigh pass through. Canonical
+* max passes through unchanged on models whose caps declare wire max
+* support (GPT-5.6 Sol); elsewhere it downmaps to xhigh (documented
+* lossy; recorded in providerMetadata). Provider 'none' is reachable
+* only via providerOptions.openai.reasoningEffort.
 */
-declare function mapOpenAiEffort(effort: Effort): {
+declare function mapOpenAiEffort(effort: Effort, options?: {
+  wireMaxEffort?: boolean;
+}): {
   wire: string;
   downmapped: boolean;
 };
@@ -127,7 +138,9 @@ declare function mapOpenAiEffort(effort: Effort): {
 * are REJECTED as a typed ConfigError. Role
 * 'system' messages project into top-level instructions on every request.
 */
-declare function buildResponsesParams(req: ChatRequest, ids: OpenAiIdMap): {
+declare function buildResponsesParams(req: ChatRequest, ids: OpenAiIdMap, options?: {
+  wireMaxEffort?: boolean;
+}): {
   params: Record<string, unknown>;
   effortDownmapped: boolean;
 };
@@ -135,7 +148,17 @@ declare function buildResponsesParams(req: ChatRequest, ids: OpenAiIdMap): {
 type ResponsesStreamEvent = Record<string, unknown> & {
   type: string;
 };
-/** Normalizes Responses usage: input_tokens already includes cached reads. */
+/**
+* Normalizes Responses usage into the canonical Usage invariant, where
+* `inputTokens` is the FULL prompt: wire `input_tokens` already includes
+* cached READS, while cache WRITE tokens arrive SEPARATELY in
+* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later families;
+* they bill at the 1.25x write premium, and earlier families report no
+* field and pay no premium). Dropping the field lost the whole write
+* charge and weakened the budget guard (v1.18.0 review P1-2), so writes
+* are added into `inputTokens` and surfaced as `cacheWriteTokens` for
+* the premium rate, exactly mirroring the Anthropic adapter's mapping.
+*/
 declare function normalizeOpenAiUsage(raw: Record<string, unknown> | undefined): Usage;
 /**
 * Maps the typed Responses SSE stream to ChatEvents, yielding each

package/dist/index.js

@@ -7,7 +7,7 @@ const REASONING_EFFORTS = [
 	"high",
 	"xhigh"
 ];
-function responses(contextWindow, maxOutputTokens, pricing) {
+function responses(contextWindow, maxOutputTokens, pricing, options) {
 	return {
 		caps: {
 			structuredOutput: "native",
@@ -19,48 +19,66 @@ function responses(contextWindow, maxOutputTokens, pricing) {
 			...pricing === void 0 ? {} : { pricing }
 		},
 		api: "responses",
-		reasoning: true
+		reasoning: true,
+		wireMaxEffort: options?.wireMaxEffort === true
 	};
 }
+const GPT_56_TIERS = [{
+	aboveInputTokens: 272e3,
+	inputMultiplier: 2,
+	outputMultiplier: 1.5
+}];
 /**
-* GPT-5.6 Sol (developers.openai.com/api/docs/models/gpt-5.6-sol):
-* prompts strictly above 272K input tokens price the FULL request at
-* 2x input and 1.5x output; cache writes bill at 1.25x uncached input.
+* GPT-5.6 Sol, Terra, and Luna are three sibling models, not snapshots
+* of one model (developers.openai.com/api/docs/models/gpt-5.6-sol,
+* .../gpt-5.6-terra, .../gpt-5.6-luna; rates verified 2026-07-18). All
+* three: prompts strictly above 272K input tokens price the FULL
+* request at 2x input and 1.5x output; cache writes bill at 1.25x
+* uncached input. Only Sol accepts wire reasoning effort `max`.
 */
 const GPT_56_SOL = responses(105e4, 128e3, {
 	inputUsdPerMTok: 5,
 	outputUsdPerMTok: 30,
 	cacheReadUsdPerMTok: .5,
 	cacheWriteUsdPerMTok: 6.25,
-	tiers: [{
-		aboveInputTokens: 272e3,
-		inputMultiplier: 2,
-		outputMultiplier: 1.5
-	}]
-});
+	tiers: GPT_56_TIERS
+}, { wireMaxEffort: true });
 /** Static seed table of the current model set. */
 const OPENAI_MODELS = {
 	"gpt-5.6-sol": GPT_56_SOL,
+	"gpt-5.6-terra": responses(105e4, 128e3, {
+		inputUsdPerMTok: 2.5,
+		outputUsdPerMTok: 15,
+		cacheReadUsdPerMTok: .25,
+		cacheWriteUsdPerMTok: 3.125,
+		tiers: GPT_56_TIERS
+	}),
+	"gpt-5.6-luna": responses(105e4, 128e3, {
+		inputUsdPerMTok: 1,
+		outputUsdPerMTok: 6,
+		cacheReadUsdPerMTok: .1,
+		cacheWriteUsdPerMTok: 1.25,
+		tiers: GPT_56_TIERS
+	}),
 	"gpt-5.6": GPT_56_SOL,
 	"gpt-5.5": responses(4e5, 128e3, {
-		inputUsdPerMTok: 10,
-		outputUsdPerMTok: 40,
-		cacheReadUsdPerMTok: 1
+		inputUsdPerMTok: 5,
+		outputUsdPerMTok: 30,
+		cacheReadUsdPerMTok: .5
 	}),
 	"gpt-5.5-pro": responses(4e5, 128e3, {
-		inputUsdPerMTok: 40,
-		outputUsdPerMTok: 160,
-		cacheReadUsdPerMTok: 4
+		inputUsdPerMTok: 30,
+		outputUsdPerMTok: 180
 	}),
 	"gpt-5.4": responses(272e3, 1e5, {
-		inputUsdPerMTok: 6,
-		outputUsdPerMTok: 24,
-		cacheReadUsdPerMTok: .6
+		inputUsdPerMTok: 2.5,
+		outputUsdPerMTok: 15,
+		cacheReadUsdPerMTok: .25
 	}),
 	"gpt-5.4-mini": responses(272e3, 1e5, {
-		inputUsdPerMTok: 1.2,
-		outputUsdPerMTok: 4.8,
-		cacheReadUsdPerMTok: .12
+		inputUsdPerMTok: .75,
+		outputUsdPerMTok: 4.5,
+		cacheReadUsdPerMTok: .075
 	})
 };
 /**
@@ -83,22 +101,30 @@ const OPENAI_MODELS = {
 * silent reinterpretation.
 */
 const OPENAI_PRICING = {
-	pricingVersion: "openai-2026-07-16",
+	pricingVersion: "openai-2026-07-18-r2",
 	models: (() => {
 		const models = {};
 		for (const [name, info] of Object.entries(OPENAI_MODELS)) if (info.caps.pricing !== void 0) models[`openai:${name}`] = info.caps.pricing;
 		return models;
 	})()
 };
+/**
+* The documented snapshot grammar: `<exact model>-YYYY-MM-DD`. Nothing
+* else inherits a table row (v1.17.0 review P1-1): a general prefix
+* matcher let the 'gpt-5.6' family alias capture the SIBLING models
+* 'gpt-5.6-terra' and 'gpt-5.6-luna' and price them as Sol, which is
+* worse than no price at all. An unknown sibling or preview suffix now
+* falls through to conservative unpriced caps.
+*/
+const DATED_SNAPSHOT = /^(?<base>.+)-\d{4}-\d{2}-\d{2}$/u;
 function openAiModelInfo(model) {
 	const exact = OPENAI_MODELS[model];
 	if (exact !== void 0) return exact;
-	let best;
-	for (const [name, info] of Object.entries(OPENAI_MODELS)) if (model.startsWith(`${name}-`) && (best === void 0 || name.length > best.name.length)) best = {
-		name,
-		info
-	};
-	if (best !== void 0) return best.info;
+	const snapshot = DATED_SNAPSHOT.exec(model)?.groups?.base;
+	if (snapshot !== void 0) {
+		const base = OPENAI_MODELS[snapshot];
+		if (base !== void 0) return base;
+	}
 	return responses(272e3, 1e5);
 }
 //#endregion
@@ -140,13 +166,14 @@ var OpenAiIdMap = class {
 	}
 };
 /**
-* Canonical-to-wire effort: low through
-* xhigh pass through; canonical max downmaps to xhigh (documented lossy;
-* recorded in providerMetadata); provider 'none' is reachable only via
-* providerOptions.openai.reasoningEffort.
+* Canonical-to-wire effort: low through xhigh pass through. Canonical
+* max passes through unchanged on models whose caps declare wire max
+* support (GPT-5.6 Sol); elsewhere it downmaps to xhigh (documented
+* lossy; recorded in providerMetadata). Provider 'none' is reachable
+* only via providerOptions.openai.reasoningEffort.
 */
-function mapOpenAiEffort(effort) {
-	if (effort === "max") return {
+function mapOpenAiEffort(effort, options) {
+	if (effort === "max" && options?.wireMaxEffort !== true) return {
 		wire: "xhigh",
 		downmapped: true
 	};
@@ -162,7 +189,7 @@ function mapOpenAiEffort(effort) {
 * are REJECTED as a typed ConfigError. Role
 * 'system' messages project into top-level instructions on every request.
 */
-function buildResponsesParams(req, ids) {
+function buildResponsesParams(req, ids, options) {
 	const openaiOptions = req.providerOptions?.openai ?? {};
 	for (const forbidden of [
 		"previous_response_id",
@@ -260,7 +287,7 @@ function buildResponsesParams(req, ids) {
 	const explicitEffort = openaiOptions.reasoningEffort;
 	if (typeof explicitEffort === "string") params.reasoning = { effort: explicitEffort };
 	else if (req.effort !== void 0) {
-		const mapped = mapOpenAiEffort(req.effort);
+		const mapped = mapOpenAiEffort(req.effort, options);
 		effortDownmapped = mapped.downmapped;
 		params.reasoning = { effort: mapped.wire };
 	}
@@ -270,15 +297,26 @@ function buildResponsesParams(req, ids) {
 		effortDownmapped
 	};
 }
-/** Normalizes Responses usage: input_tokens already includes cached reads. */
+/**
+* Normalizes Responses usage into the canonical Usage invariant, where
+* `inputTokens` is the FULL prompt: wire `input_tokens` already includes
+* cached READS, while cache WRITE tokens arrive SEPARATELY in
+* `input_tokens_details.cache_write_tokens` (GPT-5.6 and later families;
+* they bill at the 1.25x write premium, and earlier families report no
+* field and pay no premium). Dropping the field lost the whole write
+* charge and weakened the budget guard (v1.18.0 review P1-2), so writes
+* are added into `inputTokens` and surfaced as `cacheWriteTokens` for
+* the premium rate, exactly mirroring the Anthropic adapter's mapping.
+*/
 function normalizeOpenAiUsage(raw) {
 	const inputDetails = raw?.input_tokens_details;
 	const outputDetails = raw?.output_tokens_details;
+	const cacheWrite = typeof inputDetails?.cache_write_tokens === "number" ? inputDetails.cache_write_tokens : 0;
 	const usage = {
-		inputTokens: typeof raw?.input_tokens === "number" ? raw.input_tokens : 0,
+		inputTokens: (typeof raw?.input_tokens === "number" ? raw.input_tokens : 0) + cacheWrite,
 		outputTokens: typeof raw?.output_tokens === "number" ? raw.output_tokens : 0,
 		cacheReadTokens: typeof inputDetails?.cached_tokens === "number" ? inputDetails.cached_tokens : 0,
-		cacheWriteTokens: 0
+		cacheWriteTokens: cacheWrite
 	};
 	const reasoning = outputDetails?.reasoning_tokens;
 	if (typeof reasoning === "number" && reasoning > 0) usage.reasoningTokens = reasoning;
@@ -387,31 +425,59 @@ async function* mapResponsesStream(stream, ids, options) {
 			};
 			return;
 		}
-		case "response.failed":
+		case "response.failed": {
+			const response = event.response;
+			const rawUsage = response?.usage;
+			if (rawUsage !== void 0) yield {
+				type: "usage",
+				usage: normalizeOpenAiUsage(rawUsage)
+			};
+			const error = response?.error;
 			yield {
 				type: "error",
-				error: {
-					code: "agent",
-					message: (event.response?.error)?.message ?? "response.failed",
-					retryable: false,
-					data: { kind: "transport" }
-				}
+				error: failedResponseError(typeof error?.code === "string" ? error.code : void 0, error?.message ?? "response.failed")
 			};
 			return;
+		}
 		case "error":
 			yield {
 				type: "error",
-				error: {
-					code: "agent",
-					message: event.message ?? "stream error",
-					retryable: false,
-					data: { kind: "transport" }
-				}
+				error: failedResponseError(typeof event.code === "string" ? event.code : void 0, event.message ?? "stream error")
 			};
 			return;
 		default: break;
 	}
 }
+/**
+* Classifies a terminal stream failure (`response.failed` /
+* SSE `error`) into the retryable WireError vocabulary by the
+* documented `response.error.code` enum (Responses API reference):
+* `rate_limit_exceeded` retries as a rate limit, `server_error` and
+* timeout-class codes retry as transport faults, and everything else
+* (validation such as `invalid_prompt`, policy, auth) stays
+* non-retryable. Unknown codes fail closed as non-retryable: retrying a
+* permanent failure would loop-bill it (v1.18.0 review P1-3).
+*/
+function failedResponseError(code, message) {
+	if (code === "rate_limit_exceeded") return {
+		code: "agent",
+		message,
+		retryable: true,
+		data: {
+			kind: "rate-limit",
+			providerCode: code
+		}
+	};
+	return {
+		code: "agent",
+		message,
+		retryable: code === "server_error" || code !== void 0 && code.endsWith("_timeout"),
+		data: {
+			kind: "transport",
+			...code === void 0 ? {} : { providerCode: code }
+		}
+	};
+}
 /** Projects SDK/API errors into the retryable WireError vocabulary. */
 function openAiErrorToWire(error) {
 	const record = error;
@@ -578,11 +644,12 @@ async function* mapChatCompletionsStream(stream, ids) {
 		const chunkUsage = chunk.usage;
 		if (chunkUsage !== void 0 && chunkUsage !== null) {
 			const promptDetails = chunkUsage.prompt_tokens_details;
+			const cacheWrite = typeof promptDetails?.cache_write_tokens === "number" ? promptDetails.cache_write_tokens : 0;
 			usage = {
-				inputTokens: typeof chunkUsage.prompt_tokens === "number" ? chunkUsage.prompt_tokens : 0,
+				inputTokens: (typeof chunkUsage.prompt_tokens === "number" ? chunkUsage.prompt_tokens : 0) + cacheWrite,
 				outputTokens: typeof chunkUsage.completion_tokens === "number" ? chunkUsage.completion_tokens : 0,
 				cacheReadTokens: typeof promptDetails?.cached_tokens === "number" ? promptDetails.cached_tokens : 0,
-				cacheWriteTokens: 0
+				cacheWriteTokens: cacheWrite
 			};
 		}
 	}
@@ -655,7 +722,7 @@ function openai(options = {}) {
 			const info = openAiModelInfo(req.model);
 			try {
 				if (info.api === "responses") {
-					const { params, effortDownmapped } = buildResponsesParams(req, ids);
+					const { params, effortDownmapped } = buildResponsesParams(req, ids, { wireMaxEffort: info.wireMaxEffort });
 					yield* mapResponsesStream(await client.responses.create({
 						...params,
 						stream: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/openai",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Rulvar first-class provider adapter for the OpenAI Responses API, plus the openaiCompatible factory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,13 +23,13 @@
   },
   "dependencies": {
     "openai": "^6.45.0",
-    "@rulvar/core": "1.17.0"
+    "@rulvar/core": "1.19.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/testing": "1.17.0"
+    "@rulvar/testing": "1.19.0"
   },
   "repository": {
     "type": "git",