@statelyai/agent 2.0.0-alpha.21 → 2.0.0-alpha.23

package/dist/{decision-BnTCsuJv.cjs → decision-Cv6SfNWl.cjs}

@@ -1,7 +1,239 @@
-const require_errors = require("./errors-DUBBzRLP.cjs");
 require("./validate.cjs");
 let xstate = require("xstate");
+//#region src/errors.ts
+/**
+* Base class for every error this package throws. Carries a stable, kebab-case
+* `code` so hosts can branch on the failure without `instanceof` (useful across
+* bundle/realm boundaries and after serialization).
+*
+* @example
+* ```ts
+* catch (error) {
+*   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
+* }
+* ```
+*/
+var AgentError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "AgentError";
+		this.code = code;
+	}
+};
+/**
+* A model call ran out of output tokens before it produced anything usable.
+* Core never throws this: it is the adapter's signal that a `'length'` finish
+* reason left nothing to return — a structured request whose envelope never
+* closed, say. A text request that WAS cut off still returns its text, with
+* `finishReason: 'length'`.
+*
+* The code is `'truncated'`, so an invoke's `onError` can branch on it without
+* `instanceof`:
+*
+* @example
+* ```ts
+* onError: [
+*   { guard: ({ event }) => event.error.code === 'truncated', target: 'retryShorter' },
+*   { target: 'failed' },
+* ]
+* ```
+*/
+var AgentTruncatedError = class extends AgentError {
+	/** The request that was cut off — `AgentTextRequest.name`. */
+	requestName;
+	/** The durable invoke id of the request, when the host knows it. */
+	requestId;
+	/** Whatever the model did produce before it hit the limit, if anything. */
+	partialOutput;
+	constructor(message, options) {
+		super("truncated", message, { cause: options.cause });
+		this.name = "AgentTruncatedError";
+		this.requestName = options.requestName;
+		if (options.requestId !== void 0) this.requestId = options.requestId;
+		if (options.partialOutput !== void 0) this.partialOutput = options.partialOutput;
+	}
+};
+//#endregion
+//#region src/messages.ts
+/** Ordinary machine event emitted after a request returns framework-native messages. */
+const AGENT_MESSAGES_EVENT_TYPE = "agent.messages";
+/** Runtime schema for the framework-neutral `agent.messages` envelope. */
+const agentMessagesEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		if (!value || typeof value !== "object") return { issues: [{ message: "Expected an 'agent.messages' payload object" }] };
+		const event = value;
+		const issues = [];
+		if (typeof event.request !== "string") issues.push({
+			message: "Expected a string",
+			path: ["request"]
+		});
+		if (typeof event.actorId !== "string") issues.push({
+			message: "Expected a string",
+			path: ["actorId"]
+		});
+		if (!Array.isArray(event.messages)) issues.push({
+			message: "Expected an array",
+			path: ["messages"]
+		});
+		return issues.length > 0 ? { issues } : { value: event };
+	}
+} };
+function appendMessages(options) {
+	const key = options?.key ?? "messages";
+	return (({ context, event }) => {
+		const current = context[key];
+		const messages = event.messages;
+		return { context: { [key]: [...Array.isArray(current) ? current : [], ...messages ?? []] } };
+	});
+}
+const KNOWN_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+const USER_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file"
+]);
+const ASSISTANT_PART_TYPES = new Set([
+	"text",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+const TOOL_PART_TYPES = new Set(["tool-result"]);
+const TOOL_RESULT_CONTENT_PART_TYPES = new Set(["text", "image"]);
+function isKnownPart(part) {
+	const type = part && typeof part === "object" ? part.type : void 0;
+	return typeof type === "string" && KNOWN_PART_TYPES.has(type);
+}
+function requireString(part, type, field) {
+	return typeof part[field] === "string" ? void 0 : `${type} part requires a string "${field}"`;
+}
+function isMediaData(value) {
+	return typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof URL;
+}
+function requireMediaData(part, type, field) {
+	return isMediaData(part[field]) ? void 0 : `${type} part requires "${field}" to be a string, Uint8Array, ArrayBuffer, or URL`;
+}
+const TOOL_RESULT_OUTPUT_TYPES = new Set([
+	"text",
+	"json",
+	"error-text",
+	"error-json",
+	"content"
+]);
+function validateToolResultOutput(output) {
+	if (!output || typeof output !== "object" || Array.isArray(output)) return "tool-result part requires an \"output\" object";
+	const record = output;
+	const outputType = record.type;
+	if (typeof outputType !== "string" || !TOOL_RESULT_OUTPUT_TYPES.has(outputType)) return `Unknown tool-result output type: ${JSON.stringify(outputType)}`;
+	if (outputType === "text" || outputType === "error-text") {
+		if (typeof record.value !== "string") return `tool-result output of type "${outputType}" requires a string "value"`;
+		return;
+	}
+	if (outputType === "content") {
+		if (!Array.isArray(record.value)) return "tool-result output of type \"content\" requires an array \"value\"";
+		for (const contentPart of record.value) {
+			const error = validatePart(contentPart, TOOL_RESULT_CONTENT_PART_TYPES, "tool-result output content");
+			if (error) return error;
+		}
+		return;
+	}
+	return record.value !== void 0 ? void 0 : `tool-result output of type "${outputType}" requires a "value"`;
+}
+function validatePart(part, allowedTypes, location) {
+	if (!isKnownPart(part)) {
+		const type = part && typeof part === "object" ? part.type : void 0;
+		return `Unknown message part type: ${JSON.stringify(type)}`;
+	}
+	if (!allowedTypes.has(part.type)) return `${location} does not allow "${part.type}" parts`;
+	const record = part;
+	switch (record.type) {
+		case "text": return requireString(record, "text", "text");
+		case "image": return requireMediaData(record, "image", "image");
+		case "file": return requireMediaData(record, "file", "data") ?? requireString(record, "file", "mediaType");
+		case "tool-call": return requireString(record, "tool-call", "toolCallId") ?? requireString(record, "tool-call", "toolName") ?? ("input" in record ? void 0 : "tool-call part requires an \"input\" value");
+		case "tool-result": return requireString(record, "tool-result", "toolCallId") ?? requireString(record, "tool-result", "toolName") ?? validateToolResultOutput(record.output);
+		default: return;
+	}
+}
+function validatePartsArray(content, allowedTypes, location) {
+	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
+	for (const part of content) {
+		const error = validatePart(part, allowedTypes, location);
+		if (error) return error;
+	}
+}
+/**
+* A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
+* checks that every message has a known `role` (`system`/`user`/`assistant`/
+* `tool`) and that `content` is either a string (where the role allows it) or
+* an array of role-appropriate parts whose required fields and media payloads
+* have the right runtime types (extra fields are allowed). Use it directly as
+* a context schema's `messages` field when authoring with `createAgentSchemas`
+* or `fromConfig`. A zod object cannot nest a Standard Schema, so in a zod
+* context schema write `z.custom<AgentMessage[]>(isAgentMessages)`, which runs
+* this same validator (see {@link isAgentMessages}).
+*/
+const messagesSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		if (!Array.isArray(value)) return { issues: [{ message: "Expected an array of agent messages" }] };
+		for (const message of value) {
+			if (!message || typeof message !== "object") return { issues: [{ message: "Expected an array of agent messages" }] };
+			const role = message.role;
+			const content = message.content;
+			if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") return { issues: [{ message: `Unknown message role: ${JSON.stringify(role)}` }] };
+			if (role === "system") {
+				if (typeof content !== "string") return { issues: [{ message: "system message content must be a string" }] };
+				continue;
+			}
+			if (role === "tool") {
+				const error = validatePartsArray(content, TOOL_PART_TYPES, "tool message content");
+				if (error) return { issues: [{ message: error }] };
+				continue;
+			}
+			if (typeof content === "string") continue;
+			const error = validatePartsArray(content, role === "user" ? USER_PART_TYPES : ASSISTANT_PART_TYPES, `${role} message content`);
+			if (error) return { issues: [{ message: error }] };
+		}
+		return { value };
+	}
+} };
+/**
+* Type guard over {@link messagesSchema}: `true` when `value` is a valid
+* `AgentMessage[]`. The one-liner for zod context schemas:
+* `messages: z.custom<AgentMessage[]>(isAgentMessages)`.
+*/
+function isAgentMessages(value) {
+	const result = messagesSchema["~standard"].validate(value);
+	return !(result instanceof Promise) && !("issues" in result && result.issues);
+}
+//#endregion
 //#region src/utils.ts
+/** Returns the human-readable text carried by a message, ignoring non-text parts. */
+function getMessageText(message) {
+	if (typeof message.content === "string") return message.content;
+	const text = [];
+	for (const part of message.content) {
+		if (part.type === "text") {
+			text.push(part.text);
+			continue;
+		}
+		if (part.type !== "tool-result") continue;
+		if (part.output.type === "text" || part.output.type === "error-text") text.push(part.output.value);
+		else if (part.output.type === "content") text.push(...part.output.value.flatMap((item) => item.type === "text" ? [item.text] : []));
+	}
+	return text.join("\n");
+}
 /**
 * Walks a context value and returns the dot-paths of the first few values that
 * would NOT survive a JSON persist/resume round-trip (persist with XState's
@@ -69,8 +301,7 @@ function getMachineStructuralHash(machine) {
 * The version a machine is stamped with everywhere: an explicitly declared
 * `createMachine({ version })` when present, else its
 * {@link getMachineStructuralHash}. Single source of truth so `runAgent`,
-* `provideExecutors`/`traceTransitions` trace envelopes, and the event-log
-* helpers (`initEntry`, `createReplayEntry`, `replay`) never disagree.
+* `provideExecutors`/`traceTransitions` trace envelopes agree.
 * @internal
 */
 function resolveMachineVersion(machine) {
@@ -175,21 +406,37 @@ function getStateMeta(snapshot) {
 	return Object.assign({}, ...entries.map(([, meta]) => meta));
 }
 /**
-* 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).
+* Renders a snapshot's state value as one deterministic string, so a log line,
+* a progress field, or a test assertion reads the same on every 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).
+* - An atomic state is its own name: `'writing'`.
+* - A nested state joins with dots: `{ review: { editing: 'draft' } }` →
+*   `'review.editing.draft'`.
+* - A parallel state brackets its regions, sorted by region name, so key order
+*   never leaks into the string: `{ p: { left: 'x', right: { a: 'b' } } }` →
+*   `'p:{left.x,right.a.b}'`.
+*
+* Prefer this over `String(snapshot.value)`, which renders every non-atomic
+* value as `[object Object]`.
+*
+* @example
+* ```ts
+* onTransition: (snapshot) => console.log(getStatePath(snapshot));
+* ```
 */
-function getAgentMessages(snapshot) {
-	const stamped = snapshot?.messages;
-	return Array.isArray(stamped) ? stamped : [];
+function getStatePath(snapshot) {
+	return serializeStateValue(typeof snapshot === "object" && snapshot !== null && "value" in snapshot && ("status" in snapshot || typeof snapshot.matches === "function") ? snapshot.value : snapshot);
+}
+function serializeStateValue(value) {
+	if (typeof value === "string") return value;
+	const entries = Object.entries(value).map(([key, child]) => {
+		const rendered = serializeStateValue(child);
+		if (!rendered) return [key, key];
+		return [key, `${key}${rendered.startsWith("{") ? ":" : "."}${rendered}`];
+	}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	if (entries.length === 0) return "";
+	if (entries.length === 1) return entries[0][1];
+	return `{${entries.map(([, rendered]) => rendered).join(",")}}`;
 }
 /**
 * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
@@ -240,7 +487,42 @@ function validateSchemaSync(schema, value) {
 }
 //#endregion
 //#region src/internal/registry.ts
+/** Non-enumerable hook an optional adapter can attach to a model registry. */
+const DEFAULT_AGENT_EXECUTORS = Symbol.for("@statelyai/agent.defaultExecutors");
+/**
+* Registered execution options, keyed on BOTH the machine object and its root
+* `config` object. `config` is shared by reference across `machine.provide(...)`
+* (unlike the machine itself), so the `config` key is what lets a machine
+* rebound by `runAgent` — or by any host `.provide(...)` — still resolve the
+* schemas/actors `setupAgent` registered. Always write through
+* {@link setAgentExecutionOptions} and read through
+* {@link getAgentExecutionOptions}.
+*/
 const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
+/** The root `config` object a machine shares with every `.provide(...)` of itself. */
+function machineConfigKey(machine) {
+	const config = machine?.config;
+	return config && typeof config === "object" ? config : void 0;
+}
+/** Registers `options` for `machine` and for every `.provide(...)` of it. */
+function setAgentExecutionOptions(machine, options) {
+	if (!machine || typeof machine !== "object") return;
+	agentExecutionOptions.set(machine, options);
+	const config = machineConfigKey(machine);
+	if (config) agentExecutionOptions.set(config, options);
+}
+/**
+* Reads the options registered for `machine`, falling back to the root `config`
+* key so a `.provide(...)`-rebound machine (e.g. the one behind a `runAgent`
+* result snapshot) resolves the same pack.
+*/
+function getAgentExecutionOptions(machine) {
+	if (!machine || typeof machine !== "object") return void 0;
+	const direct = agentExecutionOptions.get(machine);
+	if (direct) return direct;
+	const config = machineConfigKey(machine);
+	return config ? agentExecutionOptions.get(config) : void 0;
+}
 /**
 * Machine-carried wait-state predicates, keyed on the machine's root `config`
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
@@ -248,8 +530,7 @@ const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
 * machine through `.provide` — which is why it is keyed on `config`, not the
 * machine. Set by `setupAgent({ isIdle })` in `createMachine` and by
 * `setupAgent.fromConfig` (its `isIdle` option or the config's
-* `idleTags`), read by `runAgent` (below the host `options.isIdle`
-* override, above the timing heuristic).
+* `idleTags`), read by `runAgent` before its structural default.
 */
 const machineIdlePredicates = /* @__PURE__ */ new WeakMap();
 /** Reads the {@link machineIdlePredicates} predicate carried by `machine` (via its root `config`), if any. */
@@ -257,24 +538,6 @@ function getMachineIdlePredicate(machine) {
 	const config = machine.config;
 	return config ? machineIdlePredicates.get(config) : void 0;
 }
-/**
-* Lint-reachability sidecar for `fromConfig` machines.
-*
-* Static transition targets declared by the source config of a
-* `setupAgent.fromConfig` machine, as `dotted state path → declared target
-* strings` (every `on`/`always`/`after`/`onDone`/`choice` target plus each
-* invoke's `onDone`/`onError`). The JSON layer folds a transition that carries a
-* context patch into an opaque resolver function, erasing its target from
-* `machine.config` — so `lintAgentMachine`'s reachability walk reads the
-* targets from here instead. Keyed on the machine's root `config` object (like
-* {@link machineIdlePredicates}) so it survives `machine.provide(...)`.
-*/
-const machineStaticTransitionTargets = /* @__PURE__ */ new WeakMap();
-/** Reads the {@link machineStaticTransitionTargets} map carried by `machine` (via its root `config`), if any. */
-function getMachineStaticTransitionTargets(machine) {
-	const config = machine.config;
-	return config ? machineStaticTransitionTargets.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
@@ -292,7 +555,7 @@ function isUnboundPlaceholder(logic) {
 }
 function getRegisteredAgentExecutionOptions(machine, options) {
 	return {
-		...agentExecutionOptions.get(machine),
+		...getAgentExecutionOptions(machine),
 		...options
 	};
 }
@@ -302,8 +565,6 @@ const USER_INPUT_ACTOR = "agent.userInput";
 const GENERATE_TEXT_ACTOR = "agent.generateText";
 const STREAM_TEXT_ACTOR = "agent.streamText";
 const DECIDE_ACTOR = "agent.decide";
-/** Synthetic `src` stamped on trace requests produced by `getRequests` state interpretation — NOT a registered actor source (nothing is invoked; the pass makes the call directly). */
-const INTERPRET_SOURCE = "agent.interpret";
 /**
 * Splits a portable `"provider/model-id"` model ref (the convention JSON
 * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
@@ -325,6 +586,27 @@ function parseModelRef(modelRef) {
 		modelId: modelRef.slice(slash + 1)
 	};
 }
+const AGENT_FINISH_REASONS = new Set([
+	"stop",
+	"length",
+	"tool-calls",
+	"content-filter",
+	"other"
+]);
+/**
+* Reads a settled call's {@link AgentFinishReason} off a RAW executor result's
+* `finishReason` field — the finish-reason sibling of {@link getCallUsage},
+* applied by `runAgent` before it puts the reason on the `request.end` trace.
+* A provider's `'error'` normalizes to `'other'`; anything else the union does
+* not name (an un-normalized provider string, a missing field) returns
+* `undefined`.
+*/
+function getCallFinishReason(raw) {
+	const value = raw?.finishReason;
+	if (typeof value !== "string") return;
+	if (value === "error") return "other";
+	return AGENT_FINISH_REASONS.has(value) ? value : void 0;
+}
 /** The token fields {@link AgentUsage} aggregates. @internal */
 const AGENT_USAGE_TOKEN_FIELDS = [
 	"inputTokens",
@@ -363,6 +645,13 @@ function getCallUsage(raw) {
 	}
 	return out;
 }
+function textRequestSourceIssue(request) {
+	const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
+	const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
+	const label = request.name ? ` '${request.name}'` : "";
+	if (hasPrompt && hasMessages) return `Agent text request${label} has both a non-empty \`prompt\` and \`messages\` — provide exactly one so the model has a single input source.`;
+	if (!hasPrompt && !hasMessages) return `Agent text request${label} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.`;
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -370,9 +659,8 @@ const agentTextInputSchema = { "~standard": {
 		if (!value || typeof value !== "object") return { issues: [{ message: "Expected agent text input object" }] };
 		const request = value;
 		if (typeof request.model !== "string") return { issues: [{ message: "Expected agent text input with a string `model`" }] };
-		const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
-		const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
-		if (!hasPrompt && !hasMessages) return { issues: [{ message: `Agent text request${request.name ? ` '${request.name}'` : ""} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.` }] };
+		const issue = textRequestSourceIssue(request);
+		if (issue) return { issues: [{ message: issue }] };
 		return { value: request };
 	}
 } };
@@ -486,13 +774,24 @@ function createTextLogic(config, execute) {
 		output: config.schemas?.output ?? stringOutputSchema
 	};
 	const request = (input) => {
-		const args = { input: validateSchemaSync(schemas.input, input) };
+		const parsedInput = validateSchemaSync(schemas.input, input);
+		const args = { input: parsedInput };
+		const name = resolveTextLogicValue(config.name, args);
+		const prompt = resolveTextLogicValue(config.prompt, args);
+		const messages = resolveTextLogicValue(config.messages, args);
+		const sourceIssue = textRequestSourceIssue({
+			name,
+			prompt,
+			messages
+		});
+		if (sourceIssue) throw new Error(sourceIssue);
 		return {
-			name: resolveTextLogicValue(config.name, args),
+			name,
+			input: parsedInput,
 			model: resolveTextLogicValue(config.model, args),
 			system: resolveTextLogicValue(config.system, args),
-			prompt: resolveTextLogicValue(config.prompt, args),
-			messages: resolveTextLogicValue(config.messages, args),
+			prompt,
+			messages,
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
 			outputSchema: schemas.output,
@@ -509,7 +808,7 @@ function createTextLogic(config, execute) {
 	};
 	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 getAgentEffects(..., { actors }).");
+		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 bind it through runAgent/provideExecutors, or execute the XState effect in your host.");
 		const result = await execute({
 			input,
 			request: resolvedRequest,
@@ -658,11 +957,14 @@ function parseStructuredEnvelope(request, value) {
 async function executeAgentTextRequest(mode, id, input, executors, tools = {}, info) {
 	const request = {
 		...input,
+		name: input.name ?? id,
 		tools: {
 			...input.tools,
 			...tools
 		}
 	};
+	const sourceIssue = textRequestSourceIssue(request);
+	if (sourceIssue) throw new Error(sourceIssue);
 	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);
@@ -732,7 +1034,31 @@ 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/internal/is-record.ts
+/** True for a plain object-like value (arrays excluded). @internal */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/events.ts
+/**
+* Thrown by {@link parseAgentEvent} (and {@link eventFromInteraction}) when a
+* wire payload is not a usable event: it is not an object with a string
+* `type`, it names a reserved `@agent.*` type, or its fields fail the schema
+* the machine registered for that type. A host turns it into a 400.
+*
+* Not handling an event is NOT this error — a state machine ignores events it
+* has no transition for, so an event the current state does not handle parses
+* fine and settles the run with `result.ignored` set.
+*/
+var AgentInvalidEventPayloadError = class extends AgentError {
+	eventType;
+	constructor(eventType, detail) {
+		super("invalid-event-payload", `Invalid event payload for '${eventType}': ${detail}`);
+		this.name = "AgentInvalidEventPayloadError";
+		this.eventType = eventType;
+	}
+};
 /** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. @internal */
 const EVENT_TOOL_PREFIX = "send_event_";
 function hashString(value) {
@@ -769,58 +1095,61 @@ function matchesEventPattern(eventType, pattern) {
 	return eventType === pattern;
 }
 /**
-* The namespace reserved for events the library itself delivers to a machine
-* (`@agent.init`, `@agent.usage`). A machine may declare transitions on them,
+* Event types reserved for delivery by the library (`@agent.*` and
+* `agent.messages`). A machine may declare transitions on them,
 * but they are never model-facing: {@link getAcceptedEvents} drops them before
 * any `allowedEvents` matching, so they cannot be offered as a decision
 * candidate (not even under a `'*'` wildcard) and {@link parseAgentEvent}
 * rejects them — a model or a wire message must not be able to forge one.
-* Matched as a prefix rather than a list so this module stays free of an import
-* cycle back to `effects.ts`, where the constants live.
 * @internal
 */
 const RESERVED_AGENT_EVENT_PREFIX = "@agent.";
+function isReservedAgentEvent(eventType) {
+	return eventType.startsWith(RESERVED_AGENT_EVENT_PREFIX) || eventType === "agent.messages";
+}
 /** 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.
+* Parses a wire payload (a request body, a socket frame) into an
+* event typed as the machine's event union, so it can go straight to
+* `runAgent({ event })` / `actor.send(...)` without a cast. Pass the machine
+* itself, or any snapshot of it.
+*
+* It checks exactly what a schema can check: the payload is an object with a
+* string `type`, that type is not one of the library-reserved `@agent.*` types,
+* and — when the machine registered a schema for it — the fields satisfy that
+* schema (defaults filled, transforms applied). Anything else throws
+* {@link AgentInvalidEventPayloadError}, which a host answers with a 400.
 *
-* 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.
+* It deliberately does NOT check whether the current state handles the event.
+* State machines ignore events they have no transition for; that is normal
+* behavior, not a validation failure. Send the parsed event and read
+* `result.ignored` if the host wants to tell the client nothing happened.
 *
 * @example
 * ```ts
-* const event = parseAgentEvent(result.snapshot, rawEvent, { events: schemas.events });
-* result = await runAgent(machine, { snapshot: result.snapshot, event, executors });
+* const event = parseAgentEvent(machine, await request.json());
+* const result = await runAgent(machine, { store, threadId, 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)}`);
-		}
+function parseAgentEvent(source, payload, options = {}) {
+	if (!isRecord(payload) || typeof payload.type !== "string") throw new AgentInvalidEventPayloadError("(unknown)", "expected an object with a string `type`.");
+	const event = payload;
+	if (isReservedAgentEvent(event.type)) throw new AgentInvalidEventPayloadError(event.type, "this event type is reserved for the library and cannot be sent from outside.");
+	const registered = getAgentExecutionOptions(typeof source.provide === "function" ? source : source.machine)?.schemas;
+	const inputSchema = (options.events ?? options.schemas?.events ?? registered?.events)?.[event.type];
+	if (!inputSchema) return event;
+	const { type, ...fields } = event;
+	try {
+		return {
+			...validateSchemaSync(inputSchema, fields),
+			type
+		};
+	} catch (error) {
+		throw new AgentInvalidEventPayloadError(event.type, error instanceof Error ? error.message : String(error));
 	}
-	return event;
 }
 /**
 * Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
@@ -844,7 +1173,7 @@ function getAcceptedEvents(snapshot, options = {}) {
 	const usedToolNames = /* @__PURE__ */ new Set();
 	return (0, xstate.getNextTransitions)(snapshot).flatMap((transitionDefinition) => {
 		const eventType = transitionDefinition.eventType;
-		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || eventType.startsWith(RESERVED_AGENT_EVENT_PREFIX) || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
+		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || isReservedAgentEvent(eventType) || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
 		seen.add(eventType);
 		const defaultToolName = sanitizeEventToolName(eventType);
 		const toolName = options.eventToolName ? options.eventToolName({
@@ -866,6 +1195,8 @@ function decideRequestFromInput(input) {
 	return {
 		kind: "decision",
 		id: "",
+		name: input.name,
+		input,
 		model: input.model,
 		system: input.system,
 		prompt: input.prompt,
@@ -911,18 +1242,145 @@ function resolveAllowedEventTypes(allowedEvents, input) {
 	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
 	return typeof resolved === "string" ? [resolved] : resolved;
 }
+/**
+* Creates reusable, standalone {@link DecisionLogic}: an actor that, when
+* run, resolves to exactly one currently-legal {@link ChosenEvent} by
+* calling the host `decide` executor (passed here as `execute`, or supplied
+* later via {@link DecisionLogic.withExecutor}, `machine.provide(...)`, or
+* `runAgent`'s `decide` option). Register the result under `actors:` and
+* invoke it by name; for a one-off, state-local decision, prefer the
+* `agent.decide` builtin invoke instead — it needs no separate declaration
+* and types `allowedEvents` against the machine's own event schemas.
+*
+* @example
+* ```ts
+* import { createDecisionLogic } from '@statelyai/agent';
+* import { z } from 'zod';
+*
+* export const chooseMove = createDecisionLogic({
+*   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You are playing a turn-based game. Choose exactly one legal move.',
+*   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
+*   allowedEvents: ({ input }) =>
+*     input.playerHp <= 6
+*       ? ['ATTACK', 'DEFEND', 'HEAL', 'FLEE']
+*       : ['ATTACK', 'DEFEND', 'FLEE'],
+* });
+* ```
+*/
+function createDecisionLogic(config, execute) {
+	const maxRetries = config.maxRetries ?? 2;
+	const request = (input) => {
+		const parsedInput = config.schemas ? validateSchemaSync(config.schemas.input, input) : input;
+		const args = { input: parsedInput };
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, parsedInput);
+		return {
+			kind: "decision",
+			id: "",
+			name: resolveTextLogicValue(config.name, args),
+			input: parsedInput,
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt: resolveTextLogicValue(config.prompt, args),
+			messages: resolveTextLogicValue(config.messages, args),
+			events: (allowedEventTypes ?? []).map((type) => ({
+				type,
+				toolName: sanitizeEventToolName(type)
+			})),
+			attempts: [],
+			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 }) => {
+		if (!execute) throw new Error("Decision logic has no host execution. Pass an executor as the second argument to createDecisionLogic(...), provide a runtime adapter, or bind it through runAgent/provideExecutors, or call resolveDecision from your host.");
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, input);
+		if (allowedEventTypes === void 0) throw new Error("Decision logic 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 on this logic to use it here.");
+		if (allowedEventTypes.some(isEventPattern)) throw new Error("Decision logic 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(request(input), { decide: execute }, {
+			maxRetries,
+			signal
+		});
+	} });
+	const decisionLogic = Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries,
+		request,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(config.allowedEvents, input),
+		withExecutor(nextExecute) {
+			return createDecisionLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(decisionLogic);
+	return decisionLogic;
+}
 /** 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";
 }
 /**
+* Builds an {@link AgentDecisionRequest} for {@link resolveDecision}, filling
+* in the fields a hand-written literal has to restate every time: `kind`, an
+* `id`, an empty `attempts` list, and each candidate event's `toolName`.
+*
+* @example
+* ```ts
+* const chosen = await resolveDecision(
+*   createDecisionRequest({
+*     name: 'judge',
+*     model: 'reviewer',
+*     prompt: `Judge this draft.\n\n${snapshot.context.draft}`,
+*     events: getAcceptedEvents(snapshot),
+*   }),
+*   { decide },
+*   { canTake: (event) => snapshot.can(event) },
+* );
+* ```
+*/
+function createDecisionRequest(options) {
+	const { id, name, events, attempts, ...rest } = options;
+	return {
+		...rest,
+		kind: "decision",
+		id: id ?? name ?? "decision",
+		...name === void 0 ? {} : { name },
+		events: dedupeToolNames(events.map((event) => typeof event === "string" ? {
+			type: event,
+			toolName: sanitizeEventToolName(event)
+		} : event)),
+		attempts: attempts ?? []
+	};
+}
+function dedupeToolNames(candidates) {
+	const taken = /* @__PURE__ */ new Set();
+	return candidates.map((candidate) => {
+		if (candidate.toolName === void 0) return candidate;
+		let toolName = candidate.toolName;
+		for (let n = 2; taken.has(toolName); n++) {
+			const suffix = `_${n}`;
+			toolName = `${candidate.toolName.slice(0, 64 - suffix.length)}${suffix}`;
+		}
+		taken.add(toolName);
+		return toolName === candidate.toolName ? candidate : {
+			...candidate,
+			toolName
+		};
+	});
+}
+/**
 * 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 AgentDecisionExhaustedError = class extends require_errors.AgentError {
+var AgentDecisionExhaustedError = class extends AgentError {
 	attempts;
 	constructor(attempts) {
 		super("decision-exhausted", `Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
@@ -975,7 +1433,7 @@ function renderDecisionAttempts(request) {
 */
 async function resolveDecision(request, executors, options = {}) {
 	const executor = executors?.decide;
-	if (typeof executor !== "function") throw new require_errors.AgentError("missing-decide-executor", "resolveDecision(request, executors, ...) takes the EXECUTOR SET (the same object executeAgentRequest takes), and this one has no 'decide' function. Build one with createAiSdkExecutors({ models }), or pass { decide }.");
+	if (typeof executor !== "function") throw new AgentError("missing-decide-executor", "resolveDecision(request, executors, ...) takes the EXECUTOR SET (the same object executeAgentRequest takes), and this one has no 'decide' function. Build one with createAiSdkExecutors({ models }), or pass { decide }.");
 	const maxRetries = options.maxRetries ?? 2;
 	const attempts = [];
 	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
@@ -983,8 +1441,8 @@ async function resolveDecision(request, executors, options = {}) {
 		options.signal?.throwIfAborted();
 		const result = await executor({
 			...request,
-			attempts: [...attempts],
-			signal: options.signal
+			name: request.name ?? (request.id || "agent.decide"),
+			attempts: [...attempts]
 		}, {
 			...options.signal !== void 0 ? { signal: options.signal } : {},
 			...request.id ? { requestId: request.id } : {}
@@ -1030,6 +1488,12 @@ async function resolveDecision(request, executors, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
+Object.defineProperty(exports, "AGENT_MESSAGES_EVENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return AGENT_MESSAGES_EVENT_TYPE;
+	}
+});
 Object.defineProperty(exports, "AGENT_USAGE_TOKEN_FIELDS", {
 	enumerable: true,
 	get: function() {
@@ -1042,22 +1506,40 @@ Object.defineProperty(exports, "AgentDecisionExhaustedError", {
 		return AgentDecisionExhaustedError;
 	}
 });
+Object.defineProperty(exports, "AgentError", {
+	enumerable: true,
+	get: function() {
+		return AgentError;
+	}
+});
+Object.defineProperty(exports, "AgentInvalidEventPayloadError", {
+	enumerable: true,
+	get: function() {
+		return AgentInvalidEventPayloadError;
+	}
+});
+Object.defineProperty(exports, "AgentTruncatedError", {
+	enumerable: true,
+	get: function() {
+		return AgentTruncatedError;
+	}
+});
 Object.defineProperty(exports, "DECIDE_ACTOR", {
 	enumerable: true,
 	get: function() {
 		return DECIDE_ACTOR;
 	}
 });
-Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
+Object.defineProperty(exports, "DEFAULT_AGENT_EXECUTORS", {
 	enumerable: true,
 	get: function() {
-		return GENERATE_TEXT_ACTOR;
+		return DEFAULT_AGENT_EXECUTORS;
 	}
 });
-Object.defineProperty(exports, "INTERPRET_SOURCE", {
+Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
 	enumerable: true,
 	get: function() {
-		return INTERPRET_SOURCE;
+		return GENERATE_TEXT_ACTOR;
 	}
 });
 Object.defineProperty(exports, "STREAM_TEXT_ACTOR", {
@@ -1072,10 +1554,16 @@ Object.defineProperty(exports, "USER_INPUT_ACTOR", {
 		return USER_INPUT_ACTOR;
 	}
 });
-Object.defineProperty(exports, "agentExecutionOptions", {
+Object.defineProperty(exports, "agentMessagesEventSchema", {
 	enumerable: true,
 	get: function() {
-		return agentExecutionOptions;
+		return agentMessagesEventSchema;
+	}
+});
+Object.defineProperty(exports, "appendMessages", {
+	enumerable: true,
+	get: function() {
+		return appendMessages;
 	}
 });
 Object.defineProperty(exports, "assistantMessage", {
@@ -1108,6 +1596,18 @@ Object.defineProperty(exports, "createDecideActor", {
 		return createDecideActor;
 	}
 });
+Object.defineProperty(exports, "createDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return createDecisionLogic;
+	}
+});
+Object.defineProperty(exports, "createDecisionRequest", {
+	enumerable: true,
+	get: function() {
+		return createDecisionRequest;
+	}
+});
 Object.defineProperty(exports, "createTextLogic", {
 	enumerable: true,
 	get: function() {
@@ -1144,10 +1644,10 @@ Object.defineProperty(exports, "getAcceptedEvents", {
 		return getAcceptedEvents;
 	}
 });
-Object.defineProperty(exports, "getAgentMessages", {
+Object.defineProperty(exports, "getAgentExecutionOptions", {
 	enumerable: true,
 	get: function() {
-		return getAgentMessages;
+		return getAgentExecutionOptions;
 	}
 });
 Object.defineProperty(exports, "getAgentOutputMode", {
@@ -1156,6 +1656,12 @@ Object.defineProperty(exports, "getAgentOutputMode", {
 		return getAgentOutputMode;
 	}
 });
+Object.defineProperty(exports, "getCallFinishReason", {
+	enumerable: true,
+	get: function() {
+		return getCallFinishReason;
+	}
+});
 Object.defineProperty(exports, "getCallUsage", {
 	enumerable: true,
 	get: function() {
@@ -1180,16 +1686,16 @@ Object.defineProperty(exports, "getMachineIdlePredicate", {
 		return getMachineIdlePredicate;
 	}
 });
-Object.defineProperty(exports, "getMachineStaticTransitionTargets", {
+Object.defineProperty(exports, "getMachineStructuralHash", {
 	enumerable: true,
 	get: function() {
-		return getMachineStaticTransitionTargets;
+		return getMachineStructuralHash;
 	}
 });
-Object.defineProperty(exports, "getMachineStructuralHash", {
+Object.defineProperty(exports, "getMessageText", {
 	enumerable: true,
 	get: function() {
-		return getMachineStructuralHash;
+		return getMessageText;
 	}
 });
 Object.defineProperty(exports, "getRegisteredAgentExecutionOptions", {
@@ -1204,12 +1710,30 @@ Object.defineProperty(exports, "getStateMeta", {
 		return getStateMeta;
 	}
 });
+Object.defineProperty(exports, "getStatePath", {
+	enumerable: true,
+	get: function() {
+		return getStatePath;
+	}
+});
+Object.defineProperty(exports, "isAgentMessages", {
+	enumerable: true,
+	get: function() {
+		return isAgentMessages;
+	}
+});
 Object.defineProperty(exports, "isDecisionLogic", {
 	enumerable: true,
 	get: function() {
 		return isDecisionLogic;
 	}
 });
+Object.defineProperty(exports, "isRecord", {
+	enumerable: true,
+	get: function() {
+		return isRecord;
+	}
+});
 Object.defineProperty(exports, "isStandardSchema", {
 	enumerable: true,
 	get: function() {
@@ -1234,10 +1758,10 @@ Object.defineProperty(exports, "machineIdlePredicates", {
 		return machineIdlePredicates;
 	}
 });
-Object.defineProperty(exports, "machineStaticTransitionTargets", {
+Object.defineProperty(exports, "messagesSchema", {
 	enumerable: true,
 	get: function() {
-		return machineStaticTransitionTargets;
+		return messagesSchema;
 	}
 });
 Object.defineProperty(exports, "missingActor", {
@@ -1294,6 +1818,12 @@ Object.defineProperty(exports, "resolveMachineVersion", {
 		return resolveMachineVersion;
 	}
 });
+Object.defineProperty(exports, "setAgentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return setAgentExecutionOptions;
+	}
+});
 Object.defineProperty(exports, "systemMessage", {
 	enumerable: true,
 	get: function() {