@warlock.js/ai-openai 4.1.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"to-openai-messages.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-openai/src/utils/to-openai-messages.ts"],"sourcesContent":["import type { ContentPart, Message } from \"@warlock.js/ai\";\nimport type OpenAI from \"openai\";\n\n/**\n * Convert vendor-neutral Message[] to OpenAI's chat message shape.\n * Handles the `tool` role (requires `tool_call_id`) and assistant messages\n * that carry `toolCalls` from a prior model response.\n *\n * Multipart `content` (a `ContentPart[]`) is mapped into OpenAI's user-message\n * content-parts shape: text becomes `{ type: \"text\", text }`, images become\n * `{ type: \"image_url\", image_url: { url } }` — with base64 sources rendered\n * as `data:` URLs inline.\n *\n * @example\n * const openaiMessages = toOpenAIMessages([\n *   { role: \"user\", content: \"Hi\" },\n *   { role: \"tool\", toolCallId: \"call_1\", content: '{\"ok\":true}' },\n * ]);\n *\n * @example\n * toOpenAIMessages([\n *   { role: \"user\", content: [\n *     { type: \"text\", text: \"What is this?\" },\n *     { type: \"image\", source: { url: \"https://example.com/cat.jpg\" } },\n *   ]},\n * ]);\n */\nexport function toOpenAIMessages(\n  messages: Message[],\n): OpenAI.Chat.Completions.ChatCompletionMessageParam[] {\n  return messages.map((m) => {\n    if (m.role === \"tool\") {\n      return {\n        role: \"tool\",\n        content: stringifyContent(m.content),\n        tool_call_id: m.toolCallId ?? \"\",\n      };\n    }\n    if (m.role === \"assistant\" && m.toolCalls && m.toolCalls.length > 0) {\n      return {\n        role: \"assistant\",\n        content: stringifyContent(m.content),\n        tool_calls: m.toolCalls.map((tc) => ({\n          id: tc.id,\n          type: \"function\" as const,\n          function: { name: tc.name, arguments: JSON.stringify(tc.input ?? {}) },\n        })),\n      };\n    }\n\n    if (m.role === \"user\" && Array.isArray(m.content)) {\n      return {\n        role: \"user\",\n        content: m.content.map(toOpenAIContentPart),\n      };\n    }\n\n    return { role: m.role, content: stringifyContent(m.content) } as\n      | OpenAI.Chat.Completions.ChatCompletionUserMessageParam\n      | OpenAI.Chat.Completions.ChatCompletionSystemMessageParam\n      | OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam;\n  });\n}\n\n/**\n * Multipart content is only meaningful on user messages — for any other\n * role (system / assistant text / tool), collapse a `ContentPart[]` to\n * its concatenated text so OpenAI's wire format stays valid. Plain\n * strings pass through unchanged.\n */\nfunction stringifyContent(content: string | ContentPart[]): string {\n  if (typeof content === \"string\") {\n    return content;\n  }\n\n  return content\n    .filter((part): part is { type: \"text\"; text: string } => part.type === \"text\")\n    .map((part) => part.text)\n    .join(\"\");\n}\n\nfunction toOpenAIContentPart(part: ContentPart): OpenAI.Chat.Completions.ChatCompletionContentPart {\n  if (part.type === \"text\") {\n    return { type: \"text\", text: part.text };\n  }\n\n  // TODO: Allow other types for urls not just images\n  const url =\n    \"url\" in part.source\n      ? part.source.url\n      : `data:${part.source.mediaType};base64,${part.source.base64}`;\n\n  return { type: \"image_url\", image_url: { url } };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,iBACd,UACsD;CACtD,OAAO,SAAS,KAAK,MAAM;EACzB,IAAI,EAAE,SAAS,QACb,OAAO;GACL,MAAM;GACN,SAAS,iBAAiB,EAAE,OAAO;GACnC,cAAc,EAAE,cAAc;EAChC;EAEF,IAAI,EAAE,SAAS,eAAe,EAAE,aAAa,EAAE,UAAU,SAAS,GAChE,OAAO;GACL,MAAM;GACN,SAAS,iBAAiB,EAAE,OAAO;GACnC,YAAY,EAAE,UAAU,KAAK,QAAQ;IACnC,IAAI,GAAG;IACP,MAAM;IACN,UAAU;KAAE,MAAM,GAAG;KAAM,WAAW,KAAK,UAAU,GAAG,SAAS,CAAC,CAAC;IAAE;GACvE,EAAE;EACJ;EAGF,IAAI,EAAE,SAAS,UAAU,MAAM,QAAQ,EAAE,OAAO,GAC9C,OAAO;GACL,MAAM;GACN,SAAS,EAAE,QAAQ,IAAI,mBAAmB;EAC5C;EAGF,OAAO;GAAE,MAAM,EAAE;GAAM,SAAS,iBAAiB,EAAE,OAAO;EAAE;CAI9D,CAAC;AACH;;;;;;;AAQA,SAAS,iBAAiB,SAAyC;CACjE,IAAI,OAAO,YAAY,UACrB,OAAO;CAGT,OAAO,QACJ,QAAQ,SAAiD,KAAK,SAAS,MAAM,EAC7E,KAAK,SAAS,KAAK,IAAI,EACvB,KAAK,EAAE;AACZ;AAEA,SAAS,oBAAoB,MAAsE;CACjG,IAAI,KAAK,SAAS,QAChB,OAAO;EAAE,MAAM;EAAQ,MAAM,KAAK;CAAK;CASzC,OAAO;EAAE,MAAM;EAAa,WAAW,EAAE,KAJvC,SAAS,KAAK,SACV,KAAK,OAAO,MACZ,QAAQ,KAAK,OAAO,UAAU,UAAU,KAAK,OAAO,SAEb;CAAE;AACjD"}

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

@@ -0,0 +1,41 @@
+import { extractJsonSchema } from "@warlock.js/ai";
+
+//#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 = extractJsonSchema(input);
+	if (schema && schema.type === "object") return schema;
+	return {
+		type: "object",
+		properties: {}
+	};
+}
+
+//#endregion
+export { toOpenAITools };
+//# sourceMappingURL=to-openai-tools.mjs.map

package/esm/utils/to-openai-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-openai-tools.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-openai/src/utils/to-openai-tools.ts"],"sourcesContent":["import { extractJsonSchema, type ToolConfig } from \"@warlock.js/ai\";\nimport type OpenAI from \"openai\";\n\n/**\n * Convert vendor-neutral ToolConfig[] to OpenAI's tools array.\n * Uses the shared `extractJsonSchema` helper; falls back to an empty-object\n * schema when extraction fails so the tool still registers with the provider.\n *\n * @example\n * const tools = toOpenAITools([weatherTool, calculatorTool]);\n * await client.chat.completions.create({ model, messages, tools });\n */\nexport function toOpenAITools(\n  tools: ToolConfig<unknown, unknown>[] | undefined,\n): OpenAI.Chat.Completions.ChatCompletionTool[] | undefined {\n  if (!tools || tools.length === 0) {\n    return undefined;\n  }\n\n  return tools.map((tool) => ({\n    type: \"function\",\n    function: {\n      name: tool.name,\n      description: tool.description,\n      parameters: toParameters(tool.input),\n    },\n  }));\n}\n\n/**\n * Resolve a tool's input schema to a JSON-Schema object. OpenAI's\n * function `parameters` expects an object root; anything else (or a\n * failed extraction) degrades to an empty-object schema so the tool\n * still registers and the model simply sees no parameters.\n */\nfunction toParameters(input: ToolConfig<unknown, unknown>[\"input\"]): Record<string, unknown> {\n  const schema = extractJsonSchema(input);\n\n  if (schema && schema.type === \"object\") {\n    return schema;\n  }\n\n  return { type: \"object\", properties: {} };\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAgB,cACd,OAC0D;CAC1D,IAAI,CAAC,SAAS,MAAM,WAAW,GAC7B;CAGF,OAAO,MAAM,KAAK,UAAU;EAC1B,MAAM;EACN,UAAU;GACR,MAAM,KAAK;GACX,aAAa,KAAK;GAClB,YAAY,aAAa,KAAK,KAAK;EACrC;CACF,EAAE;AACJ;;;;;;;AAQA,SAAS,aAAa,OAAuE;CAC3F,MAAM,SAAS,kBAAkB,KAAK;CAEtC,IAAI,UAAU,OAAO,SAAS,UAC5B,OAAO;CAGT,OAAO;EAAE,MAAM;EAAU,YAAY,CAAC;CAAE;AAC1C"}

package/esm/utils/wrap-openai-error.mjs

@@ -0,0 +1,147 @@
+import OpenAI from "openai";
+import { AIError, ContentFilterError, ContextLengthExceededError, InvalidRequestError, ProviderAuthError, ProviderError, ProviderRateLimitError, ProviderTimeoutError, QuotaExceededError } from "@warlock.js/ai";
+
+//#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 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 ProviderTimeoutError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.status === 401 || shape.code === "invalid_api_key") return new ProviderAuthError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.code === "insufficient_quota") return new QuotaExceededError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.status === 429 || shape.code === "rate_limit_exceeded") return new ProviderRateLimitError(message, {
+		cause: thrown,
+		context,
+		retryAfter: parseRetryAfter(shape.headers)
+	});
+	if (shape.code === "context_length_exceeded") return new ContextLengthExceededError(message, {
+		cause: thrown,
+		context
+	});
+	if (shape.code === "content_filter") return new ContentFilterError(message, {
+		cause: thrown,
+		context,
+		reason: message
+	});
+	if (typeof shape.status === "number" && shape.status >= 400 && shape.status < 500) return new InvalidRequestError(message, {
+		cause: thrown,
+		context
+	});
+	return new 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.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.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
+export { wrapOpenAIError };
+//# sourceMappingURL=wrap-openai-error.mjs.map

package/esm/utils/wrap-openai-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-openai-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-openai/src/utils/wrap-openai-error.ts"],"sourcesContent":["import {\n  AIError,\n  ContentFilterError,\n  ContextLengthExceededError,\n  InvalidRequestError,\n  ProviderAuthError,\n  ProviderError,\n  ProviderRateLimitError,\n  ProviderTimeoutError,\n  QuotaExceededError,\n} from \"@warlock.js/ai\";\nimport OpenAI from \"openai\";\n\n/**\n * Raw-error fields the wrapper reads off an OpenAI SDK error.\n *\n * `APIError` exposes `status`, `code`, `message`, `type`, `headers` —\n * we duck-type because wrapped retries, proxied errors, and custom\n * error subclasses sometimes lose the `instanceof` relationship.\n */\ntype OpenAIErrorShape = {\n  status?: number;\n  code?: string | null;\n  message?: string;\n  type?: string | null;\n  headers?: Record<string, string> | undefined;\n  name?: string;\n};\n\n/**\n * Wrap any thrown value caught inside the OpenAI adapter into the\n * appropriate `@warlock.js/ai` `AIError` subclass.\n *\n * **Dispatch strategy.** Prefers `APIError.code` when present (stable\n * machine identifier across SDK versions), falls back to `status` when\n * `code` is missing (common with proxied deployments that strip the\n * field). Name-based detection (`APIConnectionTimeoutError`) catches\n * transport-layer errors that never produced an HTTP response.\n *\n * `AIError` instances are returned unchanged — callers can pass the\n * error through `try/catch/throw wrap(e)` pipelines without accidental\n * double-wrapping.\n *\n * @example\n * try {\n *   return await this.client.chat.completions.create(...);\n * } catch (thrown) {\n *   throw wrapOpenAIError(thrown);\n * }\n */\nexport function wrapOpenAIError(thrown: unknown): AIError {\n  if (thrown instanceof AIError) {\n    return thrown;\n  }\n\n  const shape = toShape(thrown);\n  const context = buildContext(thrown, shape);\n  const message = shape.message ?? (thrown instanceof Error ? thrown.message : String(thrown));\n\n  if (isTimeout(thrown, shape)) {\n    return new ProviderTimeoutError(message, { cause: thrown, context });\n  }\n\n  if (shape.status === 401 || shape.code === \"invalid_api_key\") {\n    return new ProviderAuthError(message, { cause: thrown, context });\n  }\n\n  if (shape.code === \"insufficient_quota\") {\n    return new QuotaExceededError(message, { cause: thrown, context });\n  }\n\n  if (shape.status === 429 || shape.code === \"rate_limit_exceeded\") {\n    return new ProviderRateLimitError(message, {\n      cause: thrown,\n      context,\n      retryAfter: parseRetryAfter(shape.headers),\n    });\n  }\n\n  if (shape.code === \"context_length_exceeded\") {\n    return new ContextLengthExceededError(message, { cause: thrown, context });\n  }\n\n  if (shape.code === \"content_filter\") {\n    return new ContentFilterError(message, {\n      cause: thrown,\n      context,\n      reason: message,\n    });\n  }\n\n  if (typeof shape.status === \"number\" && shape.status >= 400 && shape.status < 500) {\n    return new InvalidRequestError(message, { cause: thrown, context });\n  }\n\n  return new ProviderError(message, { cause: thrown, context });\n}\n\n/**\n * Read the raw error shape without depending on `instanceof APIError`\n * — some consumers wrap the SDK, and proxies sometimes strip the\n * prototype chain. Duck-typing on the visible fields is resilient to\n * both.\n */\nfunction toShape(thrown: unknown): OpenAIErrorShape {\n  if (thrown instanceof OpenAI.APIError) {\n    return {\n      status: thrown.status,\n      code: thrown.code,\n      message: thrown.message,\n      type: thrown.type,\n      headers: thrown.headers as Record<string, string> | undefined,\n      name: thrown.name,\n    };\n  }\n\n  if (typeof thrown === \"object\" && thrown !== null) {\n    const raw = thrown as Record<string, unknown>;\n\n    return {\n      status: typeof raw.status === \"number\" ? raw.status : undefined,\n      code: typeof raw.code === \"string\" ? raw.code : undefined,\n      message: typeof raw.message === \"string\" ? raw.message : undefined,\n      type: typeof raw.type === \"string\" ? raw.type : undefined,\n      headers:\n        typeof raw.headers === \"object\" && raw.headers !== null\n          ? (raw.headers as Record<string, string>)\n          : undefined,\n      name: typeof raw.name === \"string\" ? raw.name : undefined,\n    };\n  }\n\n  return {};\n}\n\n/**\n * Decide whether the thrown value represents a timeout. OpenAI's SDK\n * throws `APIConnectionTimeoutError` for transport-level timeouts, and\n * Node surfaces `ETIMEDOUT` / `ECONNABORTED` on the lower socket\n * layer. Either signal counts.\n */\nfunction isTimeout(thrown: unknown, shape: OpenAIErrorShape): boolean {\n  if (thrown instanceof OpenAI.APIConnectionTimeoutError) {\n    return true;\n  }\n\n  if (shape.name === \"APIConnectionTimeoutError\") {\n    return true;\n  }\n\n  if (shape.code === \"ETIMEDOUT\" || shape.code === \"ECONNABORTED\") {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Attach the raw diagnostic fields to `error.context` so consumers\n * have everything the provider surfaced without each subclass having\n * to redeclare them. Never includes `cause` — that lives on\n * `error.cause`.\n */\nfunction buildContext(\n  thrown: unknown,\n  shape: OpenAIErrorShape,\n): Record<string, unknown> {\n  const context: Record<string, unknown> = {};\n\n  if (shape.status !== undefined) {\n    context.status = shape.status;\n  }\n\n  if (shape.code) {\n    context.code = shape.code;\n  }\n\n  if (shape.type) {\n    context.type = shape.type;\n  }\n\n  const requestId = readRequestId(thrown);\n\n  if (requestId) {\n    context.requestId = requestId;\n  }\n\n  return context;\n}\n\n/**\n * OpenAI puts the request id on `APIError.request_id`. Extract\n * defensively — both camel and snake keys exist across SDK versions.\n */\nfunction readRequestId(thrown: unknown): string | undefined {\n  if (typeof thrown !== \"object\" || thrown === null) {\n    return undefined;\n  }\n\n  const raw = thrown as Record<string, unknown>;\n\n  if (typeof raw.request_id === \"string\") {\n    return raw.request_id;\n  }\n\n  if (typeof raw.requestId === \"string\") {\n    return raw.requestId;\n  }\n\n  return undefined;\n}\n\n/**\n * Parse the `Retry-After` response header (seconds per HTTP spec)\n * into milliseconds so consumers can feed it straight to `setTimeout`.\n * Returns `undefined` when missing or unparseable.\n */\nfunction parseRetryAfter(headers: Record<string, string> | undefined): number | undefined {\n  if (!headers) {\n    return undefined;\n  }\n\n  const raw = headers[\"retry-after\"] ?? headers[\"Retry-After\"];\n\n  if (!raw) {\n    return undefined;\n  }\n\n  const seconds = Number(raw);\n\n  if (!Number.isFinite(seconds) || seconds < 0) {\n    return undefined;\n  }\n\n  return Math.round(seconds * 1000);\n}\n"],"mappings":"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"}

package/llms-full.txt

@@ -0,0 +1,145 @@
+# Warlock AI Openai — full skills
+
+> Package: `@warlock.js/ai-openai`
+
+> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-openai/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
+
+## setup-openai  `@warlock.js/ai-openai/setup-openai/SKILL.md`
+
+---
+name: setup-openai
+description: 'Wire @warlock.js/ai-openai — new OpenAISDK({apiKey, baseURL?, provider?, pricing?}) for OpenAI / Azure / OpenRouter, .model({name, vision?, structuredOutput?, responseFormat?}) for ModelContract, .embedder({name, dimensions?}) for embeddings. Triggers: `OpenAISDK`, `.model`, `.embedder`, `.embed`, `.embedMany`, `baseURL`, `pricing`, `responseSchema`, `responseFormat`; "wire openai into a warlock agent", "configure gpt-4o", "route through openrouter or azure openai", "openai embeddings with warlock"; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; adapter comparison — `@warlock.js/ai/pick-ai-provider/SKILL.md`; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK, Vercel `@ai-sdk/openai`.'
+---
+
+# `@warlock.js/ai-openai`
+
+Provider adapter that turns OpenAI Chat Completions into a vendor-neutral `ModelContract`. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
+
+## Construction
+
+```ts
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+// OpenAI-compatible endpoints (Azure OpenAI, OpenRouter, local gateways).
+// Pass `provider` to label the upstream — flows through to
+// `ModelContract.provider`, `AgentReport.model.provider`, and logs.
+const openrouter = new OpenAISDK({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseURL: "https://openrouter.ai/api/v1",
+  provider: "openrouter",
+});
+```
+
+`OpenAISDK` is a class (not a factory) — adapter entry points hold a long-lived `OpenAI` client and align with `new OpenAI(...)` upstream convention.
+
+`provider` defaults to `"openai"`. It's an SDK-level identity (one client = one upstream), not a per-model knob.
+
+## Producing a model
+
+```ts
+openai.model({ name: "gpt-4o-mini" })                       // common case
+openai.model({ name: "gpt-4o", temperature: 0.2 })          // sampling controls
+openai.model({ name: "fine-tuned-x", vision: true })        // explicit capability override
+```
+
+Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
+
+## Capabilities — what's auto-set
+
+| Flag | Default |
+| --- | --- |
+| `structuredOutput` | `true`, unless `responseFormat` is set to `"json_object"` or `"text"` (loose modes) — then `false`. |
+| `vision` | Inferred from model name. `true` for `gpt-4o*`, `gpt-4-turbo*`, `gpt-4.1*`, `o1*`, `o3*`, `chatgpt-4o*`; `false` otherwise. |
+
+**Override either flag explicitly** via `.model({ name, vision?, structuredOutput? })` — an explicit value always wins over inference.
+
+## Structured output
+
+When the agent passes `responseSchema` (a JSON Schema object), the adapter converts to `response_format: json_schema, strict: true` on the wire — token-level enforcement. Non-object schemas fall back to loose `json_object` mode (still valid JSON, no shape enforcement).
+
+Some targets reject strict `json_schema` (older OpenAI models, OpenRouter routes, Ollama OpenAI-compat). Override the wire mode per model with `responseFormat`:
+
+```ts
+openai.model({ name: "legacy-model", responseFormat: "json_object" }) // valid JSON, no strict shape
+openai.model({ name: "some-route",   responseFormat: "text" })        // no response_format on the wire
+```
+
+`"json_object"` and `"text"` also flip `structuredOutput` to `false`, so the agent re-injects the schema as a soft prompt hint. Pin `structuredOutput` explicitly to override that.
+
+## Multipart messages (vision)
+
+`ContentPart[]` user content is rendered into OpenAI's content-parts shape:
+
+- `{ type: "text", text }` → `{ type: "text", text }`
+- `{ type: "image", source: { url } }` → `{ type: "image_url", image_url: { url } }`
+- `{ type: "image", source: { base64, mediaType } }` → `{ type: "image_url", image_url: { url: "data:{mediaType};base64,{base64}" } }`
+
+The agent prepares attachments before they reach the adapter; this package never reads files itself.
+
+## Streaming
+
+`model.stream()` drains `chat.completions.create({ stream: true })` and yields `{ type: "delta", content }` per token, then — after the stream closes — one consolidated `{ type: "tool-call", id, name, input }` per requested tool, then a terminal `{ type: "done", finishReason, usage }`. `stream_options: { include_usage: true }` is enabled by default.
+
+Tool-call argument fragments arrive split across deltas; the adapter accumulates them per `tool_calls[n].index` and parses the assembled JSON once on completion, so streamed tool calls round-trip identically to non-streaming `complete()`. Accumulators that never received a function name are skipped.
+
+## Embeddings
+
+```ts
+const embedder = openai.embedder({ name: "text-embedding-3-small" });
+
+const { vector, dimensions, usage } = await embedder.embed("Hello world");
+const { vectors } = await embedder.embedMany(["doc 1", "doc 2", "doc 3"]);
+```
+
+`dimensions` is lazy — starts at `0`, populated from the first response. Pass `dimensions` in config to request output truncation (supported by `text-embedding-3-*`):
+
+```ts
+openai.embedder({ name: "text-embedding-3-large", dimensions: 256 });
+```
+
+## Token counting
+
+```ts
+await openai.count("some text")  // approximate (heuristic, not tiktoken)
+```
+
+Good enough for budgeting; not for billing.
+
+## Pricing — per-model registry
+
+`pricing` is a **registry keyed by model name** — one entry per model, all rates in **USD per 1,000,000 tokens** (`ModelPricing`: `input`, `output`, optional `cachedInput` / `cachedOutput`).
+
+```ts
+const openai = new OpenAISDK({
+  apiKey,
+  pricing: {
+    // USD per 1M tokens.
+    "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 },
+    "gpt-4o":      { input: 2.5,  output: 10,  cachedInput: 1.25 },
+  },
+});
+
+const { usage } = await ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) }).execute("hi");
+usage.cost;  // { input, output, cachedInput?, cachedOutput? } — per-channel USD breakdown of THIS run
+```
+
+The registry is per-model; `usage.cost` is the per-channel breakdown the framework computes from `tokens × pricing[model]`. Resolution at `model()` time: per-model `pricing` (`openai.model({ name, pricing })`) > SDK registry > `undefined` (no cost computed). See [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md).
+
+## Errors
+
+Raw OpenAI SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy via the adapter's error wrapper. Dispatch keys on `APIError.status + code` combined — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## When NOT to use this skill
+
+- Direct calls to the `openai` SDK without going through `@warlock.js/ai` agents.
+- Anthropic models — use `@warlock.js/ai-anthropic`. Bedrock — `@warlock.js/ai-bedrock`. Gemini — `@warlock.js/ai-google`. Ollama — `@warlock.js/ai-ollama`.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — passing the model into `ai.agent({...})`
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — embedder usage
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — adapter comparison
+
+

package/llms.txt

@@ -0,0 +1,9 @@
+# Warlock AI Openai
+
+> Package: `@warlock.js/ai-openai`
+
+> OpenAI SDK adapter for @warlock.js/ai
+
+## Skills
+
+- [setup-openai](@warlock.js/ai-openai/setup-openai/SKILL.md): Wire @warlock.js/ai-openai — new OpenAISDK({apiKey, baseURL?, provider?, pricing?}) for OpenAI / Azure / OpenRouter, .model({name, vision?, structuredOutput?, responseFormat?}) for ModelContract, .embedder({name, dimensions?}) for embeddings. Triggers: `OpenAISDK`, `.model`, `.embedder`, `.embed`, `.embedMany`, `baseURL`, `pricing`, `responseSchema`, `responseFormat`; "wire openai into a warlock agent", "configure gpt-4o", "route through openrouter or azure openai", "openai embeddings with warlock"; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; adapter comparison — `@warlock.js/ai/pick-ai-provider/SKILL.md`; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK, Vercel `@ai-sdk/openai`.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@warlock.js/ai-openai",
+  "description": "OpenAI SDK adapter for @warlock.js/ai",
+  "keywords": [
+    "warlock",
+    "ai",
+    "openai"
+  ],
+  "author": "Hasan Zohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/ai-openai"
+  },
+  "dependencies": {
+    "openai": "^6.34.0",
+    "@warlock.js/logger": "*"
+  },
+  "peerDependencies": {
+    "@warlock.js/ai": "*"
+  },
+  "version": "4.1.1",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,9 @@
+# `@warlock.js/ai-openai` — skills index
+
+Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SKILL.md`.
+
+## Skills
+
+### [`setup-openai/`](./setup-openai/SKILL.md)
+
+Wire @warlock.js/ai-openai — new OpenAISDK({apiKey, baseURL?, provider?, pricing?}) for OpenAI / Azure / OpenRouter, .model({name, vision?, structuredOutput?}) for ModelContract, .embedder({name, dimensions?}) for embeddings. Load when wiring an OpenAI-backed model into a @warlock.js agent or routing via an OpenAI-compatible gateway.

package/skills/setup-openai/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: setup-openai
+description: 'Wire @warlock.js/ai-openai — new OpenAISDK({apiKey, baseURL?, provider?, pricing?}) for OpenAI / Azure / OpenRouter, .model({name, vision?, structuredOutput?, responseFormat?}) for ModelContract, .embedder({name, dimensions?}) for embeddings. Triggers: `OpenAISDK`, `.model`, `.embedder`, `.embed`, `.embedMany`, `baseURL`, `pricing`, `responseSchema`, `responseFormat`; "wire openai into a warlock agent", "configure gpt-4o", "route through openrouter or azure openai", "openai embeddings with warlock"; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; adapter comparison — `@warlock.js/ai/pick-ai-provider/SKILL.md`; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK, Vercel `@ai-sdk/openai`.'
+---
+
+# `@warlock.js/ai-openai`
+
+Provider adapter that turns OpenAI Chat Completions into a vendor-neutral `ModelContract`. Pair with `@warlock.js/ai` for the agent / tool / system-prompt surface.
+
+## Construction
+
+```ts
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+// OpenAI-compatible endpoints (Azure OpenAI, OpenRouter, local gateways).
+// Pass `provider` to label the upstream — flows through to
+// `ModelContract.provider`, `AgentReport.model.provider`, and logs.
+const openrouter = new OpenAISDK({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseURL: "https://openrouter.ai/api/v1",
+  provider: "openrouter",
+});
+```
+
+`OpenAISDK` is a class (not a factory) — adapter entry points hold a long-lived `OpenAI` client and align with `new OpenAI(...)` upstream convention.
+
+`provider` defaults to `"openai"`. It's an SDK-level identity (one client = one upstream), not a per-model knob.
+
+## Producing a model
+
+```ts
+openai.model({ name: "gpt-4o-mini" })                       // common case
+openai.model({ name: "gpt-4o", temperature: 0.2 })          // sampling controls
+openai.model({ name: "fine-tuned-x", vision: true })        // explicit capability override
+```
+
+Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
+
+## Capabilities — what's auto-set
+
+| Flag | Default |
+| --- | --- |
+| `structuredOutput` | `true`, unless `responseFormat` is set to `"json_object"` or `"text"` (loose modes) — then `false`. |
+| `vision` | Inferred from model name. `true` for `gpt-4o*`, `gpt-4-turbo*`, `gpt-4.1*`, `o1*`, `o3*`, `chatgpt-4o*`; `false` otherwise. |
+
+**Override either flag explicitly** via `.model({ name, vision?, structuredOutput? })` — an explicit value always wins over inference.
+
+## Structured output
+
+When the agent passes `responseSchema` (a JSON Schema object), the adapter converts to `response_format: json_schema, strict: true` on the wire — token-level enforcement. Non-object schemas fall back to loose `json_object` mode (still valid JSON, no shape enforcement).
+
+Some targets reject strict `json_schema` (older OpenAI models, OpenRouter routes, Ollama OpenAI-compat). Override the wire mode per model with `responseFormat`:
+
+```ts
+openai.model({ name: "legacy-model", responseFormat: "json_object" }) // valid JSON, no strict shape
+openai.model({ name: "some-route",   responseFormat: "text" })        // no response_format on the wire
+```
+
+`"json_object"` and `"text"` also flip `structuredOutput` to `false`, so the agent re-injects the schema as a soft prompt hint. Pin `structuredOutput` explicitly to override that.
+
+## Multipart messages (vision)
+
+`ContentPart[]` user content is rendered into OpenAI's content-parts shape:
+
+- `{ type: "text", text }` → `{ type: "text", text }`
+- `{ type: "image", source: { url } }` → `{ type: "image_url", image_url: { url } }`
+- `{ type: "image", source: { base64, mediaType } }` → `{ type: "image_url", image_url: { url: "data:{mediaType};base64,{base64}" } }`
+
+The agent prepares attachments before they reach the adapter; this package never reads files itself.
+
+## Streaming
+
+`model.stream()` drains `chat.completions.create({ stream: true })` and yields `{ type: "delta", content }` per token, then — after the stream closes — one consolidated `{ type: "tool-call", id, name, input }` per requested tool, then a terminal `{ type: "done", finishReason, usage }`. `stream_options: { include_usage: true }` is enabled by default.
+
+Tool-call argument fragments arrive split across deltas; the adapter accumulates them per `tool_calls[n].index` and parses the assembled JSON once on completion, so streamed tool calls round-trip identically to non-streaming `complete()`. Accumulators that never received a function name are skipped.
+
+## Embeddings
+
+```ts
+const embedder = openai.embedder({ name: "text-embedding-3-small" });
+
+const { vector, dimensions, usage } = await embedder.embed("Hello world");
+const { vectors } = await embedder.embedMany(["doc 1", "doc 2", "doc 3"]);
+```
+
+`dimensions` is lazy — starts at `0`, populated from the first response. Pass `dimensions` in config to request output truncation (supported by `text-embedding-3-*`):
+
+```ts
+openai.embedder({ name: "text-embedding-3-large", dimensions: 256 });
+```
+
+## Token counting
+
+```ts
+await openai.count("some text")  // approximate (heuristic, not tiktoken)
+```
+
+Good enough for budgeting; not for billing.
+
+## Pricing — per-model registry
+
+`pricing` is a **registry keyed by model name** — one entry per model, all rates in **USD per 1,000,000 tokens** (`ModelPricing`: `input`, `output`, optional `cachedInput` / `cachedOutput`).
+
+```ts
+const openai = new OpenAISDK({
+  apiKey,
+  pricing: {
+    // USD per 1M tokens.
+    "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 },
+    "gpt-4o":      { input: 2.5,  output: 10,  cachedInput: 1.25 },
+  },
+});
+
+const { usage } = await ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) }).execute("hi");
+usage.cost;  // { input, output, cachedInput?, cachedOutput? } — per-channel USD breakdown of THIS run
+```
+
+The registry is per-model; `usage.cost` is the per-channel breakdown the framework computes from `tokens × pricing[model]`. Resolution at `model()` time: per-model `pricing` (`openai.model({ name, pricing })`) > SDK registry > `undefined` (no cost computed). See [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md).
+
+## Errors
+
+Raw OpenAI SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy via the adapter's error wrapper. Dispatch keys on `APIError.status + code` combined — see [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md).
+
+## When NOT to use this skill
+
+- Direct calls to the `openai` SDK without going through `@warlock.js/ai` agents.
+- Anthropic models — use `@warlock.js/ai-anthropic`. Bedrock — `@warlock.js/ai-bedrock`. Gemini — `@warlock.js/ai-google`. Ollama — `@warlock.js/ai-ollama`.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — passing the model into `ai.agent({...})`
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — embedder usage
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — adapter comparison