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

package/dist/machines.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_setup_agent = require("./setup-agent-DkCTy5Eu.cjs");
+const require_setup_agent = require("./setup-agent-Dl2VELLi.cjs");
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";
@@ -22,7 +22,35 @@ function objectSchema(properties, required = []) {
 	return { "~standard": {
 		version: 1,
 		vendor: "statelyai-agent-machines",
-		validate: (value) => value !== null && typeof value === "object" ? { value } : { issues: [{ message: "Expected an object" }] },
+		validate: (value) => {
+			if (value === null || typeof value !== "object" || Array.isArray(value)) return { issues: [{ message: "Expected an object" }] };
+			const record = value;
+			const issues = [];
+			for (const key of required) if (!(key in record) || record[key] === void 0) issues.push({
+				message: `Required property '${key}' is missing`,
+				path: [key]
+			});
+			for (const [key, schema] of Object.entries(properties)) {
+				const item = record[key];
+				if (item === void 0) continue;
+				const type = schema?.type;
+				const types = Array.isArray(type) ? type : type === void 0 ? [] : [type];
+				if (!(types.length === 0 || types.some((candidate) => {
+					switch (candidate) {
+						case "array": return Array.isArray(item);
+						case "object": return item !== null && typeof item === "object" && !Array.isArray(item);
+						case "null": return item === null;
+						case "integer": return typeof item === "number" && Number.isInteger(item);
+						case "number": return typeof item === "number" && Number.isFinite(item);
+						default: return typeof item === candidate;
+					}
+				}))) issues.push({
+					message: `Expected '${key}' to be ${String(type)}`,
+					path: [key]
+				});
+			}
+			return issues.length > 0 ? { issues } : { value };
+		},
 		jsonSchema: { input: () => json }
 	} };
 }

package/dist/machines.d.cts

@@ -1,4 +1,4 @@
-import { c as AgentTools, v as StandardSchemaV1 } from "./types-DSdj2tGs.cjs";
+import { _ as StandardSchemaV1, s as AgentTools } from "./types-CjHk5OdH.cjs";
 import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
 
 //#region src/machines/internal.d.ts

package/dist/machines.d.mts

@@ -1,4 +1,4 @@
-import { c as AgentTools, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
+import { _ as StandardSchemaV1, s as AgentTools } from "./types-DWA6X9R-.mjs";
 import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
 
 //#region src/machines/internal.d.ts

package/dist/machines.mjs

@@ -1,4 +1,4 @@
-import { r as setupAgent } from "./setup-agent-nSFYrNTP.mjs";
+import { r as setupAgent } from "./setup-agent-CeO2fARv.mjs";
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";
@@ -21,7 +21,35 @@ function objectSchema(properties, required = []) {
 	return { "~standard": {
 		version: 1,
 		vendor: "statelyai-agent-machines",
-		validate: (value) => value !== null && typeof value === "object" ? { value } : { issues: [{ message: "Expected an object" }] },
+		validate: (value) => {
+			if (value === null || typeof value !== "object" || Array.isArray(value)) return { issues: [{ message: "Expected an object" }] };
+			const record = value;
+			const issues = [];
+			for (const key of required) if (!(key in record) || record[key] === void 0) issues.push({
+				message: `Required property '${key}' is missing`,
+				path: [key]
+			});
+			for (const [key, schema] of Object.entries(properties)) {
+				const item = record[key];
+				if (item === void 0) continue;
+				const type = schema?.type;
+				const types = Array.isArray(type) ? type : type === void 0 ? [] : [type];
+				if (!(types.length === 0 || types.some((candidate) => {
+					switch (candidate) {
+						case "array": return Array.isArray(item);
+						case "object": return item !== null && typeof item === "object" && !Array.isArray(item);
+						case "null": return item === null;
+						case "integer": return typeof item === "number" && Number.isInteger(item);
+						case "number": return typeof item === "number" && Number.isFinite(item);
+						default: return typeof item === candidate;
+					}
+				}))) issues.push({
+					message: `Expected '${key}' to be ${String(type)}`,
+					path: [key]
+				});
+			}
+			return issues.length > 0 ? { issues } : { value };
+		},
 		jsonSchema: { input: () => json }
 	} };
 }

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;