@warlock.js/ai-openai 4.1.1

package/esm/model.mjs

@@ -0,0 +1,309 @@
+import { mapFinishReason } from "./utils/map-finish-reason.mjs";
+import { toOpenAIMessages } from "./utils/to-openai-messages.mjs";
+import { toOpenAITools } from "./utils/to-openai-tools.mjs";
+import { wrapOpenAIError } from "./utils/wrap-openai-error.mjs";
+import "./utils/index.mjs";
+import { inferVisionCapability } from "./known-vision-models.mjs";
+import { safeJsonParse } from "@warlock.js/ai";
+import { log } from "@warlock.js/logger";
+
+//#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 = 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: 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: safeJsonParse(toolCall.function.arguments, {})
+		}));
+	}
+};
+
+//#endregion
+export { OpenAIModel };
+//# sourceMappingURL=model.mjs.map

package/esm/model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.mjs","names":[],"sources":["../../../../../@warlock.js/ai-openai/src/model.ts"],"sourcesContent":["import {\n  safeJsonParse,\n  type Message,\n  type ModelCallOptions,\n  type ModelCapabilities,\n  type ModelContract,\n  type ModelPricing,\n  type ModelResponse,\n  type ModelStreamChunk,\n  type ModelToolCallRequest,\n  type Usage,\n} from \"@warlock.js/ai\";\nimport { log, type Logger } from \"@warlock.js/logger\";\nimport type OpenAI from \"openai\";\nimport type { OpenAIModelConfig, OpenAIResponseFormat } from \"./config.type\";\nimport { inferVisionCapability } from \"./known-vision-models\";\nimport { mapFinishReason, toOpenAIMessages, toOpenAITools, wrapOpenAIError } from \"./utils\";\n\nconst LOG_MODULE = \"ai.openai\";\n\n/**\n * Map an explicit `responseFormat` override to the default\n * `structuredOutput` capability. Loose wire modes (`\"json_object\"`,\n * `\"text\"`) don't enforce shape, so the agent needs to see the soft\n * schema hint in the system prompt — that only happens when the\n * capability is `false`. Default (no override) stays `true` to\n * preserve the prior assumption that OpenAI models support strict\n * structured output.\n */\nfunction inferStructuredOutput(responseFormat: OpenAIResponseFormat | undefined): boolean {\n  if (responseFormat === \"json_object\" || responseFormat === \"text\") {\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * OpenAI-backed implementation of `ModelContract`.\n *\n * **Role.** The provider-facing bridge between the vendor-neutral\n * `@warlock.js/ai` agent runtime and the official `openai` SDK. Agents,\n * workflows, and supervisors never talk to OpenAI directly — they hold a\n * `ModelContract`, and this class is what makes that contract concrete for\n * any OpenAI-compatible endpoint (OpenAI, Azure OpenAI, OpenRouter, local\n * gateways that speak the Chat Completions protocol).\n *\n * **Responsibility.**\n * - Owns: a long-lived `OpenAI` client + frozen `ModelConfig` (name,\n *   temperature, maxTokens) used as defaults for every call.\n * - Owns: translating vendor-neutral `Message[]` and\n *   `ToolContract[]` into OpenAI wire shapes on the way out, and\n *   translating OpenAI's response (content, finish reason, tool calls,\n *   usage) back into the neutral shapes on the way in.\n * - Does NOT own: dispatching tools, deciding whether to loop, tracking\n *   conversation history, or retrying on failure — those are agent\n *   concerns. The model is a stateless (per-call) protocol adapter.\n *\n * Because it holds a live client and shared defaults, it is modeled as a\n * class (see §4.2 of code-style.md — \"long-lived state across calls\").\n *\n * @example\n * import OpenAI from \"openai\";\n * const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });\n * const model = new OpenAIModel(client, { name: \"gpt-4o\", temperature: 0.3 });\n *\n * const myAgent = agent({\n *   model,\n *   systemPrompt: \"You are a helpful assistant.\",\n *   tools: [searchTool],\n * });\n *\n * const result = await myAgent.execute(\"Summarize today's news.\");\n */\nexport class OpenAIModel implements ModelContract {\n  public readonly name: string;\n  public readonly provider: string;\n  public readonly capabilities: ModelCapabilities;\n  public readonly pricing?: ModelPricing;\n\n  private readonly client: OpenAI;\n  private readonly config: OpenAIModelConfig;\n  private readonly logger: Logger = log;\n\n  public constructor(client: OpenAI, config: OpenAIModelConfig, provider: string = \"openai\") {\n    this.client = client;\n    this.config = config;\n    this.name = config.name;\n    this.provider = provider;\n    this.pricing = config.pricing;\n    this.capabilities = {\n      structuredOutput: config.structuredOutput ?? inferStructuredOutput(config.responseFormat),\n      vision: config.vision ?? inferVisionCapability(config.name),\n    };\n  }\n\n  /**\n   * Single-shot completion. Sends the full message list to the Chat\n   * Completions endpoint, waits for the terminal response, and reshapes it\n   * into a vendor-neutral `ModelResponse`. Per-call `options` override the\n   * instance's `ModelConfig` defaults for this call only.\n   */\n  public async complete(messages: Message[], options?: ModelCallOptions): Promise<ModelResponse> {\n    // Per-call request/response logs are hot-path in production agents\n    // — keep them at `debug` so `info` stays reserved for lifecycle\n    // events (agent starting/completed, etc.). Operators who need to\n    // audit every LLM call can raise log-level at runtime.\n    this.logger.debug(LOG_MODULE, \"request\", \"Starting call to chat.completions\", {\n      model: this.name,\n      messageCount: messages.length,\n      streaming: false,\n      toolCount: options?.tools?.length ?? 0,\n    });\n\n    let response: OpenAI.Chat.Completions.ChatCompletion;\n\n    try {\n      response = await this.client.chat.completions.create(\n        {\n          model: this.name,\n          messages: toOpenAIMessages(messages),\n          temperature: options?.temperature ?? this.config.temperature,\n          max_tokens: options?.maxTokens ?? this.config.maxTokens,\n          tools: toOpenAITools(options?.tools),\n          ...this.buildResponseFormat(options?.responseSchema),\n        },\n        options?.signal ? { signal: options.signal } : undefined,\n      );\n    } catch (thrown) {\n      const wrapped = wrapOpenAIError(thrown);\n\n      this.logger.error(LOG_MODULE, \"error\", wrapped.message, {\n        code: wrapped.code,\n        context: wrapped.context,\n      });\n\n      throw wrapped;\n    }\n\n    const choice = response.choices[0];\n    const finishReason = mapFinishReason(choice.finish_reason);\n    const usage = this.extractUsage(response.usage);\n\n    this.logger.debug(LOG_MODULE, \"response\", \"call to chat.completions succeeded\", {\n      finishReason,\n      usage,\n    });\n\n    return {\n      content: choice.message.content ?? \"\",\n      finishReason,\n      usage,\n      toolCalls: this.extractToolCalls(choice.message.tool_calls),\n    };\n  }\n\n  /**\n   * Incremental streaming completion. Yields neutral `ModelStreamChunk`s —\n   * `delta` for text tokens, `tool-call` when the model requests a tool,\n   * and a terminal `done` carrying the final finish reason + usage totals.\n   * Callers consume it with `for await`.\n   */\n  public async *stream(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): AsyncIterable<ModelStreamChunk> {\n    this.logger.debug(LOG_MODULE, \"request\", \"Starting streaming call to chat.completions\", {\n      model: this.name,\n      messageCount: messages.length,\n      streaming: true,\n      toolCount: options?.tools?.length ?? 0,\n    });\n\n    let stream: Awaited<ReturnType<typeof this.client.chat.completions.create>>;\n\n    try {\n      stream = await this.client.chat.completions.create(\n        {\n          model: this.name,\n          messages: toOpenAIMessages(messages),\n          temperature: options?.temperature ?? this.config.temperature,\n          max_tokens: options?.maxTokens ?? this.config.maxTokens,\n          tools: toOpenAITools(options?.tools),\n          stream: true,\n          stream_options: { include_usage: true },\n          ...this.buildResponseFormat(options?.responseSchema),\n        },\n        options?.signal ? { signal: options.signal } : undefined,\n      );\n    } catch (thrown) {\n      const wrapped = wrapOpenAIError(thrown);\n\n      this.logger.error(LOG_MODULE, \"error\", wrapped.message, {\n        code: wrapped.code,\n        context: wrapped.context,\n      });\n\n      throw wrapped;\n    }\n\n    let rawFinishReason: string = \"stop\";\n    const usage: Usage = { input: 0, output: 0, total: 0 };\n    const toolCallAccum = new Map<number, { id: string; name: string; arguments: string }>();\n\n    try {\n      for await (const chunk of stream as AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>) {\n        const delta = chunk.choices[0]?.delta;\n        const finish = chunk.choices[0]?.finish_reason;\n\n        if (delta?.content) {\n          yield { type: \"delta\", content: delta.content };\n        }\n\n        if (delta?.tool_calls) {\n          for (const toolCall of delta.tool_calls) {\n            const idx = toolCall.index ?? 0;\n            if (!toolCallAccum.has(idx)) {\n              toolCallAccum.set(idx, { id: \"\", name: \"\", arguments: \"\" });\n            }\n            const acc = toolCallAccum.get(idx)!;\n            if (toolCall.id) acc.id = toolCall.id;\n            if (toolCall.function?.name) acc.name = toolCall.function.name;\n            if (toolCall.function?.arguments) acc.arguments += toolCall.function.arguments;\n          }\n        }\n\n        if (finish) {\n          rawFinishReason = finish;\n        }\n\n        if (chunk.usage) {\n          usage.input = chunk.usage.prompt_tokens ?? 0;\n          usage.output = chunk.usage.completion_tokens ?? 0;\n          usage.total = chunk.usage.total_tokens ?? 0;\n          const cached = chunk.usage.prompt_tokens_details?.cached_tokens;\n          if (cached !== undefined && cached > 0) {\n            usage.cachedTokens = cached;\n          }\n        }\n      }\n\n      for (const acc of toolCallAccum.values()) {\n        // Skip accumulators that never received a function name — those\n        // are partial fragments the model started but never identified\n        // (e.g. arguments-only deltas with no originating `id`/`name`).\n        // Yielding them produces nameless tool-calls the agent runtime\n        // can't dispatch and would mis-attribute as a registered tool.\n        if (!acc.name) continue;\n\n        yield {\n          type: \"tool-call\",\n          id: acc.id,\n          name: acc.name,\n          input: safeJsonParse<Record<string, unknown>>(acc.arguments, {}),\n        };\n      }\n    } catch (thrown) {\n      const wrapped = wrapOpenAIError(thrown);\n\n      this.logger.error(LOG_MODULE, \"error\", wrapped.message, {\n        code: wrapped.code,\n        context: wrapped.context,\n      });\n\n      throw wrapped;\n    }\n\n    const finishReason = mapFinishReason(rawFinishReason);\n\n    this.logger.debug(LOG_MODULE, \"response\", \"Streaming call to chat.completions succeeded\", {\n      finishReason,\n      usage,\n    });\n\n    yield { type: \"done\", finishReason, usage };\n  }\n\n  /**\n   * Translate the neutral `responseSchema` option into OpenAI's\n   * `response_format` parameter.\n   *\n   * When `config.responseFormat` is set, it wins: `\"text\"` emits no\n   * `response_format` at all, `\"json_object\"` always picks the loose\n   * mode, and `\"json_schema\"` picks strict mode (with the same\n   * `isStrictCompatible` safety check — a malformed schema still\n   * degrades to `json_object` rather than 400). The override exists\n   * because some targets (older OpenAI models, OpenRouter routes,\n   * Ollama OpenAI-compat) reject strict `json_schema` outright.\n   *\n   * When the override is omitted, uses strict `json_schema` mode\n   * (token-level enforcement) only when the schema is a proper\n   * root-object JSON Schema (`{ type: \"object\", properties: ... }`).\n   * For anything else — malformed extractor output, non-object\n   * schemas, or future shapes we haven't tested — falls back to loose\n   * `json_object` mode, which guarantees *some* valid JSON without\n   * enforcing shape. The agent's soft instruction already embeds the\n   * schema text in the system prompt when the model declares no\n   * native structured-output capability, so shape validation still\n   * runs client-side via the Standard Schema `validate()` call.\n   *\n   * Returns an empty spread when no schema was supplied, so the caller\n   * can unconditionally `...buildResponseFormat(...)` into the request.\n   */\n  private buildResponseFormat(responseSchema: Record<string, unknown> | undefined): {\n    response_format?: OpenAI.Chat.Completions.ChatCompletionCreateParams[\"response_format\"];\n  } {\n    if (!responseSchema) {\n      return {};\n    }\n\n    const override = this.config.responseFormat;\n\n    if (override === \"text\") {\n      return {};\n    }\n\n    if (override === \"json_object\") {\n      return { response_format: { type: \"json_object\" } };\n    }\n\n    // Either auto-select (no override) or explicit `\"json_schema\"`.\n    // The strict-compat check still applies in the explicit case —\n    // a malformed / non-object schema would 400 before sampling, so\n    // we degrade to `json_object` rather than crash.\n    if (this.isStrictCompatible(responseSchema)) {\n      return {\n        response_format: {\n          type: \"json_schema\",\n          json_schema: {\n            name: \"response\",\n            schema: responseSchema,\n            strict: true,\n          },\n        },\n      };\n    }\n\n    return { response_format: { type: \"json_object\" } };\n  }\n\n  /**\n   * OpenAI strict `json_schema` mode requires the root to be a JSON\n   * Schema object type (`{ type: \"object\", properties: ... }`). Anything\n   * else (top-level arrays, primitives, unknown shapes) is rejected with\n   * a 400 before a token is sampled. We check structurally here so the\n   * first call doesn't crash on a malformed extraction — loose\n   * `json_object` mode is a safe degradation.\n   */\n  private isStrictCompatible(schema: Record<string, unknown>): boolean {\n    return (\n      schema.type === \"object\" &&\n      typeof schema.properties === \"object\" &&\n      schema.properties !== null\n    );\n  }\n\n  /**\n   * Normalize OpenAI's `usage` block (which may be absent on some responses\n   * or partials) into the neutral `Usage` shape. Missing usage collapses to\n   * zeros rather than propagating `undefined`, so downstream aggregation\n   * math stays safe.\n   */\n  private extractUsage(raw: OpenAI.Completions.CompletionUsage | undefined): Usage {\n    if (!raw) {\n      return { input: 0, output: 0, total: 0 };\n    }\n\n    const cachedTokens = raw.prompt_tokens_details?.cached_tokens;\n\n    return {\n      input: raw.prompt_tokens,\n      output: raw.completion_tokens,\n      total: raw.total_tokens,\n      ...(cachedTokens !== undefined && cachedTokens > 0 ? { cachedTokens } : {}),\n    };\n  }\n\n  /**\n   * Reshape OpenAI's `tool_calls` array into the neutral\n   * `ModelToolCallRequest[]`. The raw `arguments` field is a JSON string\n   * per OpenAI's protocol — we parse it defensively via `safeJsonParse` so\n   * malformed or empty arguments yield an empty object instead of crashing\n   * the trip. Returns `undefined` when no tools were requested so callers\n   * can branch on presence.\n   */\n  private extractToolCalls(\n    rawToolCalls: OpenAI.Chat.Completions.ChatCompletionMessageToolCall[] | undefined,\n  ): ModelToolCallRequest[] | undefined {\n    if (!rawToolCalls || rawToolCalls.length === 0) {\n      return undefined;\n    }\n\n    return rawToolCalls.map((toolCall) => ({\n      id: toolCall.id,\n      name: (toolCall as any).function.name,\n      input: safeJsonParse<Record<string, unknown>>((toolCall as any).function.arguments, {}),\n    }));\n  }\n}\n"],"mappings":"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"}

package/esm/sdk.d.mts

@@ -0,0 +1,79 @@
+import { OpenAIEmbedderConfig, OpenAIModelConfig, OpenAISDKConfig } from "./config.type.mjs";
+import { EmbedderContract, ModelContract, SDKAdapterContract } from "@warlock.js/ai";
+
+//#region ../../@warlock.js/ai-openai/src/sdk.d.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" }) });
+ */
+declare class OpenAISDK implements SDKAdapterContract {
+  private readonly client;
+  private readonly provider;
+  private readonly pricing?;
+  constructor(config: OpenAISDKConfig);
+  /**
+   * 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: OpenAIModelConfig): ModelContract;
+  /**
+   * 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.
+   */
+  count(text: string, _model?: string): Promise<number>;
+  /**
+   * 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: OpenAIEmbedderConfig): EmbedderContract;
+}
+//#endregion
+export { OpenAISDK };
+//# sourceMappingURL=sdk.d.mts.map

package/esm/sdk.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.mts","names":[],"sources":["../../../../../@warlock.js/ai-openai/src/sdk.ts"],"mappings":";;;;;;AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,SAAA,YAAqB,kBAAA;EAAA,iBACf,MAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;cAEE,MAAA,EAAQ,eAAA;;;;;;;;;;;;;EAqBpB,KAAA,CAAM,MAAA,EAAQ,iBAAA,GAAoB,aAAA;;;;;;;;EAe5B,KAAA,CAAM,IAAA,UAAc,MAAA,YAAkB,OAAA;;;;;;;;;;;EAc5C,QAAA,CAAS,MAAA,EAAQ,oBAAA,GAAuB,gBAAA;AAAA"}

package/esm/sdk.mjs

@@ -0,0 +1,97 @@
+import { OpenAIEmbedder } from "./embedder.mjs";
+import { OpenAIModel } from "./model.mjs";
+import OpenAI from "openai";
+import { approximateTokenCount } from "@warlock.js/ai";
+
+//#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({
+			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 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
+export { OpenAISDK };
+//# sourceMappingURL=sdk.mjs.map

package/esm/sdk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.mjs","names":[],"sources":["../../../../../@warlock.js/ai-openai/src/sdk.ts"],"sourcesContent":["import OpenAI from \"openai\";\nimport type {\n  EmbedderContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { approximateTokenCount } from \"@warlock.js/ai\";\nimport type { OpenAIEmbedderConfig, OpenAIModelConfig, OpenAISDKConfig } from \"./config.type\";\nimport { OpenAIEmbedder } from \"./embedder\";\nimport { OpenAIModel } from \"./model\";\n\n/**\n * OpenAI-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for any OpenAI-compatible provider\n * (OpenAI, Azure OpenAI, OpenRouter, local gateways speaking the Chat\n * Completions protocol). A single `OpenAISDK` instance holds one live\n * `OpenAI` client, shared by every `ModelContract` it produces via\n * `model()`. Users construct one SDK per provider/account and reuse it\n * across all agents, workflows, and supervisors that target that\n * provider.\n *\n * **Responsibility.**\n * - Owns: a long-lived `OpenAI` client (authentication, base URL) and\n *   its lifetime scope. Factory for `OpenAIModel` instances — each\n *   model call gets a reference to the same client.\n * - Does NOT own: anything per-call (tool execution, message history,\n *   streaming loop) — those live in `OpenAIModel` and the agent runtime.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): the `OpenAI` client is heavy to construct and\n * designed to be reused; keeping it on `this` makes that reuse\n * explicit and aligns with the PascalCase naming convention readers\n * expect from a constructor.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });\n * const model = openai.model({ name: \"gpt-4o\", temperature: 0.7 });\n * const tokens = await openai.count(\"Hello world\");\n *\n * @example\n * // Compose into an `ai.openai` namespace for ergonomic agent wiring\n * const ai = { agent, tool, systemPrompt, persona, instruction, openai: new OpenAISDK({ apiKey }) };\n * const myAgent = ai.agent({ model: ai.openai.model({ name: \"gpt-4o-mini\" }) });\n */\nexport class OpenAISDK implements SDKAdapterContract {\n  private readonly client: OpenAI;\n  private readonly provider: string;\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: OpenAISDKConfig) {\n    this.client = new OpenAI({\n      apiKey: config.apiKey,\n      baseURL: config.baseURL,\n    });\n    this.provider = config.provider ?? \"openai\";\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build an `OpenAIModel` bound to this SDK's client. Each call returns\n   * a fresh model instance, but all instances share the underlying\n   * `OpenAI` client — connection pools, rate limits, and authentication\n   * state stay unified across every model produced here. The SDK's\n   * `provider` label is forwarded so every model self-identifies as\n   * coming from the same upstream.\n   *\n   * Pricing resolution: per-model `config.pricing` wins; otherwise the\n   * SDK-level registry entry keyed by `config.name`; otherwise\n   * `undefined` (no cost computed).\n   */\n  public model(config: OpenAIModelConfig): ModelContract {\n    const resolvedPricing = config.pricing ?? this.pricing?.[config.name];\n    const resolvedConfig: OpenAIModelConfig =\n      resolvedPricing === config.pricing ? config : { ...config, pricing: resolvedPricing };\n\n    return new OpenAIModel(this.client, resolvedConfig, this.provider);\n  }\n\n  /**\n   * Rough token-count estimate for a given text. Uses a\n   * character-heuristic (`approximateTokenCount`) from the core package\n   * — good enough for budgeting and quota guards, not for billing.\n   * Accepts an optional model id for future per-model tokenizer\n   * dispatch; currently ignored.\n   */\n  public async count(text: string, _model?: string): Promise<number> {\n    return approximateTokenCount(text);\n  }\n\n  /**\n   * Build an `OpenAIEmbedder` bound to this SDK's client. Each call\n   * returns a fresh embedder instance sharing the same underlying\n   * `OpenAI` client — connection pools and authentication stay unified\n   * across every embedder produced here.\n   *\n   * @example\n   * const embedder = openai.embedder({ name: \"text-embedding-3-small\" });\n   * const { vector } = await embedder.embed(\"Hello world\");\n   */\n  public embedder(config: OpenAIEmbedderConfig): EmbedderContract {\n    return new OpenAIEmbedder(this.client, config);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,IAAa,YAAb,MAAqD;CAKnD,AAAO,YAAY,QAAyB;EAC1C,KAAK,SAAS,IAAI,OAAO;GACvB,QAAQ,OAAO;GACf,SAAS,OAAO;EAClB,CAAC;EACD,KAAK,WAAW,OAAO,YAAY;EACnC,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;CAcA,AAAO,MAAM,QAA0C;EACrD,MAAM,kBAAkB,OAAO,WAAW,KAAK,UAAU,OAAO;EAChE,MAAM,iBACJ,oBAAoB,OAAO,UAAU,SAAS;GAAE,GAAG;GAAQ,SAAS;EAAgB;EAEtF,OAAO,IAAI,YAAY,KAAK,QAAQ,gBAAgB,KAAK,QAAQ;CACnE;;;;;;;;CASA,MAAa,MAAM,MAAc,QAAkC;EACjE,OAAO,sBAAsB,IAAI;CACnC;;;;;;;;;;;CAYA,AAAO,SAAS,QAAgD;EAC9D,OAAO,IAAI,eAAe,KAAK,QAAQ,MAAM;CAC/C;AACF"}

package/esm/utils/index.mjs

@@ -0,0 +1,6 @@
+import { mapFinishReason } from "./map-finish-reason.mjs";
+import { toOpenAIMessages } from "./to-openai-messages.mjs";
+import { toOpenAITools } from "./to-openai-tools.mjs";
+import { wrapOpenAIError } from "./wrap-openai-error.mjs";
+
+export {  };

package/esm/utils/map-finish-reason.mjs

@@ -0,0 +1,22 @@
+//#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
+export { mapFinishReason };
+//# sourceMappingURL=map-finish-reason.mjs.map

package/esm/utils/map-finish-reason.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-finish-reason.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-openai/src/utils/map-finish-reason.ts"],"sourcesContent":["import type { FinishReason } from \"@warlock.js/ai\";\n\nconst finishReasonMap: Record<string, FinishReason> = {\n  stop: \"stop\",\n  tool_calls: \"tool_calls\",\n  length: \"length\",\n};\n\n/**\n * Map the raw OpenAI `finish_reason` string to the normalized FinishReason union.\n * Unknown/unexpected values fall through to \"error\".\n *\n * @example\n * mapFinishReason(\"stop\");        // \"stop\"\n * mapFinishReason(\"tool_calls\");  // \"tool_calls\"\n * mapFinishReason(null);          // \"error\"\n */\nexport function mapFinishReason(raw: string | null | undefined): FinishReason {\n  return finishReasonMap[raw ?? \"\"] ?? \"error\";\n}\n"],"mappings":";AAEA,MAAM,kBAAgD;CACpD,MAAM;CACN,YAAY;CACZ,QAAQ;AACV;;;;;;;;;;AAWA,SAAgB,gBAAgB,KAA8C;CAC5E,OAAO,gBAAgB,OAAO,OAAO;AACvC"}

package/esm/utils/to-openai-messages.mjs

@@ -0,0 +1,78 @@
+//#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
+export { toOpenAIMessages };
+//# sourceMappingURL=to-openai-messages.mjs.map