@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.24

package/dist/{decision-DxSTqzgZ.mjs → decision-BBZ2jMO1.mjs}

@@ -1,6 +1,238 @@
-import { t as AgentError } from "./errors-CeSXQx0v.mjs";
 import { createAsyncLogic, getNextTransitions } from "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
@@ -68,8 +300,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) {
@@ -174,21 +405,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.
+*
+* - 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}'`.
 *
-* 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).
+* 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
@@ -239,7 +486,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
@@ -247,8 +529,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. */
@@ -256,24 +537,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
@@ -291,7 +554,7 @@ function isUnboundPlaceholder(logic) {
 }
 function getRegisteredAgentExecutionOptions(machine, options) {
 	return {
-		...agentExecutionOptions.get(machine),
+		...getAgentExecutionOptions(machine),
 		...options
 	};
 }
@@ -301,8 +564,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
@@ -324,6 +585,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",
@@ -491,7 +773,8 @@ 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);
@@ -503,6 +786,7 @@ function createTextLogic(config, execute) {
 		if (sourceIssue) throw new Error(sourceIssue);
 		return {
 			name,
+			input: parsedInput,
 			model: resolveTextLogicValue(config.model, args),
 			system: resolveTextLogicValue(config.system, args),
 			prompt,
@@ -523,7 +807,7 @@ function createTextLogic(config, execute) {
 	};
 	const logic = 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,
@@ -672,6 +956,7 @@ function parseStructuredEnvelope(request, value) {
 async function executeAgentTextRequest(mode, id, input, executors, tools = {}, info) {
 	const request = {
 		...input,
+		name: input.name ?? id,
 		tools: {
 			...input.tools,
 			...tools
@@ -748,7 +1033,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) {
@@ -785,58 +1094,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
@@ -860,7 +1172,7 @@ function getAcceptedEvents(snapshot, options = {}) {
 	const usedToolNames = /* @__PURE__ */ new Set();
 	return 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({
@@ -882,6 +1194,8 @@ function decideRequestFromInput(input) {
 	return {
 		kind: "decision",
 		id: "",
+		name: input.name,
+		input,
 		model: input.model,
 		system: input.system,
 		prompt: input.prompt,
@@ -963,6 +1277,8 @@ function createDecisionLogic(config, execute) {
 		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),
@@ -982,7 +1298,7 @@ function createDecisionLogic(config, execute) {
 		};
 	};
 	const logic = 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 extract it with getAgentEffects(..., { actors }) and resolveDecision(...).");
+		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.");
@@ -1008,6 +1324,55 @@ 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
@@ -1075,8 +1440,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 } : {}
@@ -1122,4 +1487,4 @@ async function resolveDecision(request, executors, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { getMachineIdlePredicate as A, getAgentMessages as B, normalizeGeneratorResult as C, userInputActor as D, parseStructuredEnvelope as E, machineStaticTransitionTargets as F, isStandardSchema as G, getJsonSchemaSync as H, missingActor as I, toolMessage as J, resolveMachineVersion as K, assistantMessage as L, getRegisteredAgentExecutionOptions as M, isUnboundPlaceholder as N, agentExecutionOptions as O, machineIdlePredicates as P, djb2Hex as R, isTextLogic as S, parseOutput as T, getMachineStructuralHash as U, getJsonSchema as V, getStateMeta as W, validateSchemaSync as X, userMessage as Y, builtinTextActors as _, renderDecisionAttempts as a, getAgentOutputMode as b, parseAgentEvent as c, GENERATE_TEXT_ACTOR as d, INTERPRET_SOURCE as f, buildEnvelopeSchema as g, bindRequestExecutor as h, isDecisionLogic as i, getMachineStaticTransitionTargets as j, executorBoundLogics as k, AGENT_USAGE_TOKEN_FIELDS as l, USER_INPUT_ACTOR as m, createDecideActor as n, resolveDecision as o, STREAM_TEXT_ACTOR as p, systemMessage as q, createDecisionLogic as r, getAcceptedEvents as s, AgentDecisionExhaustedError as t, DECIDE_ACTOR as u, createTextLogic as v, parseModelRef as w, getCallUsage as x, executeAgentTextRequest as y, findNonSerializableContextPaths as z };
+export { userMessage as $, userInputActor as A, assistantMessage as B, getCallFinishReason as C, parseModelRef as D, normalizeGeneratorResult as E, getRegisteredAgentExecutionOptions as F, getMachineStructuralHash as G, findNonSerializableContextPaths as H, isUnboundPlaceholder as I, getStatePath as J, getMessageText as K, machineIdlePredicates as L, executorBoundLogics as M, getAgentExecutionOptions as N, parseOutput as O, getMachineIdlePredicate as P, toolMessage as Q, missingActor as R, getAgentOutputMode as S, isTextLogic as T, getJsonSchema as U, djb2Hex as V, getJsonSchemaSync as W, resolveMachineVersion as X, isStandardSchema as Y, systemMessage as Z, bindRequestExecutor as _, isDecisionLogic as a, messagesSchema as at, createTextLogic as b, AgentInvalidEventPayloadError as c, isRecord as d, validateSchemaSync as et, AGENT_USAGE_TOKEN_FIELDS as f, USER_INPUT_ACTOR as g, STREAM_TEXT_ACTOR as h, createDecisionRequest as i, isAgentMessages as it, DEFAULT_AGENT_EXECUTORS as j, parseStructuredEnvelope as k, getAcceptedEvents as l, GENERATE_TEXT_ACTOR as m, createDecideActor as n, agentMessagesEventSchema as nt, renderDecisionAttempts as o, AgentError as ot, DECIDE_ACTOR as p, getStateMeta as q, createDecisionLogic as r, appendMessages as rt, resolveDecision as s, AgentTruncatedError as st, AgentDecisionExhaustedError as t, AGENT_MESSAGES_EVENT_TYPE as tt, parseAgentEvent as u, buildEnvelopeSchema as v, getCallUsage as w, executeAgentTextRequest as x, builtinTextActors as y, setAgentExecutionOptions as z };