@dex-ai/openai 0.1.8

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dex-ai/openai",
+  "version": "0.1.8",
+  "description": "OpenAI Chat Completions provider for @dex-ai/sdk.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.1",
+    "zod-to-json-schema": "^3.24.0"
+  },
+  "devDependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,123 @@
+/** OpenAI model capability metadata not exposed by /v1/models. */
+
+export interface OpenAIModelCapabilities {
+	readonly contextWindow?: number;
+}
+
+/**
+ * The OpenAI Models API currently returns model identity/ownership fields, not
+ * context length. Keep a best-effort provider-side map for native OpenAI models.
+ *
+ * Context windows below were generated by intersecting OpenAI /v1/models with
+ * OpenRouter's openai/* model metadata, then adding prefix rules for dated
+ * OpenAI aliases that share the same family limits.
+ */
+const EXACT_MODEL_CAPABILITIES: Record<string, OpenAIModelCapabilities> = {
+	"gpt-3.5-turbo": { contextWindow: 16_385 },
+	"gpt-3.5-turbo-0613": { contextWindow: 4_095 },
+	"gpt-3.5-turbo-16k": { contextWindow: 16_385 },
+	"gpt-3.5-turbo-instruct": { contextWindow: 4_095 },
+	"gpt-4": { contextWindow: 8_191 },
+	"gpt-4-0314": { contextWindow: 8_191 },
+	"gpt-4-1106-preview": { contextWindow: 128_000 },
+	"gpt-4-turbo": { contextWindow: 128_000 },
+	"gpt-4-turbo-preview": { contextWindow: 128_000 },
+	"gpt-4.1": { contextWindow: 1_047_576 },
+	"gpt-4.1-mini": { contextWindow: 1_047_576 },
+	"gpt-4.1-nano": { contextWindow: 1_047_576 },
+	"gpt-4o": { contextWindow: 128_000 },
+	"gpt-4o-2024-05-13": { contextWindow: 128_000 },
+	"gpt-4o-2024-08-06": { contextWindow: 128_000 },
+	"gpt-4o-2024-11-20": { contextWindow: 128_000 },
+	"gpt-4o-audio-preview": { contextWindow: 128_000 },
+	"gpt-4o-mini": { contextWindow: 128_000 },
+	"gpt-4o-mini-2024-07-18": { contextWindow: 128_000 },
+	"gpt-4o-mini-search-preview": { contextWindow: 128_000 },
+	"gpt-4o-search-preview": { contextWindow: 128_000 },
+	"gpt-5": { contextWindow: 400_000 },
+	"gpt-5-codex": { contextWindow: 400_000 },
+	"gpt-5-mini": { contextWindow: 400_000 },
+	"gpt-5-nano": { contextWindow: 400_000 },
+	"gpt-5-pro": { contextWindow: 400_000 },
+	"gpt-5.1": { contextWindow: 400_000 },
+	"gpt-5.1-codex": { contextWindow: 400_000 },
+	"gpt-5.1-codex-max": { contextWindow: 400_000 },
+	"gpt-5.1-codex-mini": { contextWindow: 400_000 },
+	"gpt-5.2": { contextWindow: 400_000 },
+	"gpt-5.2-codex": { contextWindow: 400_000 },
+	"gpt-5.2-pro": { contextWindow: 400_000 },
+	"gpt-5.3-codex": { contextWindow: 400_000 },
+	"gpt-5.4": { contextWindow: 1_050_000 },
+	"gpt-5.4-mini": { contextWindow: 400_000 },
+	"gpt-5.4-nano": { contextWindow: 400_000 },
+	"gpt-5.4-pro": { contextWindow: 1_050_000 },
+	"gpt-5.5": { contextWindow: 1_050_000 },
+	"gpt-5.5-pro": { contextWindow: 1_050_000 },
+	"gpt-audio": { contextWindow: 128_000 },
+	"gpt-audio-mini": { contextWindow: 128_000 },
+	"o1": { contextWindow: 200_000 },
+	"o1-mini": { contextWindow: 128_000 },
+	"o1-pro": { contextWindow: 200_000 },
+	"o3": { contextWindow: 200_000 },
+	"o3-mini": { contextWindow: 200_000 },
+	"o4-mini": { contextWindow: 200_000 },
+};
+
+const PREFIX_MODEL_CAPABILITIES: ReadonlyArray<
+	readonly [prefix: string, capabilities: OpenAIModelCapabilities]
+> = [
+	["gpt-3.5-turbo-instruct-", { contextWindow: 4_095 }],
+	["gpt-3.5-turbo-", { contextWindow: 16_385 }],
+	["gpt-4-turbo-", { contextWindow: 128_000 }],
+	["gpt-4.1-mini-", { contextWindow: 1_047_576 }],
+	["gpt-4.1-nano-", { contextWindow: 1_047_576 }],
+	["gpt-4.1-", { contextWindow: 1_047_576 }],
+	["gpt-4o-mini-search-preview-", { contextWindow: 128_000 }],
+	["gpt-4o-search-preview-", { contextWindow: 128_000 }],
+	["gpt-4o-mini-", { contextWindow: 128_000 }],
+	["gpt-4o-", { contextWindow: 128_000 }],
+	["gpt-4-", { contextWindow: 8_191 }],
+	["gpt-5.5-pro-", { contextWindow: 1_050_000 }],
+	["gpt-5.5-", { contextWindow: 1_050_000 }],
+	["gpt-5.4-pro-", { contextWindow: 1_050_000 }],
+	["gpt-5.4-mini-", { contextWindow: 400_000 }],
+	["gpt-5.4-nano-", { contextWindow: 400_000 }],
+	["gpt-5.4-", { contextWindow: 1_050_000 }],
+	["gpt-5.3-codex-", { contextWindow: 400_000 }],
+	["gpt-5.3-chat-", { contextWindow: 128_000 }],
+	["gpt-5.2-pro-", { contextWindow: 400_000 }],
+	["gpt-5.2-codex-", { contextWindow: 400_000 }],
+	["gpt-5.2-chat-", { contextWindow: 128_000 }],
+	["gpt-5.2-", { contextWindow: 400_000 }],
+	["gpt-5.1-codex-", { contextWindow: 400_000 }],
+	["gpt-5.1-chat-", { contextWindow: 128_000 }],
+	["gpt-5.1-", { contextWindow: 400_000 }],
+	["gpt-5-pro-", { contextWindow: 400_000 }],
+	["gpt-5-mini-", { contextWindow: 400_000 }],
+	["gpt-5-nano-", { contextWindow: 400_000 }],
+	["gpt-5-codex-", { contextWindow: 400_000 }],
+	["gpt-5-chat-", { contextWindow: 128_000 }],
+	["gpt-5-", { contextWindow: 400_000 }],
+	["gpt-audio-mini-", { contextWindow: 128_000 }],
+	["gpt-audio-", { contextWindow: 128_000 }],
+	["o1-mini-", { contextWindow: 128_000 }],
+	["o1-pro-", { contextWindow: 200_000 }],
+	["o1-", { contextWindow: 200_000 }],
+	["o3-mini-", { contextWindow: 200_000 }],
+	["o3-pro-", { contextWindow: 200_000 }],
+	["o3-", { contextWindow: 200_000 }],
+	["o4-mini-", { contextWindow: 200_000 }],
+];
+
+export function getOpenAIModelCapabilities(
+	modelId: string,
+): OpenAIModelCapabilities {
+	const exact = EXACT_MODEL_CAPABILITIES[modelId];
+	if (exact) return exact;
+
+	for (const [prefix, capabilities] of PREFIX_MODEL_CAPABILITIES) {
+		if (modelId.startsWith(prefix)) return capabilities;
+	}
+
+	return {};
+}

package/src/errors.ts

@@ -0,0 +1,76 @@
+/** OpenAI-specific error class. */
+
+export class OpenAIError extends Error {
+	readonly status: number;
+	readonly code: string | null;
+	readonly type: string | null;
+
+	constructor(
+		status: number,
+		code: string | null,
+		type: string | null,
+		message: string,
+	) {
+		super(message);
+		this.name = "OpenAIError";
+		this.status = status;
+		this.code = code;
+		this.type = type;
+	}
+
+	static async fromResponse(res: Response): Promise<OpenAIError> {
+		let body: string;
+		try {
+			body = await res.text();
+		} catch {
+			body = "";
+		}
+
+		let code: string | null = null;
+		let type: string | null = null;
+		let message = `${res.status} ${res.statusText}`;
+
+		try {
+			const json = JSON.parse(body) as {
+				error?: {
+					message?: string;
+					code?: string | number;
+					type?: string;
+					metadata?: {
+						raw?: string;
+						provider_name?: string;
+					};
+				};
+			};
+			if (json.error) {
+				message = json.error.message ?? message;
+				code = json.error.code != null ? String(json.error.code) : null;
+				type = json.error.type ?? null;
+
+				// OpenRouter wraps upstream provider errors in metadata.raw —
+				// extract the inner message for a more helpful error.
+				if (json.error.metadata?.raw) {
+					try {
+						const inner = JSON.parse(json.error.metadata.raw) as {
+							error?: { message?: string; code?: string; type?: string };
+						};
+						if (inner.error?.message) {
+							const provider = json.error.metadata.provider_name;
+							message = provider
+								? `${inner.error.message} (provider: ${provider})`
+								: inner.error.message;
+						}
+						if (inner.error?.code) code = inner.error.code;
+						if (inner.error?.type) type = inner.error.type;
+					} catch {
+						// metadata.raw wasn't valid JSON — use outer message
+					}
+				}
+			}
+		} catch {
+			if (body) message += ` — ${body.slice(0, 200)}`;
+		}
+
+		return new OpenAIError(res.status, code, type, message);
+	}
+}

package/src/extension.ts

@@ -0,0 +1,224 @@
+/**
+ * OpenAI Extension — provides models via Chat Completions or Responses API.
+ */
+
+import type {
+	Extension,
+	Model,
+	StreamPart,
+	ModelRequest,
+	ThinkingLevel,
+} from "@dex-ai/sdk";
+import { createChatStream } from "./stream";
+import { createResponsesStream } from "./responses";
+import { getOpenAIModelCapabilities } from "./capabilities";
+
+/* ------------------------------------------------------------------ */
+/* Options                                                             */
+/* ------------------------------------------------------------------ */
+
+export interface OpenAIExtensionOptions {
+	/** API key. Falls back to OPENAI_API_KEY. */
+	readonly apiKey?: string;
+	/** Base URL (without trailing slash). Falls back to OPENAI_BASE_URL → https://api.openai.com/v1 */
+	readonly baseUrl?: string;
+	/** Extension name (used as provider name in Agent.create). Default: "openai". */
+	readonly name?: string;
+	/** Model IDs to register statically. */
+	readonly models?: ReadonlyArray<string | ModelConfig>;
+	/**
+	 * Models endpoint path appended to baseUrl for discovery.
+	 * Default: "/models". Set to null to disable discovery.
+	 */
+	readonly modelsPath?: string | null;
+	/** Emit raw-chunk parts during streaming. Default: false. */
+	readonly rawChunks?: boolean;
+	/**
+	 * API mode:
+	 * - "chat-completions" (default): POST /v1/chat/completions
+	 * - "responses": POST /v1/responses (enables reasoning-delta streaming)
+	 */
+	readonly mode?: "chat-completions" | "responses";
+	/** Additional headers sent with every request. */
+	readonly headers?: Record<string, string>;
+	/** Fetch override (for retry wrappers, testing). */
+	readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+	/** Stream idle timeout in ms. If no SSE data arrives within this window, the stream aborts. Default: 120000 (2 min). */
+	readonly streamIdleTimeoutMs?: number;
+}
+
+export interface ModelConfig {
+	readonly id: string;
+	readonly name?: string;
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+	readonly reasoning?: boolean;
+	readonly thinkingLevels?: ReadonlyArray<ThinkingLevel>;
+	readonly input?: ReadonlyArray<"text" | "image">;
+}
+
+/* ------------------------------------------------------------------ */
+/* Helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+function resolveBaseUrl(opts: OpenAIExtensionOptions): string {
+	const raw =
+		opts.baseUrl || process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
+	return raw.replace(/\/+$/, "");
+}
+
+function resolveApiKey(opts: OpenAIExtensionOptions): string {
+	const key = opts.apiKey ?? process.env.OPENAI_API_KEY;
+	if (!key) {
+		throw new Error(
+			"@dex-ai/openai: no API key found. Set apiKey or OPENAI_API_KEY.",
+		);
+	}
+	return key;
+}
+
+/* ------------------------------------------------------------------ */
+/* Extension factory                                                   */
+/* ------------------------------------------------------------------ */
+
+export function openaiExtension(opts: OpenAIExtensionOptions = {}): Extension {
+	const extName = opts.name ?? "openai";
+	const baseUrl = resolveBaseUrl(opts);
+	const apiKey = resolveApiKey(opts);
+	const rawChunks = opts.rawChunks ?? false;
+	const mode = opts.mode ?? "chat-completions";
+	const doFetch =
+		opts.fetch ?? ((url: string, init: RequestInit) => fetch(url, init));
+
+	const streamOpts = {
+		baseUrl,
+		apiKey,
+		modelId: "", // overridden per model
+		providerName: extName,
+		rawChunks,
+		doFetch,
+		...(opts.headers !== undefined ? { headers: opts.headers } : {}),
+		...(opts.streamIdleTimeoutMs !== undefined
+			? { streamIdleTimeoutMs: opts.streamIdleTimeoutMs }
+			: {}),
+	};
+
+	function createStreamFn(
+		modelId: string,
+		modelMaxTokens?: number,
+	): (req: ModelRequest) => AsyncIterable<StreamPart> {
+		const perModel = { ...streamOpts, modelId };
+		if (mode === "responses") {
+			return createResponsesStream(perModel, modelMaxTokens);
+		}
+		return createChatStream(perModel, modelMaxTokens);
+	}
+
+	// Static models from config
+	const staticModels: Model[] = (opts.models ?? []).map((m) => {
+		const cfg: ModelConfig = typeof m === "string" ? { id: m } : m;
+		const capabilities = getOpenAIModelCapabilities(cfg.id);
+		const contextWindow = cfg.contextWindow ?? capabilities.contextWindow;
+		return {
+			id: cfg.id,
+			...(cfg.name !== undefined ? { name: cfg.name } : {}),
+			...(contextWindow !== undefined ? { contextWindow } : {}),
+			...(cfg.maxTokens !== undefined ? { maxTokens: cfg.maxTokens } : {}),
+			...(cfg.reasoning !== undefined ? { reasoning: cfg.reasoning } : {}),
+			...(cfg.thinkingLevels !== undefined
+				? { thinkingLevels: cfg.thinkingLevels }
+				: {}),
+			...(cfg.input !== undefined ? { input: cfg.input } : {}),
+			stream: createStreamFn(cfg.id, cfg.maxTokens),
+		};
+	});
+
+	const allModels: Model[] = [...staticModels];
+
+	return {
+		name: extName,
+		get models() {
+			return allModels;
+		},
+
+		async init() {
+			const modelsPath =
+				opts.modelsPath !== null ? (opts.modelsPath ?? "/models") : null;
+			if (!modelsPath) return;
+
+			try {
+				const modelsUrl = modelsPath.startsWith("http")
+					? modelsPath
+					: `${baseUrl}${modelsPath}`;
+
+				const res = await doFetch(modelsUrl, {
+					method: "GET",
+					headers: {
+						Authorization: `Bearer ${apiKey}`,
+						...opts.headers,
+					},
+				});
+				if (!res.ok) return; // silently skip if discovery fails
+
+				const json = (await res.json()) as any;
+				const modelList: Array<{
+					id: string;
+					name?: string;
+					max_tokens?: number;
+					context_window?: number;
+					context_length?: number;
+					reasoning?: boolean;
+					input_modalities?: string[];
+				}> = json.data ?? json.models ?? (Array.isArray(json) ? json : []);
+
+				// Merge discovered metadata into static models + add new ones
+				const staticIds = new Set(staticModels.map((m) => m.id));
+				for (const m of modelList) {
+					if (!m.id) continue;
+					// Support OpenAI-compatible APIs that expose context metadata,
+					// then fall back to provider-side native OpenAI capability data.
+					const ctxWindow =
+						m.context_window ??
+						m.context_length ??
+						getOpenAIModelCapabilities(m.id).contextWindow;
+
+					if (staticIds.has(m.id)) {
+						// Enrich existing static model with discovered metadata
+						const idx = allModels.findIndex((am) => am.id === m.id);
+						if (idx !== -1) {
+							const existing = allModels[idx]!;
+							allModels[idx] = {
+								...existing,
+								...(ctxWindow && !existing.contextWindow
+									? { contextWindow: ctxWindow }
+									: {}),
+								...(m.max_tokens && !existing.maxTokens
+									? { maxTokens: m.max_tokens }
+									: {}),
+								...(m.reasoning !== undefined &&
+								existing.reasoning === undefined
+									? { reasoning: m.reasoning }
+									: {}),
+							};
+						}
+						continue;
+					}
+
+					allModels.push({
+						id: m.id,
+						...(m.name ? { name: m.name } : {}),
+						...(ctxWindow ? { contextWindow: ctxWindow } : {}),
+						...(m.max_tokens ? { maxTokens: m.max_tokens } : {}),
+						...(m.reasoning !== undefined ? { reasoning: m.reasoning } : {}),
+						...(m.input_modalities
+							? { input: m.input_modalities as ("text" | "image")[] }
+							: {}),
+						stream: createStreamFn(m.id, m.max_tokens),
+					});
+				}
+			} catch {
+				// Discovery failed — proceed with static models only
+			}
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { openaiExtension } from "./extension";
+export type { OpenAIExtensionOptions, ModelConfig } from "./extension";
+
+import type { ProviderDescriptor } from "@dex-ai/sdk";
+import { openaiExtension } from "./extension";
+
+export const descriptor: ProviderDescriptor = {
+	type: "openai",
+	label: "OpenAI",
+	fields: [
+		{ key: "apiKey", label: "API Key", required: true, secret: true, envVar: "OPENAI_API_KEY", hint: "sk-... (or press Enter to use OPENAI_API_KEY env var)" },
+		{ key: "baseUrl", label: "Base URL", required: false, default: "https://api.openai.com/v1", hint: "Custom endpoint for Azure, vLLM, LiteLLM, etc." },
+		{ key: "models", label: "Models", required: false, hint: "Comma-separated model IDs, or leave blank to auto-discover" },
+	],
+	create(config) {
+		const models = config.models as string[] | undefined;
+		return openaiExtension({
+			...(config.name ? { name: config.name as string } : {}),
+			...(config.apiKey ? { apiKey: config.apiKey as string } : {}),
+			...(config.baseUrl ? { baseUrl: config.baseUrl as string } : {}),
+			...(models ? { models } : {}),
+			...(models?.length ? { modelsPath: null } : {}),
+		});
+	},
+};