@rulvar/openai 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { CanonicalId, ChatEvent, ChatRequest, Effort, ModelCaps, ProviderAdapter, Usage, WireError } from "@rulvar/core";
+
+//#region src/caps.d.ts
+interface OpenAiModelInfo {
+  caps: ModelCaps;
+  api: "responses" | "chat";
+  /** Reasoning models reject non-default sampling parameters (docs/04, section 5.1). */
+  reasoning: boolean;
+}
+/** Static seed table; docs/04 section 5 names the current model set. */
+declare const OPENAI_MODELS: Record<string, OpenAiModelInfo>;
+/** Unknown OpenAI models are assumed current-generation Responses models. */
+declare function openAiModelInfo(model: string): OpenAiModelInfo;
+//#endregion
+//#region src/adapter.d.ts
+/** The client sub-surface the adapter consumes; injectable for tests. */
+interface OpenAiClientLike {
+  responses: {
+    create(params: Record<string, unknown>, opts?: {
+      signal?: AbortSignal;
+    }): Promise<unknown>;
+  };
+  chat: {
+    completions: {
+      create(params: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+      }): Promise<unknown>;
+    };
+  };
+}
+interface OpenAiAdapterOptions {
+  apiKey?: string;
+  baseURL?: string;
+  /** Test seam: a preconstructed client; production uses the openai SDK. */
+  client?: OpenAiClientLike;
+}
+/** Creates the first-class OpenAI adapter (id 'openai'); maxRetries 0. */
+declare function openai(options?: OpenAiAdapterOptions): ProviderAdapter;
+//#endregion
+//#region src/compatible.d.ts
+/**
+* Gateways cannot be introspected reliably: when caps are not supplied
+* the factory assumes the most conservative capability set (docs/04,
+* section 6). Callers SHOULD supply caps for anything beyond it; the
+* window and output floors here are deliberately small so an unprobed
+* endpoint is never overcommitted. Absent pricing is legitimate for
+* local models: they surface as unpriced in CostReport.
+*/
+declare const CONSERVATIVE_COMPATIBLE_CAPS: ModelCaps;
+interface OpenAiCompatibleConfig {
+  /** Explicit adapter id, e.g. 'ollama', 'vllm', 'openrouter'. */
+  id: string;
+  baseURL: string;
+  apiKey?: string;
+  /** Per-model capability overrides merged over the conservative set. */
+  caps?: (model: string) => ModelCaps | Partial<ModelCaps>;
+  /** Test seam: a preconstructed client; production uses the openai SDK. */
+  client?: OpenAiClientLike;
+}
+/** Creates a Chat Completions dialect adapter for a compatible endpoint. */
+declare function openaiCompatible(cfg: OpenAiCompatibleConfig): ProviderAdapter;
+//#endregion
+//#region src/wire.d.ts
+/** Bijective canonical-to-wire (call_*) id map (docs/04, section 1.2). */
+declare class OpenAiIdMap {
+  private readonly toWire;
+  private readonly toCanonical;
+  private readonly mint;
+  constructor(mint: () => CanonicalId);
+  canonicalFor(wireId: string): CanonicalId;
+  wireFor(canonicalId: CanonicalId): string;
+}
+/**
+* Canonical-to-wire effort (docs/04, sections 3.3 and 5.5): low through
+* xhigh pass through; canonical max downmaps to xhigh (documented lossy;
+* recorded in providerMetadata); provider 'none' is reachable only via
+* providerOptions.openai.reasoningEffort.
+*/
+declare function mapOpenAiEffort(effort: Effort): {
+  wire: string;
+  downmapped: boolean;
+};
+/**
+* Builds Responses API params. Manual item replay ONLY: store: false plus
+* include reasoning.encrypted_content; previous_response_id and the
+* Conversations API place state server-side, break replay identity, and
+* are REJECTED as a typed ConfigError (docs/04, section 5.1). Role
+* 'system' messages project into top-level instructions on every request.
+*/
+declare function buildResponsesParams(req: ChatRequest, ids: OpenAiIdMap): {
+  params: Record<string, unknown>;
+  effortDownmapped: boolean;
+};
+/** Raw Responses SSE events, structurally typed. */
+type ResponsesStreamEvent = Record<string, unknown> & {
+  type: string;
+};
+/** Normalizes Responses usage: input_tokens already includes cached reads. */
+declare function normalizeOpenAiUsage(raw: Record<string, unknown> | undefined): Usage;
+/**
+* Maps the typed Responses SSE stream to ChatEvents per the docs/04
+* section 5.4 table. Canonical parts come from the typed output array,
+* never the output_text aggregate. Raw output items ride
+* finish.providerMetadata.openai.outputItems so the runtime can retain
+* reasoning items as provider-raw parts.
+*/
+declare function mapResponsesStream(stream: AsyncIterable<ResponsesStreamEvent>, ids: OpenAiIdMap, emit: (event: ChatEvent) => void, options?: {
+  effortDownmapped?: boolean;
+}): Promise<void>;
+/** Projects SDK/API errors into the retryable WireError vocabulary. */
+declare function openAiErrorToWire(error: unknown): WireError;
+/**
+* The Chat Completions degraded path (docs/04, section 5.6): delta-patched
+* chunk assembly instead of typed SSE, nested function tools with explicit
+* strict where supported, response_format instead of text.format, no
+* reasoning item replay. Selected by caps (api: 'chat'), visible in
+* events, never silent.
+*/
+declare function buildChatCompletionsParams(req: ChatRequest, ids: OpenAiIdMap): Record<string, unknown>;
+/** Delta-patched chunk assembly for the degraded path. */
+declare function mapChatCompletionsStream(stream: AsyncIterable<Record<string, unknown>>, ids: OpenAiIdMap, emit: (event: ChatEvent) => void): Promise<void>;
+//#endregion
+export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, type OpenAiAdapterOptions, type OpenAiClientLike, type OpenAiCompatibleConfig, OpenAiIdMap, type OpenAiModelInfo, type ResponsesStreamEvent, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };

package/dist/index.js

@@ -0,0 +1,698 @@
+import OpenAI from "openai";
+import { ConfigError, createCanonicalIdMinter, isStrictCompatibleSchema } from "@rulvar/core";
+//#region src/caps.ts
+const REASONING_EFFORTS = [
+	"low",
+	"medium",
+	"high",
+	"xhigh"
+];
+function responses(contextWindow, maxOutputTokens, pricing) {
+	return {
+		caps: {
+			structuredOutput: "native",
+			supportsTemperature: false,
+			supportsParallelTools: true,
+			reasoningEfforts: [...REASONING_EFFORTS, "max"],
+			contextWindow,
+			maxOutputTokens,
+			pricing: {
+				inputUsdPerMTok: pricing.in,
+				outputUsdPerMTok: pricing.out,
+				cacheReadUsdPerMTok: pricing.cacheRead
+			}
+		},
+		api: "responses",
+		reasoning: true
+	};
+}
+/** Static seed table; docs/04 section 5 names the current model set. */
+const OPENAI_MODELS = {
+	"gpt-5.5": responses(4e5, 128e3, {
+		in: 10,
+		out: 40,
+		cacheRead: 1
+	}),
+	"gpt-5.5-pro": responses(4e5, 128e3, {
+		in: 40,
+		out: 160,
+		cacheRead: 4
+	}),
+	"gpt-5.4": responses(272e3, 1e5, {
+		in: 6,
+		out: 24,
+		cacheRead: .6
+	}),
+	"gpt-5.4-mini": responses(272e3, 1e5, {
+		in: 1.2,
+		out: 4.8,
+		cacheRead: .12
+	})
+};
+/** Unknown OpenAI models are assumed current-generation Responses models. */
+function openAiModelInfo(model) {
+	const exact = OPENAI_MODELS[model];
+	if (exact !== void 0) return exact;
+	for (const [name, info] of Object.entries(OPENAI_MODELS)) if (model.startsWith(`${name}-`)) return info;
+	return responses(272e3, 1e5, {
+		in: 6,
+		out: 24,
+		cacheRead: .6
+	});
+}
+//#endregion
+//#region src/wire.ts
+/**
+* Canonical-to-wire mapping for the OpenAI Responses API (M1-T13): manual
+* item replay only (store: false plus reasoning.encrypted_content, with
+* reasoning items echoed verbatim between function calls), flattened
+* strict function tools, text.format json_schema, the typed SSE catalog
+* mapped to ChatEvent, effort mapping with the documented lossy max
+* downmap, and usage normalization.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "@rulvar/openai
+* (Responses API)". Pure functions; adapter.ts owns the SDK client.
+*/
+/** Bijective canonical-to-wire (call_*) id map (docs/04, section 1.2). */
+var OpenAiIdMap = class {
+	toWire = /* @__PURE__ */ new Map();
+	toCanonical = /* @__PURE__ */ new Map();
+	mint;
+	constructor(mint) {
+		this.mint = mint;
+	}
+	canonicalFor(wireId) {
+		const existing = this.toCanonical.get(wireId);
+		if (existing !== void 0) return existing;
+		const canonical = this.mint();
+		this.toCanonical.set(wireId, canonical);
+		this.toWire.set(canonical, wireId);
+		return canonical;
+	}
+	wireFor(canonicalId) {
+		const existing = this.toWire.get(canonicalId);
+		if (existing !== void 0) return existing;
+		const wireId = `call_${canonicalId}`;
+		this.toWire.set(canonicalId, wireId);
+		this.toCanonical.set(wireId, canonicalId);
+		return wireId;
+	}
+};
+/**
+* Canonical-to-wire effort (docs/04, sections 3.3 and 5.5): low through
+* xhigh pass through; canonical max downmaps to xhigh (documented lossy;
+* recorded in providerMetadata); provider 'none' is reachable only via
+* providerOptions.openai.reasoningEffort.
+*/
+function mapOpenAiEffort(effort) {
+	if (effort === "max") return {
+		wire: "xhigh",
+		downmapped: true
+	};
+	return {
+		wire: effort,
+		downmapped: false
+	};
+}
+/**
+* Builds Responses API params. Manual item replay ONLY: store: false plus
+* include reasoning.encrypted_content; previous_response_id and the
+* Conversations API place state server-side, break replay identity, and
+* are REJECTED as a typed ConfigError (docs/04, section 5.1). Role
+* 'system' messages project into top-level instructions on every request.
+*/
+function buildResponsesParams(req, ids) {
+	const openaiOptions = req.providerOptions?.openai ?? {};
+	for (const forbidden of [
+		"previous_response_id",
+		"previousResponseId",
+		"conversation"
+	]) if (openaiOptions[forbidden] !== void 0) throw new ConfigError(`providerOptions.openai.${forbidden} is rejected: server-side conversation state is incompatible with content-addressed journal determinism (docs/04, section 5.1)`);
+	const instructions = [];
+	const input = [];
+	for (const msg of req.messages) {
+		if (msg.role === "system") {
+			for (const part of msg.parts) if (part.type === "text") instructions.push(part.text);
+			continue;
+		}
+		const content = [];
+		const flushContent = () => {
+			if (content.length > 0) input.push({
+				role: msg.role === "tool" ? "user" : msg.role,
+				content: content.splice(0)
+			});
+		};
+		for (const part of msg.parts) switch (part.type) {
+			case "text":
+				content.push({
+					type: msg.role === "assistant" ? "output_text" : "input_text",
+					text: part.text
+				});
+				break;
+			case "image":
+				content.push({
+					type: "input_image",
+					image_url: typeof part.data === "string" ? part.data : `data:${part.mediaType};base64,${Buffer.from(part.data).toString("base64")}`
+				});
+				break;
+			case "tool-call":
+				flushContent();
+				input.push({
+					type: "function_call",
+					call_id: ids.wireFor(part.id),
+					name: part.name,
+					arguments: JSON.stringify(part.args ?? {})
+				});
+				break;
+			case "tool-result":
+				flushContent();
+				input.push({
+					type: "function_call_output",
+					call_id: ids.wireFor(part.id),
+					output: typeof part.result === "string" ? part.result : JSON.stringify(part.result ?? null)
+				});
+				break;
+			case "provider-raw":
+				if (part.provider === "openai") {
+					flushContent();
+					input.push(part.block);
+				}
+				break;
+		}
+		flushContent();
+	}
+	const params = {
+		model: req.model,
+		input,
+		store: false,
+		include: ["reasoning.encrypted_content"]
+	};
+	if (instructions.length > 0) params.instructions = instructions.join("\n\n");
+	if (req.maxOutputTokens !== void 0) params.max_output_tokens = req.maxOutputTokens;
+	if (req.tools !== void 0) {
+		params.tools = req.tools.map((tool) => ({
+			type: "function",
+			name: tool.name,
+			description: tool.description,
+			parameters: tool.parameters,
+			strict: isStrictCompatibleSchema(tool.parameters)
+		}));
+		if (req.toolChoice === "required") params.tool_choice = "required";
+		else if (typeof req.toolChoice === "object") params.tool_choice = {
+			type: "function",
+			name: req.toolChoice.name
+		};
+		else if (req.toolChoice === "auto") params.tool_choice = "auto";
+		else if (req.toolChoice === "none") params.tool_choice = "none";
+	}
+	if (req.schema !== void 0) {
+		const text = { format: {
+			type: "json_schema",
+			name: "output",
+			schema: req.schema,
+			strict: isStrictCompatibleSchema(req.schema)
+		} };
+		if (typeof openaiOptions.verbosity === "string") text.verbosity = openaiOptions.verbosity;
+		params.text = text;
+	} else if (typeof openaiOptions.verbosity === "string") params.text = { verbosity: openaiOptions.verbosity };
+	let effortDownmapped = false;
+	const explicitEffort = openaiOptions.reasoningEffort;
+	if (typeof explicitEffort === "string") params.reasoning = { effort: explicitEffort };
+	else if (req.effort !== void 0) {
+		const mapped = mapOpenAiEffort(req.effort);
+		effortDownmapped = mapped.downmapped;
+		params.reasoning = { effort: mapped.wire };
+	}
+	for (const key of ["temperature", "top_p"]) if (openaiOptions[key] !== void 0) params[key] = openaiOptions[key];
+	return {
+		params,
+		effortDownmapped
+	};
+}
+/** Normalizes Responses usage: input_tokens already includes cached reads. */
+function normalizeOpenAiUsage(raw) {
+	const inputDetails = raw?.input_tokens_details;
+	const outputDetails = raw?.output_tokens_details;
+	const usage = {
+		inputTokens: typeof raw?.input_tokens === "number" ? raw.input_tokens : 0,
+		outputTokens: typeof raw?.output_tokens === "number" ? raw.output_tokens : 0,
+		cacheReadTokens: typeof inputDetails?.cached_tokens === "number" ? inputDetails.cached_tokens : 0,
+		cacheWriteTokens: 0
+	};
+	const reasoning = outputDetails?.reasoning_tokens;
+	if (typeof reasoning === "number" && reasoning > 0) usage.reasoningTokens = reasoning;
+	return usage;
+}
+/**
+* Maps the typed Responses SSE stream to ChatEvents per the docs/04
+* section 5.4 table. Canonical parts come from the typed output array,
+* never the output_text aggregate. Raw output items ride
+* finish.providerMetadata.openai.outputItems so the runtime can retain
+* reasoning items as provider-raw parts.
+*/
+async function mapResponsesStream(stream, ids, emit, options) {
+	const callIdByItemId = /* @__PURE__ */ new Map();
+	for await (const event of stream) switch (event.type) {
+		case "response.output_item.added": {
+			const item = event.item;
+			if (item?.type === "function_call") {
+				const callId = item.call_id ?? item.id;
+				if (typeof item.id === "string") callIdByItemId.set(item.id, callId);
+				emit({
+					type: "tool-call-start",
+					id: ids.canonicalFor(callId),
+					name: item.name ?? ""
+				});
+			}
+			break;
+		}
+		case "response.function_call_arguments.delta": {
+			const itemId = event.item_id;
+			const callId = itemId === void 0 ? void 0 : callIdByItemId.get(itemId);
+			if (callId !== void 0) emit({
+				type: "tool-call-delta",
+				id: ids.canonicalFor(callId),
+				argsTextDelta: event.delta ?? ""
+			});
+			break;
+		}
+		case "response.output_item.done": {
+			const item = event.item;
+			if (item?.type === "function_call") {
+				const callId = item.call_id ?? item.id;
+				let args = {};
+				try {
+					args = typeof item.arguments === "string" && item.arguments !== "" ? JSON.parse(item.arguments) : {};
+				} catch {
+					args = { __unparsed: item.arguments };
+				}
+				emit({
+					type: "tool-call-end",
+					id: ids.canonicalFor(callId),
+					args
+				});
+			}
+			break;
+		}
+		case "response.output_text.delta":
+			emit({
+				type: "text-delta",
+				text: event.delta ?? ""
+			});
+			break;
+		case "response.reasoning_summary_text.delta":
+		case "response.reasoning_text.delta":
+			emit({
+				type: "reasoning-delta",
+				text: event.delta ?? ""
+			});
+			break;
+		case "response.completed":
+		case "response.incomplete": {
+			const response = event.response;
+			const usage = normalizeOpenAiUsage(response?.usage);
+			emit({
+				type: "usage",
+				usage
+			});
+			let finish = { reason: "stop" };
+			if (event.type === "response.incomplete") {
+				const details = response?.incomplete_details;
+				finish = details?.reason === "max_output_tokens" ? { reason: "max-tokens" } : details?.reason === "content_filter" ? {
+					reason: "refusal",
+					refusal: { provider: "openai" }
+				} : { reason: "context-window-exceeded" };
+			} else {
+				const outputItems = response?.output ?? [];
+				const sawFunctionCall = outputItems.some((item) => item.type === "function_call");
+				if (outputItems.some((item) => Array.isArray(item.content) && item.content.some((part) => part.type === "refusal"))) finish = {
+					reason: "refusal",
+					refusal: { provider: "openai" }
+				};
+				else if (sawFunctionCall) finish = { reason: "tool-calls" };
+			}
+			const meta = { outputItems: response?.output ?? [] };
+			const reasoningItems = (response?.output ?? []).filter((item) => item.type === "reasoning");
+			if (reasoningItems.length > 0) meta.retainedParts = reasoningItems;
+			if (typeof response?.id === "string") meta.responseId = response.id;
+			if (options?.effortDownmapped === true) meta.effortDownmapped = "max->xhigh";
+			emit({
+				type: "finish",
+				finish,
+				usage,
+				providerMetadata: { openai: meta }
+			});
+			return;
+		}
+		case "response.failed": {
+			const error = event.response?.error;
+			emit({
+				type: "error",
+				error: {
+					code: "agent",
+					message: error?.message ?? "response.failed",
+					retryable: false,
+					data: { kind: "transport" }
+				}
+			});
+			return;
+		}
+		case "error":
+			emit({
+				type: "error",
+				error: {
+					code: "agent",
+					message: event.message ?? "stream error",
+					retryable: false,
+					data: { kind: "transport" }
+				}
+			});
+			return;
+		default: break;
+	}
+}
+/** Projects SDK/API errors into the retryable WireError vocabulary. */
+function openAiErrorToWire(error) {
+	const record = error;
+	const status = typeof record.status === "number" ? record.status : void 0;
+	const message = typeof record.message === "string" ? record.message : String(error);
+	if (status === 429) {
+		let retryAfterMs;
+		const headers = record.headers;
+		if (headers !== void 0 && headers !== null) {
+			const value = typeof headers.get === "function" ? headers.get("retry-after") ?? void 0 : headers["retry-after"];
+			if (value !== void 0) retryAfterMs = Number(value) * 1e3;
+		}
+		return {
+			code: "agent",
+			message,
+			retryable: true,
+			data: {
+				kind: "rate-limit",
+				...retryAfterMs === void 0 ? {} : { retryAfterMs },
+				status: 429
+			}
+		};
+	}
+	return {
+		code: "agent",
+		message,
+		retryable: status === void 0 || status >= 500,
+		data: {
+			kind: "transport",
+			...status === void 0 ? {} : { status }
+		}
+	};
+}
+/**
+* The Chat Completions degraded path (docs/04, section 5.6): delta-patched
+* chunk assembly instead of typed SSE, nested function tools with explicit
+* strict where supported, response_format instead of text.format, no
+* reasoning item replay. Selected by caps (api: 'chat'), visible in
+* events, never silent.
+*/
+function buildChatCompletionsParams(req, ids) {
+	const messages = [];
+	for (const msg of req.messages) {
+		if (msg.role === "system") {
+			const text = msg.parts.filter((part) => part.type === "text").map((part) => part.text).join("\n\n");
+			messages.push({
+				role: "system",
+				content: text
+			});
+			continue;
+		}
+		if (msg.role === "assistant") {
+			const text = msg.parts.filter((part) => part.type === "text").map((part) => part.text).join("");
+			const toolCalls = msg.parts.filter((part) => part.type === "tool-call").map((part) => {
+				const call = part;
+				return {
+					id: ids.wireFor(call.id),
+					type: "function",
+					function: {
+						name: call.name,
+						arguments: JSON.stringify(call.args ?? {})
+					}
+				};
+			});
+			const item = { role: "assistant" };
+			if (text !== "") item.content = text;
+			if (toolCalls.length > 0) item.tool_calls = toolCalls;
+			messages.push(item);
+			continue;
+		}
+		for (const part of msg.parts) if (part.type === "tool-result") messages.push({
+			role: "tool",
+			tool_call_id: ids.wireFor(part.id),
+			content: typeof part.result === "string" ? part.result : JSON.stringify(part.result ?? null)
+		});
+		else if (part.type === "text") messages.push({
+			role: "user",
+			content: part.text
+		});
+	}
+	const params = {
+		model: req.model,
+		messages
+	};
+	if (req.maxOutputTokens !== void 0) params.max_completion_tokens = req.maxOutputTokens;
+	if (req.stopSequences !== void 0) params.stop = req.stopSequences;
+	if (req.tools !== void 0) {
+		params.tools = req.tools.map((tool) => ({
+			type: "function",
+			function: {
+				name: tool.name,
+				description: tool.description,
+				parameters: tool.parameters,
+				strict: isStrictCompatibleSchema(tool.parameters)
+			}
+		}));
+		if (req.toolChoice === "required") params.tool_choice = "required";
+		else if (typeof req.toolChoice === "object") params.tool_choice = {
+			type: "function",
+			function: { name: req.toolChoice.name }
+		};
+		else if (req.toolChoice === "none") params.tool_choice = "none";
+	}
+	if (req.schema !== void 0) params.response_format = {
+		type: "json_schema",
+		json_schema: {
+			name: "output",
+			schema: req.schema,
+			strict: isStrictCompatibleSchema(req.schema)
+		}
+	};
+	return params;
+}
+/** Delta-patched chunk assembly for the degraded path. */
+async function mapChatCompletionsStream(stream, ids, emit) {
+	const pendingCalls = /* @__PURE__ */ new Map();
+	let finishReason;
+	let usage = {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	};
+	for await (const chunk of stream) {
+		const choice = chunk.choices?.[0];
+		const delta = choice?.delta;
+		if (typeof delta?.content === "string" && delta.content !== "") emit({
+			type: "text-delta",
+			text: delta.content
+		});
+		const toolCalls = delta?.tool_calls;
+		if (toolCalls !== void 0) for (const call of toolCalls) {
+			const index = call.index ?? 0;
+			const fn = call.function;
+			let pending = pendingCalls.get(index);
+			if (pending === void 0) {
+				pending = {
+					id: call.id ?? `call_${index}`,
+					name: "",
+					args: ""
+				};
+				pendingCalls.set(index, pending);
+				emit({
+					type: "tool-call-start",
+					id: ids.canonicalFor(pending.id),
+					name: fn?.name ?? ""
+				});
+			}
+			if (typeof fn?.name === "string") pending.name += fn.name;
+			if (typeof fn?.arguments === "string" && fn.arguments !== "") {
+				pending.args += fn.arguments;
+				emit({
+					type: "tool-call-delta",
+					id: ids.canonicalFor(pending.id),
+					argsTextDelta: fn.arguments
+				});
+			}
+		}
+		if (typeof choice?.finish_reason === "string") finishReason = choice.finish_reason;
+		const chunkUsage = chunk.usage;
+		if (chunkUsage !== void 0 && chunkUsage !== null) {
+			const promptDetails = chunkUsage.prompt_tokens_details;
+			usage = {
+				inputTokens: typeof chunkUsage.prompt_tokens === "number" ? chunkUsage.prompt_tokens : 0,
+				outputTokens: typeof chunkUsage.completion_tokens === "number" ? chunkUsage.completion_tokens : 0,
+				cacheReadTokens: typeof promptDetails?.cached_tokens === "number" ? promptDetails.cached_tokens : 0,
+				cacheWriteTokens: 0
+			};
+		}
+	}
+	for (const [, pending] of pendingCalls) {
+		let args = {};
+		try {
+			args = pending.args === "" ? {} : JSON.parse(pending.args);
+		} catch {
+			args = { __unparsed: pending.args };
+		}
+		emit({
+			type: "tool-call-end",
+			id: ids.canonicalFor(pending.id),
+			args
+		});
+	}
+	emit({
+		type: "usage",
+		usage
+	});
+	emit({
+		type: "finish",
+		finish: finishReason === "length" ? { reason: "max-tokens" } : finishReason === "tool_calls" ? { reason: "tool-calls" } : finishReason === "content_filter" ? {
+			reason: "refusal",
+			refusal: { provider: "openai" }
+		} : { reason: "stop" },
+		usage,
+		providerMetadata: { openai: { degradedPath: "chat" } }
+	});
+}
+//#endregion
+//#region src/adapter.ts
+/**
+* The @rulvar/openai ProviderAdapter (M1-T13): Responses API first, Chat
+* Completions as the caps-selected degraded path, SDK autoretries
+* disabled.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "@rulvar/openai
+* (Responses API)". The openaiCompatible factory ships in M3.
+*/
+/** Creates the first-class OpenAI adapter (id 'openai'); maxRetries 0. */
+function openai(options = {}) {
+	const client = options.client ?? new OpenAI({
+		...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
+		...options.baseURL === void 0 ? {} : { baseURL: options.baseURL },
+		maxRetries: 0
+	});
+	const ids = new OpenAiIdMap(createCanonicalIdMinter());
+	return {
+		id: "openai",
+		provider: "openai",
+		caps(model) {
+			return openAiModelInfo(model).caps;
+		},
+		async *stream(req, signal) {
+			const info = openAiModelInfo(req.model);
+			const pending = [];
+			const emit = (event) => {
+				pending.push(event);
+			};
+			try {
+				if (info.api === "responses") {
+					const { params, effortDownmapped } = buildResponsesParams(req, ids);
+					await mapResponsesStream(await client.responses.create({
+						...params,
+						stream: true
+					}, signal === void 0 ? void 0 : { signal }), ids, emit, { effortDownmapped });
+				} else {
+					const params = buildChatCompletionsParams(req, ids);
+					await mapChatCompletionsStream(await client.chat.completions.create({
+						...params,
+						stream: true,
+						stream_options: { include_usage: true }
+					}, signal === void 0 ? void 0 : { signal }), ids, emit);
+				}
+			} catch (thrown) {
+				if (signal?.aborted !== true) pending.push({
+					type: "error",
+					error: openAiErrorToWire(thrown)
+				});
+			}
+			for (const event of pending) yield event;
+		}
+	};
+}
+//#endregion
+//#region src/compatible.ts
+/**
+* openaiCompatible factory (M3-T06): a ProviderAdapter for
+* OpenAI-compatible endpoints (Ollama, vLLM, Mistral, OpenRouter,
+* arbitrary gateways) speaking the Chat Completions dialect by
+* construction. Explicit ids let several endpoints coexist in one
+* engine; a duplicate adapterId at createEngine is a typed ConfigError
+* raised by the adapter registry.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "openaiCompatible
+* factory".
+*/
+/**
+* Gateways cannot be introspected reliably: when caps are not supplied
+* the factory assumes the most conservative capability set (docs/04,
+* section 6). Callers SHOULD supply caps for anything beyond it; the
+* window and output floors here are deliberately small so an unprobed
+* endpoint is never overcommitted. Absent pricing is legitimate for
+* local models: they surface as unpriced in CostReport.
+*/
+const CONSERVATIVE_COMPATIBLE_CAPS = {
+	structuredOutput: "prompt",
+	supportsTemperature: true,
+	supportsParallelTools: false,
+	reasoningEfforts: [],
+	contextWindow: 8192,
+	maxOutputTokens: 4096
+};
+/** Creates a Chat Completions dialect adapter for a compatible endpoint. */
+function openaiCompatible(cfg) {
+	if (cfg.id === void 0 || cfg.id === "") throw new ConfigError("openaiCompatible requires an explicit non-empty 'id' (docs/04, section 6)");
+	if (cfg.baseURL === void 0 || cfg.baseURL === "") throw new ConfigError("openaiCompatible requires 'baseURL'");
+	const client = cfg.client ?? new OpenAI({
+		baseURL: cfg.baseURL,
+		apiKey: cfg.apiKey ?? "rulvar-no-key",
+		maxRetries: 0
+	});
+	const ids = new OpenAiIdMap(createCanonicalIdMinter());
+	return {
+		id: cfg.id,
+		provider: "openai",
+		caps(model) {
+			const overrides = cfg.caps?.(model);
+			return overrides === void 0 ? CONSERVATIVE_COMPATIBLE_CAPS : {
+				...CONSERVATIVE_COMPATIBLE_CAPS,
+				...overrides
+			};
+		},
+		async *stream(req, signal) {
+			const pending = [];
+			const emit = (event) => {
+				pending.push(event);
+			};
+			try {
+				const params = buildChatCompletionsParams(req, ids);
+				await mapChatCompletionsStream(await client.chat.completions.create({
+					...params,
+					stream: true,
+					stream_options: { include_usage: true }
+				}, signal === void 0 ? void 0 : { signal }), ids, emit);
+			} catch (thrown) {
+				if (signal?.aborted !== true) pending.push({
+					type: "error",
+					error: openAiErrorToWire(thrown)
+				});
+			}
+			for (const event of pending) yield event;
+		}
+	};
+}
+//#endregion
+export { CONSERVATIVE_COMPATIBLE_CAPS, OPENAI_MODELS, OpenAiIdMap, buildChatCompletionsParams, buildResponsesParams, mapChatCompletionsStream, mapOpenAiEffort, mapResponsesStream, normalizeOpenAiUsage, openAiErrorToWire, openAiModelInfo, openai, openaiCompatible };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rulvar/openai",
+  "version": "1.0.0",
+  "description": "rulvar first-class provider adapter for the OpenAI Responses API, plus the openaiCompatible factory.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openai": "^6.45.0",
+    "@rulvar/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/openai"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}