@statelyai/agent 1.1.5 → 2.0.0-alpha.5

package/dist/decision-pC-bY2DE.cjs

@@ -0,0 +1,1231 @@
+let xstate = require("xstate");
+//#region src/utils.ts
+/**
+* Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
+* shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
+* JSON-serializability: functions, `undefined`, and other non-JSON values are
+* dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
+* plain-JSON deep clone, not a live snapshot.
+*/
+function persistSnapshot(snapshot) {
+	return JSON.parse(JSON.stringify(snapshot));
+}
+/**
+* Walks a context value and returns the dot-paths of the first few values that
+* would NOT survive a JSON persist/resume round-trip (see {@link persistSnapshot}):
+* `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
+* instances (non-plain objects), and circular references. Plain objects,
+* arrays, and JSON primitives are walked/allowed. Returns `[]` for a
+* fully-JSON-safe value. Cheap and bounded (stops after `limit` findings) —
+* intended for a dev-only warning at the moment persistence matters.
+*/
+function findNonSerializableContextPaths(context, limit = 5) {
+	const paths = [];
+	const seen = /* @__PURE__ */ new WeakSet();
+	const walk = (value, path) => {
+		if (paths.length >= limit) return;
+		if (value === null) return;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") return;
+		if (type === "undefined" || type === "bigint" || type === "function" || type === "symbol") {
+			paths.push(`${path} (${type})`);
+			return;
+		}
+		const obj = value;
+		if (seen.has(obj)) {
+			paths.push(`${path} (circular)`);
+			return;
+		}
+		if (Array.isArray(value)) {
+			seen.add(obj);
+			value.forEach((item, index) => walk(item, `${path}[${index}]`));
+			seen.delete(obj);
+			return;
+		}
+		const proto = Object.getPrototypeOf(value);
+		if (proto === Object.prototype || proto === null) {
+			seen.add(obj);
+			for (const [key, item] of Object.entries(value)) walk(item, `${path}.${key}`);
+			seen.delete(obj);
+			return;
+		}
+		const ctorName = value.constructor?.name ?? "object";
+		paths.push(`${path} (${ctorName})`);
+	};
+	walk(context, "context");
+	return paths;
+}
+/**
+* A stable, dependency-free structural fingerprint of a machine — a short hex
+* `djb2` hash over its **structural** config only: state ids/nesting, transition
+* event types and targets, invoke `src`s, `initial`, and any other serializable
+* config fields. Function values (context/output builders, prompts, inline
+* guards/actions) are excluded entirely, so two machines that differ only in
+* their prompts or executors hash identically; adding/removing/retargeting a
+* state or transition changes the hash.
+*
+* Used by {@link runAgent} to stamp settled snapshots with a `version` and to
+* detect a structurally-edited machine on resume. It is a change detector, not
+* a cryptographic digest — collisions are possible but unlikely for real
+* configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+*/
+function getMachineStructuralHash(machine) {
+	return djb2Hex(stableStructuralString(machine.config));
+}
+function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null) return "null";
+	const type = typeof value;
+	if (type === "function" || type === "undefined" || type === "symbol") return "";
+	if (type === "string") return JSON.stringify(value);
+	if (type === "number" || type === "boolean") return String(value);
+	if (type === "bigint") return `${value}n`;
+	const obj = value;
+	if (seen.has(obj)) return "\"[circular]\"";
+	seen.add(obj);
+	let out;
+	if (Array.isArray(value)) out = `[${value.map((item) => stableStructuralString(item, seen)).join(",")}]`;
+	else {
+		const parts = [];
+		for (const key of Object.keys(obj).sort()) {
+			const child = obj[key];
+			const childType = typeof child;
+			if (childType === "function" || childType === "undefined" || childType === "symbol") continue;
+			parts.push(`${JSON.stringify(key)}:${stableStructuralString(child, seen)}`);
+		}
+		out = `{${parts.join(",")}}`;
+	}
+	seen.delete(obj);
+	return out;
+}
+function djb2Hex(input) {
+	let hash = 5381;
+	for (let i = 0; i < input.length; i++) hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+function userMessage(content) {
+	return {
+		role: "user",
+		content
+	};
+}
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+function assistantMessage(content) {
+	return {
+		role: "assistant",
+		content
+	};
+}
+/** Builds a {@link SystemMessage}. */
+function systemMessage(content) {
+	return {
+		role: "system",
+		content
+	};
+}
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+function toolMessage(content) {
+	return {
+		role: "tool",
+		content
+	};
+}
+/**
+* Returns the merged `meta` of a snapshot's active state(s) — the typed
+* replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+*
+* `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+* state, but parallel/nested machines can have several. This shallow-merges
+* every active state's meta into one object (later/deeper entries win) and
+* returns `{}` when no active state declares meta.
+*
+* The return type is recovered from the snapshot's own `getMeta()` type, so a
+* schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+* output type. Pass an explicit `TMeta` to override when the snapshot is
+* untyped (e.g. `AnyMachineSnapshot`).
+*
+* @example HITL: read the current state's interaction protocol off an idle
+* snapshot to render for a human.
+* ```ts
+* const { interaction } = getStateMeta(result.snapshot);
+* ```
+*/
+function getStateMeta(snapshot) {
+	return Object.assign({}, ...Object.values(snapshot.getMeta()).filter((meta) => meta != null));
+}
+/**
+* Reads the run-owned message log off a snapshot settled by a `runAgent` call
+* that used `getRequests` (or `options.messages`) — the typed replacement for
+* the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+* stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+* so it survives a JSON persist/resume round-trip; this accessor works on the
+* live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+* when no log was stamped (e.g. a default invoke-driven run).
+*
+* The write path is `runAgent(..., { messages })`: an explicit seed that
+* overrides the resume snapshot's stamped log (fold in a user reply on
+* resume, or start a run with prior history).
+*/
+function getAgentMessages(snapshot) {
+	const stamped = snapshot?.messages;
+	return Array.isArray(stamped) ? stamped : [];
+}
+/**
+* Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+* the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+* (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+* can't read directly — see the `ai-sdk` tool pass-through and `openai-compat`
+* tool serialization.
+*/
+function isStandardSchema(value) {
+	return typeof value === "object" && value !== null && "~standard" in value;
+}
+/**
+* Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+* `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+* `z.toJSONSchema`), awaiting it when the producer is async. Returns
+* `undefined` when the schema doesn't expose the extension. Use this to build
+* a provider request's `response_format`/tool `parameters` from a schema.
+*/
+async function getJsonSchema(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Synchronous variant of {@link getJsonSchema}, for call sites that can't
+* await (building tool/event descriptors inline). An async JSON Schema
+* producer is treated as absent (returns `undefined`) — in practice Zod's
+* `z.toJSONSchema` resolves synchronously.
+*/
+function getJsonSchemaSync(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? void 0 : result;
+}
+/**
+* Validates `value` against a {@link StandardSchemaV1}, synchronously.
+* Throws if the schema's `validate` returns a `Promise` (async validation is
+* not supported anywhere in this library) or if validation reports issues —
+* in which case the thrown `Error.message` joins every issue message with
+* `', '`.
+*/
+function validateSchemaSync(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new Error("Async schema validation is not supported.");
+	if (result.issues) throw new Error(result.issues.map((issue) => issue.message).join(", "));
+	return result.value;
+}
+//#endregion
+//#region src/internal/registry.ts
+const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
+/**
+* Machine-carried wait-state predicates, keyed on the machine's root `config`
+* object. `config` is shared by reference across `machine.provide(...)` (unlike
+* the machine object itself), so a predicate registered here travels with the
+* machine through `.provide` — which is why it is keyed on `config`, not the
+* machine. Set by `setupAgent({ isSuspended })` in `createMachine`, read by
+* `runAgent` (below the host `options.isSuspended` override, above the timing
+* heuristic).
+*/
+const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */
+function getMachineSuspensionPredicate(machine) {
+	const config = machine.config;
+	return config ? machineSuspensionPredicates.get(config) : void 0;
+}
+const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
+/** Text/decision logics created WITH their own executor (withExecutor or the
+* factory's second arg) — these are runnable as-is, so runAgent's bind check
+* must not reject them as direct-object invoke srcs. */
+const executorBoundLogics = /* @__PURE__ */ new WeakSet();
+function missingActor(src) {
+	const logic = (0, xstate.createAsyncLogic)({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }).`);
+	} });
+	unboundPlaceholderLogics.add(logic);
+	return logic;
+}
+function isUnboundPlaceholder(logic) {
+	return !!logic && typeof logic === "object" && unboundPlaceholderLogics.has(logic);
+}
+function getRegisteredAgentExecutionOptions(machine, options) {
+	return {
+		...agentExecutionOptions.get(machine),
+		...options
+	};
+}
+//#endregion
+//#region src/text-logic.ts
+const USER_INPUT_ACTOR = "agent.userInput";
+const GENERATE_TEXT_ACTOR = "agent.generateText";
+const STREAM_TEXT_ACTOR = "agent.streamText";
+const DECIDE_ACTOR = "agent.decide";
+const PLAN_ACTOR = "agent.plan";
+const agentTextInputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return !!value && typeof value === "object" && typeof value.model === "string" ? { value } : { issues: [{ message: "Expected agent text input with a model" }] };
+	}
+} };
+const unknownOutputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return { value };
+	}
+} };
+const stringOutputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
+	}
+} };
+function createBuiltinTextActor(src, mode, outputSchema) {
+	const logic = (0, xstate.createAsyncLogic)({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode,
+		schemas: {
+			input: agentTextInputSchema,
+			output: outputSchema
+		},
+		request(input) {
+			return validateSchemaSync(agentTextInputSchema, input);
+		},
+		async execute(input, executors) {
+			const { output } = await executeAgentTextRequest(mode, src, validateSchemaSync(agentTextInputSchema, input), executors);
+			return validateSchemaSync(outputSchema, output);
+		},
+		withExecutor(execute) {
+			return Object.assign(createTextLogic({
+				mode,
+				schemas: {
+					input: agentTextInputSchema,
+					output: outputSchema
+				},
+				name: ({ input }) => input.name,
+				model: ({ input }) => input.model,
+				system: ({ input }) => input.system,
+				prompt: ({ input }) => input.prompt,
+				messages: ({ input }) => input.messages,
+				tools: ({ input }) => input.tools,
+				toolChoice: ({ input }) => input.toolChoice,
+				reasoning: ({ input }) => input.reasoning,
+				temperature: ({ input }) => input.temperature,
+				maxOutputTokens: ({ input }) => input.maxOutputTokens,
+				topP: ({ input }) => input.topP,
+				topK: ({ input }) => input.topK,
+				seed: ({ input }) => input.seed,
+				stopSequences: ({ input }) => input.stopSequences,
+				metadata: ({ input }) => input.metadata
+			}, execute));
+		}
+	});
+}
+/** The unbound `agent.generateText`/`agent.streamText` builtins registered by setupAgent. @internal */
+const builtinTextActors = {
+	[GENERATE_TEXT_ACTOR]: createBuiltinTextActor(GENERATE_TEXT_ACTOR, "generate", unknownOutputSchema),
+	[STREAM_TEXT_ACTOR]: createBuiltinTextActor(STREAM_TEXT_ACTOR, "stream", stringOutputSchema)
+};
+/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). @internal */
+const userInputActor = (0, xstate.createAsyncLogic)({ run: async () => {
+	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${USER_INPUT_ACTOR}': ... } }).`);
+} });
+unboundPlaceholderLogics.add(userInputActor);
+/**
+* Validates a raw model/executor output against `schema`, returning the
+* parsed value. Thin wrapper over {@link validateSchemaSync} for parsing a
+* text request's structured output outside of `TextLogic.execute`/
+* `executeAgentRequest` (e.g. a custom host loop).
+*/
+function parseOutput(schema, output) {
+	return validateSchemaSync(schema, output);
+}
+/** Resolves a `ResolveTextLogicValue` (calls it if it's a function, else returns it as-is). @internal */
+function resolveTextLogicValue(value, args) {
+	return typeof value === "function" ? value(args) : value;
+}
+/**
+* Creates reusable, standalone {@link TextLogic}: an actor that, when run,
+* resolves typed input to typed output via a model call. Register the
+* result under `actorSources:` and invoke it by name (equivalent to what
+* `setupAgent({ requests })` builds internally for each request entry). Pass
+* `execute` here, or bind it later with `.withExecutor(...)`, a runtime
+* adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
+* `streamText` options.
+*
+* @example
+* ```ts
+* export const tellJoke = createTextLogic({
+*   mode: 'stream',
+*   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You tell short, punchy jokes.',
+*   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
+* });
+* ```
+*/
+function createTextLogic(config, execute) {
+	const request = (input) => {
+		const args = { input: validateSchemaSync(config.schemas.input, input) };
+		return {
+			name: resolveTextLogicValue(config.name, args),
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt: resolveTextLogicValue(config.prompt, args),
+			messages: resolveTextLogicValue(config.messages, args),
+			tools: resolveTextLogicValue(config.tools, args),
+			toolChoice: resolveTextLogicValue(config.toolChoice, args),
+			outputSchema: config.schemas.output,
+			reasoning: resolveTextLogicValue(config.reasoning, args),
+			temperature: resolveTextLogicValue(config.temperature, args),
+			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
+			topP: resolveTextLogicValue(config.topP, args),
+			topK: resolveTextLogicValue(config.topK, args),
+			seed: resolveTextLogicValue(config.seed, args),
+			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			metadata: resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = (0, xstate.createAsyncLogic)({ run: async ({ input, signal, system, self }, enq) => {
+		const resolvedRequest = request(input);
+		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or extract it with getAgentRequests(..., { actorSources }).");
+		const result = await execute({
+			input,
+			request: resolvedRequest,
+			signal,
+			system,
+			self,
+			emit: enq.emit
+		});
+		const selfId = self?.id;
+		const output = await normalizeGeneratorResult(result, typeof selfId === "string" ? selfId : "text logic", { request: resolvedRequest });
+		return validateSchemaSync(config.schemas.output, output);
+	} });
+	const textLogic = Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode: config.mode ?? "generate",
+		schemas: config.schemas,
+		request,
+		async execute(input, executors) {
+			const { output } = await executeAgentTextRequest(config.mode ?? "generate", "textLogic", request(input), executors);
+			return validateSchemaSync(config.schemas.output, output);
+		},
+		withExecutor(nextExecute) {
+			return createTextLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(textLogic);
+	return textLogic;
+}
+/**
+* Binds a child machine's {@link TextLogic} to a raw
+* {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
+* implement). Encapsulates the `withExecutor` idiom child agents repeat:
+* default the request's `tools` to `{}`, forward the actor `signal`, call the
+* executor, and return its `{ output }` envelope. Use this to share ONE
+* executor across a parent and its nested children.
+*
+* @example
+* ```ts
+* childMachine.provide({
+*   actorSources: {
+*     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
+*   },
+* });
+* ```
+*/
+function bindRequestExecutor(logic, executor) {
+	return logic.withExecutor(async ({ request, signal }) => {
+		const { output } = await executor({
+			...request,
+			tools: request.tools ?? {}
+		}, { signal });
+		return { output };
+	});
+}
+/** Type guard: true for any actor logic built by createTextLogic (checks the `kind` marker). @internal */
+function isTextLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.textLogic" && typeof value.request === "function";
+}
+/**
+* Classifies a text request's output schema as `'structured'` (its JSON
+* Schema is `type: 'object'`, `type: 'array'`, or a top-level union/
+* composition — `anyOf`/`oneOf`/`allOf`, which a bare `z.union`/
+* `z.discriminatedUnion` emits with no top-level `type`) or `'text'`
+* (anything else, including no schema). Reads the schema's
+* `~standard.jsonSchema.input()` extension — schemas without it are treated
+* as `'text'`.
+*/
+function getAgentOutputMode(schema) {
+	const jsonSchema = getStandardSchemaJson(schema);
+	if (!jsonSchema) return "text";
+	if (jsonSchema.type === "object" || jsonSchema.type === "array") return "structured";
+	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
+	return "text";
+}
+/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
+function isStructuredOutputSchema(schema) {
+	return getAgentOutputMode(schema) === "structured";
+}
+/**
+* Builds the uniform structured-output envelope schema every structured request
+* is sent to the provider as: a root object `{ result: <inner> }`, plus — when
+* `options.reasoning` is `true` — an optional string `reasoning` property listed
+* BEFORE `result` (property order nudges the model to reason first). This is THE
+* wire contract for structured output: a root object is universally accepted as
+* a provider response schema, unlike a bare union/array root that many providers
+* reject.
+*
+* The returned {@link StandardSchemaV1} validates the `{ reasoning?, result }`
+* envelope (unwrapping `result` through the original schema, capturing a string
+* `reasoning` when present) and exposes the enveloped JSON Schema. Adapters read
+* `.result` off the provider output before the machine validates it — so this is
+* transparent: user-facing output types stay the declared (un-enveloped) schema,
+* and `reasoning` is surfaced only on the raw executor result, never in machine
+* context/output.
+*/
+function buildEnvelopeSchema(inner, options = {}) {
+	const includeReasoning = options.reasoning === true;
+	const buildJson = (innerJson) => ({
+		type: "object",
+		properties: {
+			...includeReasoning ? { reasoning: { type: "string" } } : {},
+			result: innerJson ?? {}
+		},
+		required: ["result"],
+		additionalProperties: false
+	});
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			if (!value || typeof value !== "object" || !("result" in value)) return { issues: [{ message: "Expected a { result } envelope object" }] };
+			const innerResult = inner["~standard"].validate(value.result);
+			if (innerResult instanceof Promise) throw new Error("Async schema validation is not supported.");
+			if (innerResult.issues) return innerResult;
+			const envelope = { result: innerResult.value };
+			const reasoning = value.reasoning;
+			if (typeof reasoning === "string") envelope.reasoning = reasoning;
+			return { value: envelope };
+		},
+		jsonSchema: { input: () => {
+			const innerJson = inner["~standard"].jsonSchema?.input?.();
+			return innerJson instanceof Promise ? innerJson.then(buildJson) : buildJson(innerJson);
+		} }
+	} };
+}
+function getStandardSchemaJson(schema) {
+	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
+	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
+}
+/**
+* Merges request-declared and call-site `tools`, dispatches to the
+* `mode`-appropriate executor (`generateText`/`streamText`), and normalizes
+* the raw result via {@link normalizeGeneratorResult}. Shared by
+* `TextLogic.execute`, `executeAgentRequest`, and the `agent.generateText`/
+* `agent.streamText` builtins. Throws if no executor is registered for
+* `mode`.
+*
+* @internal
+*/
+async function executeAgentTextRequest(mode, id, input, executors, tools = {}, info) {
+	const request = {
+		...input,
+		tools: {
+			...input.tools,
+			...tools
+		}
+	};
+	const executor = mode === "stream" ? executors.streamText : executors.generateText;
+	if (!executor) throw new Error(`No executor provided for ${mode === "stream" ? "stream" : "generate"} request '${id}'.`);
+	const raw = await executor(request, info);
+	return {
+		output: await normalizeGeneratorResult(raw, id, {
+			request,
+			onChunk: info?.onChunk
+		}),
+		raw
+	};
+}
+function hasTextStream(value) {
+	return "textStream" in value && typeof value.textStream === "object" && !!value.textStream?.[Symbol.asyncIterator];
+}
+function parseRawAiSdkText(text, request, id) {
+	if (!request?.outputSchema) return text;
+	let parsed = text;
+	try {
+		parsed = JSON.parse(text);
+	} catch {}
+	try {
+		return parseOutput(request.outputSchema, parsed);
+	} catch (error) {
+		throw new Error(`Executor for '${id}' returned a raw AI SDK result whose text could not be parsed against the request's outputSchema. Structured-output requests through raw AI SDK generateText/streamText functions are best-effort — for reliable structured output, use createAiSdkExecutors from '@statelyai/agent/ai-sdk'. Cause: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/**
+* Unwraps an executor result into the request's final output. Accepts three
+* shapes:
+* - `{ output }` (the {@link AgentRequestExecutorResult} envelope) — awaits and
+*   returns `output` (the fast path; unchanged).
+* - a raw AI SDK `streamText` result (`{ textStream }` async iterable) — iterates
+*   `textStream`, forwarding each string chunk to `info.onChunk`, then resolves
+*   the final text from `await result.text` if present else the accumulated chunks.
+* - a raw AI SDK `generateText` result (`{ text }` string or promise) — awaits `text`.
+*
+* For the two raw AI SDK shapes, if `info.request?.outputSchema` is set the final
+* text is parsed through {@link parseOutput} (best-effort); a parse failure throws
+* an error recommending `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
+*
+* A value matching none of these is a runtime error naming `id`. This is
+* generator-result unwrapping only — decision results are extracted separately
+* by `resolveDecision`.
+*
+* @internal
+*/
+async function normalizeGeneratorResult(result, id = "text request", info) {
+	const resolved = await result;
+	if (!resolved || typeof resolved !== "object") throw invalidGeneratorResult(id);
+	if ("output" in resolved) return await resolved.output;
+	if (hasTextStream(resolved)) {
+		let accumulated = "";
+		for await (const chunk of resolved.textStream) {
+			accumulated += chunk;
+			info?.onChunk?.(chunk);
+		}
+		const finalText = "text" in resolved && resolved.text !== void 0 ? await resolved.text : accumulated;
+		return parseRawAiSdkText(String(finalText), info?.request, id);
+	}
+	if ("text" in resolved) {
+		const finalText = await resolved.text;
+		return parseRawAiSdkText(String(finalText), info?.request, id);
+	}
+	throw invalidGeneratorResult(id);
+}
+function invalidGeneratorResult(id) {
+	return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { output } (an envelope with the text string or structured object as \`output\`, plus optional passthrough fields). Raw Vercel AI SDK generateText/streamText results ({ text } or { textStream }) are also accepted.`);
+}
+//#endregion
+//#region src/events.ts
+/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. */
+const EVENT_TOOL_PREFIX = "send_event_";
+function hashString(value) {
+	let hash = 5381;
+	for (let i = 0; i < value.length; i++) hash = hash * 33 ^ value.charCodeAt(i);
+	return (hash >>> 0).toString(36);
+}
+function sanitizeEventToolName(eventType) {
+	const base = `${EVENT_TOOL_PREFIX}${eventType.replace(/[^a-zA-Z0-9_-]/g, "_") || "event"}`;
+	if (base.length <= 64) return base;
+	const hash = hashString(eventType);
+	const prefixLength = 64 - hash.length - 1;
+	return `${base.slice(0, prefixLength)}_${hash}`;
+}
+function disambiguateEventToolName(toolName, eventType, usedToolNames) {
+	if (!usedToolNames.has(toolName)) {
+		usedToolNames.add(toolName);
+		return toolName;
+	}
+	const suffix = `_${hashString(eventType)}`;
+	const uniqueToolName = `${toolName.slice(0, 64 - suffix.length)}${suffix}`;
+	usedToolNames.add(uniqueToolName);
+	return uniqueToolName;
+}
+/**
+* True when an event type matches an `allowedEvents` entry: an exact type,
+* `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
+* segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
+* `'todo'` itself — mirroring xstate's partial wildcard events).
+*/
+function matchesEventPattern(eventType, pattern) {
+	if (pattern === "*") return true;
+	if (pattern.endsWith(".*")) return eventType.startsWith(`${pattern.slice(0, -1)}`);
+	return eventType === pattern;
+}
+/** True when an `allowedEvents` entry is a wildcard pattern rather than a concrete event type. @internal */
+function isEventPattern(entry) {
+	return entry === "*" || entry.endsWith(".*");
+}
+/**
+* Runtime-validates a dynamically-built `{ type, ...payload }` event against a
+* snapshot's currently-accepted events (via {@link getAcceptedEvents}) and,
+* when one is registered, the event type's payload schema — returning the
+* event typed as the machine's event union (recovered from the snapshot type)
+* so it can be sent to `runAgent({ event })` / `actor.send(...)` without an
+* `as never` cast. For generic, meta-driven hosts that assemble events from
+* user input or a wire message.
+*
+* Throws a descriptive error when `event.type` is not currently accepted
+* (listing the accepted types) or when its payload fails the registered schema.
+* Pass event payload schemas via `options.events`/`options.schemas` (the same
+* shape {@link getAcceptedEvents} takes) — the accepted TYPES always come from
+* the live snapshot; the schemas only add payload validation.
+*
+* @example
+* ```ts
+* const event = parseAgentEvent(result.snapshot, rawEvent, { events: schemas.events });
+* result = await runAgent(machine, { snapshot: result.snapshot, event, executors });
+* ```
+*/
+function parseAgentEvent(snapshot, event, options = {}) {
+	const accepted = getAcceptedEvents(snapshot, options);
+	const descriptor = accepted.find((candidate) => candidate.type === event.type);
+	if (!descriptor) throw new Error(`parseAgentEvent: '${event.type}' is not an accepted event in the current state. Accepted: ${accepted.map((candidate) => candidate.type).join(", ") || "(none)"}.`);
+	if (descriptor.inputSchema) {
+		const { type, ...payload } = event;
+		try {
+			return {
+				...validateSchemaSync(descriptor.inputSchema, payload),
+				type
+			};
+		} catch (error) {
+			throw new Error(`parseAgentEvent: '${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return event;
+}
+function getAcceptedEvents(snapshot, options = {}) {
+	const eventTypes = options.eventTypes;
+	const seen = /* @__PURE__ */ new Set();
+	const usedToolNames = /* @__PURE__ */ new Set();
+	return (0, xstate.getNextTransitions)(snapshot).flatMap((transitionDefinition) => {
+		const eventType = transitionDefinition.eventType;
+		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
+		seen.add(eventType);
+		const defaultToolName = sanitizeEventToolName(eventType);
+		const toolName = options.eventToolName ? options.eventToolName({
+			eventType,
+			defaultToolName
+		}) : disambiguateEventToolName(defaultToolName, eventType, usedToolNames);
+		const inputSchema = (options.events ?? options.schemas?.events)?.[eventType];
+		return [{
+			type: eventType,
+			toolName,
+			...inputSchema ? { inputSchema } : {}
+		}];
+	});
+}
+//#endregion
+//#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 = (0, xstate.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 = (0, xstate.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 { event } = await executor({
+			...request,
+			attempts: [...attempts],
+			signal: options.signal
+		});
+		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
+Object.defineProperty(exports, "DECIDE_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return DECIDE_ACTOR;
+	}
+});
+Object.defineProperty(exports, "DecisionExhaustedError", {
+	enumerable: true,
+	get: function() {
+		return DecisionExhaustedError;
+	}
+});
+Object.defineProperty(exports, "EVENT_TOOL_PREFIX", {
+	enumerable: true,
+	get: function() {
+		return EVENT_TOOL_PREFIX;
+	}
+});
+Object.defineProperty(exports, "PLAN_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return PLAN_ACTOR;
+	}
+});
+Object.defineProperty(exports, "PLAN_DONE_EVENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return PLAN_DONE_EVENT_TYPE;
+	}
+});
+Object.defineProperty(exports, "USER_INPUT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return USER_INPUT_ACTOR;
+	}
+});
+Object.defineProperty(exports, "advancePlanLedger", {
+	enumerable: true,
+	get: function() {
+		return advancePlanLedger;
+	}
+});
+Object.defineProperty(exports, "agentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return agentExecutionOptions;
+	}
+});
+Object.defineProperty(exports, "assistantMessage", {
+	enumerable: true,
+	get: function() {
+		return assistantMessage;
+	}
+});
+Object.defineProperty(exports, "bindRequestExecutor", {
+	enumerable: true,
+	get: function() {
+		return bindRequestExecutor;
+	}
+});
+Object.defineProperty(exports, "buildEnvelopeSchema", {
+	enumerable: true,
+	get: function() {
+		return buildEnvelopeSchema;
+	}
+});
+Object.defineProperty(exports, "builtinTextActors", {
+	enumerable: true,
+	get: function() {
+		return builtinTextActors;
+	}
+});
+Object.defineProperty(exports, "createDecideActor", {
+	enumerable: true,
+	get: function() {
+		return createDecideActor;
+	}
+});
+Object.defineProperty(exports, "createPlanActor", {
+	enumerable: true,
+	get: function() {
+		return createPlanActor;
+	}
+});
+Object.defineProperty(exports, "createTextLogic", {
+	enumerable: true,
+	get: function() {
+		return createTextLogic;
+	}
+});
+Object.defineProperty(exports, "executeAgentTextRequest", {
+	enumerable: true,
+	get: function() {
+		return executeAgentTextRequest;
+	}
+});
+Object.defineProperty(exports, "executorBoundLogics", {
+	enumerable: true,
+	get: function() {
+		return executorBoundLogics;
+	}
+});
+Object.defineProperty(exports, "findNonSerializableContextPaths", {
+	enumerable: true,
+	get: function() {
+		return findNonSerializableContextPaths;
+	}
+});
+Object.defineProperty(exports, "getAcceptedEvents", {
+	enumerable: true,
+	get: function() {
+		return getAcceptedEvents;
+	}
+});
+Object.defineProperty(exports, "getAgentMessages", {
+	enumerable: true,
+	get: function() {
+		return getAgentMessages;
+	}
+});
+Object.defineProperty(exports, "getAgentOutputMode", {
+	enumerable: true,
+	get: function() {
+		return getAgentOutputMode;
+	}
+});
+Object.defineProperty(exports, "getJsonSchema", {
+	enumerable: true,
+	get: function() {
+		return getJsonSchema;
+	}
+});
+Object.defineProperty(exports, "getJsonSchemaSync", {
+	enumerable: true,
+	get: function() {
+		return getJsonSchemaSync;
+	}
+});
+Object.defineProperty(exports, "getMachineStructuralHash", {
+	enumerable: true,
+	get: function() {
+		return getMachineStructuralHash;
+	}
+});
+Object.defineProperty(exports, "getMachineSuspensionPredicate", {
+	enumerable: true,
+	get: function() {
+		return getMachineSuspensionPredicate;
+	}
+});
+Object.defineProperty(exports, "getRegisteredAgentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return getRegisteredAgentExecutionOptions;
+	}
+});
+Object.defineProperty(exports, "getStateMeta", {
+	enumerable: true,
+	get: function() {
+		return getStateMeta;
+	}
+});
+Object.defineProperty(exports, "initialPlanLedger", {
+	enumerable: true,
+	get: function() {
+		return initialPlanLedger;
+	}
+});
+Object.defineProperty(exports, "isDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return isDecisionLogic;
+	}
+});
+Object.defineProperty(exports, "isPlanLogic", {
+	enumerable: true,
+	get: function() {
+		return isPlanLogic;
+	}
+});
+Object.defineProperty(exports, "isStandardSchema", {
+	enumerable: true,
+	get: function() {
+		return isStandardSchema;
+	}
+});
+Object.defineProperty(exports, "isStructuredOutputSchema", {
+	enumerable: true,
+	get: function() {
+		return isStructuredOutputSchema;
+	}
+});
+Object.defineProperty(exports, "isTextLogic", {
+	enumerable: true,
+	get: function() {
+		return isTextLogic;
+	}
+});
+Object.defineProperty(exports, "isUnboundPlaceholder", {
+	enumerable: true,
+	get: function() {
+		return isUnboundPlaceholder;
+	}
+});
+Object.defineProperty(exports, "machineSuspensionPredicates", {
+	enumerable: true,
+	get: function() {
+		return machineSuspensionPredicates;
+	}
+});
+Object.defineProperty(exports, "matchesEventPattern", {
+	enumerable: true,
+	get: function() {
+		return matchesEventPattern;
+	}
+});
+Object.defineProperty(exports, "missingActor", {
+	enumerable: true,
+	get: function() {
+		return missingActor;
+	}
+});
+Object.defineProperty(exports, "normalizeGeneratorResult", {
+	enumerable: true,
+	get: function() {
+		return normalizeGeneratorResult;
+	}
+});
+Object.defineProperty(exports, "parseAgentEvent", {
+	enumerable: true,
+	get: function() {
+		return parseAgentEvent;
+	}
+});
+Object.defineProperty(exports, "parseOutput", {
+	enumerable: true,
+	get: function() {
+		return parseOutput;
+	}
+});
+Object.defineProperty(exports, "persistSnapshot", {
+	enumerable: true,
+	get: function() {
+		return persistSnapshot;
+	}
+});
+Object.defineProperty(exports, "renderDecisionAttempts", {
+	enumerable: true,
+	get: function() {
+		return renderDecisionAttempts;
+	}
+});
+Object.defineProperty(exports, "resolveDecision", {
+	enumerable: true,
+	get: function() {
+		return resolveDecision;
+	}
+});
+Object.defineProperty(exports, "sanitizeEventToolName", {
+	enumerable: true,
+	get: function() {
+		return sanitizeEventToolName;
+	}
+});
+Object.defineProperty(exports, "systemMessage", {
+	enumerable: true,
+	get: function() {
+		return systemMessage;
+	}
+});
+Object.defineProperty(exports, "toolMessage", {
+	enumerable: true,
+	get: function() {
+		return toolMessage;
+	}
+});
+Object.defineProperty(exports, "userInputActor", {
+	enumerable: true,
+	get: function() {
+		return userInputActor;
+	}
+});
+Object.defineProperty(exports, "userMessage", {
+	enumerable: true,
+	get: function() {
+		return userMessage;
+	}
+});
+Object.defineProperty(exports, "validateSchemaSync", {
+	enumerable: true,
+	get: function() {
+		return validateSchemaSync;
+	}
+});