@statelyai/agent 1.1.6 → 2.0.0-alpha.6

package/dist/openai-compat.cjs

@@ -0,0 +1,319 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_decision = require("./decision-CX3YdwrO.cjs");
+//#region src/openai-compat/index.ts
+/**
+* OpenAI-compatible Chat Completions adapter — a COMPLETE `{ generateText,
+* streamText, decide }` executor set built on raw `fetch`, with zero runtime
+* dependencies (no `openai` package, no Vercel AI SDK).
+*
+* The OpenAI Chat Completions wire format is the lingua franca of hosted and
+* local inference: Groq, Together, Fireworks, OpenRouter, vLLM, Ollama, LM
+* Studio, and OpenAI itself all speak it. Point `baseUrl` at any of them.
+*
+* Compare `createAiSdkExecutors` in `../ai-sdk/index.ts` (the AI-SDK-backed
+* adapter) — same three-function contract, different transport. The request
+* mapping is ported from `examples/openai-sdk-host/index.ts`, but wired
+* against `POST {baseUrl}/chat/completions` instead of the `openai` package.
+*/
+/**
+* Reads a Standard Schema's optional `~standard.jsonSchema.input()` extension
+* (implemented by e.g. Zod v4's `z.toJSONSchema`), awaiting it when it returns
+* a Promise. Returns `undefined` when the schema doesn't expose the extension.
+* Thin re-export of core's {@link getJsonSchema}.
+*/
+const extractJsonSchema = require_decision.getJsonSchema;
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to Chat Completions messages. */
+function toOpenAiMessages(request) {
+	if (request.messages) return request.messages.flatMap((message) => {
+		const content = typeof message.content === "string" ? message.content : "";
+		switch (message.role) {
+			case "system": return [{
+				role: "system",
+				content
+			}];
+			case "user": return [{
+				role: "user",
+				content
+			}];
+			case "assistant": return [{
+				role: "assistant",
+				content
+			}];
+			case "tool": return message.content.map((part) => ({
+				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
+			}));
+		}
+	});
+	const messages = [];
+	if (request.system) messages.push({
+		role: "system",
+		content: request.system
+	});
+	messages.push({
+		role: "user",
+		content: request.prompt ?? ""
+	});
+	return messages;
+}
+/**
+* Maps sampling/stop settings. Targets `max_tokens` (not
+* `max_completion_tokens`) — it's the field every OpenAI-compatible backend
+* accepts (Ollama, vLLM, Groq, …), where `max_completion_tokens` is
+* OpenAI-only. Undefined fields are pruned so they never hit the wire.
+*/
+function toOpenAiCallSettings(request) {
+	return pruneUndefined({
+		temperature: request.temperature,
+		max_tokens: request.maxOutputTokens,
+		top_p: request.topP,
+		seed: request.seed,
+		stop: request.stopSequences
+	});
+}
+/** One wire 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: typeof descriptor === "function" ? void 0 : descriptor.description,
+				parameters: (require_decision.isStandardSchema(inputSchema) ? require_decision.getJsonSchemaSync(inputSchema) : void 0) ?? {}
+			}
+		}];
+	});
+}
+/** One wire function tool per candidate decision event — the
+* "tool-per-event + tool_choice: 'required'" recipe. */
+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
+* appended user messages (via core's {@link renderDecisionAttempts}) so
+* retries converge. */
+function toDecisionMessages(request) {
+	const messages = toOpenAiMessages(request);
+	for (const attempt of require_decision.renderDecisionAttempts(request)) messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return messages;
+}
+function pruneUndefined(record) {
+	return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+}
+/**
+* Builds a complete `{ generateText, streamText, decide }` executor set over
+* the OpenAI Chat Completions wire format via raw `fetch`.
+*
+* @example
+* ```ts
+* const executors = createOpenAiCompatExecutors({
+*   baseUrl: 'https://api.groq.com/openai/v1',
+*   apiKey: process.env.GROQ_API_KEY,
+*   models: { quick: 'llama-3.3-70b-versatile' },
+* });
+* const result = await runAgent(machine, { input, executors });
+* ```
+*/
+function createOpenAiCompatExecutors(options) {
+	const doFetch = options.fetch ?? globalThis.fetch;
+	if (!doFetch) throw new Error("createOpenAiCompatExecutors: no `fetch` available — pass options.fetch for this runtime.");
+	const url = `${options.baseUrl.replace(/\/+$/, "")}/chat/completions`;
+	function resolveModel(modelRef) {
+		const resolved = options.models?.[modelRef] ?? modelRef ?? options.model;
+		if (!resolved) throw new Error("createOpenAiCompatExecutors: no model to send — set request.model, options.model, or options.models.");
+		return resolved;
+	}
+	function buildHeaders() {
+		return {
+			"content-type": "application/json",
+			...options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {},
+			...options.headers
+		};
+	}
+	async function post(body, signal) {
+		const response = await doFetch(url, {
+			method: "POST",
+			headers: buildHeaders(),
+			body: JSON.stringify(body),
+			signal
+		});
+		if (!response.ok) {
+			const snippet = await response.text().catch(() => "");
+			throw new Error(`createOpenAiCompatExecutors: ${url} responded ${response.status} ${response.statusText}: ` + snippet.slice(0, 500));
+		}
+		return response;
+	}
+	const generateText = async (request, info) => {
+		const tools = toOpenAiTools(request.tools);
+		const body = {
+			model: resolveModel(request.model),
+			messages: toOpenAiMessages(request),
+			...toOpenAiCallSettings(request),
+			...tools.length > 0 ? { tools } : {},
+			...request.toolChoice ? { tool_choice: toWireToolChoice(request.toolChoice) } : {}
+		};
+		const structured = require_decision.getAgentOutputMode(request.outputSchema) === "structured";
+		if (structured) {
+			const jsonSchema = await require_decision.getJsonSchema(require_decision.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }));
+			body.response_format = jsonSchema ? {
+				type: "json_schema",
+				json_schema: {
+					name: "output",
+					schema: jsonSchema,
+					strict: false
+				}
+			} : { type: "json_object" };
+		}
+		const json = await (await post(body, info?.signal)).json();
+		const choice = json.choices?.[0];
+		const content = choice?.message?.content ?? "";
+		if (structured) {
+			let parsed;
+			try {
+				parsed = content ? JSON.parse(content) : void 0;
+			} catch (error) {
+				throw new Error(`createOpenAiCompatExecutors: generateText${nameSuffix(request)} — structured request returned non-JSON content: ${errorMessage(error)}`);
+			}
+			let output = parsed;
+			let reasoning;
+			if (parsed && typeof parsed === "object" && "result" in parsed) {
+				output = parsed.result;
+				const rawReasoning = parsed.reasoning;
+				if (typeof rawReasoning === "string") reasoning = rawReasoning;
+			}
+			return {
+				output,
+				...reasoning !== void 0 ? { reasoning } : {},
+				usage: json.usage,
+				finishReason: choice?.finish_reason ?? void 0
+			};
+		}
+		return {
+			output: content,
+			usage: json.usage,
+			finishReason: choice?.finish_reason ?? void 0
+		};
+	};
+	const streamText = async (request, info) => {
+		const response = await post({
+			model: resolveModel(request.model),
+			messages: toOpenAiMessages(request),
+			...toOpenAiCallSettings(request),
+			stream: true
+		}, info?.signal);
+		let text = "";
+		for await (const data of iterateSse(response, request)) {
+			let chunk;
+			try {
+				chunk = JSON.parse(data);
+			} catch (error) {
+				throw new Error(`createOpenAiCompatExecutors: streamText${nameSuffix(request)} — malformed SSE JSON chunk: ${errorMessage(error)}`);
+			}
+			const delta = chunk.choices?.[0]?.delta?.content;
+			if (delta) {
+				text += delta;
+				info?.onChunk?.(delta);
+			}
+		}
+		return { output: text };
+	};
+	const decide = async (request) => {
+		const tools = toOpenAiEventTools(request.events);
+		const json = await (await post({
+			model: resolveModel(request.model),
+			messages: toDecisionMessages(request),
+			tools,
+			tool_choice: "required",
+			...pruneUndefined({
+				temperature: request.temperature,
+				max_tokens: request.maxOutputTokens,
+				top_p: request.topP,
+				seed: request.seed,
+				stop: request.stopSequences
+			})
+		}, request.signal)).json();
+		const choice = json.choices?.[0];
+		const toolCall = choice?.message?.tool_calls?.[0];
+		if (!toolCall || toolCall.type && toolCall.type !== "function" || !toolCall.function?.name) throw new Error("createOpenAiCompatExecutors: decide — model did not call an event tool.");
+		const chosenEvent = request.events.find((event) => event.toolName === toolCall.function.name);
+		if (!chosenEvent) throw new Error(`createOpenAiCompatExecutors: decide — model called unknown tool '${toolCall.function.name}'.`);
+		let args = {};
+		if (toolCall.function.arguments) try {
+			args = JSON.parse(toolCall.function.arguments);
+		} catch (error) {
+			throw new Error(`createOpenAiCompatExecutors: decide — could not parse tool arguments for '${chosenEvent.type}': ${errorMessage(error)}`);
+		}
+		return {
+			event: {
+				...args && typeof args === "object" ? args : {},
+				type: chosenEvent.type
+			},
+			usage: json.usage,
+			finishReason: choice?.finish_reason ?? void 0
+		};
+	};
+	return {
+		generateText,
+		streamText,
+		decide
+	};
+}
+/** Maps an `AgentToolChoice` to the wire `tool_choice` shape. */
+function toWireToolChoice(toolChoice) {
+	return typeof toolChoice === "object" ? {
+		type: "function",
+		function: { name: toolChoice.name }
+	} : toolChoice;
+}
+async function* iterateSse(response, request) {
+	const body = response.body;
+	if (!body) throw new Error(`createOpenAiCompatExecutors: streamText${nameSuffix(request)} — response has no body to read SSE from.`);
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const flushLine = function* (line) {
+		const trimmed = line.trim();
+		if (!trimmed || !trimmed.startsWith("data:")) return;
+		const data = trimmed.slice(5).trim();
+		if (data && data !== "[DONE]") yield data;
+	};
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let newlineIndex;
+		while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+			const line = buffer.slice(0, newlineIndex);
+			buffer = buffer.slice(newlineIndex + 1);
+			yield* flushLine(line);
+		}
+	}
+	yield* flushLine(buffer);
+}
+function nameSuffix(request) {
+	return request.name ? ` '${request.name}'` : "";
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+exports.createOpenAiCompatExecutors = createOpenAiCompatExecutors;
+exports.extractJsonSchema = extractJsonSchema;
+exports.toDecisionMessages = toDecisionMessages;
+exports.toOpenAiCallSettings = toOpenAiCallSettings;
+exports.toOpenAiEventTools = toOpenAiEventTools;
+exports.toOpenAiMessages = toOpenAiMessages;
+exports.toOpenAiTools = toOpenAiTools;

package/dist/openai-compat.d.cts

@@ -0,0 +1,98 @@
+import { c as AgentTools } from "./types-BHjeDdch.cjs";
+import { B as AgentEventDescriptor, D as AgentDecisionExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-1ZQkO3zr.cjs";
+import { r as getJsonSchema } from "./utils-lK1wnL2i.cjs";
+
+//#region src/openai-compat/index.d.ts
+interface WireMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_call_id?: string;
+}
+interface WireTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}
+/**
+ * Reads a Standard Schema's optional `~standard.jsonSchema.input()` extension
+ * (implemented by e.g. Zod v4's `z.toJSONSchema`), awaiting it when it returns
+ * a Promise. Returns `undefined` when the schema doesn't expose the extension.
+ * Thin re-export of core's {@link getJsonSchema}.
+ */
+declare const extractJsonSchema: typeof getJsonSchema;
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to Chat Completions messages. */
+declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt" | "messages">): WireMessage[];
+/**
+ * Maps sampling/stop settings. Targets `max_tokens` (not
+ * `max_completion_tokens`) — it's the field every OpenAI-compatible backend
+ * accepts (Ollama, vLLM, Groq, …), where `max_completion_tokens` is
+ * OpenAI-only. Undefined fields are pruned so they never hit the wire.
+ */
+declare function toOpenAiCallSettings(request: AgentTextRequest): Record<string, unknown>;
+/** One wire function tool per `AgentTools` entry. */
+declare function toOpenAiTools(tools: AgentTools): WireTool[];
+/** One wire function tool per candidate decision event — the
+ * "tool-per-event + tool_choice: 'required'" recipe. */
+declare function toOpenAiEventTools(events: AgentEventDescriptor[]): WireTool[];
+/** Messages for a decision request, with prior failed `attempts` rendered as
+ * appended user messages (via core's {@link renderDecisionAttempts}) so
+ * retries converge. */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): WireMessage[];
+/** Minimal `fetch` shape the adapter needs — matches the global `fetch` and
+ * Cloudflare Workers' `fetch`, so a custom transport is drop-in. */
+type FetchLike = (input: string, init: {
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+  body: ReadableStream<Uint8Array> | null;
+}>;
+/** Options for {@link createOpenAiCompatExecutors}. */
+interface CreateOpenAiCompatExecutorsOptions {
+  /** Base URL of the Chat Completions API, e.g. `"https://api.groq.com/openai/v1"`
+   * or `"http://localhost:11434/v1"`. `/chat/completions` is appended. */
+  baseUrl: string;
+  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Omit for keyless
+   * local servers (Ollama, LM Studio). */
+  apiKey?: string;
+  /** Extra headers merged onto every request (e.g. `HTTP-Referer` for OpenRouter). */
+  headers?: Record<string, string>;
+  /** `fetch` override for Workers/tests. Defaults to the global `fetch`. */
+  fetch?: FetchLike;
+  /** Default wire model id, used when a request's model ref is empty. */
+  model?: string;
+  /** Model ref → wire model id map. A `request.model` present here resolves
+   * to its mapped id; otherwise it passes through as the wire id. */
+  models?: Record<string, string>;
+}
+/** `createOpenAiCompatExecutors` always populates all three executor slots. */
+interface OpenAiCompatExecutors extends AgentRequestExecutors {
+  streamText: NonNullable<AgentRequestExecutors["streamText"]>;
+  decide: AgentDecisionExecutor;
+}
+/**
+ * Builds a complete `{ generateText, streamText, decide }` executor set over
+ * the OpenAI Chat Completions wire format via raw `fetch`.
+ *
+ * @example
+ * ```ts
+ * const executors = createOpenAiCompatExecutors({
+ *   baseUrl: 'https://api.groq.com/openai/v1',
+ *   apiKey: process.env.GROQ_API_KEY,
+ *   models: { quick: 'llama-3.3-70b-versatile' },
+ * });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createOpenAiCompatExecutors(options: CreateOpenAiCompatExecutorsOptions): OpenAiCompatExecutors;
+//#endregion
+export { CreateOpenAiCompatExecutorsOptions, FetchLike, OpenAiCompatExecutors, createOpenAiCompatExecutors, extractJsonSchema, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiTools };

package/dist/openai-compat.d.mts

@@ -0,0 +1,98 @@
+import { c as AgentTools } from "./types-Cq1YlAQ6.mjs";
+import { B as AgentEventDescriptor, D as AgentDecisionExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2EMJIS-n.mjs";
+import { r as getJsonSchema } from "./utils-CWUCa3pF.mjs";
+
+//#region src/openai-compat/index.d.ts
+interface WireMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  tool_call_id?: string;
+}
+interface WireTool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}
+/**
+ * Reads a Standard Schema's optional `~standard.jsonSchema.input()` extension
+ * (implemented by e.g. Zod v4's `z.toJSONSchema`), awaiting it when it returns
+ * a Promise. Returns `undefined` when the schema doesn't expose the extension.
+ * Thin re-export of core's {@link getJsonSchema}.
+ */
+declare const extractJsonSchema: typeof getJsonSchema;
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to Chat Completions messages. */
+declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt" | "messages">): WireMessage[];
+/**
+ * Maps sampling/stop settings. Targets `max_tokens` (not
+ * `max_completion_tokens`) — it's the field every OpenAI-compatible backend
+ * accepts (Ollama, vLLM, Groq, …), where `max_completion_tokens` is
+ * OpenAI-only. Undefined fields are pruned so they never hit the wire.
+ */
+declare function toOpenAiCallSettings(request: AgentTextRequest): Record<string, unknown>;
+/** One wire function tool per `AgentTools` entry. */
+declare function toOpenAiTools(tools: AgentTools): WireTool[];
+/** One wire function tool per candidate decision event — the
+ * "tool-per-event + tool_choice: 'required'" recipe. */
+declare function toOpenAiEventTools(events: AgentEventDescriptor[]): WireTool[];
+/** Messages for a decision request, with prior failed `attempts` rendered as
+ * appended user messages (via core's {@link renderDecisionAttempts}) so
+ * retries converge. */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): WireMessage[];
+/** Minimal `fetch` shape the adapter needs — matches the global `fetch` and
+ * Cloudflare Workers' `fetch`, so a custom transport is drop-in. */
+type FetchLike = (input: string, init: {
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+  signal?: AbortSignal;
+}) => Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+  body: ReadableStream<Uint8Array> | null;
+}>;
+/** Options for {@link createOpenAiCompatExecutors}. */
+interface CreateOpenAiCompatExecutorsOptions {
+  /** Base URL of the Chat Completions API, e.g. `"https://api.groq.com/openai/v1"`
+   * or `"http://localhost:11434/v1"`. `/chat/completions` is appended. */
+  baseUrl: string;
+  /** Bearer token sent as `Authorization: Bearer <apiKey>`. Omit for keyless
+   * local servers (Ollama, LM Studio). */
+  apiKey?: string;
+  /** Extra headers merged onto every request (e.g. `HTTP-Referer` for OpenRouter). */
+  headers?: Record<string, string>;
+  /** `fetch` override for Workers/tests. Defaults to the global `fetch`. */
+  fetch?: FetchLike;
+  /** Default wire model id, used when a request's model ref is empty. */
+  model?: string;
+  /** Model ref → wire model id map. A `request.model` present here resolves
+   * to its mapped id; otherwise it passes through as the wire id. */
+  models?: Record<string, string>;
+}
+/** `createOpenAiCompatExecutors` always populates all three executor slots. */
+interface OpenAiCompatExecutors extends AgentRequestExecutors {
+  streamText: NonNullable<AgentRequestExecutors["streamText"]>;
+  decide: AgentDecisionExecutor;
+}
+/**
+ * Builds a complete `{ generateText, streamText, decide }` executor set over
+ * the OpenAI Chat Completions wire format via raw `fetch`.
+ *
+ * @example
+ * ```ts
+ * const executors = createOpenAiCompatExecutors({
+ *   baseUrl: 'https://api.groq.com/openai/v1',
+ *   apiKey: process.env.GROQ_API_KEY,
+ *   models: { quick: 'llama-3.3-70b-versatile' },
+ * });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createOpenAiCompatExecutors(options: CreateOpenAiCompatExecutorsOptions): OpenAiCompatExecutors;
+//#endregion
+export { CreateOpenAiCompatExecutorsOptions, FetchLike, OpenAiCompatExecutors, createOpenAiCompatExecutors, extractJsonSchema, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiTools };