@statelyai/agent 2.0.0-alpha.14 → 2.0.0-alpha.16

package/dist/{setup-agent-CpK0ZRWV.cjs → setup-agent-BLU77gqr.cjs}

@@ -1,6 +1,6 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_decision = require("./decision-C0cUKvNt.cjs");
-const require_event_log_store = require("./event-log-store-CNT_7F0V.cjs");
+const require_decision = require("./decision-Ba8qrT8r.cjs");
+const require_event_log_store = require("./event-log-store-yquOV1TX.cjs");
 let xstate = require("xstate");
 //#region src/messages.ts
 function addMessages(resolve) {
@@ -85,7 +85,7 @@ const messagesSchema = { "~standard": {
 * 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`).
+* effect/replay loop in `./effects.ts` (re-exported from `@statelyai/agent`).
 * 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).
@@ -106,17 +106,20 @@ function getInvokeEffectMetadata(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.
+* lowers each into an {@link AgentStepRequest}. Pass `options.machine` to
+* pre-fill `schemas`/`actors` from the machine's registered `setupAgent`
+* options instead of passing them by hand.
 * `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 = {}) {
+function getAgentRequests(actions, { machine, ...options } = {}) {
+	if (machine) options = {
+		...require_decision.getRegisteredAgentExecutionOptions(machine),
+		...options
+	};
 	return actions.flatMap((action) => {
 		const params = getInvokeEffectMetadata(action);
 		if (!params || typeof params.src !== "string") return [];
@@ -217,7 +220,7 @@ function resolveAgentStep(machine, step, request, output, options) {
 	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
 	return createAgentStep(machine, snapshot, actions, require_decision.getRegisteredAgentExecutionOptions(machine, options));
 }
-async function executeAgentRequest(requestOrEffect, executors, options) {
+async function executeAgentRequest(requestOrEffect, executors) {
 	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",
@@ -230,11 +233,10 @@ async function executeAgentRequest(requestOrEffect, executors, options) {
 	} : requestOrEffect;
 	assertTextExecutor(request, executors);
 	const { output, raw } = await require_decision.executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
-	const normalizedOutput = request.input.outputSchema ? require_decision.validateSchemaSync(request.input.outputSchema, output) : output;
-	return options?.verbose ? {
-		output: normalizedOutput,
+	return {
+		output: request.input.outputSchema ? require_decision.validateSchemaSync(request.input.outputSchema, output) : output,
 		raw
-	} : normalizedOutput;
+	};
 }
 function assertTextExecutor(request, executors) {
 	const mode = request.mode ?? "generate";
@@ -246,7 +248,7 @@ function createAgentStep(machine, snapshot, actions, options) {
 	return {
 		snapshot,
 		actions,
-		requests: getAgentRequestsWith(actions, {
+		requests: getAgentRequests(actions, {
 			...options,
 			snapshot
 		}),
@@ -327,26 +329,6 @@ const AGENT_INIT_EVENT_TYPE = "@agent.init";
 */
 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 require_decision.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.
 */
@@ -374,7 +356,6 @@ function createReplayEntry(machine, entries, event, options = {}) {
 		});
 		entry.verification = replayVerification(result.snapshot, result.effects);
 	}
-	require_event_log_store.assertAgentLogEntry(entry);
 	return entry;
 }
 /** Reserved first replay entry carrying machine input and verification hashes. */
@@ -527,14 +508,15 @@ function buildInvokeEffect(meta, mapped, events, snapshot, options) {
 function getAgentEffects(machine, snapshot, actions, options = {}) {
 	const resolved = require_decision.getRegisteredAgentExecutionOptions(machine, options);
 	const events = toEvents(options.history);
-	const requests = getAgentRequestsWith(actions, {
+	const rawActions = actions;
+	const requests = getAgentRequests(rawActions, {
 		...resolved,
 		snapshot
 	});
 	const requestById = new Map(requests.map((request) => [request.id, request]));
 	const effects = [];
 	const emitted = /* @__PURE__ */ new Set();
-	for (const rawAction of actions) {
+	for (const rawAction of rawActions) {
 		const meta = getInvokeEffectMetadata(rawAction);
 		if (meta) {
 			const effect = buildInvokeEffect(meta, typeof meta.id === "string" ? requestById.get(meta.id) : void 0, events, snapshot, resolved);
@@ -626,45 +608,48 @@ var AgentReplayDivergenceError = class extends require_errors.AgentError {
 * 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 ?? require_decision.getMachineStructuralHash(machine);
+/**
+* Validates a replay entry sequence: envelope shape, contiguity from index 0,
+* unique event ids, and machine identity.
+*
+* @internal
+*/
+function validateReplayEntries(entries, expected, label) {
 	const eventIds = /* @__PURE__ */ new Set();
 	for (let index = 0; index < entries.length; index++) {
 		const entry = entries[index];
 		require_event_log_store.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}'.`);
+		if (entry.index !== index) throw new Error(`${label} must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
+		if (eventIds.has(entry.id)) throw new Error(`${label} 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
-		}, {
+		if (entry.machineId !== expected.machineId || entry.machineVersion !== expected.machineVersion) throw new AgentReplayMachineMismatchError(entry.id, entry.index, expected, {
 			machineId: entry.machineId,
 			machineVersion: entry.machineVersion
 		});
 	}
+}
+function replay(machine, entries, options = {}) {
+	validateReplayEntries(entries, {
+		machineId: machine.config.id ?? machine.id ?? "(machine)",
+		machineVersion: options.machineVersion ?? require_decision.getMachineStructuralHash(machine)
+	}, "Replay entries");
 	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);
-	}
+	const initOffset = events[0]?.type === "@agent.init" ? 1 : 0;
+	const input = initOffset ? events[0].input : options.input;
+	const journal = events.slice(initOffset);
+	const journalEntries = entries.slice(initOffset);
 	let [snapshot, actions] = (0, xstate.initialTransition)(machine, input);
 	let effects = getAgentEffects(machine, snapshot, actions, {
 		...options,
-		history: entries.slice(0, events[0]?.type === "@agent.init" ? 1 : 0)
+		history: entries.slice(0, initOffset)
 	});
-	if (events[0]?.type === "@agent.init") verifyEntry(entries[0], snapshot, effects, options.verify);
+	if (initOffset) 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] = (0, xstate.transition)(machine, snapshot, reboundEvent);
-		const consumed = entries.slice(0, entries.length - journalEntries.length + index + 1);
+		const consumed = entries.slice(0, initOffset + index + 1);
 		effects = getAgentEffects(machine, snapshot, actions, {
 			...options,
 			history: consumed
@@ -816,10 +801,7 @@ function sortJson(value) {
 	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");
+	return require_decision.djb2Hex(stableJson(value));
 }
 function diffJson(before, after, path = "") {
 	if (stableJson(before) === stableJson(after)) return [];
@@ -893,6 +875,9 @@ const DECIDE_SRC = "agent.decide";
 const workflowConfigWholeExpressionPattern = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
 const workflowConfigTemplateExpressionPattern = /\{\{\s*([\s\S]*?)\s*\}\}/g;
 const workflowConfigHasTemplatePattern = /\{\{[\s\S]*?\}\}/;
+function toArray(value) {
+	return Array.isArray(value) ? value : [value];
+}
 function evaluateWorkflowConfigPath(expression, scope) {
 	const parts = expression.trim().split(".").filter(Boolean);
 	let current = scope;
@@ -926,6 +911,7 @@ function createSchemasFromWorkflowConfig(config, compileSchema) {
 	});
 }
 function createRequestsFromWorkflowConfig(config, compileSchema) {
+	const resolver = (value) => value === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(value, { input });
 	return Object.fromEntries(Object.entries(config.requests ?? {}).map(([key, request]) => [key, {
 		mode: request.mode,
 		description: request.description,
@@ -934,19 +920,19 @@ function createRequestsFromWorkflowConfig(config, compileSchema) {
 			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 }),
+		system: resolver(request.system),
+		prompt: resolver(request.prompt),
+		messages: resolver(request.messages),
 		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 })
+		temperature: resolver(request.temperature),
+		maxOutputTokens: resolver(request.maxOutputTokens),
+		topP: resolver(request.topP),
+		topK: resolver(request.topK),
+		seed: resolver(request.seed),
+		stopSequences: resolver(request.stopSequences),
+		metadata: resolver(request.metadata)
 	}]));
 }
 function createActorPlaceholdersFromWorkflowConfig(config) {
@@ -1012,7 +998,7 @@ function translateWorkflowAction(action, translation, location) {
 	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 actionConfigs = transitionConfig.actions ? toArray(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));
@@ -1054,9 +1040,8 @@ function translateWorkflowInvoke(invokeConfig, translation, stateKey) {
 }
 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 transition of toArray(transitionConfig)) {
+		const targets = transition.target === void 0 ? [] : toArray(transition.target);
 		for (const target of targets) {
 			if (typeof target !== "string") continue;
 			declaredTargets.push(target);
@@ -1068,16 +1053,16 @@ function assertValidTransitionTargets(stateKey, location, transitionConfig, sibl
 }
 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);
-	}
+	const invokes = stateConfig.invoke ? toArray(stateConfig.invoke) : [];
+	const sources = [
+		...Object.entries(stateConfig.on ?? {}).map(([eventType, transition]) => [`'on.${eventType}'`, transition]),
+		...Object.entries(stateConfig.after ?? {}).map(([delay, transition]) => [`'after.${delay}'`, transition]),
+		["'always'", stateConfig.always],
+		["'onDone'", stateConfig.onDone],
+		["'choice'", stateConfig.choice],
+		...invokes.flatMap((invoke) => [["invoke 'onDone'", invoke.onDone], ["invoke 'onError'", invoke.onError]])
+	];
+	for (const [location, transition] of sources) assertValidTransitionTargets(stateKey, location, transition, siblingKeys, declaredTargets);
 	return declaredTargets;
 }
 function translateWorkflowState(stateKey, stateConfig, siblingKeys, path, translation) {
@@ -1097,7 +1082,7 @@ function translateWorkflowState(stateKey, stateConfig, siblingKeys, path, transl
 		...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) => {
+		...stateConfig.choice !== void 0 ? { choice: toArray(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 {
@@ -1113,8 +1098,8 @@ function translateWorkflowState(stateKey, stateConfig, siblingKeys, path, transl
 		...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.entry !== void 0 ? { entry: toArray(stateConfig.entry).map((action) => translateWorkflowAction(action, translation, location)) } : {},
+		...stateConfig.exit !== void 0 ? { exit: toArray(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 } : {}
@@ -1226,7 +1211,7 @@ const agentUsageEventSchema = { "~standard": {
 				path: ["usage", field]
 			});
 		}
-		if (event.kind !== void 0 && !USAGE_KINDS.includes(event.kind)) issues.push({
+		if (event.kind !== void 0 && !USAGE_KINDS.some((kind) => kind === event.kind)) issues.push({
 			message: `Expected one of ${USAGE_KINDS.join(", ")}`,
 			path: ["kind"]
 		});
@@ -1356,7 +1341,47 @@ function resolveAgentStateSchemas(contextSchema, states) {
 * ```
 */
 function setupAgent(config) {
-	return createSetupAgent(config);
+	const schemas = normalizeAgentSchemas(config);
+	const requestActors = createRequestActors(config.requests ?? {});
+	const actors = createAgentActors(config.actors, requestActors);
+	const base = (0, xstate.setup)({
+		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
+	});
+	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));
+			require_decision.agentExecutionOptions.set(machine, machineOptions);
+			if (config.isSuspended) {
+				const rootConfig = machine.config;
+				if (rootConfig) require_decision.machineSuspensionPredicates.set(rootConfig, config.isSuspended);
+			}
+			return machine;
+		},
+		schemas,
+		models,
+		requests: requestActors,
+		appendMessages
+	});
 }
 function collectFinalStateOutputs(states, outputs = []) {
 	for (const state of Object.values(states ?? {})) {
@@ -1400,24 +1425,6 @@ function normalizeAgentSchemas(config) {
 		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
@@ -1443,20 +1450,30 @@ const RESERVED_AGENT_ACTOR_KEYS = [
 	require_decision.DECIDE_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`, …) silently. Deliberate override of a builtin
-* is still possible after the machine is created, via
-* `machine.provide({ actors: { 'agent.decide': ... } })`.
+* Runtime guards over the user-supplied `actors`/`requests` keys, in one walk
+* of both groups:
+*
+* 1. A key in the reserved `agent.*` builtin namespace is rejected. Without
+*    this, the builtins-first spread in {@link createAgentActors} lets such a
+*    key overwrite the builtin (`agent.decide`, …) silently. Deliberate
+*    override of a builtin is still possible after the machine is created, via
+*    `machine.provide({ actors: { 'agent.decide': ... } })`.
+* 2. A key appearing in BOTH groups 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 assertNoReservedAgentKeys(actors, requests) {
+function assertActorKeys(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 ?? {})) 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}': ... } }).`);
+	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
+		if (RESERVED_AGENT_ACTOR_KEYS.some((reserved) => reserved === 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}': ... } }).`);
+		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);
+	}
 }
 function createAgentActors(actors, requestActors) {
-	assertNoActorKeyCollisions(actors, requestActors);
-	assertNoReservedAgentKeys(actors, requestActors);
+	assertActorKeys(actors, requestActors);
 	return {
 		...require_decision.builtinTextActors,
 		[require_decision.USER_INPUT_ACTOR]: require_decision.userInputActor,
@@ -1465,54 +1482,6 @@ function createAgentActors(actors, requestActors) {
 		...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 = (0, xstate.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));
-			require_decision.agentExecutionOptions.set(machine, machineOptions);
-			if (config.isSuspended) {
-				const rootConfig = machine.config;
-				if (rootConfig) require_decision.machineSuspensionPredicates.set(rootConfig, config.isSuspended);
-			}
-			return machine;
-		},
-		schemas,
-		models,
-		requests: requestActors,
-		appendMessages(resolve) {
-			return appendMessages(resolve);
-		}
-	});
-}
 //#endregion
 Object.defineProperty(exports, "AGENT_INIT_EVENT_TYPE", {
 	enumerable: true,
@@ -1574,12 +1543,6 @@ Object.defineProperty(exports, "getAgentEffects", {
 		return getAgentEffects;
 	}
 });
-Object.defineProperty(exports, "getCallUsage", {
-	enumerable: true,
-	get: function() {
-		return getCallUsage;
-	}
-});
 Object.defineProperty(exports, "getInvokeEffectMetadata", {
 	enumerable: true,
 	get: function() {
@@ -1628,6 +1591,12 @@ Object.defineProperty(exports, "transitionAgentStep", {
 		return transitionAgentStep;
 	}
 });
+Object.defineProperty(exports, "validateReplayEntries", {
+	enumerable: true,
+	get: function() {
+		return validateReplayEntries;
+	}
+});
 Object.defineProperty(exports, "verifyReplay", {
 	enumerable: true,
 	get: function() {