@warlock.js/ai-openai 4.1.1

package/cjs/index.cjs

@@ -0,0 +1,838 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let openai = require("openai");
+openai = __toESM(openai, 1);
+let _warlock_js_ai = require("@warlock.js/ai");
+let _warlock_js_logger = require("@warlock.js/logger");
+
+//#region ../../@warlock.js/ai-openai/src/utils/map-finish-reason.ts
+const finishReasonMap = {
+	stop: "stop",
+	tool_calls: "tool_calls",
+	length: "length"
+};
+/**
+* Map the raw OpenAI `finish_reason` string to the normalized FinishReason union.
+* Unknown/unexpected values fall through to "error".
+*
+* @example
+* mapFinishReason("stop");        // "stop"
+* mapFinishReason("tool_calls");  // "tool_calls"
+* mapFinishReason(null);          // "error"
+*/
+function mapFinishReason(raw) {
+	return finishReasonMap[raw ?? ""] ?? "error";
+}
+
+//#endregion
+//#region ../../@warlock.js/ai-openai/src/utils/to-openai-messages.ts
+/**
+* Convert vendor-neutral Message[] to OpenAI's chat message shape.
+* Handles the `tool` role (requires `tool_call_id`) and assistant messages
+* that carry `toolCalls` from a prior model response.
+*
+* Multipart `content` (a `ContentPart[]`) is mapped into OpenAI's user-message
+* content-parts shape: text becomes `{ type: "text", text }`, images become
+* `{ type: "image_url", image_url: { url } }` — with base64 sources rendered
+* as `data:` URLs inline.
+*
+* @example
+* const openaiMessages = toOpenAIMessages([
+*   { role: "user", content: "Hi" },
+*   { role: "tool", toolCallId: "call_1", content: '{"ok":true}' },
+* ]);
+*
+* @example
+* toOpenAIMessages([
+*   { role: "user", content: [
+*     { type: "text", text: "What is this?" },
+*     { type: "image", source: { url: "https://example.com/cat.jpg" } },
+*   ]},
+* ]);
+*/
+function toOpenAIMessages(messages) {
+	return messages.map((m) => {
+		if (m.role === "tool") return {
+			role: "tool",
+			content: stringifyContent(m.content),
+			tool_call_id: m.toolCallId ?? ""
+		};
+		if (m.role === "assistant" && m.toolCalls && m.toolCalls.length > 0) return {
+			role: "assistant",
+			content: stringifyContent(m.content),
+			tool_calls: m.toolCalls.map((tc) => ({
+				id: tc.id,
+				type: "function",
+				function: {
+					name: tc.name,
+					arguments: JSON.stringify(tc.input ?? {})
+				}
+			}))
+		};
+		if (m.role === "user" && Array.isArray(m.content)) return {
+			role: "user",
+			content: m.content.map(toOpenAIContentPart)
+		};
+		return {
+			role: m.role,
+			content: stringifyContent(m.content)
+		};
+	});
+}
+/**
+* Multipart content is only meaningful on user messages — for any other
+* role (system / assistant text / tool), collapse a `ContentPart[]` to
+* its concatenated text so OpenAI's wire format stays valid. Plain
+* strings pass through unchanged.
+*/
+function stringifyContent(content) {
+	if (typeof content === "string") return content;
+	return content.filter((part) => part.type === "text").map((part) => part.text).join("");
+}
+function toOpenAIContentPart(part) {
+	if (part.type === "text") return {
+		type: "text",
+		text: part.text
+	};
+	return {
+		type: "image_url",
+		image_url: { url: "url" in part.source ? part.source.url : `data:${part.source.mediaType};base64,${part.source.base64}` }
+	};
+}
+
+//#endregion
+//#region ../../@warlock.js/ai-openai/src/utils/to-openai-tools.ts
+/**
+* Convert vendor-neutral ToolConfig[] to OpenAI's tools array.
+* Uses the shared `extractJsonSchema` helper; falls back to an empty-object
+* schema when extraction fails so the tool still registers with the provider.
+*
+* @example
+* const tools = toOpenAITools([weatherTool, calculatorTool]);
+* await client.chat.completions.create({ model, messages, tools });
+*/
+function toOpenAITools(tools) {
+	if (!tools || tools.length === 0) return;
+	return tools.map((tool) => ({
+		type: "function",
+		function: {
+			name: tool.name,
+			description: tool.description,
+			parameters: toParameters(tool.input)
+		}
+	}));
+}
+/**
+* Resolve a tool's input schema to a JSON-Schema object. OpenAI's
+* function `parameters` expects an object root; anything else (or a
+* 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 ../../@warlock.js/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,
+		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,
+			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;
+	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.
+*/
+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;
+}
+/**
+* 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 ../../@warlock.js/ai-openai/src/embedder.ts
+const LOG_MODULE$1 = "ai.openai";
+/**
+* OpenAI-backed implementation of `EmbedderContract`.
+*
+* **Role.** Converts text (or a batch of texts) into floating-point
+* vectors via OpenAI's Embeddings API. Standalone primitive — no
+* relationship to chat completions, tools, or the agent loop.
+*
+* **Dimensions.** When no `dimensions` override is supplied in config,
+* `this.dimensions` starts at `0` and is populated from the first
+* response's vector length, then cached for all subsequent calls —
+* even if a later response were to return a different length, the
+* first value wins so batches stay dimensionally consistent. Passing
+* `dimensions` in config both forwards the truncation hint to the API
+* (for models like `text-embedding-3-*`) and sets the initial value.
+*
+* **Error handling.** Raw OpenAI SDK errors are wrapped into the
+* typed `@warlock.js/ai` `AIError` hierarchy via `wrapOpenAIError` —
+* callers catch `AIError` subclasses (`ProviderRateLimitError`,
+* `ProviderAuthError`, etc.) instead of OpenAI's own classes.
+*
+* @example
+* const embedder = new OpenAIEmbedder(client, { name: "text-embedding-3-small" });
+* const { vector, dimensions, usage } = await embedder.embed("Hello world");
+* const { vectors } = await embedder.embedMany(["doc 1", "doc 2"]);
+*/
+var OpenAIEmbedder = class {
+	constructor(client, config) {
+		this.provider = "openai";
+		this.logger = _warlock_js_logger.log;
+		this.client = client;
+		this.name = config.name;
+		this.configuredDimensions = config.dimensions;
+		this.dimensions = config.dimensions ?? 0;
+	}
+	async embed(input) {
+		const { response, usage } = await this.request(input);
+		return {
+			vector: response.data[0].embedding,
+			dimensions: this.dimensions,
+			usage
+		};
+	}
+	async embedMany(inputs) {
+		const { response, usage } = await this.request(inputs);
+		return {
+			vectors: response.data.map((d) => d.embedding),
+			dimensions: this.dimensions,
+			usage
+		};
+	}
+	/**
+	* Shared transport for both `embed()` and `embedMany()` — issues the
+	* `embeddings.create` call, wraps provider errors, caches dimensions
+	* on the first successful response, and returns the raw response
+	* plus a camelCase usage object for the caller to shape.
+	*/
+	async request(input) {
+		this.logger.debug(LOG_MODULE$1, "embedder.request", "embeddings.create", {
+			model: this.name,
+			batch: Array.isArray(input),
+			count: Array.isArray(input) ? input.length : 1
+		});
+		let response;
+		try {
+			response = await this.client.embeddings.create({
+				model: this.name,
+				input,
+				...this.configuredDimensions !== void 0 ? { dimensions: this.configuredDimensions } : {}
+			});
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE$1, "embedder.error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		this.logger.debug(LOG_MODULE$1, "embedder.response", "embeddings.create returned", {
+			dimensions: response.data[0]?.embedding.length,
+			usage: {
+				promptTokens: response.usage.prompt_tokens,
+				totalTokens: response.usage.total_tokens
+			}
+		});
+		if (this.dimensions === 0) this.dimensions = response.data[0].embedding.length;
+		const usage = {
+			promptTokens: response.usage.prompt_tokens,
+			totalTokens: response.usage.total_tokens
+		};
+		return {
+			response,
+			usage
+		};
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/ai-openai/src/known-vision-models.ts
+/**
+* Model-name prefixes for OpenAI families that support vision input
+* (image attachments) on the Chat Completions API.
+*
+* Matched as a prefix so dated variants (`gpt-4o-2024-08-06`) and
+* `-mini` / `-preview` suffixes (`gpt-4o-mini`, `gpt-4-turbo-preview`)
+* are covered without listing every release tag explicitly.
+*
+* Maintenance: append a new prefix when OpenAI ships a vision-capable
+* model family that doesn't already match. Devs can always override
+* per-model via `openai.model({ name, vision: true | false })` —
+* explicit config wins over inference in either direction.
+*/
+const VISION_CAPABLE_PREFIXES = [
+	"gpt-4o",
+	"gpt-4-turbo",
+	"gpt-4.1",
+	"o1",
+	"o3",
+	"chatgpt-4o"
+];
+/**
+* Infer whether a given OpenAI model name supports vision based on the
+* known-prefix list. Unknown models default to `false` so that passing
+* an image attachment to an unsupported model surfaces a clear,
+* agent-side capability error instead of an opaque OpenAI 400.
+*
+* @example
+* inferVisionCapability("gpt-4o-mini");          // → true
+* inferVisionCapability("gpt-4o-2024-08-06");    // → true
+* inferVisionCapability("gpt-3.5-turbo");        // → false
+* inferVisionCapability("custom-llm");           // → false
+*/
+function inferVisionCapability(modelName) {
+	const normalized = modelName.toLowerCase();
+	return VISION_CAPABLE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+//#endregion
+//#region ../../@warlock.js/ai-openai/src/model.ts
+const LOG_MODULE = "ai.openai";
+/**
+* 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;
+}
+/**
+* OpenAI-backed implementation of `ModelContract`.
+*
+* **Role.** The provider-facing bridge between the vendor-neutral
+* `@warlock.js/ai` agent runtime and the official `openai` SDK. Agents,
+* workflows, and supervisors never talk to OpenAI directly — they hold a
+* `ModelContract`, and this class is what makes that contract concrete for
+* any OpenAI-compatible endpoint (OpenAI, Azure OpenAI, OpenRouter, local
+* gateways that speak the Chat Completions protocol).
+*
+* **Responsibility.**
+* - Owns: a long-lived `OpenAI` client + frozen `ModelConfig` (name,
+*   temperature, maxTokens) used as defaults for every call.
+* - Owns: translating vendor-neutral `Message[]` and
+*   `ToolContract[]` into OpenAI wire shapes on the way out, and
+*   translating OpenAI's response (content, finish reason, tool calls,
+*   usage) back into the neutral shapes on the way in.
+* - Does NOT own: dispatching tools, deciding whether to loop, tracking
+*   conversation history, or retrying on failure — those are agent
+*   concerns. The model is a stateless (per-call) protocol adapter.
+*
+* Because it holds a live client and shared defaults, it is modeled as a
+* class (see §4.2 of code-style.md — "long-lived state across calls").
+*
+* @example
+* import OpenAI from "openai";
+* const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+* const model = new OpenAIModel(client, { name: "gpt-4o", temperature: 0.3 });
+*
+* const myAgent = agent({
+*   model,
+*   systemPrompt: "You are a helpful assistant.",
+*   tools: [searchTool],
+* });
+*
+* const result = await myAgent.execute("Summarize today's news.");
+*/
+var OpenAIModel = class {
+	constructor(client, config, provider = "openai") {
+		this.logger = _warlock_js_logger.log;
+		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)
+		};
+	}
+	/**
+	* Single-shot completion. Sends the full message list to the Chat
+	* Completions endpoint, waits for the terminal response, and reshapes it
+	* into a vendor-neutral `ModelResponse`. Per-call `options` override the
+	* instance's `ModelConfig` defaults for this call only.
+	*/
+	async complete(messages, options) {
+		this.logger.debug(LOG_MODULE, "request", "Starting call to chat.completions", {
+			model: this.name,
+			messageCount: messages.length,
+			streaming: false,
+			toolCount: options?.tools?.length ?? 0
+		});
+		let response;
+		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,
+				tools: toOpenAITools(options?.tools),
+				...this.buildResponseFormat(options?.responseSchema)
+			}, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		const choice = response.choices[0];
+		const finishReason = mapFinishReason(choice.finish_reason);
+		const usage = this.extractUsage(response.usage);
+		this.logger.debug(LOG_MODULE, "response", "call to chat.completions succeeded", {
+			finishReason,
+			usage
+		});
+		return {
+			content: choice.message.content ?? "",
+			finishReason,
+			usage,
+			toolCalls: this.extractToolCalls(choice.message.tool_calls)
+		};
+	}
+	/**
+	* Incremental streaming completion. Yields neutral `ModelStreamChunk`s —
+	* `delta` for text tokens, `tool-call` when the model requests a tool,
+	* and a terminal `done` carrying the final finish reason + usage totals.
+	* Callers consume it with `for await`.
+	*/
+	async *stream(messages, options) {
+		this.logger.debug(LOG_MODULE, "request", "Starting streaming call to chat.completions", {
+			model: this.name,
+			messageCount: messages.length,
+			streaming: true,
+			toolCount: options?.tools?.length ?? 0
+		});
+		let stream;
+		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,
+				tools: toOpenAITools(options?.tools),
+				stream: true,
+				stream_options: { include_usage: true },
+				...this.buildResponseFormat(options?.responseSchema)
+			}, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		let rawFinishReason = "stop";
+		const usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		const toolCallAccum = /* @__PURE__ */ new Map();
+		try {
+			for await (const chunk of stream) {
+				const delta = chunk.choices[0]?.delta;
+				const finish = chunk.choices[0]?.finish_reason;
+				if (delta?.content) yield {
+					type: "delta",
+					content: delta.content
+				};
+				if (delta?.tool_calls) for (const toolCall of delta.tool_calls) {
+					const idx = toolCall.index ?? 0;
+					if (!toolCallAccum.has(idx)) toolCallAccum.set(idx, {
+						id: "",
+						name: "",
+						arguments: ""
+					});
+					const acc = toolCallAccum.get(idx);
+					if (toolCall.id) acc.id = toolCall.id;
+					if (toolCall.function?.name) acc.name = toolCall.function.name;
+					if (toolCall.function?.arguments) acc.arguments += toolCall.function.arguments;
+				}
+				if (finish) rawFinishReason = finish;
+				if (chunk.usage) {
+					usage.input = chunk.usage.prompt_tokens ?? 0;
+					usage.output = chunk.usage.completion_tokens ?? 0;
+					usage.total = chunk.usage.total_tokens ?? 0;
+					const cached = chunk.usage.prompt_tokens_details?.cached_tokens;
+					if (cached !== void 0 && cached > 0) usage.cachedTokens = cached;
+				}
+			}
+			for (const acc of toolCallAccum.values()) {
+				if (!acc.name) continue;
+				yield {
+					type: "tool-call",
+					id: acc.id,
+					name: acc.name,
+					input: (0, _warlock_js_ai.safeJsonParse)(acc.arguments, {})
+				};
+			}
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		const finishReason = mapFinishReason(rawFinishReason);
+		this.logger.debug(LOG_MODULE, "response", "Streaming call to chat.completions succeeded", {
+			finishReason,
+			usage
+		});
+		yield {
+			type: "done",
+			finishReason,
+			usage
+		};
+	}
+	/**
+	* 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.
+	*
+	* 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: {
+			type: "json_schema",
+			json_schema: {
+				name: "response",
+				schema: responseSchema,
+				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;
+	}
+	/**
+	* Normalize OpenAI's `usage` block (which may be absent on some responses
+	* or partials) into the neutral `Usage` shape. Missing usage collapses to
+	* zeros rather than propagating `undefined`, so downstream aggregation
+	* math stays safe.
+	*/
+	extractUsage(raw) {
+		if (!raw) return {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		const cachedTokens = raw.prompt_tokens_details?.cached_tokens;
+		return {
+			input: raw.prompt_tokens,
+			output: raw.completion_tokens,
+			total: raw.total_tokens,
+			...cachedTokens !== void 0 && cachedTokens > 0 ? { cachedTokens } : {}
+		};
+	}
+	/**
+	* Reshape OpenAI's `tool_calls` array into the neutral
+	* `ModelToolCallRequest[]`. The raw `arguments` field is a JSON string
+	* per OpenAI's protocol — we parse it defensively via `safeJsonParse` so
+	* malformed or empty arguments yield an empty object instead of crashing
+	* the trip. Returns `undefined` when no tools were requested so callers
+	* can branch on presence.
+	*/
+	extractToolCalls(rawToolCalls) {
+		if (!rawToolCalls || rawToolCalls.length === 0) return;
+		return rawToolCalls.map((toolCall) => ({
+			id: toolCall.id,
+			name: toolCall.function.name,
+			input: (0, _warlock_js_ai.safeJsonParse)(toolCall.function.arguments, {})
+		}));
+	}
+};
+
+//#endregion
+//#region ../../@warlock.js/ai-openai/src/sdk.ts
+/**
+* OpenAI-backed implementation of `SDKAdapterContract`.
+*
+* **Role.** The package entry point for any OpenAI-compatible provider
+* (OpenAI, Azure OpenAI, OpenRouter, local gateways speaking the Chat
+* Completions protocol). A single `OpenAISDK` instance holds one live
+* `OpenAI` client, shared by every `ModelContract` it produces via
+* `model()`. Users construct one SDK per provider/account and reuse it
+* across all agents, workflows, and supervisors that target that
+* provider.
+*
+* **Responsibility.**
+* - Owns: a long-lived `OpenAI` client (authentication, base URL) and
+*   its lifetime scope. Factory for `OpenAIModel` instances — each
+*   model call gets a reference to the same client.
+* - Does NOT own: anything per-call (tool execution, message history,
+*   streaming loop) — those live in `OpenAIModel` and the agent runtime.
+*
+* Modeled as a class (see §4.2 of code-style.md — "long-lived state
+* across many calls"): the `OpenAI` client is heavy to construct and
+* designed to be reused; keeping it on `this` makes that reuse
+* explicit and aligns with the PascalCase naming convention readers
+* expect from a constructor.
+*
+* @example
+* const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+* const model = openai.model({ name: "gpt-4o", temperature: 0.7 });
+* const tokens = await openai.count("Hello world");
+*
+* @example
+* // Compose into an `ai.openai` namespace for ergonomic agent wiring
+* const ai = { agent, tool, systemPrompt, persona, instruction, openai: new OpenAISDK({ apiKey }) };
+* const myAgent = ai.agent({ model: ai.openai.model({ name: "gpt-4o-mini" }) });
+*/
+var OpenAISDK = class {
+	constructor(config) {
+		this.client = new openai.default({
+			apiKey: config.apiKey,
+			baseURL: config.baseURL
+		});
+		this.provider = config.provider ?? "openai";
+		this.pricing = config.pricing;
+	}
+	/**
+	* Build an `OpenAIModel` bound to this SDK's client. Each call returns
+	* a fresh model instance, but all instances share the underlying
+	* `OpenAI` client — connection pools, rate limits, and authentication
+	* state stay unified across every model produced here. The SDK's
+	* `provider` label is forwarded so every model self-identifies as
+	* coming from the same upstream.
+	*
+	* Pricing resolution: per-model `config.pricing` wins; otherwise the
+	* SDK-level registry entry keyed by `config.name`; otherwise
+	* `undefined` (no cost computed).
+	*/
+	model(config) {
+		const resolvedPricing = config.pricing ?? this.pricing?.[config.name];
+		const resolvedConfig = resolvedPricing === config.pricing ? config : {
+			...config,
+			pricing: resolvedPricing
+		};
+		return new OpenAIModel(this.client, resolvedConfig, this.provider);
+	}
+	/**
+	* Rough token-count estimate for a given text. Uses a
+	* character-heuristic (`approximateTokenCount`) from the core package
+	* — good enough for budgeting and quota guards, not for billing.
+	* Accepts an optional model id for future per-model tokenizer
+	* dispatch; currently ignored.
+	*/
+	async count(text, _model) {
+		return (0, _warlock_js_ai.approximateTokenCount)(text);
+	}
+	/**
+	* Build an `OpenAIEmbedder` bound to this SDK's client. Each call
+	* returns a fresh embedder instance sharing the same underlying
+	* `OpenAI` client — connection pools and authentication stay unified
+	* across every embedder produced here.
+	*
+	* @example
+	* const embedder = openai.embedder({ name: "text-embedding-3-small" });
+	* const { vector } = await embedder.embed("Hello world");
+	*/
+	embedder(config) {
+		return new OpenAIEmbedder(this.client, config);
+	}
+};
+
+//#endregion
+exports.OpenAIEmbedder = OpenAIEmbedder;
+exports.OpenAISDK = OpenAISDK;
+//# sourceMappingURL=index.cjs.map