@fevex/openai 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,73 @@
+# @fevex/openai
+
+Official OpenAI `ModelGateway` adapter for Fevex.
+
+```bash
+npm install @fevex/core @fevex/openai
+```
+
+```ts
+import { createOpenAI } from '@fevex/openai';
+
+const model = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY!,
+  organization: process.env.OPENAI_ORG_ID,
+  project: process.env.OPENAI_PROJECT_ID,
+  schemaPolicy: 'strict',
+})('gpt-5.6');
+```
+
+The adapter uses native `fetch` and implements only the Fevex model contract.
+Runtime behavior such as tool execution, validation, events and retries belongs
+to `@fevex/core`. Returned gateways include `metadata: { provider: "openai",
+model: modelId }` for traces, eval cost calculators and OpenTelemetry export.
+
+## Text, tools and continuation
+
+Without `outputSchema`, OpenAI text is returned as the exact string supplied by
+the Responses API, even when it looks like JSON. With `outputSchema`, the
+adapter requires valid JSON before Fevex performs local schema validation.
+Refusals, incomplete responses and malformed function calls fail explicitly.
+
+During tool loops the adapter stores the original response items, including
+[reasoning items required by Responses API](https://platform.openai.com/docs/api-reference/responses-streaming/response/refusal?lang=python),
+in opaque `providerState`. Fevex returns that state to the next model step
+automatically. Direct `ModelGateway` consumers must do the same; the state is
+run-local and must not be inspected. The adapter's `stateCodec` lets Fevex
+persist it only inside a private durable checkpoint.
+
+Core reasoning efforts are forwarded to `reasoning.effort`;
+`provider-default` leaves provider options untouched. Model-specific effort
+support remains an OpenAI capability and an unsupported value is reported by
+the API. Provider-only settings can be supplied through
+`modelOptions.reasoning`.
+
+The adapter always uses the Responses streaming API. It emits only
+`response.output_text.delta` as visible output and builds the terminal result
+from `response.completed`; reasoning and partial function arguments remain
+private.
+
+Tool names and `schemaName` must match `[A-Za-z0-9_-]{1,64}`. Fevex-owned
+fields such as model, input, tools, tool choice, schema format, parallel calls
+and output caps override conflicting `modelOptions`. Background provider jobs
+and built-in tools remain outside this gateway.
+
+## Schema policy
+
+`schemaPolicy` defaults to `"strict"`. Before sending a request, the adapter
+checks tool inputs and final outputs against OpenAI's documented
+[Structured Outputs subset](https://developers.openai.com/api/docs/guides/structured-outputs).
+Every schema must have an object root; every object must require all its
+properties and set `additionalProperties: false`. Unsupported keywords and
+documented size limits throw `OpenAIError` with
+`code: "PROVIDER_SCHEMA_UNSUPPORTED"` before `fetch` runs.
+
+Set `schemaPolicy: "best-effort"` to send tools with `strict: false`. Object
+outputs use JSON mode and other JSON values use a schema instruction. Fevex
+still validates the returned value locally, but OpenAI does not guarantee schema
+adherence in this mode, so the caller may need to retry an invalid result.
+
+| Policy | Tool input | Final output |
+| --- | --- | --- |
+| `strict` | OpenAI strict function schema | Structured Outputs |
+| `best-effort` | Non-strict function schema | JSON mode or JSON instruction |

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+import { ModelGateway, PROVIDER_REASONING_UNSUPPORTED, PROVIDER_SCHEMA_UNSUPPORTED } from "@fevex/core";
+//#region src/config.d.ts
+type OpenAISchemaPolicy = 'strict' | 'best-effort';
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+interface OpenAIConfig {
+  apiKey: string;
+  baseURL?: string;
+  organization?: string;
+  project?: string;
+  schemaName?: string;
+  schemaPolicy?: OpenAISchemaPolicy;
+  fetch?: FetchLike;
+}
+//#endregion
+//#region src/openai-error.d.ts
+type OpenAIErrorCode = typeof PROVIDER_SCHEMA_UNSUPPORTED | typeof PROVIDER_REASONING_UNSUPPORTED;
+interface OpenAIErrorOptions {
+  status?: number;
+  requestId?: string;
+  code?: OpenAIErrorCode;
+  cause?: unknown;
+}
+declare class OpenAIError extends Error {
+  status?: number;
+  requestId?: string;
+  code?: OpenAIErrorCode;
+  constructor(message: string, options?: OpenAIErrorOptions);
+}
+//#endregion
+//#region src/index.d.ts
+declare function createOpenAI(config: OpenAIConfig): (modelId: string) => ModelGateway;
+//#endregion
+export { type OpenAIConfig, OpenAIError, type OpenAISchemaPolicy, createOpenAI };

package/dist/index.mjs

@@ -0,0 +1,742 @@
+import { PROVIDER_SCHEMA_UNSUPPORTED } from "@fevex/core";
+//#region src/config.ts
+function resolveOpenAIConfig(config) {
+	if (!isRecord$3(config)) throw new TypeError("OpenAI config must be an object");
+	if (typeof config.apiKey !== "string" || !config.apiKey.trim()) throw new TypeError("OpenAI apiKey cannot be empty");
+	assertOptionalString(config.baseURL, "baseURL");
+	assertOptionalString(config.organization, "organization");
+	assertOptionalString(config.project, "project");
+	if (config.schemaName !== void 0 && !isProviderName$1(config.schemaName)) throw new TypeError("OpenAI schemaName must match [A-Za-z0-9_-]{1,64}");
+	if (config.schemaPolicy !== void 0 && config.schemaPolicy !== "strict" && config.schemaPolicy !== "best-effort") throw new TypeError("OpenAI schemaPolicy must be \"strict\" or \"best-effort\"");
+	const requestFetch = config.fetch ?? globalThis.fetch;
+	if (typeof requestFetch !== "function") throw new TypeError("OpenAI adapter requires fetch");
+	return {
+		apiKey: config.apiKey,
+		baseURL: config.baseURL,
+		organization: config.organization,
+		project: config.project,
+		schemaName: config.schemaName,
+		schemaPolicy: config.schemaPolicy ?? "strict",
+		fetch: requestFetch
+	};
+}
+function assertOptionalString(value, name) {
+	if (value !== void 0 && (typeof value !== "string" || !value.trim())) throw new TypeError(`OpenAI ${name} must be a non-empty string`);
+}
+function isProviderName$1(value) {
+	return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value);
+}
+function isRecord$3(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/openai-error.ts
+var OpenAIError = class extends Error {
+	status;
+	requestId;
+	code;
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "OpenAIError";
+		this.status = options.status;
+		this.requestId = options.requestId;
+		this.code = options.code;
+	}
+};
+//#endregion
+//#region src/internal/provider-state.ts
+const stateBrand = Symbol("openai-provider-state");
+function readOpenAIProviderState(value, modelId) {
+	if (value === void 0) return void 0;
+	if (!isOpenAIProviderState(value) || value.modelId !== modelId) throw new OpenAIError("OpenAI providerState is invalid for this model");
+	return value;
+}
+function appendOpenAIProviderState(previous, modelId, output, toolCallIds) {
+	return {
+		[stateBrand]: true,
+		modelId,
+		turns: [...previous?.turns ?? [], {
+			toolCallIds: [...toolCallIds],
+			output: [...output]
+		}]
+	};
+}
+function serializeOpenAIProviderState(value, modelId) {
+	const state = readOpenAIProviderState(value, modelId);
+	if (!state) throw new OpenAIError("OpenAI providerState is required");
+	return JSON.parse(JSON.stringify({
+		modelId: state.modelId,
+		turns: state.turns
+	}));
+}
+function restoreOpenAIProviderState(value, modelId) {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || value.modelId !== modelId || !Array.isArray(value.turns)) throw new OpenAIError("OpenAI serialized providerState is invalid for this model");
+	const turns = value.turns.map((turn) => {
+		if (typeof turn !== "object" || turn === null || Array.isArray(turn) || !Array.isArray(turn.toolCallIds) || !turn.toolCallIds.every((id) => typeof id === "string" && id.length > 0) || !Array.isArray(turn.output)) throw new OpenAIError("OpenAI serialized providerState is invalid for this model");
+		return {
+			toolCallIds: [...turn.toolCallIds],
+			output: structuredClone(turn.output)
+		};
+	});
+	return {
+		[stateBrand]: true,
+		modelId,
+		turns
+	};
+}
+function isOpenAIProviderState(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (value[stateBrand] !== true || typeof value.modelId !== "string" || !Array.isArray(value.turns)) return false;
+	return value.turns.every((turn) => typeof turn === "object" && turn !== null && Array.isArray(turn.toolCallIds) && turn.toolCallIds.every((id) => typeof id === "string" && id.length > 0) && Array.isArray(turn.output));
+}
+//#endregion
+//#region src/internal/provider-schema.ts
+const supportedTypes = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"boolean",
+	"integer",
+	"object",
+	"array",
+	"null"
+]);
+const supportedFormats = /* @__PURE__ */ new Set([
+	"date-time",
+	"time",
+	"date",
+	"duration",
+	"email",
+	"hostname",
+	"ipv4",
+	"ipv6",
+	"uuid"
+]);
+const supportedKeywords = /* @__PURE__ */ new Set([
+	"$schema",
+	"$id",
+	"$ref",
+	"$defs",
+	"title",
+	"description",
+	"type",
+	"properties",
+	"required",
+	"additionalProperties",
+	"items",
+	"enum",
+	"const",
+	"anyOf",
+	"format",
+	"pattern",
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"multipleOf",
+	"minItems",
+	"maxItems"
+]);
+function findOpenAISchemaIssue(schema) {
+	if (schema.type !== "object" || schema.anyOf !== void 0) return "$: root must be an object and must not use anyOf";
+	const state = {
+		propertyCount: 0,
+		enumCount: 0,
+		stringLength: 0
+	};
+	const issue = visitSchema(schema, "$", 0, state);
+	if (issue) return issue;
+	if (state.propertyCount > 5e3) return "$: schema exceeds OpenAI limit of 5000 object properties";
+	if (state.enumCount > 1e3) return "$: schema exceeds OpenAI limit of 1000 enum values";
+	if (state.stringLength > 12e4) return "$: schema exceeds OpenAI limit of 120000 schema string characters";
+}
+function visitSchema(schema, path, objectDepth, state) {
+	if (!isRecord$2(schema)) return `${path}: schema must be an object`;
+	for (const keyword of Object.keys(schema)) if (!supportedKeywords.has(keyword)) return `${path}.${keyword}: keyword is not supported by OpenAI strict schemas`;
+	if (schema.$ref !== void 0 && typeof schema.$ref !== "string") return `${path}.$ref: must be a string`;
+	const typeIssue = validateType(schema.type, path);
+	if (typeIssue) return typeIssue;
+	const types = typeof schema.type === "string" ? [schema.type] : Array.isArray(schema.type) ? schema.type : [];
+	const isObject = types.includes("object");
+	const isArray = types.includes("array");
+	const isString = types.includes("string");
+	const isNumeric = types.includes("number") || types.includes("integer");
+	const nextObjectDepth = isObject ? objectDepth + 1 : objectDepth;
+	if (nextObjectDepth > 10) return `${path}: schema exceeds OpenAI limit of 10 object nesting levels`;
+	if (!isObject && hasAny(schema, [
+		"properties",
+		"required",
+		"additionalProperties"
+	])) return `${path}: object keywords require type "object"`;
+	if (!isArray && hasAny(schema, [
+		"items",
+		"minItems",
+		"maxItems"
+	])) return `${path}: array keywords require type "array"`;
+	if (!isString && hasAny(schema, ["pattern", "format"])) return `${path}: string keywords require type "string"`;
+	if (!isNumeric && hasAny(schema, [
+		"minimum",
+		"maximum",
+		"exclusiveMinimum",
+		"exclusiveMaximum",
+		"multipleOf"
+	])) return `${path}: numeric keywords require type "number" or "integer"`;
+	if (isObject) {
+		if (!isRecord$2(schema.properties)) return `${path}.properties: must be an object`;
+		if (schema.additionalProperties !== false) return `${path}.additionalProperties: must be false`;
+		const propertyNames = Object.keys(schema.properties);
+		const required = schema.required;
+		if (!Array.isArray(required) || required.some((name) => typeof name !== "string") || required.length !== propertyNames.length || propertyNames.some((name) => !required.includes(name))) return `${path}.required: must contain every property exactly once`;
+		state.propertyCount += propertyNames.length;
+		state.stringLength += propertyNames.reduce((total, name) => total + name.length, 0);
+		for (const name of propertyNames) {
+			const issue = visitSchema(schema.properties[name], `${path}.properties.${name}`, nextObjectDepth, state);
+			if (issue) return issue;
+		}
+	}
+	if (isArray) {
+		if (!isRecord$2(schema.items)) return `${path}.items: must be a schema object`;
+		const issue = visitSchema(schema.items, `${path}.items`, objectDepth, state);
+		if (issue) return issue;
+	}
+	if (schema.anyOf !== void 0) {
+		if (!Array.isArray(schema.anyOf) || schema.anyOf.length === 0) return `${path}.anyOf: must be a non-empty array`;
+		for (let index = 0; index < schema.anyOf.length; index += 1) {
+			const issue = visitSchema(schema.anyOf[index], `${path}.anyOf[${index}]`, objectDepth, state);
+			if (issue) return issue;
+		}
+	}
+	const definitions = schema.$defs;
+	if (definitions !== void 0) {
+		if (!isRecord$2(definitions)) return `${path}.$defs: must be an object`;
+		const names = Object.keys(definitions);
+		state.stringLength += names.reduce((total, name) => total + name.length, 0);
+		for (const name of names) {
+			const issue = visitSchema(definitions[name], `${path}.$defs.${name}`, objectDepth, state);
+			if (issue) return issue;
+		}
+	}
+	if (schema.enum !== void 0) {
+		if (!Array.isArray(schema.enum) || schema.enum.some((value) => !isJsonPrimitive(value))) return `${path}.enum: must contain only JSON primitive values`;
+		state.enumCount += schema.enum.length;
+		const enumStringLength = schema.enum.reduce((total, value) => total + (typeof value === "string" ? value.length : 0), 0);
+		state.stringLength += enumStringLength;
+		if (schema.enum.length > 250 && enumStringLength > 15e3) return `${path}.enum: exceeds OpenAI limit of 15000 characters for large enums`;
+	}
+	if (schema.const !== void 0 && !isJsonPrimitive(schema.const)) return `${path}.const: must be a JSON primitive`;
+	if (typeof schema.const === "string") state.stringLength += schema.const.length;
+	if (schema.pattern !== void 0 && typeof schema.pattern !== "string") return `${path}.pattern: must be a string`;
+	if (schema.format !== void 0 && (typeof schema.format !== "string" || !supportedFormats.has(schema.format))) return `${path}.format: format "${String(schema.format)}" is not supported by OpenAI`;
+	for (const keyword of [
+		"minimum",
+		"maximum",
+		"exclusiveMinimum",
+		"exclusiveMaximum",
+		"multipleOf"
+	]) if (schema[keyword] !== void 0 && (typeof schema[keyword] !== "number" || !Number.isFinite(schema[keyword]))) return `${path}.${keyword}: must be a number`;
+	for (const keyword of ["minItems", "maxItems"]) if (schema[keyword] !== void 0 && (typeof schema[keyword] !== "number" || !Number.isInteger(schema[keyword]) || schema[keyword] < 0)) return `${path}.${keyword}: must be a non-negative integer`;
+}
+function validateType(value, path) {
+	if (value === void 0) return void 0;
+	if (typeof value === "string") return supportedTypes.has(value) ? void 0 : `${path}.type: type "${value}" is not supported by OpenAI`;
+	if (Array.isArray(value) && value.length === 2 && value.filter((type) => type === "null").length === 1 && value.every((type) => typeof type === "string" && supportedTypes.has(type))) return;
+	return `${path}.type: must be a supported type or a nullable two-type union`;
+}
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasAny(schema, keywords) {
+	return keywords.some((keyword) => schema[keyword] !== void 0);
+}
+function isJsonPrimitive(value) {
+	return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+//#endregion
+//#region src/internal/response.ts
+function parseOpenAIResponse(response, input, modelId) {
+	assertCompletedResponse(response);
+	if (!Array.isArray(response.output)) throw new OpenAIError("OpenAI response returned an invalid output array");
+	const providerOutput = response.output;
+	const toolCalls = parseToolCalls(providerOutput);
+	const output = parseOutput(providerOutput, input.outputSchema !== void 0);
+	const usage = parseUsage(response.usage);
+	const providerState = toolCalls?.length ? appendOpenAIProviderState(readOpenAIProviderState(input.providerState, modelId), modelId, providerOutput, toolCalls.map(({ id }) => id)) : void 0;
+	if (output === void 0 && !toolCalls?.length) throw new OpenAIError("OpenAI response returned no output");
+	return {
+		...output === void 0 ? {} : { output },
+		...toolCalls?.length ? { toolCalls } : {},
+		...usage ? { usage } : {},
+		...providerState ? { providerState } : {}
+	};
+}
+function parseToolCalls(output) {
+	if (!Array.isArray(output)) return void 0;
+	const calls = [];
+	const callIds = /* @__PURE__ */ new Set();
+	for (const item of output) {
+		if (!isRecord$1(item) || item.type !== "function_call") continue;
+		if (typeof item.call_id !== "string" || !item.call_id.trim()) throw new OpenAIError("OpenAI tool call returned an invalid call_id");
+		if (typeof item.name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(item.name)) throw new OpenAIError("OpenAI tool call returned an invalid name");
+		if (callIds.has(item.call_id)) throw new OpenAIError(`OpenAI tool call id "${item.call_id}" is duplicated`);
+		callIds.add(item.call_id);
+		if (typeof item.arguments !== "string") throw new OpenAIError(`OpenAI tool call "${item.name}" returned invalid arguments`);
+		let parsedArguments;
+		try {
+			parsedArguments = JSON.parse(item.arguments);
+		} catch (error) {
+			throw new OpenAIError(`OpenAI tool call "${item.name}" returned invalid JSON arguments`, { cause: error });
+		}
+		if (!isRecord$1(parsedArguments)) throw new OpenAIError(`OpenAI tool call "${item.name}" arguments must be a JSON object`);
+		calls.push({
+			id: item.call_id,
+			name: item.name,
+			input: parsedArguments
+		});
+	}
+	return calls.length ? calls : void 0;
+}
+function parseOutput(providerOutput, structured) {
+	const texts = [];
+	for (const item of providerOutput) {
+		if (!isRecord$1(item) || item.type !== "message" || !Array.isArray(item.content)) continue;
+		for (const content of item.content) {
+			if (!isRecord$1(content)) continue;
+			if (content.type === "refusal" && typeof content.refusal === "string") throw new OpenAIError(`OpenAI refused the response: ${content.refusal}`);
+			if (content.type === "output_text" && typeof content.text === "string") texts.push(content.text);
+		}
+	}
+	const text = texts.length ? texts.join("") : void 0;
+	if (text === void 0) return void 0;
+	if (!structured) return text;
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new OpenAIError("OpenAI structured output was not valid JSON", { cause: error });
+	}
+}
+function assertCompletedResponse(response) {
+	if (response.status === "completed") return;
+	if (typeof response.status !== "string") throw new OpenAIError("OpenAI response returned an invalid status");
+	let detail;
+	if (isRecord$1(response.error) && typeof response.error.message === "string") detail = response.error.message;
+	else if (isRecord$1(response.incomplete_details) && typeof response.incomplete_details.reason === "string") detail = response.incomplete_details.reason;
+	throw new OpenAIError(`OpenAI response was ${response.status}${detail ? `: ${detail}` : ""}`);
+}
+function parseUsage(usage) {
+	if (!usage) return void 0;
+	return {
+		...typeof usage.input_tokens === "number" ? { inputTokens: usage.input_tokens } : {},
+		...typeof usage.output_tokens === "number" ? { outputTokens: usage.output_tokens } : {},
+		...typeof usage.total_tokens === "number" ? { totalTokens: usage.total_tokens } : {}
+	};
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/internal/sse.ts
+async function* readSSE(body, signal) {
+	if (!body) throw new TypeError("SSE response body is missing");
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let finished = false;
+	const takeFrame = () => {
+		const match = /\r?\n\r?\n/.exec(buffer);
+		if (!match || match.index === void 0) return void 0;
+		const frame = buffer.slice(0, match.index);
+		buffer = buffer.slice(match.index + match[0].length);
+		return frame;
+	};
+	const data = (frame) => {
+		const lines = frame.split(/\r?\n/).filter((line) => line === "data" || line.startsWith("data:")).map((line) => line.slice(5).replace(/^ /, ""));
+		return lines.length ? lines.join("\n") : void 0;
+	};
+	try {
+		while (true) {
+			signal?.throwIfAborted();
+			const next = await readChunk(reader, signal);
+			if (next.done) {
+				finished = true;
+				buffer += decoder.decode();
+				if (buffer) {
+					const value = data(buffer);
+					if (value !== void 0) yield value;
+				}
+				return;
+			}
+			buffer += decoder.decode(next.value, { stream: true });
+			let frame;
+			while ((frame = takeFrame()) !== void 0) {
+				const value = data(frame);
+				if (value !== void 0) yield value;
+			}
+		}
+	} finally {
+		if (!finished) await reader.cancel().catch(() => {});
+		reader.releaseLock();
+	}
+}
+function readChunk(reader, signal) {
+	if (!signal) return reader.read();
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const aborted = () => reject(signal.reason);
+		signal.addEventListener("abort", aborted, { once: true });
+		reader.read().then((value) => {
+			signal.removeEventListener("abort", aborted);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", aborted);
+			reject(error);
+		});
+	});
+}
+//#endregion
+//#region src/internal/responses-api.ts
+const defaultBaseURL = "https://api.openai.com/v1";
+async function* streamOpenAIResponse(config, modelId, input) {
+	input.signal?.throwIfAborted();
+	assertCompatibleInput(input);
+	if (config.schemaPolicy === "strict") assertStrictSchemas(input);
+	const body = buildRequestBody(config, modelId, input);
+	let response;
+	try {
+		response = await config.fetch(toResponsesURL(config.baseURL), {
+			method: "POST",
+			headers: buildHeaders(config),
+			body: JSON.stringify(body),
+			signal: input.signal
+		});
+	} catch (error) {
+		if (input.signal?.aborted) throw input.signal.reason;
+		throw new OpenAIError("OpenAI request failed", { cause: error });
+	}
+	input.signal?.throwIfAborted();
+	const requestId = response.headers.get("x-request-id") ?? void 0;
+	if (!response.ok) {
+		const data = await readResponseJson(response, requestId, input.signal);
+		throw new OpenAIError(toOpenAIErrorMessage(data, response.status), {
+			status: response.status,
+			requestId,
+			cause: data
+		});
+	}
+	let completed = false;
+	try {
+		for await (const data of readSSE(response.body, input.signal)) {
+			if (data === "[DONE]") continue;
+			let event;
+			try {
+				event = JSON.parse(data);
+			} catch (error) {
+				throw new OpenAIError("OpenAI stream event was not valid JSON", {
+					status: response.status,
+					requestId,
+					cause: error
+				});
+			}
+			if (!isRecord(event) || typeof event.type !== "string") throw new OpenAIError("OpenAI stream event was invalid", {
+				status: response.status,
+				requestId,
+				cause: event
+			});
+			if (event.type === "response.output_text.delta") {
+				if (typeof event.delta !== "string") throw new OpenAIError("OpenAI output delta was invalid", {
+					status: response.status,
+					requestId,
+					cause: event
+				});
+				if (event.delta) yield {
+					type: "output.delta",
+					delta: event.delta
+				};
+				continue;
+			}
+			if (event.type === "response.completed") {
+				if (completed || !isRecord(event.response)) throw new OpenAIError("OpenAI stream returned an invalid completion", {
+					status: response.status,
+					requestId,
+					cause: event
+				});
+				completed = true;
+				yield {
+					type: "completed",
+					result: parseOpenAIResponse(event.response, input, modelId)
+				};
+				continue;
+			}
+			if (event.type === "response.failed" || event.type === "response.incomplete") {
+				if (!isRecord(event.response)) throw new OpenAIError("OpenAI stream returned an invalid terminal response", {
+					status: response.status,
+					requestId,
+					cause: event
+				});
+				parseOpenAIResponse(event.response, input, modelId);
+			}
+			if (event.type === "error") throw new OpenAIError(toOpenAIStreamErrorMessage(event), {
+				status: response.status,
+				requestId,
+				cause: event
+			});
+		}
+	} catch (error) {
+		if (input.signal?.aborted) throw input.signal.reason;
+		if (error instanceof OpenAIError) throw error;
+		throw new OpenAIError("OpenAI stream failed", {
+			status: response.status,
+			requestId,
+			cause: error
+		});
+	}
+	if (!completed) throw new OpenAIError("OpenAI stream ended without response.completed", {
+		status: response.status,
+		requestId
+	});
+}
+function buildHeaders(config) {
+	return {
+		authorization: `Bearer ${config.apiKey}`,
+		"content-type": "application/json",
+		accept: "text/event-stream",
+		...config.organization ? { "openai-organization": config.organization } : {},
+		...config.project ? { "openai-project": config.project } : {}
+	};
+}
+function buildRequestBody(config, modelId, input) {
+	const strict = config.schemaPolicy === "strict";
+	const options = { ...input.modelOptions ?? {} };
+	const providerLimit = options.max_output_tokens;
+	const providerReasoning = options.reasoning;
+	const providerText = options.text;
+	for (const key of [
+		"model",
+		"input",
+		"tools",
+		"tool_choice",
+		"parallel_tool_calls",
+		"max_output_tokens",
+		"text",
+		"reasoning",
+		"stream",
+		"background",
+		"previous_response_id",
+		"conversation"
+	]) delete options[key];
+	const messages = input.outputSchema && !strict ? withSchemaInstruction(input.messages, input.outputSchema) : input.messages;
+	const maxOutputTokens = cappedTokenLimit(input.maxOutputTokens, providerLimit);
+	const text = toOpenAIText(config, input, providerText);
+	const reasoning = toOpenAIReasoning(input, providerReasoning);
+	return {
+		...options,
+		model: modelId,
+		stream: true,
+		input: toOpenAIInput(messages, readOpenAIProviderState(input.providerState, modelId)),
+		...input.tools?.length ? {
+			tools: input.tools.map((tool) => toOpenAITool(tool, strict)),
+			parallel_tool_calls: false
+		} : {},
+		...text === void 0 ? {} : { text },
+		...reasoning === void 0 ? {} : { reasoning },
+		...maxOutputTokens === void 0 ? {} : { max_output_tokens: maxOutputTokens }
+	};
+}
+function toResponsesURL(baseURL) {
+	return `${(baseURL ?? defaultBaseURL).replace(/\/$/, "")}/responses`;
+}
+function cappedTokenLimit(runtimeLimit, providerLimit) {
+	if (runtimeLimit === void 0) return providerLimit;
+	return typeof providerLimit === "number" && Number.isFinite(providerLimit) && providerLimit > 0 ? Math.min(runtimeLimit, providerLimit) : runtimeLimit;
+}
+async function readResponseJson(response, requestId, signal) {
+	const text = await response.text();
+	signal?.throwIfAborted();
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new OpenAIError("OpenAI response was not valid JSON", {
+			status: response.status,
+			requestId,
+			cause: error
+		});
+	}
+}
+function toOpenAIInput(messages, state) {
+	const input = [];
+	let turnIndex = 0;
+	for (const message of messages) {
+		if (message.role === "tool") {
+			input.push({
+				type: "function_call_output",
+				call_id: message.toolCallId ?? "",
+				output: message.content
+			});
+			continue;
+		}
+		if (message.role === "assistant" && message.toolCalls?.length) {
+			const turn = state?.turns[turnIndex];
+			if (!turn) throw new OpenAIError("OpenAI providerState is required for assistant tool-call history");
+			const ids = message.toolCalls.map(({ id }) => id);
+			if (!sameStrings(turn.toolCallIds, ids)) throw new OpenAIError("OpenAI providerState does not match assistant tool-call history");
+			input.push(...turn.output);
+			turnIndex += 1;
+			continue;
+		}
+		input.push({
+			role: message.role,
+			content: message.content
+		});
+	}
+	if (turnIndex !== (state?.turns.length ?? 0)) throw new OpenAIError("OpenAI providerState does not match assistant tool-call history");
+	return input;
+}
+function toOpenAIText(config, input, providerText) {
+	if (!input.outputSchema) return providerText;
+	const text = isRecord(providerText) ? providerText : {};
+	if (config.schemaPolicy === "strict") return {
+		...text,
+		format: {
+			type: "json_schema",
+			name: config.schemaName ?? "fevex_output",
+			strict: true,
+			schema: input.outputSchema
+		}
+	};
+	if (!isObjectRoot(input.outputSchema) && providerText === void 0) return;
+	return {
+		...text,
+		format: isObjectRoot(input.outputSchema) ? { type: "json_object" } : { type: "text" }
+	};
+}
+function toOpenAIReasoning(input, providerReasoning) {
+	if (!input.reasoning || input.reasoning === "provider-default") return providerReasoning;
+	return {
+		...isRecord(providerReasoning) ? providerReasoning : {},
+		effort: input.reasoning
+	};
+}
+function toOpenAITool(tool, strict) {
+	return {
+		type: "function",
+		name: tool.name,
+		...tool.description ? { description: tool.description } : {},
+		parameters: tool.inputSchema ?? emptyObjectSchema(strict),
+		strict
+	};
+}
+function assertStrictSchemas(input) {
+	for (const tool of input.tools ?? []) assertStrictSchema(tool.inputSchema ?? emptyObjectSchema(true), `tool-input "${tool.name}"`);
+	if (input.outputSchema) assertStrictSchema(input.outputSchema, "output");
+}
+function assertCompatibleInput(input) {
+	if (!isRecord(input)) throw new OpenAIError("OpenAI input must be an object");
+	if (!Array.isArray(input.messages) || input.messages.length === 0) throw new OpenAIError("OpenAI messages must be a non-empty array");
+	if (input.modelOptions !== void 0 && !isRecord(input.modelOptions)) throw new OpenAIError("OpenAI modelOptions must be an object");
+	if (input.maxOutputTokens !== void 0 && (!Number.isInteger(input.maxOutputTokens) || input.maxOutputTokens < 1)) throw new OpenAIError("OpenAI maxOutputTokens must be a positive integer");
+	if (input.reasoning !== void 0 && ![
+		"provider-default",
+		"none",
+		"minimal",
+		"low",
+		"medium",
+		"high"
+	].includes(input.reasoning)) throw new OpenAIError("OpenAI reasoning effort is invalid");
+	if (input.outputSchema !== void 0 && !isRecord(input.outputSchema)) throw new OpenAIError("OpenAI outputSchema must be an object");
+	if (input.tools !== void 0 && !Array.isArray(input.tools)) throw new OpenAIError("OpenAI tools must be an array");
+	if ((input.tools?.length ?? 0) > 128) throw new OpenAIError("OpenAI supports at most 128 tools");
+	const toolNames = /* @__PURE__ */ new Set();
+	for (const tool of input.tools ?? []) {
+		if (!isRecord(tool) || !isProviderName(tool.name)) throw new OpenAIError("OpenAI tool names must match [A-Za-z0-9_-]{1,64}");
+		if (toolNames.has(tool.name)) throw new OpenAIError(`OpenAI tool "${tool.name}" is duplicated`);
+		toolNames.add(tool.name);
+	}
+	const callIds = /* @__PURE__ */ new Set();
+	const completedCallIds = /* @__PURE__ */ new Set();
+	for (const message of input.messages) {
+		if (!isRecord(message) || ![
+			"system",
+			"user",
+			"assistant",
+			"tool"
+		].includes(String(message.role)) || typeof message.content !== "string") throw new OpenAIError("OpenAI message is invalid");
+		if (message.role === "assistant" && message.toolCalls !== void 0) {
+			if (!Array.isArray(message.toolCalls)) throw new OpenAIError("OpenAI assistant toolCalls must be an array");
+			for (const call of message.toolCalls) {
+				if (!isRecord(call) || typeof call.id !== "string" || !call.id.trim() || !isProviderName(call.name)) throw new OpenAIError("OpenAI assistant tool call is invalid");
+				if (callIds.has(call.id)) throw new OpenAIError(`OpenAI tool call id "${call.id}" is duplicated`);
+				callIds.add(call.id);
+			}
+		}
+		if (message.role === "tool") {
+			if (typeof message.toolCallId !== "string" || !message.toolCallId.trim() || !callIds.has(message.toolCallId) || completedCallIds.has(message.toolCallId)) throw new OpenAIError("OpenAI tool result has an invalid toolCallId");
+			completedCallIds.add(message.toolCallId);
+		}
+	}
+	if (completedCallIds.size !== callIds.size) throw new OpenAIError("OpenAI assistant tool call is missing a tool result");
+}
+function assertStrictSchema(schema, boundary) {
+	const issue = findOpenAISchemaIssue(schema);
+	if (!issue) return;
+	throw new OpenAIError(`OpenAI strict schema for ${boundary} is unsupported at ${issue}`, { code: PROVIDER_SCHEMA_UNSUPPORTED });
+}
+function emptyObjectSchema(strict) {
+	return strict ? {
+		type: "object",
+		properties: {},
+		required: [],
+		additionalProperties: false
+	} : {
+		type: "object",
+		properties: {}
+	};
+}
+function withSchemaInstruction(messages, schema) {
+	return [{
+		role: "system",
+		content: `Respond with a ${isObjectRoot(schema) ? "JSON object" : "JSON value"} matching this schema: ${JSON.stringify(schema)}`
+	}, ...messages];
+}
+function isObjectRoot(schema) {
+	return schema.type === "object" && schema.anyOf === void 0;
+}
+function isProviderName(value) {
+	return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value);
+}
+function sameStrings(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function toOpenAIErrorMessage(data, status) {
+	if (isRecord(data) && isRecord(data.error) && typeof data.error.message === "string") return data.error.message;
+	return `OpenAI request failed with status ${status}`;
+}
+function toOpenAIStreamErrorMessage(event) {
+	if (typeof event.message === "string") return event.message;
+	if (isRecord(event.error) && typeof event.error.message === "string") return event.error.message;
+	return "OpenAI stream failed";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/index.ts
+function createOpenAI(config) {
+	const resolvedConfig = resolveOpenAIConfig(config);
+	return (modelId) => {
+		if (typeof modelId !== "string" || !modelId.trim()) throw new TypeError("OpenAI modelId cannot be empty");
+		return {
+			metadata: {
+				provider: "openai",
+				model: modelId
+			},
+			stateCodec: {
+				serialize: (state) => serializeOpenAIProviderState(state, modelId),
+				restore: (state) => restoreOpenAIProviderState(state, modelId)
+			},
+			stream(input) {
+				return streamOpenAIResponse(resolvedConfig, modelId, input);
+			}
+		};
+	};
+}
+//#endregion
+export { OpenAIError, createOpenAI };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@fevex/openai",
+  "version": "0.1.0-alpha.1",
+  "description": "OpenAI ModelGateway adapter for Fevex.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hemia-labs/fevex.git",
+    "directory": "packages/openai"
+  },
+  "bugs": {
+    "url": "https://github.com/hemia-labs/fevex/issues"
+  },
+  "homepage": "https://github.com/hemia-labs/fevex#readme",
+  "keywords": ["ai", "agents", "openai", "typescript", "fevex"],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "prepack": "bun run build",
+    "test": "bun test src/index.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@fevex/core": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}