@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/openai-compat.mjs

@@ -0,0 +1,308 @@
+import { L as isStandardSchema, N as getJsonSchema, P as getJsonSchemaSync, d as buildEnvelopeSchema, h as getAgentOutputMode } from "./events-JiVPYrct.mjs";
+import { l as renderDecisionAttempts } from "./decision-C3k4ve51.mjs";
+//#region src/openai-compat/mappers.ts
+/** 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: (isStandardSchema(inputSchema) ? 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: 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 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));
+}
+//#endregion
+//#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.
+*/
+/**
+* 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 = getAgentOutputMode(request.outputSchema) === "structured";
+		if (structured) {
+			const jsonSchema = await getJsonSchema(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
+export { createOpenAiCompatExecutors };

package/dist/steps-BALp1eZo.d.mts

@@ -0,0 +1,198 @@
+import { m as ChosenEvent, u as AgentTools } from "./types-qm00QF91.mjs";
+import { G as AgentRequestOptions, K as AgentRequestSource, M as AgentPlanInput, U as AgentEventDescriptor, c as AgentRequestMode, j as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-CaKqgX4Y.mjs";
+import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, SnapshotFrom } from "xstate";
+
+//#region src/internal/registry.d.ts
+type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actorSources"> & {
+  models?: object;
+};
+//#endregion
+//#region src/steps.d.ts
+/**
+ * A pending text request surfaced by step discovery ({@link getAgentRequests}
+ * / {@link AgentStep.requests}): the machine has spawned a
+ * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
+ * {@link executeAgentRequest} (or by hand, then feed the output into
+ * {@link resolveAgentStep} via `xstate.done.actor.<id>`).
+ */
+interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
+  kind: "text";
+  id: string;
+  src: AgentRequestSource;
+  mode?: AgentRequestMode;
+  input: TInput;
+  tools: AgentTools;
+  events: AgentEventDescriptor[];
+}
+/**
+ * A pending **plan** request re-surfaced by step discovery: the machine
+ * invoked `agent.plan`, which applies an ordered sequence of legal events
+ * (each one a decision) rather than a single one. Unlike text/decision
+ * requests — surfaced once and resolved once — a plan request **re-surfaces on
+ * every step** while the plan is in flight, its `events`/`applied`/
+ * `stepsRemaining` updated each time, until it terminates.
+ *
+ * All fields are plain serializable data. Resolve ONE decision per step from
+ * `events` (via {@link resolveDecision}, wiring `canTake` to
+ * `snapshot.can` exactly like a single decision) then apply it: a real machine
+ * event advances the plan (the next step re-surfaces this request); the
+ * reserved `agent.plan.done` move, a `stopOn` event, an exhausted budget, or no
+ * legal events completes it (its invoke resolves with `{ steps, stopped }`).
+ * {@link resolveAgentRequests} does all of this natively — one decision (or one
+ * completion) per call.
+ *
+ * The in-progress plan state (`applied` trail + remaining budget) lives in the
+ * plan invoke child's own `createLogic` snapshot `context`
+ * (`children.<id>.snapshot.context`), so it survives a full JSON
+ * `getPersistedSnapshot` → restore round-trip: a host that persists the step
+ * after every event and reloads resumes the plan identically.
+ */
+interface AgentPlanRequest {
+  kind: "plan";
+  /** Durable invoke id of the `agent.plan` invoke. */
+  id: string;
+  /** Invoke src (`'agent.plan'` or a registered plan-logic source name). */
+  src: AgentRequestSource;
+  /** The resolved plan input (`model`/`system`/`prompt`/`allowedEvents`/`stopOn`/`maxSteps`/…). */
+  input: AgentPlanInput;
+  /**
+   * The legal candidates for the NEXT plan step: the currently
+   * snapshot-legal machine events (∩ declared `allowedEvents`) plus the
+   * reserved `agent.plan.done` move.
+   */
+  events: AgentEventDescriptor[];
+  /** The events applied so far in this plan, in order (the trail). */
+  applied: ChosenEvent[];
+  /** How many more events the plan may apply (`maxSteps - applied.length`). */
+  stepsRemaining: number;
+}
+/** `AgentStep.requests` element: a text, decision, or plan request. */
+type AgentStepRequest = AgentRequest | AgentDecisionRequest | AgentPlanRequest;
+/**
+ * One durable checkpoint on the step path: the machine's current snapshot,
+ * the executable actions that produced it, the pending
+ * {@link AgentStepRequest}s (text/decision work still to resolve), and
+ * whether the machine has reached a final state. This is the
+ * per-model-call-checkpoint path for durable hosts (Workflows, Temporal,
+ * queues, …) — a peer of `runAgent`, not a lesser version of it. Produced by
+ * {@link initialAgentStep}/{@link transitionAgentStep}/{@link resolveAgentStep}.
+ */
+interface AgentStep<TSnapshot extends AnyMachineSnapshot = AnyMachineSnapshot> {
+  snapshot: TSnapshot;
+  actions: readonly {
+    type?: string;
+    params?: unknown;
+  }[];
+  requests: AgentStepRequest[];
+  done: boolean;
+}
+/**
+ * Starts a machine and returns its first {@link AgentStep} — the step-path
+ * equivalent of `initialTransition` plus request discovery. Begins the
+ * durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+ * (via {@link executeAgentRequest} for `kind: 'text'`, or
+ * {@link resolveDecision} for `kind: 'decision'`), then advance with
+ * {@link resolveAgentStep} or {@link transitionAgentStep}.
+ */
+declare function initialAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, input?: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies an externally-sent event (e.g. a decision's chosen event, or a
+ * human's reply) and returns the next {@link AgentStep}. Accepts **either**
+ * a raw snapshot **or** a prior `AgentStep` as the second argument —
+ * `.snapshot` is unwrapped automatically, so callers can thread the whole
+ * step object through without manually plucking the snapshot out.
+ */
+declare function transitionAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, snapshotOrStep: SnapshotFrom<TMachine> | AgentStep<SnapshotFrom<TMachine>>, event: EventFromLogic<TMachine>, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies a resolved text request's output (a `kind: 'text'`
+ * {@link AgentRequest} — not a decision) as a done event and returns the
+ * next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+ * (which returns a {@link ChosenEvent}) and apply it with
+ * {@link transitionAgentStep} instead — a decision has no output value of
+ * its own to feed here.
+ */
+declare function resolveAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, request: Pick<AgentRequest, "id"> | string, output: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Snapshot in, requests out: scans executable actions for spawned agent
+ * invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+ * the machine's registered `setupAgent` schemas/actorSources (so callers
+ * don't pass them by hand each call) — merged with any `options` passed here,
+ * which take precedence. The step path's public discovery primitive;
+ * `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+ * internally to populate `AgentStep.requests`.
+ */
+declare function getAgentRequests(machine: AnyActorLogic, actions: readonly {
+  type?: string;
+  params?: unknown;
+}[], snapshot?: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "eventToolName"> & Partial<AgentExecutionOptions>): AgentStepRequest[];
+/**
+ * Resolves one **text** {@link AgentRequest} against a host's
+ * {@link AgentRequestExecutors} — merges the request's tools, dispatches to
+ * `generateText`/`streamText` per `request.mode`, and validates the result
+ * against `request.input.outputSchema` if present. **Text-only**: passing a
+ * `kind: 'decision'` request throws, directing the caller to
+ * `resolveDecision(request, executors.decide, ...)` instead. By default
+ * returns the normalized output; pass `{ verbose: true }` to also get the
+ * raw executor result (tool calls, usage, finish reason — needed for
+ * observability and event-sourced replay).
+ */
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+/**
+ * Options for {@link resolveAgentRequests}.
+ */
+interface ResolveAgentRequestsOptions extends Partial<AgentExecutionOptions> {
+  /** Retries per decision, passed to `resolveDecision`. Default `2`. */
+  maxRetries?: number;
+}
+/**
+ * Resolves the current step's pending requests and returns the next
+ * {@link AgentStep} — one iteration of the durable step loop, collapsing the
+ * manual `request.kind` dispatch a host would otherwise write by hand.
+ *
+ * For each pending request, in order: a `kind: 'text'` request is run with
+ * {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+ * `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+ * `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+ * applied with {@link transitionAgentStep}. The **current** step is re-read
+ * after each application — the machine may advance and its `requests` change —
+ * so this always resolves against the live step, never a stale list.
+ *
+ * A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+ * step per call. It resolves a single decision from `request.events` (wiring
+ * `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+ * move and `stopOn` events), then either applies the chosen machine event and
+ * lets the next step re-surface the plan, or completes the plan (feeding its
+ * `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+ * exhausted budget / no legal events. The plan's applied trail is carried in
+ * the invoke child's snapshot, so persisting the step between calls resumes the
+ * plan identically.
+ *
+ * Missing the executor a request needs throws a clear error
+ * (`generateText`/`streamText` for text, `decide` for decisions and plans).
+ *
+ * A complete durable host is two lines:
+ *
+ * ```ts
+ * let step = initialAgentStep(machine, input);
+ * while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+ * ```
+ *
+ * All pending **text** requests of a step are resolved in parallel
+ * (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+ * their model calls run concurrently — then their outputs apply in
+ * **request-array order** (deterministic for durable replay regardless of which
+ * call finishes first). Decisions and plans stay **one at a time**: applying
+ * either changes the set of legal candidates for what follows, so they cannot be
+ * resolved against a stale snapshot. A host that instead wants strictly
+ * sequential text resolution loops the manual per-request helpers
+ * ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+ */
+declare function resolveAgentRequests<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, executors: Partial<AgentRequestExecutors>, options?: ResolveAgentRequestsOptions): Promise<AgentStep<SnapshotFrom<TMachine>>>;
+//#endregion
+export { ResolveAgentRequestsOptions as a, initialAgentStep as c, transitionAgentStep as d, AgentStepRequest as i, resolveAgentRequests as l, AgentRequest as n, executeAgentRequest as o, AgentStep as r, getAgentRequests as s, AgentPlanRequest as t, resolveAgentStep as u };