@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/setup-agent-DAZZSjDS.mjs

@@ -0,0 +1,1711 @@
+import { t as AgentError } from "./errors-CeSXQx0v.mjs";
+import { $ as validateSchemaSync, B as missingActor, C as executeAgentTextRequest, E as isTextLogic, I as getRegisteredAgentExecutionOptions, K as getMachineStructuralHash, M as agentExecutionOptions, R as machineStaticTransitionTargets, S as createTextLogic, _ as PLAN_ACTOR, a as createPlanActor, c as isPlanLogic, d as getAcceptedEvents, h as DECIDE_ACTOR, i as createDecideActor, j as userInputActor, n as PLAN_DONE_EVENT_TYPE, p as sanitizeEventToolName, r as advancePlanLedger, s as isDecisionLogic, u as resolveDecision, v as USER_INPUT_ACTOR, w as extractCallUsage, x as builtinTextActors, z as machineSuspensionPredicates } from "./decision-BezSD_YC.mjs";
+import { i as assertAgentLogEntry, o as assertJsonSerializable } from "./event-log-store-D7pWtIhb.mjs";
+import { createMachineFromConfig, initialTransition, setup, transition } from "xstate";
+//#region src/messages.ts
+function addMessages(resolve) {
+	return (args) => {
+		const resolved = typeof resolve === "function" ? resolve(args) : resolve;
+		return [...args.context.messages, ...Array.isArray(resolved) ? resolved : [resolved]];
+	};
+}
+/**
+* Builds a transition-function result that appends one or more
+* {@link AgentMessage}s to a context's `messages` array. `resolve` is either
+* a message (or array of messages) or a function of `{ context, event }`
+* returning them; the returned function is meant to be used directly as (or
+* composed into) a transition's result, e.g. `on: { USER_REPLIED:
+* agent.appendMessages(({ event }) => userMessage(event.text)) }`. Requires
+* `messages: AgentMessage[]` on context — see {@link messagesSchema} for a
+* ready-made schema for that field.
+*
+* @example
+* ```ts
+* on: {
+*   USER_REPLIED: appendMessages(({ event }) => userMessage(event.text)),
+* }
+* ```
+*/
+function appendMessages(resolve) {
+	return (args) => ({ context: { messages: addMessages(resolve)(args) } });
+}
+const KNOWN_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+function isKnownPart(part) {
+	return !!part && typeof part === "object" && KNOWN_PART_TYPES.has(part.type);
+}
+function validatePartsArray(content) {
+	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
+	for (const part of content) if (!isKnownPart(part)) {
+		const type = part && typeof part === "object" ? part.type : void 0;
+		return `Unknown message part type: ${JSON.stringify(type)}`;
+	}
+}
+/**
+* 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 parts with a known `type`. Use it directly as a context
+* schema's `messages` field when authoring with `createAgentSchemas`.
+*/
+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) ?? (content.some((part) => part.type !== "tool-result") ? "tool message content must contain only tool-result parts" : void 0);
+				if (error) return { issues: [{ message: error }] };
+				continue;
+			}
+			if (typeof content === "string") continue;
+			const error = validatePartsArray(content);
+			if (error) return { issues: [{ message: error }] };
+		}
+		return { value };
+	}
+} };
+//#endregion
+//#region src/steps.ts
+/**
+* The step envelope: an INTERNAL, per-model-call-checkpoint view of an agent
+* machine (`AgentStep` = snapshot + actions + discovered requests + done). It
+* once backed a public step API; the public step path is now the thin
+* effect/replay loop in `./effects.ts` (re-exported from `@statelyai/agent/steps`).
+* These helpers survive as internals that `runAgent`, `verify.ts`, and the
+* effect path build on — the only symbol still on the public surface is
+* {@link executeAgentRequest} (the `text`-effect resolver).
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. The hand-passed-schemas
+* implementation detail behind the public {@link getAgentRequests} — it needs
+* `schemas`/`actors` passed explicitly, whereas `getAgentRequests`
+* pre-fills them from the machine's registered `setupAgent` options.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequestsWith(actions, options = {}) {
+	return [...actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	}), ...getActivePlanRequests(options)];
+}
+/**
+* Scans the live snapshot's children for active `agent.plan` (plan-logic)
+* invokes and lowers each into an {@link AgentPlanRequest} — the re-surfacing
+* half of plan discovery. Reads the applied-event trail and remaining budget
+* from the child's own ledger `context` ({@link PlanLedgerContext}), recomputes
+* the currently-legal candidates (∩ declared `allowedEvents`) plus the reserved
+* `agent.plan.done` move, and takes `stepsRemaining` from the ledger (falling
+* back to `maxSteps - applied.length` for a snapshot with no context yet).
+* Returns `[]` when no snapshot is available (candidates need a live snapshot).
+*
+* @internal
+*/
+function getActivePlanRequests(options) {
+	const snapshot = options.snapshot;
+	if (!snapshot) return [];
+	const children = snapshot.children;
+	if (!children) return [];
+	const requests = [];
+	for (const [id, child] of Object.entries(children)) {
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const src = typeof ref.src === "string" ? ref.src : void 0;
+		const logic = (src ? options.actors?.[src] : void 0) ?? ref.logic;
+		if (!isPlanLogic(logic)) continue;
+		const childSnapshot = ref.getSnapshot();
+		if (childSnapshot?.status !== "active") continue;
+		const input = childSnapshot.input ?? {};
+		const maxSteps = input.maxSteps ?? 8;
+		const ledger = childSnapshot.context ?? {};
+		const applied = ledger.applied ?? [];
+		const stepsRemaining = ledger.stepsRemaining ?? maxSteps - applied.length;
+		const machineEvents = getAcceptedEvents(snapshot, {
+			events: options.events,
+			schemas: options.schemas,
+			eventTypes: logic.allowedEventTypes(input) ?? void 0,
+			eventToolName: options.eventToolName
+		});
+		const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, {
+			type: PLAN_DONE_EVENT_TYPE,
+			toolName: sanitizeEventToolName(PLAN_DONE_EVENT_TYPE)
+		}];
+		requests.push({
+			kind: "plan",
+			id,
+			src: src ?? "",
+			input,
+			events,
+			applied,
+			stepsRemaining: Math.max(0, stepsRemaining)
+		});
+	}
+	return requests;
+}
+/**
+* Builds the canonical `xstate.done.actor` event xstate's `transition()`
+* expects to resolve a spawned invoke — including the child session identity
+* that rejects a stale completion from an earlier incarnation.
+*
+* @internal
+*/
+function doneEvent(snapshot, request, output) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.done.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		output
+	};
+}
+/**
+* Applies a request's `output` as a done event via `transition(...)`,
+* returning the raw `[snapshot, actions]` tuple. Lower-level than
+* {@link resolveAgentStep} — that helper wraps this and also runs
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output) {
+	const event = doneEvent(snapshot, request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+async function executeAgentRequest(requestOrEffect, executors, options) {
+	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	const request = "requestId" in requestOrEffect ? {
+		kind: "text",
+		id: requestOrEffect.requestId,
+		src: "",
+		mode: requestOrEffect.mode,
+		input: requestOrEffect.request,
+		tools: requestOrEffect.request.tools ?? {},
+		events: []
+	} : requestOrEffect;
+	assertTextExecutor(request, executors);
+	const { output, raw } = await executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	const normalizedOutput = request.input.outputSchema ? validateSchemaSync(request.input.outputSchema, output) : output;
+	return options?.verbose ? {
+		output: normalizedOutput,
+		raw
+	} : normalizedOutput;
+}
+/**
+* Resolves the current step's pending requests and returns the next
+* {@link AgentStep} — one iteration of the durable step loop, collapsing the
+* manual `request.kind` dispatch a host would otherwise write by hand.
+*
+* For each pending request, in order: a `kind: 'text'` request is run with
+* {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+* `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+* `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+* applied with {@link transitionAgentStep}. The **current** step is re-read
+* after each application — the machine may advance and its `requests` change —
+* so this always resolves against the live step, never a stale list.
+*
+* A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+* step per call. It resolves a single decision from `request.events` (wiring
+* `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+* move and `stopOn` events), then either applies the chosen machine event and
+* lets the next step re-surface the plan, or completes the plan (feeding its
+* `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+* exhausted budget / no legal events. The plan's applied trail is carried in
+* the invoke child's snapshot, so persisting the step between calls resumes the
+* plan identically.
+*
+* Missing the executor a request needs throws a clear error
+* (`generateText`/`streamText` for text, `decide` for decisions and plans).
+*
+* A complete durable host is two lines:
+*
+* ```ts
+* let step = initialAgentStep(machine, input);
+* while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+* ```
+*
+* All pending **text** requests of a step are resolved in parallel
+* (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+* their model calls run concurrently — then their outputs apply in
+* **request-array order** (deterministic for durable replay regardless of which
+* call finishes first). Decisions and plans stay **one at a time**: applying
+* either changes the set of legal candidates for what follows, so they cannot be
+* resolved against a stale snapshot. A host that instead wants strictly
+* sequential text resolution loops the manual per-request helpers
+* ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+*/
+async function resolveAgentRequests(machine, step, executors, options) {
+	const [request] = step.requests;
+	if (!request) return step;
+	if (request.kind === "decision") {
+		if (!executors.decide) throw new Error(`this step's decision request '${request.id}' needs a 'decide' executor but none was provided.`);
+		return transitionAgentStep(machine, step, await resolveDecision(request, executors.decide, {
+			canTake: (event) => step.snapshot.can(event),
+			maxRetries: options?.maxRetries
+		}), options);
+	}
+	if (request.kind === "plan") return resolvePlanRequest(machine, step, request, executors, options);
+	const textRequests = step.requests.filter((candidate) => candidate.kind === "text");
+	for (const textRequest of textRequests) assertTextExecutor(textRequest, executors);
+	const outputs = await Promise.all(textRequests.map((textRequest) => executeAgentRequest(textRequest, executors)));
+	let next = step;
+	for (let index = 0; index < textRequests.length; index++) next = resolveAgentStep(machine, next, textRequests[index], outputs[index], options);
+	return next;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+async function resolvePlanRequest(machine, step, request, executors, options) {
+	if (!executors.decide) throw new Error(`this step's plan request '${request.src}' needs a 'decide' executor but none was provided.`);
+	const stopOn = new Set(request.input.stopOn ?? []);
+	if (request.stepsRemaining <= 0) return completePlan(machine, step, request.id, request.applied, "max-steps", options);
+	if (request.events.filter((event) => event.type !== "agent.plan.done").length === 0) return completePlan(machine, step, request.id, request.applied, "no-legal-events", options);
+	const chosen = await resolveDecision(planStepDecisionRequest(request), executors.decide, {
+		maxRetries: options?.maxRetries,
+		canTake: (event) => {
+			if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+			return step.snapshot.can(event);
+		}
+	});
+	if (chosen.type === "agent.plan.done") return completePlan(machine, step, request.id, request.applied, "done", options);
+	const applied = [...request.applied, chosen];
+	advancePlanChildLedger(step.snapshot, request.id, {
+		type: "plan.applied",
+		event: chosen
+	});
+	const next = transitionAgentStep(machine, step, chosen, options);
+	if (stopOn.has(chosen.type)) {
+		if (isPlanActive(next.snapshot, request.id)) return completePlan(machine, next, request.id, applied, "stop-event", options);
+	}
+	return next;
+}
+function completePlan(machine, step, id, steps, stopped, options) {
+	return resolveAgentStep(machine, step, { id }, {
+		steps,
+		stopped
+	}, options);
+}
+function planStepDecisionRequest(request) {
+	const { input, applied, events, id } = request;
+	const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+	const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${PLAN_DONE_EVENT_TYPE}'.`;
+	return {
+		kind: "decision",
+		id: `${id}[${applied.length}]`,
+		model: input.model,
+		system: input.system,
+		prompt: `${input.prompt ?? ""}${trail}${doneHint}`,
+		messages: input.messages,
+		events,
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function advancePlanChildLedger(snapshot, id, event) {
+	const child = snapshot.children?.[id];
+	const childSnapshot = child?.getSnapshot?.();
+	if (!isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
+	Object.assign(childSnapshot, advancePlanLedger(child.logic, childSnapshot, event));
+}
+function isPlanActive(snapshot, id) {
+	return (snapshot.children?.[id])?.getSnapshot?.()?.status === "active";
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequestsWith(actions, {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+//#region src/effects.ts
+/**
+* The effect/replay path: the library's new append-only-log core. Two
+* primitives sit under every host loop:
+*
+* - {@link getAgentEffects} maps a transition's ordered executable actions
+*   (reconciled with the still-owed effects visible only on the snapshot) into
+*   an ordered {@link AgentEffect} list a host starts at the frontier.
+* - {@link replay} folds a journal of EXTERNAL inputs through xstate's pure
+*   `initialTransition`/`transition` WITHOUT executing anything, returning the
+*   final snapshot plus the effects still owed — crash recovery, fork resume,
+*   and time travel in one function.
+*
+* The journal of external inputs (effect completions with outputs inline, user
+* events, timer firings) is the authoritative artifact; raised/internal events
+* are never journaled (replay re-derives them). A reserved first entry
+* {@link initEntry} carries the machine input so a log is self-contained.
+* @module
+*/
+/**
+* The reserved journal event type of the {@link initEntry} first entry: it
+* carries the machine `input` so a log replays with no side-channel. Named in
+* the `agent.*` builtin-actor namespace so it never collides with a machine's
+* own event vocabulary. Consumed by {@link replay}; never fed to `transition`.
+*/
+const AGENT_INIT_EVENT_TYPE = "@agent.init";
+/**
+* The reserved event type `runAgent` delivers to the running machine after
+* every settled model call that reported usage — the one seam that puts a
+* call's tokens in reach of ordinary `context` and guards, so a token budget
+* is a plain machine transition instead of host bookkeeping.
+*
+* Like {@link AGENT_INIT_EVENT_TYPE} it lives in the reserved `@agent.*`
+* namespace: it can never collide with a machine's own vocabulary, and
+* `getAcceptedEvents`/`parseAgentEvent` never offer it — a model can neither
+* be shown it as a decision candidate nor forge one.
+*
+* Delivery is opt-in BY CONSTRUCTION: the event is sent only when the live
+* snapshot can currently take it (i.e. the machine declares an
+* `'@agent.usage'` transition, usually machine-level `on`). A machine without
+* one sees no extra transition, no extra trace event, and no extra log entry.
+* When it IS taken it rides the event log like any other external input, so
+* events-only recovery (`runAgent({ events })`) replays the folded tokens
+* without re-calling a model.
+*/
+const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
+/**
+* Reads a settled call's token usage off a RAW executor result — the same
+* normalization `runAgent` applies before it delivers
+* {@link AGENT_USAGE_EVENT_TYPE}. Returns `undefined` when the executor
+* reported none.
+*
+* The seam for the step-loop path, where the host holds the raw result itself:
+*
+* ```ts
+* const { output, raw } = await executeAgentRequest(effect, executors, { verbose: true });
+* const usage = getCallUsage(raw);
+* if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+* append(effect.toDoneEvent(output));
+* ```
+*
+* See "Token usage on this path" in docs/steps.md for the full loop.
+*/
+function getCallUsage(raw) {
+	return extractCallUsage(raw);
+}
+/**
+* Creates a JSON-safe, self-describing entry and records the state/effect
+* hashes produced after replaying it. `entries` must be the complete prefix.
+*/
+function createReplayEntry(machine, entries, event, options = {}) {
+	const index = entries.length;
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = options.machineVersion ?? getMachineStructuralHash(machine);
+	const entry = {
+		schemaVersion: 1,
+		id: options.id ?? `evt_${String(index).padStart(8, "0")}`,
+		index,
+		recordedAt: options.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		machineId,
+		machineVersion,
+		event: normalizeEventErrors(event),
+		...options.causationId !== void 0 ? { causationId: options.causationId } : {},
+		...options.correlationId !== void 0 ? { correlationId: options.correlationId } : {},
+		...options.metadata !== void 0 ? { metadata: options.metadata } : {}
+	};
+	assertAgentLogEntry(entry);
+	if (options.verification !== false) {
+		const result = replay(machine, [...entries, entry], {
+			machineVersion,
+			verify: false
+		});
+		entry.verification = replayVerification(result.snapshot, result.effects);
+	}
+	assertAgentLogEntry(entry);
+	return entry;
+}
+/** Reserved first replay entry carrying machine input and verification hashes. */
+function initEntry(machine, input, options = {}) {
+	return createReplayEntry(machine, [], {
+		type: AGENT_INIT_EVENT_TYPE,
+		...input !== void 0 ? { input } : {}
+	}, options);
+}
+/** Normalizes a mixed `EventObject | AgentLogEntry` history into bare events. */
+function toEvents(history) {
+	if (!history) return [];
+	return history.map((entry) => {
+		const candidate = entry;
+		return candidate && typeof candidate === "object" && "event" in candidate && candidate.event ? candidate.event : entry;
+	});
+}
+function rebindActorSession(event, snapshot, sessions) {
+	const actorEvent = event;
+	if (typeof actorEvent.actorId !== "string" || typeof actorEvent.sessionId !== "string") return event;
+	const key = `${actorEvent.actorId}\0${actorEvent.sessionId}`;
+	let sessionId = sessions.get(key);
+	if (!sessionId) {
+		const child = snapshot.children[actorEvent.actorId];
+		if (typeof child?.sessionId !== "string") return event;
+		sessionId = child.sessionId;
+		sessions.set(key, sessionId);
+	}
+	return {
+		...event,
+		sessionId
+	};
+}
+const DONE_ACTOR_EVENT_TYPE = "xstate.done.actor";
+const ERROR_ACTOR_EVENT_TYPE = "xstate.error.actor";
+function isInvokeCompletion(event, id) {
+	return (event.type === DONE_ACTOR_EVENT_TYPE || event.type === ERROR_ACTOR_EVENT_TYPE) && event.actorId === id;
+}
+/**
+* 1-based occurrence for an invoke/spawn site: `1 + completions` (done AND
+* error both count — an error is a semantic completion) for `id` in `events`.
+*/
+function invokeOccurrence(events, id) {
+	let count = 0;
+	for (const event of events) if (isInvokeCompletion(event, id)) count++;
+	return count + 1;
+}
+/** The exact canonical done/error events xstate's actor system delivers for an invoke `id`. */
+function invokeEventMinters(id, snapshot) {
+	const child = snapshot.children[id];
+	const identity = {
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {}
+	};
+	return {
+		toDoneEvent: (output) => ({
+			type: DONE_ACTOR_EVENT_TYPE,
+			output,
+			...identity
+		}),
+		toErrorEvent: (error) => ({
+			type: ERROR_ACTOR_EVENT_TYPE,
+			error,
+			...identity
+		})
+	};
+}
+/** Splits an `xstate.after.<delayKey>.<statePath>` id into its parts. */
+function parseAfterId(afterId) {
+	if (!afterId.startsWith("xstate.after.")) return;
+	const rest = afterId.slice(13);
+	const dot = rest.indexOf(".");
+	if (dot === -1) return;
+	return {
+		delayKey: rest.slice(0, dot),
+		statePath: rest.slice(dot + 1)
+	};
+}
+function buildInvokeEffect(meta, mapped, events, snapshot, options) {
+	const id = typeof meta.id === "string" ? meta.id : void 0;
+	if (!id) return;
+	const requestId = `${id}#${invokeOccurrence(events, id)}`;
+	if (mapped?.kind === "text") return {
+		kind: "text",
+		requestId,
+		request: mapped.input,
+		mode: mapped.mode,
+		...invokeEventMinters(id, snapshot)
+	};
+	if (mapped?.kind === "decision") return {
+		kind: "decision",
+		requestId,
+		request: mapped
+	};
+	if (mapped?.kind === "plan") return {
+		kind: "plan",
+		requestId,
+		request: mapped
+	};
+	const logic = isTextLogic(meta.logic) || isDecisionLogic(meta.logic) || isPlanLogic(meta.logic) ? meta.logic : typeof meta.src === "string" ? options.actors?.[meta.src] : void 0;
+	if (isTextLogic(logic)) return {
+		kind: "text",
+		requestId,
+		request: logic.request(meta.input),
+		mode: logic.mode,
+		...invokeEventMinters(id, snapshot)
+	};
+	if (isDecisionLogic(logic)) {
+		const base = logic.request(meta.input);
+		const eventTypes = logic.allowedEventTypes?.(meta.input);
+		const candidateEvents = getAcceptedEvents(snapshot, {
+			events: options.schemas?.events,
+			schemas: options.schemas,
+			eventTypes
+		});
+		return {
+			kind: "decision",
+			requestId,
+			request: {
+				...base,
+				id,
+				events: candidateEvents
+			}
+		};
+	}
+	return {
+		kind: "task",
+		requestId,
+		id,
+		src: typeof meta.src === "string" ? meta.src : id,
+		input: meta.input,
+		...invokeEventMinters(id, snapshot)
+	};
+}
+/**
+* Maps a transition's ORDERED executable actions (plus the still-owed effects
+* visible only on the snapshot) into an ordered {@link AgentEffect} list the
+* host starts at the frontier.
+*
+* Ordering is load-bearing: a single transition's actions are emitted in
+* document order (a custom entry action, a spawn, and a `sendTo` in that order
+* yield `execute`, then `task`/agent effect, then `execute` — never a
+* reordered set). Effects visible only on the snapshot (an `agent.plan` that
+* re-surfaces every step, and children spawned by an EARLIER transition that
+* have not completed yet — the fan-out / crash-resume case) are appended after
+* the action-derived effects, deduped by site id.
+*
+* Every `requestId` is `${siteId}#${n}`, `n` the 1-based occurrence derived
+* from `options.history` — so the same log yields identical requestIds on every
+* replay. XState alpha.24 prunes a child when its matching completion is
+* folded; the history check also prevents older/restored snapshots from
+* re-surfacing completed work. A re-entered invoke site instead re-derives
+* from the action list each fresh entry (so `#2`, `#3`, … stay correct).
+*/
+function getAgentEffects(machine, snapshot, actions, options = {}) {
+	const resolved = getRegisteredAgentExecutionOptions(machine, options);
+	const events = toEvents(options.history);
+	const requests = getAgentRequestsWith(actions, {
+		...resolved,
+		snapshot
+	});
+	const requestById = new Map(requests.map((request) => [request.id, request]));
+	const effects = [];
+	const emitted = /* @__PURE__ */ new Set();
+	for (const rawAction of actions) {
+		const meta = getInvokeEffectMetadata(rawAction);
+		if (meta) {
+			const effect = buildInvokeEffect(meta, typeof meta.id === "string" ? requestById.get(meta.id) : void 0, events, snapshot, resolved);
+			if (effect && typeof meta.id === "string") {
+				effects.push(effect);
+				emitted.add(meta.id);
+			}
+			continue;
+		}
+		if (rawAction.type === "@xstate.raise" && typeof rawAction.delay === "number") {
+			const afterId = typeof rawAction.id === "string" ? rawAction.id : "";
+			const parsed = parseAfterId(afterId);
+			const siteId = parsed ? `${parsed.statePath}#${parsed.delayKey}` : afterId;
+			const event = {
+				type: "xstate.timer",
+				id: afterId
+			};
+			const firings = events.filter((candidate) => candidate.type === event.type && candidate.id === afterId).length;
+			effects.push({
+				kind: "delay",
+				requestId: `${siteId}#${firings + 1}`,
+				id: afterId,
+				delayMs: rawAction.delay,
+				event
+			});
+			continue;
+		}
+		if (rawAction.type === "@xstate.start" || rawAction.type === "@xstate.stop" || rawAction.type === "@xstate.terminate" || rawAction.type === "@xstate.raise" || rawAction.type === "registerChild") continue;
+		if (typeof rawAction.exec === "function") {
+			const action = rawAction;
+			effects.push({
+				kind: "execute",
+				action: rawAction,
+				exec: () => {
+					action.exec();
+				}
+			});
+		}
+	}
+	for (const request of requests) if (request.kind === "plan" && !emitted.has(request.id)) {
+		effects.push({
+			kind: "plan",
+			requestId: `${request.id}#${invokeOccurrence(events, request.id)}`,
+			request
+		});
+		emitted.add(request.id);
+	}
+	const children = snapshot.children;
+	for (const [id, child] of Object.entries(children ?? {})) {
+		if (emitted.has(id) || invokeOccurrence(events, id) > 1) continue;
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const effect = buildInvokeEffect({
+			id,
+			src: ref.src,
+			input: ref.getSnapshot().input,
+			logic: ref.logic
+		}, requestById.get(id), events, snapshot, resolved);
+		if (effect) {
+			effects.push(effect);
+			emitted.add(id);
+		}
+	}
+	return effects;
+}
+var AgentReplayMachineMismatchError = class extends AgentError {
+	constructor(eventId, index, expected, actual) {
+		super("replay-machine-mismatch", `Replay entry '${eventId}' at index ${index} targets machine '${actual.machineId}'@'${actual.machineVersion}', expected '${expected.machineId}'@'${expected.machineVersion}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentReplayMachineMismatchError";
+	}
+};
+var AgentReplayDivergenceError = class extends AgentError {
+	constructor(eventId, index, kind, expected, actual) {
+		super("replay-divergence", kind === "missing-verification" ? `Replay entry '${eventId}' at index ${index} has no verification hashes.` : `Replay diverged after '${eventId}' at index ${index} (${kind}): expected '${expected}', got '${actual}'.`);
+		this.eventId = eventId;
+		this.index = index;
+		this.kind = kind;
+		this.expected = expected;
+		this.actual = actual;
+		this.name = "AgentReplayDivergenceError";
+	}
+};
+/**
+* Folds a journal through `initialTransition`/`transition` WITHOUT executing
+* anything, then returns the final snapshot plus the still-owed effects
+* ({@link getAgentEffects} of the final frontier, occurrence counts taken from
+* the whole log). Crash recovery, fork resume, and time travel in one call.
+*
+* `entries` is a versioned {@link AgentLogEntry} array. A reserved
+* {@link initEntry} first envelope carries `{ type: '@agent.init', input }`,
+* so a complete log replays with no side-channel; when absent,
+* `options.input` is used instead.
+* Raised/internal events are never in the journal — replay re-derives them
+* deterministically from the machine's own logic.
+*/
+function replay(machine, entries, options = {}) {
+	const machineId = machine.config.id ?? machine.id ?? "(machine)";
+	const machineVersion = options.machineVersion ?? getMachineStructuralHash(machine);
+	const eventIds = /* @__PURE__ */ new Set();
+	for (let index = 0; index < entries.length; index++) {
+		const entry = entries[index];
+		assertAgentLogEntry(entry);
+		if (entry.index !== index) throw new Error(`Replay entries must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
+		if (eventIds.has(entry.id)) throw new Error(`Replay entries contain duplicate event id '${entry.id}'.`);
+		eventIds.add(entry.id);
+		if (entry.machineId !== machineId || entry.machineVersion !== machineVersion) throw new AgentReplayMachineMismatchError(entry.id, entry.index, {
+			machineId,
+			machineVersion
+		}, {
+			machineId: entry.machineId,
+			machineVersion: entry.machineVersion
+		});
+	}
+	const events = toEvents(entries);
+	let input = options.input;
+	let journal = events;
+	let journalEntries = entries;
+	if (events[0]?.type === "@agent.init") {
+		input = events[0].input;
+		journal = events.slice(1);
+		journalEntries = entries.slice(1);
+	}
+	let [snapshot, actions] = initialTransition(machine, input);
+	let effects = getAgentEffects(machine, snapshot, actions, {
+		...options,
+		history: entries.slice(0, events[0]?.type === "@agent.init" ? 1 : 0)
+	});
+	if (events[0]?.type === "@agent.init") verifyEntry(entries[0], snapshot, effects, options.verify);
+	const sessions = /* @__PURE__ */ new Map();
+	for (let index = 0; index < journal.length; index++) {
+		const event = journal[index];
+		const reboundEvent = rebindActorSession(event, snapshot, sessions);
+		[snapshot, actions] = transition(machine, snapshot, reboundEvent);
+		const consumed = entries.slice(0, entries.length - journalEntries.length + index + 1);
+		effects = getAgentEffects(machine, snapshot, actions, {
+			...options,
+			history: consumed
+		});
+		verifyEntry(journalEntries[index], snapshot, effects, options.verify);
+	}
+	return {
+		snapshot,
+		effects
+	};
+}
+/** Requires and checks every entry's recorded state/effect hashes. */
+function verifyReplay(machine, entries, options = {}) {
+	return replay(machine, entries, {
+		...options,
+		verify: "strict"
+	});
+}
+/** Structural event-tail, logical-state, and owed-effect comparison. */
+function diffEventLogs(machine, parentEntries, forkEntries, options = {}) {
+	let commonLength = 0;
+	while (commonLength < parentEntries.length && commonLength < forkEntries.length && stableJson(parentEntries[commonLength]) === stableJson(forkEntries[commonLength])) commonLength++;
+	const parent = replay(machine, parentEntries, options);
+	const fork = replay(machine, forkEntries, options);
+	const parentState = logicalReplayState(parent.snapshot);
+	const forkState = logicalReplayState(fork.snapshot);
+	return {
+		commonPrefix: {
+			length: commonLength,
+			...commonLength > 0 ? { throughEventId: parentEntries[commonLength - 1].id } : {}
+		},
+		parentOnly: parentEntries.slice(commonLength),
+		forkOnly: forkEntries.slice(commonLength),
+		parent,
+		fork,
+		stateChanges: diffJson(parentState, forkState),
+		effectChanges: diffEffects(parent.effects, fork.effects)
+	};
+}
+function verifyEntry(entry, snapshot, effects, mode) {
+	if (mode === false) return;
+	if (!entry.verification) {
+		if (mode === "strict") throw new AgentReplayDivergenceError(entry.id, entry.index, "missing-verification");
+		return;
+	}
+	const actual = replayVerification(snapshot, effects);
+	if (actual.stateHash !== entry.verification.stateHash) throw new AgentReplayDivergenceError(entry.id, entry.index, "state", entry.verification.stateHash, actual.stateHash);
+	if (actual.effectsHash !== entry.verification.effectsHash) throw new AgentReplayDivergenceError(entry.id, entry.index, "effects", entry.verification.effectsHash, actual.effectsHash);
+}
+function replayVerification(snapshot, effects) {
+	return {
+		stateHash: hashStableJson(logicalReplayState(snapshot)),
+		effectsHash: hashStableJson(serializableEffects(effects))
+	};
+}
+function logicalReplayState(snapshot) {
+	const state = {
+		status: snapshot.status,
+		value: snapshot.value,
+		context: snapshot.context
+	};
+	if (snapshot.output !== void 0) state.output = snapshot.output;
+	if (snapshot.error !== void 0) state.error = snapshot.error;
+	const canonical = canonicalizeForHash(state);
+	assertJsonSerializable(canonical, "snapshot");
+	return canonical;
+}
+function serializableEffects(effects) {
+	return effects.map((effect) => canonicalizeEffect(effect));
+}
+function canonicalizeEffect(effect) {
+	if (effect.kind === "execute") return {
+		kind: effect.kind,
+		type: String(effect.action.type)
+	};
+	const value = { ...effect };
+	delete value.toDoneEvent;
+	delete value.toErrorEvent;
+	delete value.exec;
+	delete value.action;
+	return canonicalizeForHash(value);
+}
+function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === void 0) return "[undefined]";
+	if (typeof value === "function") return "[function]";
+	if (typeof value === "bigint") return `[bigint:${String(value)}]`;
+	if (typeof value === "symbol") return `[symbol:${String(value)}]`;
+	if (value === null || typeof value !== "object") return value;
+	if (value instanceof Date) return `[Date:${value.toISOString()}]`;
+	if (value instanceof Error) return {
+		errorName: value.name,
+		message: value.message,
+		...value.cause !== void 0 ? { cause: canonicalizeForHash(value.cause, seen) } : {}
+	};
+	if (value instanceof Set) return [...value].map((item) => canonicalizeForHash(item, seen)).sort((a, b) => stableJson(a).localeCompare(stableJson(b)));
+	if (value instanceof Map) return [...value.entries()].map(([key, item]) => [canonicalizeForHash(key, seen), canonicalizeForHash(item, seen)]).sort(([a], [b]) => stableJson(a).localeCompare(stableJson(b)));
+	if (seen.has(value)) return "[circular]";
+	seen.add(value);
+	if (Array.isArray(value)) {
+		const result = value.map((item) => canonicalizeForHash(item, seen));
+		seen.delete(value);
+		return result;
+	}
+	const standard = value["~standard"];
+	if (standard) {
+		seen.delete(value);
+		return {
+			schemaVendor: standard.vendor,
+			schemaVersion: standard.version
+		};
+	}
+	const result = {};
+	for (const key of Object.keys(value).sort()) result[key] = canonicalizeForHash(value[key], seen);
+	seen.delete(value);
+	return result;
+}
+function normalizeEventErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
+	if (value instanceof Error) {
+		const normalized = {
+			name: value.name,
+			message: value.message
+		};
+		seen.set(value, normalized);
+		if (value.cause !== void 0) normalized.cause = normalizeEventErrors(value.cause, seen);
+		return normalized;
+	}
+	if (value === null || typeof value !== "object") return value;
+	const existing = seen.get(value);
+	if (existing !== void 0) return existing;
+	if (Array.isArray(value)) {
+		const result = [];
+		seen.set(value, result);
+		for (const item of value) result.push(normalizeEventErrors(item, seen));
+		return result;
+	}
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return value;
+	const result = {};
+	seen.set(value, result);
+	for (const [key, item] of Object.entries(value)) result[key] = normalizeEventErrors(item, seen);
+	return result;
+}
+function stableJson(value) {
+	return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+	if (Array.isArray(value)) return value.map(sortJson);
+	if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+	return value;
+}
+function hashStableJson(value) {
+	const input = stableJson(value);
+	let hash = 5381;
+	for (let index = 0; index < input.length; index++) hash = (hash << 5) + hash + input.charCodeAt(index) | 0;
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function diffJson(before, after, path = "") {
+	if (stableJson(before) === stableJson(after)) return [];
+	if (before === null || after === null || typeof before !== "object" || typeof after !== "object" || Array.isArray(before) || Array.isArray(after)) return [{
+		op: "replace",
+		path,
+		value: after
+	}];
+	const changes = [];
+	const beforeObject = before;
+	const afterObject = after;
+	const keys = new Set([...Object.keys(beforeObject), ...Object.keys(afterObject)]);
+	for (const key of [...keys].sort()) {
+		const childPath = `${path}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+		if (!(key in afterObject)) changes.push({
+			op: "remove",
+			path: childPath
+		});
+		else if (!(key in beforeObject)) changes.push({
+			op: "add",
+			path: childPath,
+			value: afterObject[key]
+		});
+		else changes.push(...diffJson(beforeObject[key], afterObject[key], childPath));
+	}
+	return changes;
+}
+function diffEffects(before, after) {
+	const beforeValues = serializableEffects(before);
+	const afterValues = serializableEffects(after);
+	const key = (value, index) => {
+		const record = value;
+		return typeof record.requestId === "string" ? record.requestId : `${String(record.kind ?? "effect")}:${index}`;
+	};
+	const beforeMap = new Map(beforeValues.map((value, index) => [key(value, index), value]));
+	const afterMap = new Map(afterValues.map((value, index) => [key(value, index), value]));
+	const added = [];
+	const removed = [];
+	const changed = [];
+	for (const [id, value] of beforeMap) {
+		const next = afterMap.get(id);
+		if (next === void 0) removed.push(value);
+		else if (stableJson(value) !== stableJson(next)) changed.push({
+			before: value,
+			after: next
+		});
+	}
+	for (const [id, value] of afterMap) if (!beforeMap.has(id)) added.push(value);
+	return {
+		added,
+		removed,
+		changed
+	};
+}
+//#endregion
+//#region src/workflow-config.ts
+/**
+* The machines-as-data lowering: `setupAgent(...).fromConfig(config, options)`.
+*
+* Takes a serializable `AgentWorkflowConfig` (the JSON form of an agent
+* machine — published schema at `schemas/agent-workflow.json`, docs at
+* docs/machines-as-data.md), compiles its embedded JSON Schemas with the
+* host-provided `compileSchema`, resolves named guards/actions/actors from
+* `options`, and lowers the whole thing to an ordinary XState machine plus its
+* schema pack. This is what makes LLM-generated and stored-as-JSON machines
+* first-class: the config validates against the shipped schema before any
+* model call, and the resulting machine lints, simulates, and runs like a
+* hand-authored one.
+*/
+const DECIDE_SRC = "agent.decide";
+const workflowConfigWholeExpressionPattern = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
+const workflowConfigTemplateExpressionPattern = /\{\{\s*([\s\S]*?)\s*\}\}/g;
+const workflowConfigHasTemplatePattern = /\{\{[\s\S]*?\}\}/;
+function evaluateWorkflowConfigPath(expression, scope) {
+	const parts = expression.trim().split(".").filter(Boolean);
+	let current = scope;
+	for (const part of parts) {
+		if (!current || typeof current !== "object") return;
+		current = current[part];
+	}
+	return current;
+}
+function evaluateWorkflowConfigValue(value, scope) {
+	if (typeof value === "string") {
+		const wholeMatch = value.match(workflowConfigWholeExpressionPattern);
+		if (wholeMatch?.[1]) return evaluateWorkflowConfigPath(wholeMatch[1], scope);
+		return value.replace(workflowConfigTemplateExpressionPattern, (_match, expression) => {
+			const resolved = evaluateWorkflowConfigPath(expression, scope);
+			return resolved === void 0 || resolved === null ? "" : String(resolved);
+		});
+	}
+	if (Array.isArray(value)) return value.map((item) => evaluateWorkflowConfigValue(item, scope));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, evaluateWorkflowConfigValue(item, scope)]));
+	return value;
+}
+function createSchemasFromWorkflowConfig(config, compileSchema) {
+	return createAgentSchemas({
+		context: compileSchema(config.schemas?.context ?? { type: "object" }, "context"),
+		events: Object.fromEntries(Object.entries(config.schemas?.events ?? {}).map(([key, schema]) => [key, compileSchema(schema, `event.${key}`)])),
+		emitted: Object.fromEntries(Object.entries(config.schemas?.emitted ?? {}).map(([key, schema]) => [key, compileSchema(schema, `emitted.${key}`)])),
+		input: compileSchema(config.schemas?.input ?? {}, "input"),
+		output: compileSchema(config.schemas?.output ?? {}, "output"),
+		meta: compileSchema(config.schemas?.meta ?? {}, "meta")
+	});
+}
+function createRequestsFromWorkflowConfig(config, compileSchema) {
+	return Object.fromEntries(Object.entries(config.requests ?? {}).map(([key, request]) => [key, {
+		mode: request.mode,
+		description: request.description,
+		schemas: {
+			input: compileSchema(request.input, `${key}.input`),
+			output: compileSchema(request.output, `${key}.output`)
+		},
+		model: ({ input }) => String(evaluateWorkflowConfigValue(request.model, { input }) ?? ""),
+		system: request.system === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.system, { input }),
+		prompt: request.prompt === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.prompt, { input }),
+		messages: request.messages === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.messages, { input }),
+		tools: request.tools,
+		toolChoice: request.toolChoice,
+		reasoning: request.reasoning,
+		temperature: request.temperature === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.temperature, { input }),
+		maxOutputTokens: request.maxOutputTokens === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.maxOutputTokens, { input }),
+		topP: request.topP === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topP, { input }),
+		topK: request.topK === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topK, { input }),
+		seed: request.seed === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.seed, { input }),
+		stopSequences: request.stopSequences === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.stopSequences, { input }),
+		metadata: request.metadata === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.metadata, { input })
+	}]));
+}
+function createActorPlaceholdersFromWorkflowConfig(config) {
+	return Object.fromEntries(Object.keys(config.actors ?? {}).map((key) => [key, missingActor(key)]));
+}
+const AGENT_EXPRESSION_LANG = "agent-template";
+function containsTemplateExpression(value) {
+	if (typeof value === "string") return workflowConfigHasTemplatePattern.test(value);
+	if (Array.isArray(value)) return value.some(containsTemplateExpression);
+	if (value && typeof value === "object") return Object.values(value).some(containsTemplateExpression);
+	return false;
+}
+function toWorkflowExpression(value) {
+	if (!containsTemplateExpression(value)) return value;
+	return { "@expr": JSON.stringify(value) };
+}
+function createWorkflowConfigEvaluator(contextSchema) {
+	const decoded = /* @__PURE__ */ new Map();
+	const decode = (source) => {
+		if (!decoded.has(source)) decoded.set(source, JSON.parse(source));
+		return decoded.get(source);
+	};
+	return ({ source, slot, scope }) => {
+		const value = decode(source);
+		if (slot === "context") return validateSchemaSync(contextSchema, evaluateWorkflowConfigValue(value, { input: scope.input }));
+		return evaluateWorkflowConfigValue(value, {
+			context: scope.context,
+			event: scope.event,
+			input: scope.input
+		});
+	};
+}
+function translateWorkflowGuard(guard, translation, location) {
+	if (guard === void 0) return;
+	if (typeof guard === "string") {
+		if (workflowConfigHasTemplatePattern.test(guard)) return { "@expr": JSON.stringify(guard) };
+		if (!(guard in translation.guards)) throw new Error(`setupAgent.fromConfig: ${location} references guard '${guard}', which has no implementation. Provide one via fromConfig options: setupAgent.fromConfig(config, { guards: { '${guard}': ({ context, event }) => ... } }).`);
+		return { type: guard };
+	}
+	if (typeof guard === "function") {
+		const name = `__fromConfigGuard${Object.keys(translation.syntheticGuards).length}`;
+		translation.syntheticGuards[name] = guard;
+		return { type: name };
+	}
+	throw new Error(`setupAgent.fromConfig: ${location} has an unsupported guard value. Use a '{{ ... }}' template string, a named guard reference (string), or a function.`);
+}
+function translateWorkflowAction(action, translation, location) {
+	if (action.assign !== void 0) return {
+		type: "@xstate.assign",
+		context: toWorkflowExpression(action.assign)
+	};
+	if (action.emit !== void 0) return {
+		type: "@xstate.emit",
+		event: toWorkflowExpression(action.emit)
+	};
+	if (action.type) {
+		if (!(action.type in translation.actions)) throw new Error(`setupAgent.fromConfig: ${location} uses named action type '${action.type}', which has no implementation. Provide one via fromConfig options: setupAgent.fromConfig(config, { actions: { '${action.type}': (params) => ... } }).`);
+		return {
+			type: action.type,
+			...action.params !== void 0 ? { params: toWorkflowExpression(action.params) } : {}
+		};
+	}
+	throw new Error(`setupAgent.fromConfig: ${location} action must declare 'assign', 'emit', or 'type'.`);
+}
+function translateWorkflowTransition(transitionConfig, translation, location) {
+	const actionConfigs = transitionConfig.actions ? Array.isArray(transitionConfig.actions) ? transitionConfig.actions : [transitionConfig.actions] : [];
+	const assignConfigs = [...transitionConfig.assign !== void 0 ? [transitionConfig.assign] : [], ...actionConfigs.filter((action) => action.assign !== void 0).map((action) => action.assign)];
+	const contextPatch = assignConfigs.length ? toWorkflowExpression(Object.assign({}, ...assignConfigs)) : void 0;
+	const actions = actionConfigs.filter((action) => action.assign === void 0).map((action) => translateWorkflowAction(action, translation, location));
+	const guard = translateWorkflowGuard(transitionConfig.guard, translation, location);
+	return {
+		...transitionConfig.target !== void 0 ? { target: transitionConfig.target } : {},
+		...guard ? { guard } : {},
+		...contextPatch !== void 0 ? { context: contextPatch } : {},
+		...actions.length ? { actions } : {},
+		...transitionConfig.description !== void 0 ? { description: transitionConfig.description } : {},
+		...transitionConfig.reenter !== void 0 ? { reenter: transitionConfig.reenter } : {},
+		...transitionConfig.meta !== void 0 ? { meta: transitionConfig.meta } : {}
+	};
+}
+function translateWorkflowTransitions(transitionConfig, translation, location) {
+	if (!transitionConfig) return;
+	return Array.isArray(transitionConfig) ? transitionConfig.map((candidate) => translateWorkflowTransition(candidate, translation, location)) : translateWorkflowTransition(transitionConfig, translation, location);
+}
+function addTransitionMatch(transition, matches) {
+	if (Array.isArray(transition)) return transition.map((candidate) => addTransitionMatch(candidate, matches));
+	return transition ? {
+		...transition,
+		matches: {
+			...transition.matches,
+			...matches
+		}
+	} : void 0;
+}
+function translateWorkflowInvoke(invokeConfig, translation, stateKey) {
+	if (invokeConfig.src === DECIDE_SRC && invokeConfig.onDone !== void 0) throw new Error(`setupAgent.fromConfig: state '${stateKey}' declares an 'onDone' on its 'agent.decide' invoke, which is always a config error. A decision has no output of its own — the chosen event is delivered automatically and handled by the state's 'on' transitions. Remove the 'onDone' (use 'on' for the chosen event; 'onError' still handles retries exhausted).`);
+	const location = `state '${stateKey}'`;
+	return {
+		...invokeConfig.id !== void 0 ? { id: invokeConfig.id } : {},
+		src: invokeConfig.src,
+		...invokeConfig.input !== void 0 ? { input: toWorkflowExpression(invokeConfig.input) } : {},
+		...invokeConfig.onDone !== void 0 ? { onDone: translateWorkflowTransitions(invokeConfig.onDone, translation, location) } : {},
+		...invokeConfig.onError !== void 0 ? { onError: translateWorkflowTransitions(invokeConfig.onError, translation, location) } : {}
+	};
+}
+function assertValidTransitionTargets(stateKey, location, transitionConfig, siblingKeys, declaredTargets) {
+	if (!transitionConfig) return;
+	const transitions = Array.isArray(transitionConfig) ? transitionConfig : [transitionConfig];
+	for (const transition of transitions) {
+		const targets = transition.target === void 0 ? [] : Array.isArray(transition.target) ? transition.target : [transition.target];
+		for (const target of targets) {
+			if (typeof target !== "string") continue;
+			declaredTargets.push(target);
+			if (target.startsWith("#") || target.startsWith(".")) continue;
+			const head = target.split(".")[0];
+			if (!siblingKeys.has(head)) throw new Error(`setupAgent.fromConfig: state '${stateKey}' has a ${location} transition targeting '${target}', which is not a state at that level. Valid targets: ${[...siblingKeys].join(", ") || "(none)"}.`);
+		}
+	}
+}
+function assertStateTransitionTargets(stateKey, stateConfig, siblingKeys) {
+	const declaredTargets = [];
+	for (const [eventType, transition] of Object.entries(stateConfig.on ?? {})) assertValidTransitionTargets(stateKey, `'on.${eventType}'`, transition, siblingKeys, declaredTargets);
+	for (const [delay, transition] of Object.entries(stateConfig.after ?? {})) assertValidTransitionTargets(stateKey, `'after.${delay}'`, transition, siblingKeys, declaredTargets);
+	assertValidTransitionTargets(stateKey, "'always'", stateConfig.always, siblingKeys, declaredTargets);
+	assertValidTransitionTargets(stateKey, "'onDone'", stateConfig.onDone, siblingKeys, declaredTargets);
+	assertValidTransitionTargets(stateKey, "'choice'", stateConfig.choice, siblingKeys, declaredTargets);
+	const invokes = stateConfig.invoke ? Array.isArray(stateConfig.invoke) ? stateConfig.invoke : [stateConfig.invoke] : [];
+	for (const invoke of invokes) {
+		assertValidTransitionTargets(stateKey, "invoke 'onDone'", invoke.onDone, siblingKeys, declaredTargets);
+		assertValidTransitionTargets(stateKey, "invoke 'onError'", invoke.onError, siblingKeys, declaredTargets);
+	}
+	return declaredTargets;
+}
+function translateWorkflowState(stateKey, stateConfig, siblingKeys, path, translation) {
+	const location = `state '${stateKey}'`;
+	if (stateKey.includes(".")) throw new Error(`setupAgent.fromConfig: state key '${stateKey}' contains a '.', which is reserved as the state-path separator. Rename the state (e.g. '${stateKey.replace(/\./g, "_")}').`);
+	const childKeys = new Set(Object.keys(stateConfig.states ?? {}));
+	const childPath = [...path, stateKey];
+	translation.transitionTargets[childPath.join(".")] = assertStateTransitionTargets(stateKey, stateConfig, siblingKeys);
+	const doneStateId = stateConfig.onDone !== void 0 ? `@state.${childPath.join(".")}` : void 0;
+	const translatedOn = {
+		...Object.fromEntries(Object.entries(stateConfig.on ?? {}).map(([eventType, transitionConfig]) => [eventType, translateWorkflowTransitions(transitionConfig, translation, location)])),
+		...doneStateId ? { "xstate.done.state": addTransitionMatch(translateWorkflowTransitions(stateConfig.onDone, translation, location), { stateId: doneStateId }) } : {}
+	};
+	return {
+		...stateConfig.description !== void 0 ? { description: stateConfig.description } : {},
+		...stateConfig.type !== void 0 ? { type: stateConfig.type } : {},
+		...doneStateId ? { id: doneStateId } : {},
+		...stateConfig.initial !== void 0 ? { initial: stateConfig.initial } : {},
+		...stateConfig.states !== void 0 ? { states: Object.fromEntries(Object.entries(stateConfig.states).map(([key, child]) => [key, translateWorkflowState(key, child, childKeys, childPath, translation)])) } : {},
+		...stateConfig.choice !== void 0 ? { choice: (Array.isArray(stateConfig.choice) ? stateConfig.choice : [stateConfig.choice]).map((branch) => {
+			if (branch.actions !== void 0) throw new Error(`setupAgent.fromConfig: state '${stateKey}' has a 'choice' branch with 'actions', which is not supported. Use 'assign' on the branch, or move the actions to the target state's 'entry'.`);
+			const when = translateWorkflowGuard(branch.guard, translation, location);
+			return {
+				...when ? { when } : {},
+				target: branch.target,
+				...branch.assign !== void 0 ? { context: toWorkflowExpression(branch.assign) } : {},
+				...branch.description !== void 0 ? { description: branch.description } : {},
+				...branch.reenter !== void 0 ? { reenter: branch.reenter } : {},
+				...branch.meta !== void 0 ? { meta: branch.meta } : {}
+			};
+		}) } : {},
+		...stateConfig.invoke !== void 0 ? { invoke: Array.isArray(stateConfig.invoke) ? stateConfig.invoke.map((invoke) => translateWorkflowInvoke(invoke, translation, stateKey)) : translateWorkflowInvoke(stateConfig.invoke, translation, stateKey) } : {},
+		...Object.keys(translatedOn).length ? { on: translatedOn } : {},
+		...stateConfig.always !== void 0 ? { always: translateWorkflowTransitions(stateConfig.always, translation, location) } : {},
+		...stateConfig.after !== void 0 ? { after: Object.fromEntries(Object.entries(stateConfig.after).map(([delay, transitionConfig]) => [delay, translateWorkflowTransitions(transitionConfig, translation, location)])) } : {},
+		...stateConfig.entry !== void 0 ? { entry: (Array.isArray(stateConfig.entry) ? stateConfig.entry : [stateConfig.entry]).map((action) => translateWorkflowAction(action, translation, location)) } : {},
+		...stateConfig.exit !== void 0 ? { exit: (Array.isArray(stateConfig.exit) ? stateConfig.exit : [stateConfig.exit]).map((action) => translateWorkflowAction(action, translation, location)) } : {},
+		...stateConfig.tags !== void 0 ? { tags: stateConfig.tags } : {},
+		...stateConfig.output !== void 0 ? { output: toWorkflowExpression(stateConfig.output) } : {},
+		...stateConfig.meta !== void 0 ? { meta: stateConfig.meta } : {}
+	};
+}
+function collectTranslatedFinalOutputs(states, outputs = []) {
+	for (const state of Object.values(states ?? {})) {
+		if (state?.type === "final" && state.output !== void 0) outputs.push(state.output);
+		collectTranslatedFinalOutputs(state?.states, outputs);
+	}
+	return outputs;
+}
+function translateWorkflowConfig(config, translation) {
+	const rootKeys = new Set(Object.keys(config.states));
+	const states = Object.fromEntries(Object.entries(config.states).map(([key, state]) => [key, translateWorkflowState(key, state, rootKeys, [], translation)]));
+	const json = {
+		"@exprLang": AGENT_EXPRESSION_LANG,
+		...config.id !== void 0 ? { id: config.id } : {},
+		...config.description !== void 0 ? { description: config.description } : {},
+		...config.context !== void 0 ? { context: { "@expr": JSON.stringify(config.context) } } : {},
+		initial: config.initial,
+		states,
+		...config.meta !== void 0 ? { meta: config.meta } : {}
+	};
+	const finalOutputs = collectTranslatedFinalOutputs(states);
+	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
+	return json;
+}
+function setupAgentFromConfig(config, options) {
+	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
+	const { compileSchema } = options;
+	const schemas = createSchemasFromWorkflowConfig(config, compileSchema);
+	const requestActors = createRequestActors(createRequestsFromWorkflowConfig(config, compileSchema));
+	const actors = createAgentActors(createActorPlaceholdersFromWorkflowConfig(config), requestActors);
+	const translation = {
+		guards: options.guards ?? {},
+		actions: options.actions ?? {},
+		syntheticGuards: {},
+		transitionTargets: {}
+	};
+	const machine = createMachineFromConfig(translateWorkflowConfig(config, translation), {
+		guards: Object.fromEntries(Object.entries({
+			...translation.guards,
+			...translation.syntheticGuards
+		}).map(([name, implementation]) => [name, (args) => Boolean(implementation({
+			context: args.context,
+			event: args.event
+		}))])),
+		...options.actions ? { actions: options.actions } : {},
+		actors: Object.fromEntries(Object.keys(actors).map((key) => [key, key])),
+		evaluators: { [AGENT_EXPRESSION_LANG]: createWorkflowConfigEvaluator(schemas.context) }
+	}).provide({ actors });
+	agentExecutionOptions.set(machine, {
+		schemas,
+		actors,
+		models: {}
+	});
+	if (machine.config) machineStaticTransitionTargets.set(machine.config, translation.transitionTargets);
+	return {
+		machine,
+		schemas
+	};
+}
+//#endregion
+//#region src/setup-agent.ts
+const emptyEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return value !== null && typeof value === "object" && Object.keys(value).length === 0 ? { value: {} } : { issues: [{ message: "Expected an empty event payload" }] };
+	}
+} };
+const USAGE_TOKEN_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"totalTokens",
+	"reasoningTokens",
+	"cachedInputTokens"
+];
+const USAGE_ATTRIBUTION_FIELDS = [
+	"id",
+	"src",
+	"model",
+	"name"
+];
+const USAGE_KINDS = [
+	"text",
+	"decision",
+	"plan"
+];
+/**
+* Standard Schema for the reserved `'@agent.usage'` payload. Hand-rolled (no
+* validation-library dependency in core) and deliberately permissive about
+* unknown fields, so a newer runtime adding an attribution field cannot fail
+* an older machine's validation.
+*/
+const agentUsageEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		const issues = [];
+		if (!value || typeof value !== "object") return { issues: [{ message: "Expected an '@agent.usage' payload object" }] };
+		const event = value;
+		const usage = event.usage;
+		if (!usage || typeof usage !== "object") issues.push({
+			message: "Expected 'usage' to be an object",
+			path: ["usage"]
+		});
+		else for (const field of USAGE_TOKEN_FIELDS) {
+			const token = usage[field];
+			if (token !== void 0 && (typeof token !== "number" || !Number.isFinite(token))) issues.push({
+				message: `Expected a finite number`,
+				path: ["usage", field]
+			});
+		}
+		if (event.kind !== void 0 && !USAGE_KINDS.includes(event.kind)) issues.push({
+			message: `Expected one of ${USAGE_KINDS.join(", ")}`,
+			path: ["kind"]
+		});
+		for (const field of USAGE_ATTRIBUTION_FIELDS) if (event[field] !== void 0 && typeof event[field] !== "string") issues.push({
+			message: "Expected a string",
+			path: [field]
+		});
+		return issues.length > 0 ? { issues } : { value: event };
+	}
+} };
+/**
+* Adds the reserved `'@agent.usage'` schema to an authored event map. A
+* user-declared entry under that key is rejected: the `@agent.*` namespace
+* belongs to the library (same rule as the reserved `agent.*` actor keys), and
+* a custom payload schema would silently disagree with what `runAgent`
+* delivers.
+*/
+function withAgentUsageEventSchema(events) {
+	const declared = events?.[AGENT_USAGE_EVENT_TYPE];
+	if (declared !== void 0 && declared !== agentUsageEventSchema) throw new Error(`setupAgent: event type '${AGENT_USAGE_EVENT_TYPE}' is in the reserved '@agent.' namespace and cannot be declared in 'events' — setupAgent registers it for you with the usage payload schema. Remove it from 'events'; to receive it, declare a transition instead: on: { '${AGENT_USAGE_EVENT_TYPE}': … }.`);
+	return {
+		...events,
+		[AGENT_USAGE_EVENT_TYPE]: agentUsageEventSchema
+	};
+}
+function normalizeEventSchemas(events) {
+	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
+}
+/**
+* Builds a machine's {@link AgentSchemaPack} from a partial schema
+* declaration — only `context` is required; `events`/`input`/`output`/`meta`
+* default to empty/unknown schemas when omitted. Pass the result as
+* `setupAgent({ schemas })`'s `schemas` (or spread the individual fields
+* directly into `setupAgent({ context, events, ... })` — both forms are
+* accepted).
+*/
+function createAgentSchemas(schemas) {
+	return {
+		context: schemas.context,
+		events: normalizeEventSchemas(withAgentUsageEventSchema(schemas.events)),
+		input: schemas.input,
+		output: schemas.output,
+		meta: schemas.meta,
+		emitted: schemas.emitted
+	};
+}
+function mergeContextSchema(base, fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			const baseResult = base["~standard"].validate(value);
+			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+			if (baseResult.issues) return baseResult;
+			const merged = { ...baseResult.value };
+			const issues = [];
+			for (const [key, fieldSchema] of Object.entries(fields)) {
+				const fieldResult = fieldSchema["~standard"].validate(value[key]);
+				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
+					...issue,
+					path: [key, ...issue.path ?? []]
+				})));
+				else merged[key] = fieldResult.value;
+			}
+			return issues.length > 0 ? { issues } : { value: merged };
+		}
+	} };
+}
+function resolveAgentStateSchemas(contextSchema, states) {
+	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
+		if (!state || typeof state !== "object") return [key, state];
+		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
+		if ("context" in state && state.context) return [key, {
+			schemas: { context: mergeContextSchema(contextSchema, state.context) },
+			...children ? { states: children } : {}
+		}];
+		return [key, children ? {
+			...state,
+			states: children
+		} : state];
+	}));
+}
+/**
+* Schema-first `setup(...)` for agent machines — the standard entry point
+* for authoring a machine (the blueprint) that this library then runs (via
+* {@link runAgent} or the step helpers) against host-supplied model/decision
+* executors. Context, events, machine input, machine output, and
+* state/transition meta are all standard schemas — no `{} as Type` casts —
+* and are retained on `result.schemas` for runtime validation. Also
+* registers the `agent.generateText`/`agent.streamText`/`agent.userInput`/
+* `agent.decide`/`agent.plan` builtin actors and lowers `requests`/`actors` into the
+* machine's actor sources. The result is the xstate `setup(...)` object with
+* a wrapped `result.createMachine(...)` plus `result.schemas`/`models`/
+* `requests`/`appendMessages` attached. Also has a
+* `setupAgent.fromConfig(...)` namespace member for building a machine from
+* a serializable {@link AgentWorkflowConfig} instead of this TS API.
+*
+* @example
+* ```ts
+* const schemas = createAgentSchemas({
+*   context: z.object({ topic: z.string(), joke: z.string().nullable() }),
+*   input: z.object({ topic: z.string() }),
+*   output: z.object({ joke: z.string() }),
+* });
+*
+* const agent = setupAgent({
+*   schemas,
+*   actors: { tellJoke },
+* });
+*
+* const jokeMachine = agent.createMachine({
+*   context: ({ input }) => ({ topic: input.topic, joke: null }),
+*   initial: 'telling',
+*   states: {
+*     telling: {
+*       invoke: {
+*         id: 'joke',
+*         src: 'tellJoke',
+*         input: ({ context }) => ({ topic: context.topic }),
+*         onDone: ({ output }) => ({ target: 'done', context: { joke: output } }),
+*       },
+*     },
+*     done: { type: 'final', output: ({ context }) => ({ joke: context.joke ?? '' }) },
+*   },
+* });
+* ```
+*/
+function setupAgent(config) {
+	return createSetupAgent(config);
+}
+function collectFinalStateOutputs(states, outputs = []) {
+	for (const state of Object.values(states ?? {})) {
+		if (state?.type === "final" && state.output !== void 0) outputs.push(state.output);
+		collectFinalStateOutputs(state?.states, outputs);
+	}
+	return outputs;
+}
+function withRootOutputFromSingleFinal(config) {
+	if (!config || typeof config !== "object" || "output" in config || !("states" in config)) return config;
+	const outputs = collectFinalStateOutputs(config.states);
+	return outputs.length === 1 ? {
+		...config,
+		output: outputs[0]
+	} : config;
+}
+(function(_setupAgent) {
+	function fromConfig(config, options) {
+		return setupAgentFromConfig(config, options);
+	}
+	_setupAgent.fromConfig = fromConfig;
+})(setupAgent || (setupAgent = {}));
+/** Builds one TextLogic actor per `setupAgent({ requests })` entry. @internal */
+function createRequestActors(requests) {
+	return Object.fromEntries(Object.entries(requests).map(([key, request]) => {
+		return [key, createTextLogic({
+			...request,
+			name: key,
+			mode: request.mode ?? "generate"
+		})];
+	}));
+}
+function normalizeAgentSchemas(config) {
+	if ("schemas" in config && config.schemas) return {
+		...config.schemas,
+		events: normalizeEventSchemas(withAgentUsageEventSchema(config.schemas.events))
+	};
+	const loose = config;
+	return createAgentSchemas({
+		...loose,
+		context: loose.context
+	});
+}
+function normalizeAgentRequestInput(requests) {
+	return requests ?? {};
+}
+/**
+* Runtime guard: a key appearing in both `actors`/`requests` is almost
+* certainly a mistake (whichever spread applies last would silently win) —
+* fail fast with a clear message rather than let one implementation shadow
+* another.
+*/
+function assertNoActorKeyCollisions(actors, requests) {
+	const seenIn = /* @__PURE__ */ new Map();
+	const groups = [["actors", actors], ["requests", requests]];
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
+		const existingGroup = seenIn.get(key);
+		if (existingGroup) throw new Error(`setupAgent: key '${key}' is defined in both '${existingGroup}' and '${groupName}'. Each actor source key must be unique across 'actors' and 'requests'.`);
+		seenIn.set(key, groupName);
+	}
+}
+/**
+* Runtime guard: every key of the `setupAgent({ states })` narrowing map must
+* name a real state node in the machine config. A typo'd key is otherwise a
+* silent no-op — the narrowing simply never applies — so fail fast at
+* `createMachine` time. Walks nested `states` maps in parallel with the
+* machine config, since narrowing entries nest the same way.
+*/
+function assertStateSchemaKeysExist(stateSchemas, machineStates, path = []) {
+	if (!stateSchemas) return;
+	for (const [key, stateSchema] of Object.entries(stateSchemas)) {
+		const machineState = machineStates?.[key];
+		if (!machineState || typeof machineState !== "object") {
+			const validKeys = Object.keys(machineStates ?? {});
+			const parent = path.length > 0 ? ` of state '${path.join(".")}'` : "";
+			throw new Error(`setupAgent: 'states' key '${[...path, key].join(".")}' does not name a state in the machine config, so its context narrowing would silently never apply. Valid child states${parent}: ${validKeys.join(", ") || "(none)"}. Fix the key to match a state in createMachine({ states }), or remove it from setupAgent({ states }).`);
+		}
+		if (stateSchema && typeof stateSchema === "object" && "states" in stateSchema && stateSchema.states) assertStateSchemaKeysExist(stateSchema.states, machineState.states, [...path, key]);
+	}
+}
+const RESERVED_AGENT_ACTOR_KEYS = [
+	...Object.keys(builtinTextActors),
+	USER_INPUT_ACTOR,
+	DECIDE_ACTOR,
+	PLAN_ACTOR
+];
+/**
+* Rejects a user-supplied `actors`/`requests` key in the reserved
+* `agent.*` builtin namespace. Without this, the builtins-first spread in
+* {@link createAgentActors} lets such a key overwrite the builtin
+* (`agent.decide`, `agent.plan`, …) silently. Deliberate override of a builtin
+* is still possible after the machine is created, via
+* `machine.provide({ actors: { 'agent.decide': ... } })`.
+*/
+function assertNoReservedAgentKeys(actors, requests) {
+	const groups = [["actors", actors], ["requests", requests]];
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) if (RESERVED_AGENT_ACTOR_KEYS.includes(key)) throw new Error(`setupAgent: '${groupName}' key '${key}' is a reserved builtin agent actor and cannot be redefined here (it would silently clobber the builtin). Reserved keys: ${RESERVED_AGENT_ACTOR_KEYS.join(", ")}. To deliberately override a builtin, do it on the created machine instead: machine.provide({ actors: { '${key}': ... } }).`);
+}
+function createAgentActors(actors, requestActors) {
+	assertNoActorKeyCollisions(actors, requestActors);
+	assertNoReservedAgentKeys(actors, requestActors);
+	return {
+		...builtinTextActors,
+		[USER_INPUT_ACTOR]: userInputActor,
+		[DECIDE_ACTOR]: createDecideActor(),
+		[PLAN_ACTOR]: createPlanActor(),
+		...actors,
+		...requestActors
+	};
+}
+function createAgentSetupConfig(schemas, actors, config) {
+	return {
+		schemas: {
+			context: schemas.context,
+			events: schemas.events,
+			input: schemas.input,
+			output: schemas.output,
+			meta: schemas.meta,
+			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
+		},
+		...config.states ? { states: resolveAgentStateSchemas(schemas.context, config.states) } : {},
+		actors,
+		actions: config.actions,
+		guards: config.guards,
+		delays: config.delays
+	};
+}
+function createSetupAgent(config) {
+	const schemas = normalizeAgentSchemas(config);
+	const requestActors = createRequestActors(normalizeAgentRequestInput(config.requests));
+	const actors = createAgentActors(config.actors, requestActors);
+	const base = setup(createAgentSetupConfig(schemas, actors, config));
+	const createBaseMachine = base.createMachine.bind(base);
+	const models = config.models ?? {};
+	const machineOptions = {
+		schemas,
+		actors,
+		models
+	};
+	return Object.assign(base, {
+		createMachine(machineConfig) {
+			assertStateSchemaKeysExist(config.states, machineConfig?.states);
+			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
+			agentExecutionOptions.set(machine, machineOptions);
+			if (config.isSuspended) {
+				const rootConfig = machine.config;
+				if (rootConfig) machineSuspensionPredicates.set(rootConfig, config.isSuspended);
+			}
+			return machine;
+		},
+		schemas,
+		models,
+		requests: requestActors,
+		appendMessages(resolve) {
+			return appendMessages(resolve);
+		}
+	});
+}
+//#endregion
+export { resolveAgentRequests as _, AgentReplayDivergenceError as a, appendMessages as b, diffEventLogs as c, initEntry as d, replay as f, initialAgentStep as g, getInvokeEffectMetadata as h, AGENT_USAGE_EVENT_TYPE as i, getAgentEffects as l, executeAgentRequest as m, setupAgent as n, AgentReplayMachineMismatchError as o, verifyReplay as p, AGENT_INIT_EVENT_TYPE as r, createReplayEntry as s, createAgentSchemas as t, getCallUsage as u, resolveAgentStep as v, messagesSchema as x, transitionAgentStep as y };