@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.24

package/dist/openai.mjs

@@ -0,0 +1,437 @@
+import { S as getAgentOutputMode, U as getJsonSchema, W as getJsonSchemaSync, Y as isStandardSchema, f as AGENT_USAGE_TOKEN_FIELDS, k as parseStructuredEnvelope, o as renderDecisionAttempts, st as AgentTruncatedError, v as buildEnvelopeSchema } from "./decision-BBZ2jMO1.mjs";
+//#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: (isStandardSchema(inputSchema) ? 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: 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 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 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 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 (getAgentOutputMode(request.outputSchema) !== "structured") return;
+		return getJsonSchema(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) => 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 (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
+export { addAgentCallUsage, createOpenAiExecutors, toAgentCallUsage, toAgentFinishReason, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiToolChoice, toOpenAiTools };

package/dist/otel.cjs

@@ -210,15 +210,12 @@ function createOtelTraceHandler(options) {
 					});
 				});
 				break;
-			case "machine.transition": {
-				const attributes = {
+			case "machine.transition":
+				addRunEvent(event, "agent.transition", {
 					"agent.event_type": event.event.type,
 					"agent.state": toJson(event.snapshot.value) ?? ""
-				};
-				if (event.eventId !== void 0) attributes["agent.event_id"] = event.eventId;
-				addRunEvent(event, "agent.transition", attributes);
+				});
 				break;
-			}
 			case "emit":
 				addRunEvent(event, "agent.emit", { "agent.event_type": event.event.type });
 				break;

package/dist/otel.d.cts

@@ -1,4 +1,4 @@
-import { d as AgentTraceEvent } from "./run-agent-Zbkx7XP8.cjs";
+import { o as AgentTraceEvent } from "./run-agent-DWqA8KiI.cjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts

package/dist/otel.d.mts

@@ -1,4 +1,4 @@
-import { d as AgentTraceEvent } from "./run-agent-0fpEZ1wJ.mjs";
+import { o as AgentTraceEvent } from "./run-agent-Ck7Sa3Tb.mjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts

package/dist/otel.mjs

@@ -208,15 +208,12 @@ function createOtelTraceHandler(options) {
 					});
 				});
 				break;
-			case "machine.transition": {
-				const attributes = {
+			case "machine.transition":
+				addRunEvent(event, "agent.transition", {
 					"agent.event_type": event.event.type,
 					"agent.state": toJson(event.snapshot.value) ?? ""
-				};
-				if (event.eventId !== void 0) attributes["agent.event_id"] = event.eventId;
-				addRunEvent(event, "agent.transition", attributes);
+				});
 				break;
-			}
 			case "emit":
 				addRunEvent(event, "agent.emit", { "agent.event_type": event.event.type });
 				break;