@statelyai/agent 2.0.0-alpha.21 → 2.0.0-alpha.23

package/dist/openai.cjs

@@ -0,0 +1,447 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_decision = require("./decision-Cv6SfNWl.cjs");
+//#region src/openai/index.ts
+/** Thrown for a message part Chat Completions cannot carry — dropping it would
+* silently change what the model sees. */
+function unsupportedPart(role, type) {
+	throw new Error(`createOpenAiExecutors: a ${role} message part of type '${type}' has no Chat Completions equivalent. Send text, image, tool-call, or tool-result parts, or convert it before the request.`);
+}
+/** A `DataContent`/`URL` image as the URL string OpenAI's `image_url` part wants:
+* an http(s) or `data:` string and a `URL` pass through, a bare base64 string and
+* raw bytes are wrapped in a data URL. */
+function toImageUrl(image, mediaType) {
+	if (image instanceof URL) return image.href;
+	const type = mediaType ?? "image/jpeg";
+	if (typeof image === "string") return /^(https?:|data:)/.test(image) ? image : `data:${type};base64,${image}`;
+	const bytes = image instanceof Uint8Array ? image : new Uint8Array(image);
+	const encode = globalThis.btoa;
+	if (!encode) throw new Error("createOpenAiExecutors: binary image parts need a global `btoa` to base64-encode. Pass the image as a URL or a base64 string instead.");
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return `data:${type};base64,${encode(binary)}`;
+}
+/** One OpenAI tool message per `ToolResultPart` — the tool role is one message per result. */
+function toToolMessage(part) {
+	return {
+		role: "tool",
+		content: part.output.type === "text" || part.output.type === "error-text" ? part.output.value : JSON.stringify(part.output.value),
+		tool_call_id: part.toolCallId
+	};
+}
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
+function toOpenAiMessages(request) {
+	if (request.messages) return request.messages.flatMap((message) => {
+		switch (message.role) {
+			case "system": return [{
+				role: "system",
+				content: message.content
+			}];
+			case "user":
+				if (typeof message.content === "string") return [{
+					role: "user",
+					content: message.content
+				}];
+				return [{
+					role: "user",
+					content: message.content.map((part) => {
+						switch (part.type) {
+							case "text": return {
+								type: "text",
+								text: part.text
+							};
+							case "image": return {
+								type: "image_url",
+								image_url: { url: toImageUrl(part.image, part.mediaType) }
+							};
+							default: return unsupportedPart("user", part.type);
+						}
+					})
+				}];
+			case "assistant": {
+				if (typeof message.content === "string") return [{
+					role: "assistant",
+					content: message.content
+				}];
+				let text = "";
+				const toolCalls = [];
+				const trailing = [];
+				for (const part of message.content) switch (part.type) {
+					case "text":
+						text += part.text;
+						break;
+					case "tool-call":
+						toolCalls.push({
+							id: part.toolCallId,
+							type: "function",
+							function: {
+								name: part.toolName,
+								arguments: JSON.stringify(part.input ?? {})
+							}
+						});
+						break;
+					case "tool-result":
+						trailing.push(toToolMessage(part));
+						break;
+					default: unsupportedPart("assistant", part.type);
+				}
+				return [{
+					role: "assistant",
+					content: text,
+					...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
+				}, ...trailing];
+			}
+			case "tool": return message.content.map(toToolMessage);
+		}
+	});
+	const messages = [];
+	if (request.system) messages.push({
+		role: "system",
+		content: request.system
+	});
+	messages.push({
+		role: "user",
+		content: request.prompt ?? ""
+	});
+	return messages;
+}
+/** Drops keys whose value is `undefined`, so a spread cannot erase what it lands on. */
+function defined(settings) {
+	return Object.fromEntries(Object.entries(settings).filter(([, value]) => value !== void 0));
+}
+/**
+* Maps the generation settings a text and a decision request share onto OpenAI
+* Chat Completions parameters, with unset keys omitted.
+*
+* Omitting matters: these are the top layer of a stack — the host's
+* {@link CreateOpenAiExecutorsOptions.settings}, then the request's — and an
+* `undefined` spread over the layer below would erase it.
+*
+* `max_tokens` is deprecated by OpenAI in favor of `max_completion_tokens`, so
+* that's what `maxOutputTokens` targets. Chat Completions has no `top_k`
+* parameter, so `topK` is dropped.
+*/
+function toOpenAiCallSettings(request) {
+	return defined({
+		temperature: request.temperature,
+		max_completion_tokens: request.maxOutputTokens,
+		top_p: request.topP,
+		seed: request.seed,
+		stop: request.stopSequences
+	});
+}
+/** A tool `description` may be a string or, for an AI SDK v7 tool, a function
+* of the call's context. A raw JSON payload can only carry the static form. */
+function staticDescription(descriptor) {
+	if (typeof descriptor === "function") return;
+	return typeof descriptor.description === "string" ? descriptor.description : void 0;
+}
+/** One OpenAI function tool per `AgentTools` entry. */
+function toOpenAiTools(tools) {
+	return Object.entries(tools).flatMap(([name, descriptor]) => {
+		if (!descriptor) return [];
+		const inputSchema = typeof descriptor === "function" ? void 0 : descriptor.inputSchema;
+		return [{
+			type: "function",
+			function: {
+				name,
+				description: staticDescription(descriptor),
+				parameters: (require_decision.isStandardSchema(inputSchema) ? require_decision.getJsonSchemaSync(inputSchema) : void 0) ?? {}
+			}
+		}];
+	});
+}
+/**
+* Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
+* `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
+* `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
+* `undefined` stays `undefined`, so the key is omitted.
+*/
+function toOpenAiToolChoice(toolChoice) {
+	if (toolChoice === void 0) return;
+	return typeof toolChoice === "object" ? {
+		type: "function",
+		function: { name: toolChoice.name }
+	} : toolChoice;
+}
+/** One OpenAI function tool per candidate decision event — the "tool-per-event
+* + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
+function toOpenAiEventTools(events) {
+	return events.map((event) => ({
+		type: "function",
+		function: {
+			name: event.toolName,
+			description: `Choose the '${event.type}' move.`,
+			parameters: require_decision.getJsonSchemaSync(event.inputSchema) ?? {}
+		}
+	}));
+}
+/**
+* Messages for a decision request, with prior failed `attempts` rendered as an
+* appended user message so retries converge. Mirrors the AI SDK adapter's
+* `toDecisionMessages`.
+*/
+function toDecisionMessages(request) {
+	const messages = toOpenAiMessages(request);
+	for (const attempt of require_decision.renderDecisionAttempts(request)) messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return messages;
+}
+/**
+* Folds OpenAI's usage payload onto the flat {@link AgentCallUsage} field names
+* core aggregates. OpenAI nests the reasoning count under
+* `completion_tokens_details` and the cache-read count under
+* `prompt_tokens_details`; a field the response omitted stays omitted, so it
+* never contributes a `0` to a run's partial sums.
+*/
+function toAgentCallUsage(usage) {
+	if (!usage) return;
+	const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens;
+	const cachedInputTokens = usage.prompt_tokens_details?.cached_tokens;
+	return {
+		...usage.prompt_tokens !== void 0 ? { inputTokens: usage.prompt_tokens } : {},
+		...usage.completion_tokens !== void 0 ? { outputTokens: usage.completion_tokens } : {},
+		...usage.total_tokens !== void 0 ? { totalTokens: usage.total_tokens } : {},
+		...reasoningTokens !== void 0 ? { reasoningTokens } : {},
+		...cachedInputTokens !== void 0 ? { cachedInputTokens } : {}
+	};
+}
+/**
+* Maps an OpenAI `finish_reason` onto the portable {@link AgentFinishReason}.
+* `'function_call'` (the deprecated legacy path) joins `'tool_calls'` under
+* `'tool-calls'`; anything unrecognized, including a missing reason, lands on
+* `'other'`. OpenAI's own string stays on the result's `raw`.
+*/
+function toAgentFinishReason(finishReason) {
+	switch (finishReason) {
+		case "stop": return "stop";
+		case "length": return "length";
+		case "tool_calls":
+		case "function_call": return "tool-calls";
+		case "content_filter": return "content-filter";
+		default: return "other";
+	}
+}
+/** Resolves the host's `settings` option for one request. */
+function callSettings(options, request) {
+	const settings = options.settings;
+	if (typeof settings === "function") return settings(request) ?? {};
+	const entry = settings?.[request.model];
+	if (entry === void 0) return {};
+	if (typeof entry !== "object" || entry === null) throw new Error(`createOpenAiExecutors: \`settings\` is keyed by model ref, so every value must be an object of OpenAI parameters, but '${request.model}' is a ${typeof entry}. Pass a function if you want one set of settings for every call.`);
+	return entry;
+}
+function truncated(request, info, partialOutput, cause) {
+	return new require_decision.AgentTruncatedError(`createOpenAiExecutors: request '${request.name ?? "(unnamed)"}' hit the output token limit — its structured output never completed. Raise \`maxOutputTokens\`, shorten the input, or ask for a smaller output schema.`, {
+		requestName: request.name ?? "(unnamed)",
+		...info?.requestId !== void 0 ? { requestId: info.requestId } : {},
+		...partialOutput !== void 0 ? { partialOutput } : {},
+		...cause !== void 0 ? { cause } : {}
+	});
+}
+function usageField(usage) {
+	return usage ? { usage } : {};
+}
+/**
+* Adds two calls' usage together, field by field. A tool loop makes several
+* OpenAI calls per request, and core folds ONE `usage` per executor result into
+* the run's totals, so the steps' usages have to be summed here or the run
+* undercounts. A field neither call reported stays absent.
+*/
+function addAgentCallUsage(total, next) {
+	if (!total || !next) return total ?? next;
+	const sum = {};
+	for (const field of require_decision.AGENT_USAGE_TOKEN_FIELDS) if (total[field] !== void 0 || next[field] !== void 0) sum[field] = (total[field] ?? 0) + (next[field] ?? 0);
+	return sum;
+}
+/**
+* The function that runs one of the request's tools host-side, or `undefined`
+* when the tool has no `execute` (a client-side tool: the model's call is
+* handed back to the caller instead of being answered here).
+*/
+function toolExecutor(tools, name) {
+	const descriptor = tools[name];
+	if (!descriptor) return;
+	if (typeof descriptor === "function") return (input) => descriptor(input);
+	const execute = descriptor.execute;
+	return typeof execute === "function" ? (input) => execute(input) : void 0;
+}
+function toToolContent(output) {
+	return typeof output === "string" ? output : JSON.stringify(output ?? null);
+}
+/**
+* Builds the `{ generateText, streamText, decide }` executor set for the raw
+* `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
+* same shape, different SDK underneath.
+*
+* Structured output uses `response_format: { type: 'json_schema' }` around the
+* uniform `{ result, reasoning? }` envelope, and decisions force a tool call
+* with `tool_choice: 'required'`, one function tool per candidate event.
+*
+* @example
+* ```ts
+* const executors = createOpenAiExecutors({
+*   client: new OpenAI(),
+*   resolveModel: () => 'gpt-5.4-mini',
+* });
+* const result = await runAgent(machine, { input, executors });
+* ```
+*/
+function createOpenAiExecutors(options) {
+	const { client, resolveModel = (modelRef) => modelRef } = options;
+	const textParams = (request, messages, extra = {}) => {
+		const tools = toOpenAiTools(request.tools);
+		return {
+			model: resolveModel(request.model),
+			messages,
+			...callSettings(options, request),
+			...toOpenAiCallSettings(request),
+			...tools.length > 0 ? { tools } : {},
+			...extra
+		};
+	};
+	const envelopeSchema = async (request) => {
+		if (require_decision.getAgentOutputMode(request.outputSchema) !== "structured") return;
+		return require_decision.getJsonSchema(require_decision.buildEnvelopeSchema(request.outputSchema, { reasoning: request.includeReasoning }));
+	};
+	const generateText = async (request, info) => {
+		const jsonSchema = await envelopeSchema(request);
+		const responseFormat = jsonSchema ? { response_format: {
+			type: "json_schema",
+			json_schema: {
+				name: "output",
+				schema: jsonSchema,
+				strict: false
+			}
+		} } : {};
+		const maxSteps = typeof request.maxSteps === "number" && Number.isFinite(request.maxSteps) ? Math.max(1, Math.floor(request.maxSteps)) : 1;
+		const messages = toOpenAiMessages(request);
+		const toolChoice = toOpenAiToolChoice(request.toolChoice);
+		let response;
+		let usage;
+		let step = 0;
+		for (;;) {
+			step++;
+			response = await client.chat.completions.create(textParams(request, messages, {
+				...responseFormat,
+				...step === 1 && toolChoice !== void 0 ? { tool_choice: toolChoice } : {}
+			}), { signal: info?.signal });
+			usage = addAgentCallUsage(usage, toAgentCallUsage(response.usage));
+			const message = response.choices[0]?.message;
+			const toolCalls = message?.tool_calls ?? [];
+			if (toolCalls.length === 0 || step >= maxSteps) break;
+			const executors = toolCalls.map((call) => call.type === "function" ? toolExecutor(request.tools, call.function.name) : void 0);
+			if (executors.some((execute) => !execute)) break;
+			messages.push(message);
+			for (const [index, call] of toolCalls.entries()) {
+				const input = call.type === "function" && call.function.arguments ? JSON.parse(call.function.arguments) : {};
+				let content;
+				try {
+					content = toToolContent(await executors[index](input));
+				} catch (error) {
+					content = `Error: ${error instanceof Error ? error.message : String(error)}`;
+				}
+				messages.push({
+					role: "tool",
+					tool_call_id: call.id,
+					content
+				});
+			}
+		}
+		const unwrap = (content) => require_decision.parseStructuredEnvelope(request, content ? JSON.parse(content) : void 0);
+		const choice = response.choices[0];
+		const finishReason = toAgentFinishReason(choice?.finish_reason);
+		const content = choice?.message.content;
+		if (jsonSchema) {
+			if (finishReason === "length") throw truncated(request, info, content ?? void 0);
+			const parsed = unwrap(content);
+			return {
+				output: parsed.result,
+				...typeof parsed.reasoning === "string" ? { reasoning: parsed.reasoning } : {},
+				...usageField(usage),
+				finishReason,
+				raw: response
+			};
+		}
+		return {
+			output: content ?? "",
+			...usageField(usage),
+			finishReason,
+			raw: response
+		};
+	};
+	const streamText = async (request, info) => {
+		if (require_decision.getAgentOutputMode(request.outputSchema) === "structured") throw new Error("createOpenAiExecutors: streamText is text-only — a request declaring a structured output schema must be routed to generateText.");
+		if (Object.keys(request.tools ?? {}).length > 0) throw new Error("createOpenAiExecutors: streamText is text-only — a request declaring tools must be routed to generateText.");
+		const stream = await client.chat.completions.create({
+			model: resolveModel(request.model),
+			messages: toOpenAiMessages(request),
+			...callSettings(options, request),
+			...toOpenAiCallSettings(request),
+			stream: true,
+			stream_options: { include_usage: true }
+		}, { signal: info?.signal });
+		let text = "";
+		let finishReason = "other";
+		let usage;
+		let last;
+		for await (const chunk of stream) {
+			last = chunk;
+			const choice = chunk.choices[0];
+			const delta = choice?.delta.content;
+			if (delta) {
+				text += delta;
+				info?.onChunk?.(delta);
+			}
+			if (choice?.finish_reason) finishReason = toAgentFinishReason(choice.finish_reason);
+			if (chunk.usage) usage = chunk.usage;
+		}
+		return {
+			output: text,
+			...usageField(toAgentCallUsage(usage)),
+			finishReason,
+			raw: last
+		};
+	};
+	const decide = async (request, info) => {
+		const response = await client.chat.completions.create({
+			model: resolveModel(request.model),
+			messages: toDecisionMessages(request),
+			...callSettings(options, request),
+			...toOpenAiCallSettings(request),
+			tools: toOpenAiEventTools(request.events),
+			tool_choice: "required"
+		}, { signal: info?.signal });
+		const toolCall = response.choices[0]?.message.tool_calls?.[0];
+		if (!toolCall || toolCall.type !== "function") throw new Error("createOpenAiExecutors: decide — model did not call an event tool.");
+		const chosenEvent = request.events.find((event) => event.toolName === toolCall.function.name);
+		if (!chosenEvent) throw new Error(`createOpenAiExecutors: decide — model called unknown tool '${toolCall.function.name}'.`);
+		const args = toolCall.function.arguments ? JSON.parse(toolCall.function.arguments) : {};
+		return {
+			event: {
+				...args && typeof args === "object" ? args : {},
+				type: chosenEvent.type
+			},
+			...usageField(toAgentCallUsage(response.usage)),
+			finishReason: toAgentFinishReason(response.choices[0]?.finish_reason),
+			raw: response
+		};
+	};
+	return {
+		generateText,
+		streamText,
+		decide
+	};
+}
+//#endregion
+exports.addAgentCallUsage = addAgentCallUsage;
+exports.createOpenAiExecutors = createOpenAiExecutors;
+exports.toAgentCallUsage = toAgentCallUsage;
+exports.toAgentFinishReason = toAgentFinishReason;
+exports.toDecisionMessages = toDecisionMessages;
+exports.toOpenAiCallSettings = toOpenAiCallSettings;
+exports.toOpenAiEventTools = toOpenAiEventTools;
+exports.toOpenAiMessages = toOpenAiMessages;
+exports.toOpenAiToolChoice = toOpenAiToolChoice;
+exports.toOpenAiTools = toOpenAiTools;

package/dist/openai.d.cts

@@ -0,0 +1,177 @@
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-CjHk5OdH.cjs";
+import { F as AgentDecisionRequest, K as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-C7bSnH_B.cjs";
+import OpenAI from "openai";
+import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
+
+//#region src/openai/index.d.ts
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
+declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
+  messages?: AgentMessage[];
+}): ChatCompletionMessageParam[];
+/**
+ * Maps the generation settings a text and a decision request share onto OpenAI
+ * Chat Completions parameters, with unset keys omitted.
+ *
+ * Omitting matters: these are the top layer of a stack — the host's
+ * {@link CreateOpenAiExecutorsOptions.settings}, then the request's — and an
+ * `undefined` spread over the layer below would erase it.
+ *
+ * `max_tokens` is deprecated by OpenAI in favor of `max_completion_tokens`, so
+ * that's what `maxOutputTokens` targets. Chat Completions has no `top_k`
+ * parameter, so `topK` is dropped.
+ */
+declare function toOpenAiCallSettings(request: Pick<AgentTextRequest, "temperature" | "maxOutputTokens" | "topP" | "seed" | "stopSequences">): Partial<{
+  temperature: number | undefined;
+  max_completion_tokens: number | undefined;
+  top_p: number | undefined;
+  seed: number | undefined;
+  stop: string[] | undefined;
+}>;
+/** One OpenAI function tool per `AgentTools` entry. */
+declare function toOpenAiTools(tools: AgentTools): ChatCompletionTool[];
+/**
+ * Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
+ * `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
+ * `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
+ * `undefined` stays `undefined`, so the key is omitted.
+ */
+declare function toOpenAiToolChoice(toolChoice: AgentToolChoice | undefined): "auto" | "none" | "required" | {
+  type: "function";
+  function: {
+    name: string;
+  };
+} | undefined;
+/** One OpenAI function tool per candidate decision event — the "tool-per-event
+ * + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
+declare function toOpenAiEventTools(events: AgentEventDescriptor[]): ChatCompletionTool[];
+/**
+ * Messages for a decision request, with prior failed `attempts` rendered as an
+ * appended user message so retries converge. Mirrors the AI SDK adapter's
+ * `toDecisionMessages`.
+ */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ChatCompletionMessageParam[];
+type OpenAiUsage = NonNullable<ChatCompletion["usage"]>;
+/**
+ * Folds OpenAI's usage payload onto the flat {@link AgentCallUsage} field names
+ * core aggregates. OpenAI nests the reasoning count under
+ * `completion_tokens_details` and the cache-read count under
+ * `prompt_tokens_details`; a field the response omitted stays omitted, so it
+ * never contributes a `0` to a run's partial sums.
+ */
+declare function toAgentCallUsage(usage: OpenAiUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Maps an OpenAI `finish_reason` onto the portable {@link AgentFinishReason}.
+ * `'function_call'` (the deprecated legacy path) joins `'tool_calls'` under
+ * `'tool-calls'`; anything unrecognized, including a missing reason, lands on
+ * `'other'`. OpenAI's own string stays on the result's `raw`.
+ */
+declare function toAgentFinishReason(finishReason: ChatCompletion.Choice["finish_reason"] | null | undefined): AgentFinishReason;
+/**
+ * Per-call OpenAI Chat Completions parameters a host can apply on top of what
+ * the machine asked for — `reasoning_effort`, `service_tier`,
+ * `max_completion_tokens`, and anything else the API accepts. Typed straight
+ * off the installed `openai` package, so it tracks that version instead of
+ * restating its vocabulary.
+ *
+ * The request's own fields are excluded: `model`, `messages`, `tools`,
+ * `tool_choice`, `response_format`, `n`, and the streaming switches belong to
+ * the machine and the adapter, and a host override would silently contradict
+ * them.
+ */
+type OpenAiCallSettings = Omit<Partial<ChatCompletionCreateParamsNonStreaming>, "model" | "messages" | "tools" | "tool_choice" | "response_format" | "n" | "stream">;
+/**
+ * Options for {@link createOpenAiExecutors}.
+ *
+ * `client` is the injected `OpenAI` instance — this adapter never constructs
+ * one, so the API key, base URL, and transport stay the host's business.
+ *
+ * `resolveModel` maps a machine's model *ref* (e.g. `'ticketTriage'`) to a real
+ * OpenAI model id. A machine's requests carry refs, not ids, so a raw-SDK host
+ * must resolve them (the AI SDK adapter does this via its `models` map).
+ * Defaults to identity, for machines that already use real ids.
+ *
+ * `settings` carries provider knobs that are the HOST's business rather than
+ * the machine's, such as reasoning effort. Pass a map keyed by model ref to
+ * give a ref a persona — `deep` thinks harder than `quick` — without the
+ * machine naming a provider knob, or a function to vary settings per request
+ * (`request.name` is the request's registered key; return `undefined` for the
+ * defaults). Settings are merged UNDER what the request declared, so a machine
+ * that set `maxOutputTokens` still wins.
+ */
+type CreateOpenAiExecutorsOptions = {
+  client: OpenAI;
+  resolveModel?: (modelRef: string) => string;
+  settings?: Record<string, OpenAiCallSettings> | ((request: AgentTextRequest | AgentDecisionRequest) => OpenAiCallSettings | undefined);
+};
+/**
+ * Raw result shape from {@link OpenAiExecutors.generateText} — the `{ output }`
+ * envelope (the validated structured object for structured-output requests, or
+ * the model's text otherwise) plus the call metadata. Core only reads `output`; everything else flows
+ * verbatim to `runAgent`'s `onResult(request, { raw })`.
+ */
+type OpenAiGenerateResult = {
+  output: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `includeReasoning` and the model produced it. Never enters machine
+   * context/output. */
+  reasoning?: string;
+  /** The call's token usage, on the flat field names `runAgent` folds into the
+   * run result's aggregated `AgentUsage`. Absent when OpenAI reported none. */
+  usage?: AgentCallUsage; /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
+  finishReason: AgentFinishReason; /** The untouched OpenAI response. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.streamText} — the accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata. */
+type OpenAiStreamResult = {
+  output: string; /** Present when the stream carried a usage chunk (the adapter asks for one via `stream_options`). */
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason; /** The last chunk seen, which carries the stream's finish metadata. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event plus the call metadata, delivered per decision attempt to `onResult`. */
+type OpenAiDecideResult = {
+  event: ChosenEvent;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  raw: unknown;
+};
+/** `createOpenAiExecutors` always populates all three slots (unlike the general
+ * `AgentRequestExecutors`, where `streamText`/`decide` are optional), and its
+ * results are concretely typed. */
+interface OpenAiExecutors {
+  generateText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiGenerateResult>;
+  streamText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiStreamResult>;
+  decide: (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => Promise<OpenAiDecideResult>;
+}
+/**
+ * Adds two calls' usage together, field by field. A tool loop makes several
+ * OpenAI calls per request, and core folds ONE `usage` per executor result into
+ * the run's totals, so the steps' usages have to be summed here or the run
+ * undercounts. A field neither call reported stays absent.
+ */
+declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: AgentCallUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Builds the `{ generateText, streamText, decide }` executor set for the raw
+ * `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
+ * same shape, different SDK underneath.
+ *
+ * Structured output uses `response_format: { type: 'json_schema' }` around the
+ * uniform `{ result, reasoning? }` envelope, and decisions force a tool call
+ * with `tool_choice: 'required'`, one function tool per candidate event.
+ *
+ * @example
+ * ```ts
+ * const executors = createOpenAiExecutors({
+ *   client: new OpenAI(),
+ *   resolveModel: () => 'gpt-5.4-mini',
+ * });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createOpenAiExecutors(options: CreateOpenAiExecutorsOptions): OpenAiExecutors;
+//#endregion
+export { CreateOpenAiExecutorsOptions, OpenAiCallSettings, OpenAiDecideResult, OpenAiExecutors, OpenAiGenerateResult, OpenAiStreamResult, addAgentCallUsage, createOpenAiExecutors, toAgentCallUsage, toAgentFinishReason, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiToolChoice, toOpenAiTools };