@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/ai-sdk.mjs

@@ -0,0 +1,304 @@
+import { L as isStandardSchema, d as buildEnvelopeSchema, h as getAgentOutputMode } from "./events-JiVPYrct.mjs";
+import { l as renderDecisionAttempts } from "./decision-C3k4ve51.mjs";
+import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
+//#region src/ai-sdk/mappers.ts
+/**
+* Maps an {@link AgentTools} map onto AI SDK `tool()` definitions. A tool that
+* already carries its own Standard Schema `inputSchema` — an AI SDK
+* `tool({...})`, or any equivalent descriptor — is passed through **unchanged**,
+* so the SDK applies its own validation, calls `execute(input, options)`, and
+* every extra property (`providerOptions`, `toModelOutput`, …) survives. A bare
+* `AgentToolExecute` function becomes a tool with an unconstrained input schema;
+* a minimal descriptor with no readable schema is converted with a permissive
+* fallback. Used by {@link toAiSdkCallSettings}.
+*/
+function toAiSdkTools(tools) {
+	const entries = [];
+	for (const [name, descriptor] of Object.entries(tools)) {
+		if (!descriptor) continue;
+		if (typeof descriptor === "function") {
+			entries.push([name, tool({
+				inputSchema: unknownSchema,
+				execute: (input) => descriptor(input)
+			})]);
+			continue;
+		}
+		if (isStandardSchema(descriptor.inputSchema)) {
+			entries.push([name, descriptor]);
+			continue;
+		}
+		const inputSchema = descriptor.inputSchema ?? descriptor.schemas?.input;
+		const toolOptions = {
+			description: descriptor.description,
+			inputSchema: inputSchema ? inputSchema : unknownSchema
+		};
+		if (descriptor.execute) {
+			entries.push([name, tool({
+				...toolOptions,
+				execute: (input) => descriptor.execute?.(input)
+			})]);
+			continue;
+		}
+		entries.push([name, tool(toolOptions)]);
+	}
+	return Object.fromEntries(entries);
+}
+const unknownSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate: (value) => ({ value }),
+	jsonSchema: { input: () => ({}) }
+} };
+/**
+* AI SDK request-mapping settings shared by `generateText`/`streamText`.
+* `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
+* are structurally compatible by design (§1 of .scratch/p0-design.md) — the cast
+* below is a typed identity mapping, not a semantic conversion.
+*/
+function toAiSdkCallSettings(request) {
+	const messages = request.messages;
+	return {
+		system: request.system,
+		...messages ? { messages } : { prompt: request.prompt ?? "" },
+		temperature: request.temperature,
+		maxOutputTokens: request.maxOutputTokens,
+		topP: request.topP,
+		topK: request.topK,
+		seed: request.seed,
+		stopSequences: request.stopSequences,
+		tools: request.tools ? toAiSdkTools(request.tools) : void 0,
+		toolChoice: toAiSdkToolChoice(request.toolChoice)
+	};
+}
+/** Maps an {@link AgentToolChoice} to AI SDK's tool-choice shape — `{ type: 'tool'; name }` becomes `{ type: 'tool'; toolName }`; `'auto'`/`'none'`/`'required'`/`undefined` pass through unchanged. */
+function toAiSdkToolChoice(toolChoice) {
+	return typeof toolChoice === "object" ? {
+		type: "tool",
+		toolName: toolChoice.name
+	} : toolChoice;
+}
+/** `true` when the request should use AI SDK structured `Output.object`. */
+function isStructuredOutputRequest(request) {
+	return getAgentOutputMode(request.outputSchema) === "structured";
+}
+/**
+* Extracts the first complete top-level JSON value from `text`, or returns
+* `undefined` when there is nothing to repair (no complete value, or the value
+* already spans the whole text). Models occasionally emit two structured-output
+* envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+* parsing wholesale; the balanced scan below recovers the first value and
+* drops the rest.
+*/
+function extractFirstJsonValue(text) {
+	const start = text.search(/[{[]/);
+	if (start === -1) return;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") inString = true;
+		else if (char === "{" || char === "[") depth++;
+		else if (char === "}" || char === "]") {
+			depth--;
+			if (depth === 0) {
+				const value = text.slice(start, i + 1);
+				return value === text.trim() ? void 0 : value;
+			}
+		}
+	}
+}
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+* toolChoice: 'required'" recipe from .scratch/p0-design.md §2.6. */
+function toAiSdkEventTools(events) {
+	return Object.fromEntries(events.map((event) => [event.toolName, tool({
+		description: `Choose the '${event.type}' move.`,
+		inputSchema: event.inputSchema ? event.inputSchema : unknownSchema
+	})]));
+}
+/**
+* Messages for a decision request, with prior failed `attempts` (§2.6)
+* rendered as appended user messages (via core's {@link renderDecisionAttempts})
+* so retries converge. Core never rewrites prompts — this is adapter business.
+*/
+function toDecisionMessages(request) {
+	if (!request.messages && request.attempts.length === 0) return;
+	const messages = [...request.messages ?? (request.prompt !== void 0 ? [{
+		role: "user",
+		content: request.prompt
+	}] : [])];
+	for (const attempt of renderDecisionAttempts(request)) messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return messages;
+}
+//#endregion
+//#region src/ai-sdk/index.ts
+function maxStepsSetting(request) {
+	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: stepCountIs(request.metadata.maxSteps) } : {};
+}
+/**
+* Identity helper for a `models` map whose value is exported. Returns the map
+* unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
+* portable, nameable type — so an exported `const models = defineModels({...})`
+* needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
+* TS2742 ("inferred type cannot be named without a reference to …"). The exact
+* ref keys survive, so `createAiSdkExecutors({ models })` and
+* `setupAgent({ models })` still infer/autocomplete them.
+*
+* @example
+* ```ts
+* export const models = defineModels({
+*   quick: openai('gpt-5.4-mini'),
+*   deep: openai('gpt-5.4'),
+* });
+* // typeof models === AiSdkModelMap<'quick' | 'deep'>
+* ```
+*/
+function defineModels(models) {
+	return models;
+}
+function resolveAiSdkModel(options, modelRef) {
+	if (options.resolveModel) return options.resolveModel(modelRef);
+	const models = options.models;
+	if (!models) throw new Error(`createAiSdkExecutors: no model resolver configured for '${modelRef}'.`);
+	const model = models[modelRef];
+	if (!model) throw new Error(`createAiSdkExecutors: unknown model '${modelRef}'.`);
+	return model;
+}
+function withJsonRepair(output) {
+	return {
+		...output,
+		parseCompleteOutput: async (options, context) => {
+			try {
+				return await output.parseCompleteOutput(options, context);
+			} catch (error) {
+				const repaired = extractFirstJsonValue(options.text);
+				if (repaired === void 0) throw error;
+				return await output.parseCompleteOutput({
+					...options,
+					text: repaired
+				}, context);
+			}
+		}
+	};
+}
+/**
+* The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
+* decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
+* must not become a dependency of core `src/` files — this subpath is the one
+* place it's imported, and callers must supply their own model resolver so no
+* concrete provider package (e.g. `@ai-sdk/openai`) becomes a dependency here
+* either.
+*
+* @example
+* ```ts
+* const executors = createAiSdkExecutors({ models: { quick: openai('gpt-5.4-mini') } });
+* const result = await runAgent(machine, { input, executors });
+* ```
+*/
+function createAiSdkExecutors(options) {
+	const generateText$1 = async (request, info) => {
+		const common = {
+			model: resolveAiSdkModel(options, request.model),
+			abortSignal: info?.signal,
+			...toAiSdkCallSettings(request),
+			...maxStepsSetting(request)
+		};
+		if (isStructuredOutputRequest(request)) {
+			const envelope = buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
+			const structuredOutput = withJsonRepair(Output.object({ schema: envelope }));
+			const canRetry = !request.tools || Object.keys(request.tools).length === 0;
+			let result;
+			try {
+				result = await generateText({
+					...common,
+					output: structuredOutput
+				});
+			} catch (error) {
+				if (!canRetry || !NoObjectGeneratedError.isInstance(error) || info?.signal?.aborted) throw error;
+				result = await generateText({
+					...common,
+					output: structuredOutput
+				});
+			}
+			const { result: output, reasoning } = result.output;
+			return {
+				output,
+				...reasoning !== void 0 ? { reasoning } : {},
+				usage: result.usage,
+				finishReason: result.finishReason,
+				toolCalls: result.toolCalls,
+				toolResults: result.toolResults
+			};
+		}
+		const result = await generateText(common);
+		return {
+			output: result.text,
+			usage: result.usage,
+			finishReason: result.finishReason,
+			toolCalls: result.toolCalls,
+			toolResults: result.toolResults
+		};
+	};
+	const streamText$1 = async (request, info) => {
+		const result = streamText({
+			model: resolveAiSdkModel(options, request.model),
+			abortSignal: info?.signal,
+			...toAiSdkCallSettings(request),
+			...maxStepsSetting(request)
+		});
+		for await (const chunk of result.textStream) info?.onChunk?.(chunk);
+		return {
+			output: await result.text,
+			usage: await result.usage,
+			finishReason: await result.finishReason
+		};
+	};
+	const decide = async (request) => {
+		const model = resolveAiSdkModel(options, request.model);
+		const tools = toAiSdkEventTools(request.events);
+		const messages = toDecisionMessages(request);
+		const result = await generateText({
+			model,
+			abortSignal: request.signal,
+			system: request.system,
+			...messages ? { messages } : { prompt: request.prompt ?? "" },
+			tools,
+			toolChoice: "required",
+			stopWhen: stepCountIs(1),
+			temperature: request.temperature,
+			maxOutputTokens: request.maxOutputTokens,
+			topP: request.topP,
+			topK: request.topK,
+			seed: request.seed,
+			stopSequences: request.stopSequences
+		});
+		const toolCall = result.toolCalls[0];
+		if (!toolCall) throw new Error("createAiSdkExecutors: decide — model did not call an event tool.");
+		const chosenEvent = request.events.find((event) => event.toolName === toolCall.toolName);
+		if (!chosenEvent) throw new Error(`createAiSdkExecutors: decide — model called unknown tool '${toolCall.toolName}'.`);
+		return {
+			event: {
+				...toolCall.input && typeof toolCall.input === "object" ? toolCall.input : {},
+				type: chosenEvent.type
+			},
+			usage: result.usage,
+			finishReason: result.finishReason
+		};
+	};
+	return {
+		generateText: generateText$1,
+		streamText: streamText$1,
+		decide
+	};
+}
+//#endregion
+export { createAiSdkExecutors, defineModels };

package/dist/decision-C3k4ve51.mjs

@@ -0,0 +1,227 @@
+import { H as validateSchemaSync, V as userMessage, a as sanitizeEventToolName, n as isEventPattern, o as DECIDE_ACTOR } from "./events-JiVPYrct.mjs";
+import { createAsyncLogic, createLogic } from "xstate";
+//#region src/decision.ts
+function decideRequestFromInput(input) {
+	const allowedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input) ?? [];
+	return {
+		kind: "decision",
+		id: "",
+		model: input.model,
+		system: input.system,
+		prompt: input.prompt,
+		messages: input.messages,
+		events: allowedEventTypes.filter((type) => !isEventPattern(type)).map((type) => ({
+			type,
+			toolName: sanitizeEventToolName(type)
+		})),
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function decideActorWithExecutor(execute) {
+	const logic = createAsyncLogic({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error(`'${DECIDE_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		const resolvedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input);
+		if (resolvedEventTypes === void 0) throw new Error(`'${DECIDE_ACTOR}' input has omitted \`allowedEvents\`, which means "all currently-legal events" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare \`allowedEvents\` explicitly to use this actor here.`);
+		if (resolvedEventTypes.some(isEventPattern)) throw new Error(`'${DECIDE_ACTOR}' input uses wildcard \`allowedEvents\` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.`);
+		return resolveDecision(decideRequestFromInput(input), execute, {
+			maxRetries: input.maxRetries ?? 2,
+			signal
+		});
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input),
+		withExecutor: (nextExecute) => decideActorWithExecutor(nextExecute)
+	});
+}
+function createDecideActor() {
+	return decideActorWithExecutor();
+}
+/**
+* Reserved event type the `agent.plan` builtin adds to every step's
+* candidates as the explicit "no further action needed" move. Choosing it
+* ends the plan (`stopped: 'done'`); it is never sent to the machine, so
+* machines need no no-op sentinel event of their own.
+*/
+const PLAN_DONE_EVENT_TYPE = "agent.plan.done";
+function createPlanActor() {
+	const logic = createLogic({
+		context: ({ input }) => ({
+			applied: [],
+			stepsRemaining: input.maxSteps ?? 8,
+			stopped: null
+		}),
+		run: ({ context, event }) => event.type === "plan.applied" ? { context: {
+			...context,
+			applied: [...context.applied, event.event],
+			stepsRemaining: context.stepsRemaining - 1
+		} } : event.type === "plan.ended" ? {
+			context: {
+				...context,
+				stopped: event.stopped
+			},
+			status: "done",
+			output: {
+				steps: context.applied,
+				stopped: event.stopped
+			}
+		} : void 0
+	});
+	return Object.assign(logic, {
+		kind: "statelyai.planLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input)
+	});
+}
+const PLAN_LEDGER_SCOPE = { emit: () => {} };
+/**
+* Builds a fresh plan ledger snapshot from resolved plan input — the shared
+* starting point for BOTH hosts (the step path reads the invoke child's own
+* initial snapshot; runAgent seeds a local ledger with this). @internal
+*/
+function initialPlanLedger(logic, input) {
+	return logic.getInitialSnapshot(PLAN_LEDGER_SCOPE, input);
+}
+/**
+* Advances a plan ledger by one {@link PlanLedgerEvent}, returning the next
+* snapshot (unwrapping `createLogic`'s `[snapshot, effects]` tuple). Pure — no
+* mutation of the input snapshot. @internal
+*/
+function advancePlanLedger(logic, snapshot, event) {
+	const result = logic.transition(snapshot, event, PLAN_LEDGER_SCOPE);
+	return Array.isArray(result) ? result[0] : result;
+}
+/** Type guard: true for the `agent.plan` builtin logic (checks the `kind` marker). @internal */
+function isPlanLogic(logic) {
+	return !!logic && logic.kind === "statelyai.planLogic";
+}
+function resolveAllowedEventTypes(allowedEvents, input) {
+	if (allowedEvents === void 0) return;
+	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
+	return typeof resolved === "string" ? [resolved] : resolved;
+}
+/** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
+function isDecisionLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
+}
+/**
+* Thrown by {@link resolveDecision} when every attempt (up to
+* `maxRetries + 1` of them) fails one of the three checks recorded in
+* {@link DecisionAttempt.failure}. Carries the full `attempts` list for
+* diagnostics; a machine typically routes this via the decision invoke's
+* `onError`.
+*/
+var DecisionExhaustedError = class extends Error {
+	attempts;
+	constructor(attempts) {
+		super(`Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
+		this.name = "DecisionExhaustedError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Renders a decision request's prior failed `attempts` into feedback messages
+* a host appends to the model call so retries converge — the transport-agnostic
+* "your last choice failed because X, choose again from Y" logic every adapter
+* and raw-SDK host repeats. Returns one `user`-role {@link AgentMessage} per
+* attempt (empty when there are none); adapters map each onto their wire
+* message shape (`attempt.content` is always a string). Core never rewrites the
+* request itself — this only turns the recorded attempts into messages.
+*
+* @example
+* ```ts
+* const messages = [...baseMessages, ...renderDecisionAttempts(request)];
+* ```
+*/
+function renderDecisionAttempts(request) {
+	const types = request.events.map((event) => event.type).join(", ") || "(none)";
+	return request.attempts.map((attempt) => userMessage(`Your previous choice failed: ${attempt.reason}. Choose again from: ${types}`));
+}
+/**
+* Validation + retry core for decisions. No provider mechanics — the
+* `executor` is responsible for making the model choose an event; this
+* function only validates the choice and retries on failure, up to
+* `options.maxRetries` (default 2, i.e. up to 3 attempts total).
+*
+* Each attempt is checked in order and can fail one of three ways (recorded
+* as a {@link DecisionAttempt}): `'unknown-event'` (the chosen `type` is not
+* among `request.events`), `'invalid-payload'` (the payload fails that
+* event's schema), or `'rejected-by-guard'` (passes both checks but
+* `options.canTake` returns `false` — a type/payload-legal event the
+* machine's guard rejects right now; omit `canTake` to skip this check).
+* Every prior failed attempt for this call is fed back to the executor on
+* the next attempt via `request.attempts`, so an adapter can render "your
+* last choice failed because X — try again" into the next model call; core
+* never rewrites the request itself. Exhausting all attempts throws
+* {@link DecisionExhaustedError} with the full attempts list.
+*
+* @example
+* ```ts
+* const event = await resolveDecision(request, decide, {
+*   canTake: (e) => snapshot.can(e),
+* });
+* ```
+*/
+async function resolveDecision(request, executor, options = {}) {
+	const maxRetries = options.maxRetries ?? 2;
+	const attempts = [];
+	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		options.signal?.throwIfAborted();
+		const result = await executor({
+			...request,
+			attempts: [...attempts],
+			signal: options.signal
+		});
+		if (!result || typeof result !== "object" || typeof result.event !== "object" || result.event === null || typeof result.event.type !== "string") throw new Error(`decide executor must return { event: { type: string, ... } }; got ${JSON.stringify(result)}. Wrap the chosen event: return { event: { type: 'SAFE' } }.`);
+		const { event } = result;
+		const descriptor = eventsByType.get(event.type);
+		if (!descriptor) {
+			attempts.push({
+				event,
+				failure: "unknown-event",
+				reason: `'${event.type}' is not among the currently allowed events: ${request.events.map((candidate) => candidate.type).join(", ") || "(none)"}.`
+			});
+			continue;
+		}
+		let validatedEvent = event;
+		if (descriptor.inputSchema) {
+			const { type, ...payload } = event;
+			try {
+				validatedEvent = {
+					...validateSchemaSync(descriptor.inputSchema, payload),
+					type
+				};
+			} catch (error) {
+				attempts.push({
+					event,
+					failure: "invalid-payload",
+					reason: `'${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`
+				});
+				continue;
+			}
+		}
+		if (options.canTake?.(validatedEvent) === false) {
+			attempts.push({
+				event: validatedEvent,
+				failure: "rejected-by-guard",
+				reason: `'${validatedEvent.type}' is not currently takeable (guard rejected it).`
+			});
+			continue;
+		}
+		return validatedEvent;
+	}
+	throw new DecisionExhaustedError(attempts);
+}
+//#endregion
+export { createPlanActor as a, isPlanLogic as c, createDecideActor as i, renderDecisionAttempts as l, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, advancePlanLedger as r, isDecisionLogic as s, DecisionExhaustedError as t, resolveDecision as u };