@statelyai/agent 2.0.0-alpha.18 → 2.0.0-alpha.19

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { _ as initialAgentStep, a as AGENT_USAGE_EVENT_TYPE, b as appendMessages, c as createReplayEntry, d as initEntry, f as replay, g as getInvokeEffectMetadata, h as executeAgentRequest, i as AGENT_INIT_EVENT_TYPE, l as diffEventLogs, m as verifyReplay, n as getAgentSchemas, o as AgentReplayDivergenceError, p as validateReplayEntries, r as setupAgent, s as AgentReplayMachineMismatchError, t as createAgentSchemas, u as getAgentEffects, v as resolveAgentStep, x as messagesSchema, y as transitionAgentStep } from "./setup-agent-BrE2zFDy.mjs";
-import { A as isUnboundPlaceholder, B as getMachineStructuralHash, C as parseStructuredEnvelope, D as getMachineStaticTransitionTargets, E as executorBoundLogics, G as toolMessage, H as isStandardSchema, I as findNonSerializableContextPaths, K as userMessage, L as getAgentMessages, O as getMachineSuspensionPredicate, P as assistantMessage, R as getJsonSchema, S as parseOutput, U as persistSnapshot, V as getStateMeta, W as systemMessage, _ as getAgentOutputMode, a as resolveDecision, b as normalizeGeneratorResult, c as AGENT_USAGE_TOKEN_FIELDS, f as bindRequestExecutor, h as createTextLogic, i as renderDecisionAttempts, k as getRegisteredAgentExecutionOptions, o as getAcceptedEvents, p as buildEnvelopeSchema, q as validateSchemaSync, r as isDecisionLogic, s as parseAgentEvent, t as AgentDecisionExhaustedError, u as INTERPRET_SOURCE, v as getCallUsage, x as parseModelRef, y as isTextLogic, z as getJsonSchemaSync } from "./decision-C11xuud2.mjs";
-import { a as assertJsonSerializable, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as createInMemoryEventLogStore, r as NonSerializableAgentEventError, s as assertEventLogStoreConformance, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-B-1fcfkT.mjs";
+import { _ as resolveAgentStep, a as AGENT_USAGE_EVENT_TYPE, b as messagesSchema, c as createReplayEntry, d as initEntry, f as replay, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_INIT_EVENT_TYPE, l as diffEventLogs, m as executeAgentRequest, n as getAgentSchemas, o as AgentReplayDivergenceError, p as validateReplayEntries, r as setupAgent, s as AgentReplayMachineMismatchError, t as createAgentSchemas, u as getAgentEffects, v as transitionAgentStep, y as appendMessages } from "./setup-agent-CPFPN06s.mjs";
+import { A as isUnboundPlaceholder, B as getMachineStructuralHash, C as parseStructuredEnvelope, D as getMachineIdlePredicate, E as executorBoundLogics, G as toolMessage, H as isStandardSchema, I as findNonSerializableContextPaths, K as userMessage, L as getAgentMessages, O as getMachineStaticTransitionTargets, P as assistantMessage, R as getJsonSchema, S as parseOutput, U as resolveMachineVersion, V as getStateMeta, W as systemMessage, _ as getAgentOutputMode, a as resolveDecision, b as normalizeGeneratorResult, c as AGENT_USAGE_TOKEN_FIELDS, f as bindRequestExecutor, h as createTextLogic, i as renderDecisionAttempts, k as getRegisteredAgentExecutionOptions, o as getAcceptedEvents, p as buildEnvelopeSchema, q as validateSchemaSync, r as isDecisionLogic, s as parseAgentEvent, t as AgentDecisionExhaustedError, u as INTERPRET_SOURCE, v as getCallUsage, x as parseModelRef, y as isTextLogic, z as getJsonSchemaSync } from "./decision-DsIkEuHz.mjs";
+import { a as assertJsonSerializable, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as createInMemoryEventLogStore, r as NonSerializableAgentEventError, s as assertEventLogStoreConformance, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-DmIDosD6.mjs";
 import { createActor, createAsyncLogic, getNextTransitions, isMachineSnapshot } from "xstate";
 //#region src/internal/state-request-pass.ts
 async function runTextPhase(stateRequest, baseMessages, deps) {
@@ -102,7 +102,7 @@ async function runAdvancePhase(plan, deps) {
 		messages: [...deps.messages],
 		events,
 		attempts: []
-	}, deps.decide, {
+	}, { decide: deps.decide }, {
 		signal: deps.signal,
 		canTake: (event) => deps.getSnapshot().can(event)
 	});
@@ -138,8 +138,7 @@ async function runStateRequestPass(requests, deps) {
 * {@link getAcceptedEvents}). A programmer/integration error, in the same
 * class as runAgent's bind-time throws — it throws rather than settling an
 * `error` result. A type-legal event a guard rejects is NOT this error (the
-* machine simply takes no transition). Opt out with
-* {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
+* machine simply takes no transition). Always enforced; there is no opt-out.
 */
 var AgentIllegalResumeEventError = class extends AgentError {
 	eventType;
@@ -257,7 +256,7 @@ function toJsonValue(value, ancestors) {
 * in a JSONL file). Live values are sanitized rather than trusted:
 *
 * - Snapshots (`run.start`, `machine.transition`, `run.end`) go through the
-*   same JSON round-trip as {@link persistSnapshot}, so what lands on disk is
+*   same JSON round-trip as `machine.getPersistedSnapshot(...)`, so what lands on disk is
 *   what a resume would see.
 * - `request.end`'s `raw` (a provider SDK object, frequently cyclic) is DROPPED
 *   unless `includeRaw` is set, in which case it is sanitized like everything
@@ -284,11 +283,92 @@ function serializeTraceEvent(event, options = {}) {
 	}
 	return out;
 }
+function snapshotNodes(snapshot) {
+	return (snapshot._nodes ?? []).map((raw) => {
+		const node = raw;
+		return {
+			id: node.id ?? "",
+			key: node.key ?? "",
+			...node.description !== void 0 ? { description: node.description } : {},
+			tags: [...node.tags ?? []],
+			...node.meta !== void 0 ? { meta: node.meta } : {},
+			ownEvents: [...node.ownEvents ?? []],
+			leaf: Object.keys(node.states ?? {}).length === 0
+		};
+	});
+}
+/**
+* The active state nodes of a snapshot, as plain {@link AgentSnapshotNode}
+* descriptors. The escape hatch under {@link getSnapshotRequests}: use it when
+* your `getRequests` hook needs to build requests some other way, so host code
+* never touches xstate's private `snapshot._nodes`.
+*/
+function getSnapshotNodes(snapshot) {
+	return snapshotNodes(snapshot);
+}
+/**
+* Builds the {@link AgentStateRequest}s for a snapshot straight from its active
+* state nodes — the prompts-in-descriptions recipe as a function, so a
+* {@link RunAgentOptions.getRequests} hook is one line and never reaches into
+* xstate's private `snapshot._nodes`:
+*
+* ```ts
+* runAgent(machine, {
+*   executors,
+*   getRequests: (snapshot) => getSnapshotRequests(snapshot, { model: 'writer' }),
+* });
+* ```
+*
+* Each described active node becomes one request: `prompt` from the node's
+* `description`, `kind: 'decision'` when it is tagged `'decision'`, `system`
+* from `meta.role` when present, `allowedEvents` scoped to the node's own
+* events, and an explicit `onDone` when the node has exactly one own event
+* (single-outcome states advance deterministically; anything else falls
+* through to a `decide` call). Nodes tagged `'waiting'` produce nothing, so the
+* run settles idle for a human. Override any of it with `filter`/`map`.
+*/
+function getSnapshotRequests(snapshot, options) {
+	const filter = options.filter ?? ((node) => !!node.description && !node.tags.includes("waiting"));
+	const requests = [];
+	for (const node of snapshotNodes(snapshot)) {
+		if (!filter(node)) continue;
+		const system = node.meta?.role;
+		const request = {
+			model: options.model,
+			prompt: node.description ?? "",
+			kind: node.tags.includes("decision") ? "decision" : "text",
+			...system !== void 0 ? { system } : {},
+			...node.ownEvents.length > 0 ? { allowedEvents: node.ownEvents } : {},
+			...node.ownEvents.length === 1 ? { onDone: { type: node.ownEvents[0] } } : {}
+		};
+		const mapped = options.map ? options.map(request, node) : request;
+		if (mapped) requests.push(mapped);
+	}
+	return requests;
+}
 let nextRunAgentTraceId = 1;
+/**
+* Thrown into the invoke that would have made the call once
+* {@link RunAgentOptions.maxModelCalls} is spent. It reaches the machine
+* through the normal error channel, so an invoke's `onError` can branch on it
+* (`error.code === 'max-model-calls'`, the same string the settled result's
+* `cause` uses) and route to a degraded/finish state instead of failing the
+* run. Unhandled, it settles `{ status: 'error', cause: 'max-model-calls' }`.
+*
+* ```ts
+* onError: [
+*   { guard: ({ event }) => event.error?.code === 'max-model-calls', target: 'budgetSpent' },
+*   { target: 'failed' },
+* ]
+* ```
+*/
 var AgentMaxModelCallsExceededError = class extends AgentError {
-	constructor() {
-		super("max-model-calls-exceeded", "runAgent exceeded maxModelCalls.");
+	/** The budget that was exceeded (`options.maxModelCalls`). */
+	maxModelCalls;
+	constructor(maxModelCalls) {
+		super("max-model-calls", `runAgent exceeded maxModelCalls (${maxModelCalls}). Raise the budget, or handle it in the invoke's onError (error.code === 'max-model-calls').`);
 		this.name = "AgentMaxModelCallsExceededError";
+		this.maxModelCalls = maxModelCalls;
 	}
 };
 function wrapsDecisionExhausted(error) {
@@ -328,7 +408,7 @@ function collectConfiguredInvokeSrcs(stateConfig, stateName, out) {
 * walk into invoked child machines (their internal agent requests are opaque
 * to the parent-level source walk otherwise).
 */
-function isStateMachine(logic) {
+function isStateMachineLogic(logic) {
 	return !!logic && typeof logic === "object" && "config" in logic && "root" in logic && typeof logic.provide === "function" && typeof logic.sources === "object" && !!logic.sources?.actors;
 }
 /**
@@ -360,7 +440,7 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 	const where = ctx.isChild ? `child machine '${ctx.childPath}' state` : "state";
 	for (const { stateName, src } of invokes) {
 		if (typeof src !== "string") {
-			if (isStateMachine(src)) {
+			if (isStateMachineLogic(src)) {
 				assertChildMachineBindable(src, src, stateName, executors, ctx);
 				continue;
 			}
@@ -369,7 +449,7 @@ function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 		}
 		const logic = effectiveSources[src];
 		if (logic === void 0) throw new Error(`runAgent: ${where} '${stateName}' invokes unregistered actor source '${src}'. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
-		if (isStateMachine(logic)) {
+		if (isStateMachineLogic(logic)) {
 			assertChildMachineBindable(logic, src, stateName, executors, ctx);
 			continue;
 		}
@@ -415,18 +495,16 @@ function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
 	return /* @__PURE__ */ new Error(`runAgent: child machine '${childPath}' (state '${stateName}') invokes ${kind} source '${requestSrc}', which has no host execution and is reached through a direct-object invoke src that runAgent cannot rebind. Requests reached through string-keyed actor sources inherit runAgent's generateText/streamText/decide executors automatically; a direct-object child machine does not. Either bind the request with its own executor (requestLogic.withExecutor(...)), or register the child as a string-keyed actor source (machine.provide({ actors: { <child>: childMachine } })) and invoke it by name.`);
 }
 /**
-* True when the snapshot's active states declare a transition for the reserved
-* `'@agent.usage'` type EXPLICITLY. A catch-all `on: { '*': … }` deliberately
-* does not count: a wildcard is a machine's own event vocabulary, not an
-* opt-in to a library-reserved event, and `snapshot.can(event)` alone cannot
-* tell the two apart (it answers "would this event be taken?", which a
-* wildcard makes true for everything). Gating delivery on the explicit
-* declaration is what keeps `@agent.usage` opt-in by construction — and keeps
-* a wildcard machine's context and event log byte-identical to a run without
-* the feature. @internal
+* True when the snapshot's active states declare a transition that would
+* receive the reserved `'@agent.usage'` type — an explicit `on: { '@agent.usage'
+* }` OR a catch-all `on: { '*': … }`. Plain XState semantics apply unmodified:
+* a wildcard matches every event delivered to the machine, reserved ones
+* included. (The MODEL-facing side stays closed: `getAcceptedEvents` drops
+* `@agent.*` before any `allowedEvents` matching, so a wildcard never offers
+* the reserved event as a decision candidate.) @internal
 */
 function declaresUsageTransition(snapshot) {
-	return getNextTransitions(snapshot).some((transition) => transition.eventType === AGENT_USAGE_EVENT_TYPE);
+	return getNextTransitions(snapshot).some((transition) => transition.eventType === "@agent.usage" || transition.eventType === "*");
 }
 /**
 * Builds the ONE place a trace payload is emitted: it hands the payload to the
@@ -493,7 +571,7 @@ function bindTextLogic(logic, runCtx) {
 		const self = selfArg;
 		const { id, src } = selfIdAndSrc(self);
 		const executor = logic.mode === "stream" ? runCtx.streamText : runCtx.generateText;
-		if (!executor) throw new Error(`runAgent: no '${logic.mode === "stream" ? "streamText" : "generateText"}' executor provided.`);
+		if (!executor) throw new Error(`No '${logic.mode === "stream" ? "streamText" : "generateText"}' executor provided.`);
 		const requestWithTools = {
 			...request,
 			tools: request.tools ?? {}
@@ -565,17 +643,22 @@ function bindTextLogic(logic, runCtx) {
 	});
 }
 function createCountingDecide(runCtx, self) {
-	return async (attemptRequest) => {
+	return async (attemptRequest, info) => {
 		runCtx.consumeModelCall();
 		runCtx.emitTrace?.({
 			type: "request.start",
 			request: attemptRequest
 		}, self);
 		try {
+			const { id } = selfIdAndSrc(self);
 			const result = await runCtx.decide(runCtx.runId !== void 0 ? {
 				...attemptRequest,
 				runId: runCtx.runId
-			} : attemptRequest);
+			} : attemptRequest, {
+				...info,
+				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
+				...info?.requestId === void 0 && id !== "" ? { requestId: id } : {}
+			});
 			const usage = getCallUsage(result);
 			if (usage) {
 				const { src } = selfIdAndSrc(self);
@@ -621,7 +704,7 @@ function createCountingDecide(runCtx, self) {
 */
 function bindDecisionLogic(logic, runCtx) {
 	const decisionLogic = createAsyncLogic({ run: async ({ input, signal, self: selfArg }) => {
-		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
+		if (!runCtx.decide) throw new Error("No 'decide' executor provided.");
 		const self = selfArg;
 		const { id } = selfIdAndSrc(self);
 		const declaredEventTypes = logic.allowedEventTypes?.(input);
@@ -635,7 +718,7 @@ function bindDecisionLogic(logic, runCtx) {
 			...logic.request(input),
 			id,
 			events
-		}, createCountingDecide(runCtx, self), {
+		}, { decide: createCountingDecide(runCtx, self) }, {
 			maxRetries: logic.maxRetries,
 			signal,
 			canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
@@ -680,7 +763,7 @@ function rootTraceState(root) {
 	if (!state) {
 		const logic = root.logic;
 		const machineId = (logic?.config)?.id ?? logic?.id ?? "(machine)";
-		const machineVersion = logic ? getMachineStructuralHash(logic) : "";
+		const machineVersion = logic ? resolveMachineVersion(logic) : "";
 		state = {
 			runId: `run_${nextProvideRunId++}`,
 			seq: 0,
@@ -752,9 +835,9 @@ function provideBindContext(machine, executors, options) {
 * under a live `createActor` tree) on the `provideExecutors` path.
 *
 * Gating is identical on both: the target snapshot must be active, must declare
-* an `'@agent.usage'` transition EXPLICITLY (see {@link declaresUsageTransition}
-* — a catch-all `on: { '*' }` is not an opt-in), and must be able to take the
-* event. `onDropped` is the run path's straggler gate: it returns `true` for a
+* an `'@agent.usage'` transition — explicitly, or through a catch-all
+* `on: { '*' }` (see {@link declaresUsageTransition}) — and must be able to
+* take the event. `onDropped` is the run path's straggler gate: it returns `true` for a
 * call that settled after the cycle resolved, which drops the event (traced as
 * `usage.dropped`) rather than delivering it. Uncontrolled mode has no cycle to
 * settle, so it passes no gate and has no dropped stragglers.
@@ -796,6 +879,19 @@ function bindDecisionForProvide(machine, logic, executors, options) {
 	return bindDecisionLogic(logic, provideBindContext(machine, executors, options));
 }
 /**
+* Recursively binds an invoked child state machine for {@link provideExecutors},
+* with the same semantics `runAgent` applies ({@link rebindChildMachine}):
+* string-keyed text/decision sources at any depth inherit the host executors,
+* a source that carries its own executor is left alone, and a cycle is
+* returned as-is. Each machine in the tree is bound with its own registered
+* `setupAgent` schemas. Returns the original machine when nothing needed
+* wrapping. @internal
+*/
+function bindChildMachineForProvide(childMachine, executors, options, visited) {
+	const ctxFor = (target) => provideBindContext(target, executors, options);
+	return rebindChildMachine(childMachine, ctxFor(childMachine), visited, ctxFor);
+}
+/**
 * Validates `input` against the machine's registered input schema, returning
 * the schema's output — so defaults are filled and transforms applied before
 * the value reaches `createActor` or the replayable event log.
@@ -829,9 +925,10 @@ function resolveMachineInput(machine, input) {
 * (`executorBoundLogics`) is left as-is: explicit binding shadows inheritance.
 * Cycle-safe via `visited` (a machine that invokes itself is returned as-is).
 */
-function rebindChildMachine(childMachine, runCtx, visited) {
+function rebindChildMachine(childMachine, runCtx, visited, ctxFor) {
 	if (visited.has(childMachine)) return childMachine;
 	const childVisited = new Set([...visited, childMachine]);
+	runCtx = ctxFor ? ctxFor(childMachine) : runCtx;
 	const sources = childMachine.sources.actors;
 	const wrapped = {};
 	for (const [key, logic] of Object.entries(sources)) {
@@ -843,8 +940,8 @@ function rebindChildMachine(childMachine, runCtx, visited) {
 			if (!executorBoundLogics.has(logic)) wrapped[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
-		if (isStateMachine(logic)) {
-			const rebound = rebindChildMachine(logic, runCtx, childVisited);
+		if (isStateMachineLogic(logic)) {
+			const rebound = rebindChildMachine(logic, runCtx, childVisited, ctxFor);
 			if (rebound !== logic) wrapped[key] = rebound;
 			continue;
 		}
@@ -927,7 +1024,7 @@ function createAgentSession(machine, options, lifecycle) {
 	let traceSeq = 0;
 	const resolvedInput = resolveMachineInput(machine, options.input);
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
-	const machineVersion = options.machineVersion ?? machine.version ?? getMachineStructuralHash(machine);
+	const machineVersion = resolveMachineVersion(machine);
 	const agentMeta = {
 		machineId,
 		version: machineVersion
@@ -949,10 +1046,10 @@ function createAgentSession(machine, options, lifecycle) {
 		onTransition: options.onTransition
 	});
 	const consumeModelCall = () => {
-		if (budgetExceeded) throw new AgentMaxModelCallsExceededError();
+		if (budgetExceeded) throw new AgentMaxModelCallsExceededError(maxModelCalls);
 		if (modelCallCount + 1 > maxModelCalls) {
 			budgetExceeded = true;
-			throw new AgentMaxModelCallsExceededError();
+			throw new AgentMaxModelCallsExceededError(maxModelCalls);
 		}
 		modelCallCount += 1;
 	};
@@ -1026,19 +1123,20 @@ function createAgentSession(machine, options, lifecycle) {
 			if (!executorBoundLogics.has(logic)) wrappedSources[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
-		if (isStateMachine(logic)) {
+		if (isStateMachineLogic(logic)) {
 			const rebound = rebindChildMachine(logic, runCtx, new Set([machine]));
 			if (rebound !== logic) wrappedSources[key] = rebound;
 			continue;
 		}
 	}
 	const boundMachine = provided.provide({ actors: wrappedSources });
-	const declaredSuspensionPredicate = options.isSuspended ?? getMachineSuspensionPredicate(machine);
-	const isSuspended = declaredSuspensionPredicate ?? (() => false);
+	const declaredIdlePredicate = options.isIdle ?? getMachineIdlePredicate(machine);
+	const isIdle = declaredIdlePredicate ?? (() => false);
+	const machineDeclaresMigrate = typeof machine.config.migrate === "function";
 	let effectiveSnapshot = options.snapshot;
 	if (effectiveSnapshot !== void 0) {
 		const from = effectiveSnapshot.agentMeta?.version ?? effectiveSnapshot.version;
-		if (from !== void 0 && from !== machineVersion) {
+		if (from !== void 0 && from !== machineVersion && !(machineDeclaresMigrate && !options.migrateSnapshot)) {
 			const info = {
 				from,
 				to: machineVersion
@@ -1057,7 +1155,7 @@ function createAgentSession(machine, options, lifecycle) {
 		effectiveSnapshot = machine.getPersistedSnapshot(replayedSnapshot);
 	}
 	const machineOwnVersion = machine.version;
-	if (effectiveSnapshot !== void 0 && effectiveSnapshot.version !== machineOwnVersion) {
+	if (!machineDeclaresMigrate && effectiveSnapshot !== void 0 && effectiveSnapshot.version !== machineOwnVersion) {
 		const aligned = Object.assign(Object.create(Object.getPrototypeOf(effectiveSnapshot)), effectiveSnapshot);
 		if (machineOwnVersion === void 0) delete aligned.version;
 		else aligned.version = machineOwnVersion;
@@ -1071,7 +1169,7 @@ function createAgentSession(machine, options, lifecycle) {
 		if (!options.getRequests && !options.messages && messages.length === 0) return;
 		snapshot.messages = [...messages];
 	};
-	if (effectiveSnapshot !== void 0 && options.event !== void 0 && (options.onIllegalResumeEvent ?? "throw") === "throw") {
+	if (effectiveSnapshot !== void 0 && options.event !== void 0) {
 		const acceptedTypes = getAcceptedEvents(createActor(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
 		const eventType = options.event.type;
 		if (!acceptedTypes.includes(eventType)) throw new AgentIllegalResumeEventError(eventType, acceptedTypes);
@@ -1217,9 +1315,9 @@ function createAgentSession(machine, options, lifecycle) {
 			const current = actor.getSnapshot();
 			if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
 				if (!maybeInterpret(current)) {
-					if (!declaredSuspensionPredicate && current.status === "active" && !warnedHeuristicIdle && process.env.NODE_ENV !== "production") {
+					if (!declaredIdlePredicate && current.status === "active" && !warnedHeuristicIdle && process.env.NODE_ENV !== "production") {
 						warnedHeuristicIdle = true;
-						console.warn("[@statelyai/agent] runAgent settled idle via the timing heuristic (no suspension predicate declared). This is best-effort; for deterministic idle detection, declare setupAgent({ isSuspended }) or pass runAgent(machine, { isSuspended }), e.g. (s) => s.hasTag('waiting').");
+						console.warn("[@statelyai/agent] runAgent settled idle via the timing heuristic (no idle predicate declared). This is best-effort; for deterministic idle detection, declare setupAgent({ isIdle }) or pass runAgent(machine, { isIdle }), e.g. (s) => s.hasTag('waiting').");
 					}
 					settleIdle(current);
 				}
@@ -1274,11 +1372,11 @@ function createAgentSession(machine, options, lifecycle) {
 				});
 				return;
 			}
-			if (!deliveringResumeEvent && isSuspended(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+			if (!deliveringResumeEvent && isIdle(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
 				queueMicrotask(() => {
 					if (settled) return;
 					const current = actor.getSnapshot();
-					if (isSuspended(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+					if (isIdle(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
 						if (!maybeInterpret(current)) settleIdle(current);
 					} else scheduleIdleCheck();
 				});
@@ -1575,9 +1673,12 @@ function createAgentRun(machine, options) {
 * Throws at bind time if a source needs an executor kind that `executors` does
 * not provide.
 *
-* `provideExecutors` does not descend into invoked child state machines: a string-keyed child
-* machine source is left untouched, so a child with its own agent invokes needs
-* its own `provideExecutors(...)` (or `runAgent`, which does rebind children).
+* Executor inheritance is RECURSIVE, exactly as in `runAgent`: a string-keyed
+* invoked child machine is rebound too, so its own text/decision requests — at
+* any depth — reach the same host executors. A direct-object invoke `src`
+* cannot be swapped via `.provide`, so nothing under one inherits; bind those
+* with `.withExecutor(...)` or register the child as a string-keyed source. A
+* source that already carries its own executor is never overwritten.
 */
 function provideExecutors(machine, executors, options = {}) {
 	const bindOptions = {
@@ -1591,21 +1692,18 @@ function provideExecutors(machine, executors, options = {}) {
 	const invokedSrcs = getConfiguredInvokeSrcs(provided);
 	for (const [key, logic] of Object.entries(effectiveSources)) {
 		if (key === "agent.userInput") continue;
-		let binding;
-		if (isDecisionLogic(logic)) binding = {
-			executorKey: "decide",
-			kind: "decision",
-			bind: () => bindDecisionForProvide(provided, logic, executors, bindOptions)
-		};
-		else if (isTextLogic(logic)) {
-			const streaming = logic.mode === "stream";
-			binding = {
-				executorKey: streaming ? "streamText" : "generateText",
-				kind: streaming ? "streaming text" : "text",
-				bind: () => bindTextForProvide(provided, logic, executors, bindOptions)
-			};
+		if (isStateMachineLogic(logic)) {
+			if (invokedSrcs.has(key)) assertChildBindable(logic, executors, key, new Set([provided]));
+			const rebound = bindChildMachineForProvide(logic, executors, bindOptions, new Set([provided]));
+			if (rebound !== logic) wrappedSources[key] = rebound;
+			continue;
 		}
-		if (!binding) continue;
+		const requirement = executorRequirementOf(logic);
+		if (!requirement) continue;
+		const binding = {
+			...requirement,
+			bind: () => isDecisionLogic(logic) ? bindDecisionForProvide(provided, logic, executors, bindOptions) : bindTextForProvide(provided, logic, executors, bindOptions)
+		};
 		if (executorBoundLogics.has(logic)) continue;
 		if (!executors[binding.executorKey]) {
 			if (invokedSrcs.has(key)) throw missingExecutorError(key, binding.kind, binding.executorKey);
@@ -1615,12 +1713,50 @@ function provideExecutors(machine, executors, options = {}) {
 	}
 	return withActors(provided, wrappedSources);
 }
+/** The executor slot + label an agent logic needs, or `undefined` for a non-agent actor. */
+function executorRequirementOf(logic) {
+	if (isDecisionLogic(logic)) return {
+		executorKey: "decide",
+		kind: "decision"
+	};
+	if (isTextLogic(logic)) return logic.mode === "stream" ? {
+		executorKey: "streamText",
+		kind: "streaming text"
+	} : {
+		executorKey: "generateText",
+		kind: "text"
+	};
+}
+/**
+* Walks an invoked child machine's own invoked sources (recursively, at any
+* depth) and throws the same missing-executor error `provideExecutors` throws
+* for the top-level machine — before any actor starts. Mirrors runAgent's
+* `assertBindable` for the uncontrolled path. Cycle-safe via `visited`.
+*/
+function assertChildBindable(childMachine, executors, path, visited) {
+	if (visited.has(childMachine)) return;
+	const nextVisited = new Set([...visited, childMachine]);
+	const sources = childMachine.sources.actors;
+	for (const src of getConfiguredInvokeSrcs(childMachine)) {
+		if (src === "agent.userInput") continue;
+		const logic = sources[src];
+		if (!logic) continue;
+		if (isStateMachineLogic(logic)) {
+			assertChildBindable(logic, executors, `${path} > ${src}`, nextVisited);
+			continue;
+		}
+		const requirement = executorRequirementOf(logic);
+		if (!requirement || executorBoundLogics.has(logic)) continue;
+		if (!executors[requirement.executorKey]) throw missingExecutorError(`${path} > ${src}`, requirement.kind, requirement.executorKey);
+	}
+}
 function missingExecutorError(src, kind, executor) {
 	return /* @__PURE__ */ new Error(`provideExecutors: actor source '${src}' is a ${kind} source but no '${executor}' executor was provided. Add it to the executors object, or bind the source with its own executor (logic.withExecutor(...)) before calling provideExecutors.`);
 }
 //#endregion
 //#region src/verify.ts
 const DECIDE_SRC = "agent.decide";
+const USER_INPUT_SRC = "agent.userInput";
 function normalizeInvokes(invoke) {
 	if (invoke === void 0 || invoke === null) return [];
 	return Array.isArray(invoke) ? invoke : [invoke];
@@ -1907,11 +2043,23 @@ const LINT_CHECKS = [
 * call this to catch dead states, undeliverable decisions, un-rebindable
 * invoke srcs, and output-contract gaps before ever running it.
 *
+* Pass `{ throw: true }` for the one-liner form used in tests and generation
+* loops: it returns silently when the machine is clean and throws
+* {@link AgentLintError} (findings on `.diagnostics`) on error-severity
+* findings, or on warnings too with `{ throw: true, warnings: true }`.
+*
 * @example
 * ```ts
 * const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
 * if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
 * ```
+*
+* @example Throwing form
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   lintAgentMachine(machine, { throw: true });
+* });
+* ```
 */
 function lintAgentMachine(machine, options = {}) {
 	const config = machine.config ?? {};
@@ -1926,10 +2074,16 @@ function lintAgentMachine(machine, options = {}) {
 		actors: registered.actors ?? machine.sources?.actors ?? {}
 	};
 	const disabled = new Set(options.disable ?? []);
-	return LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+	const diagnostics = LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+	if (options.throw) {
+		const failing = options.warnings ? diagnostics : diagnostics.filter((d) => d.severity === "error");
+		if (failing.length > 0) throw new AgentLintError(machine.id ?? "(machine)", failing);
+	}
+	return diagnostics;
 }
 /**
-* Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+* Thrown by `lintAgentMachine(machine, { throw: true })` when lint finds
+* failing diagnostics.
 * `diagnostics` holds the findings; the message lists them one per finding,
 * so a test runner's failure output reads like the CLI's lint report.
 */
@@ -1942,24 +2096,6 @@ var AgentLintError = class extends AgentError {
 		this.diagnostics = diagnostics;
 	}
 };
-/**
-* Asserts a machine passes {@link lintAgentMachine}: returns silently when
-* clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
-* otherwise. Fails on error-severity findings; set `warnings: true` to fail on
-* warnings too. The one-liner for tests and generation loops:
-*
-* @example
-* ```ts
-* test('agent machine is structurally sound', () => {
-*   assertAgentMachine(machine);
-* });
-* ```
-*/
-function assertAgentMachine(machine, options = {}) {
-	const diagnostics = lintAgentMachine(machine, options);
-	const failing = options.warnings ? diagnostics : diagnostics.filter((d) => d.severity === "error");
-	if (failing.length > 0) throw new AgentLintError(machine.id ?? "(machine)", failing);
-}
 function pendingInvokes(step) {
 	const out = [];
 	for (const action of step.actions) {
@@ -2005,6 +2141,7 @@ async function simulateAgent(machine, options) {
 		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
 		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
 	};
+	if (options.script.userInput?.length) script.invokes[USER_INPUT_SRC] = [...options.script.userInput, ...script.invokes[USER_INPUT_SRC] ?? []];
 	let step = initialAgentStep(machine, options.input);
 	const trail = [];
 	for (let i = 0; i < maxSteps; i++) {
@@ -2071,13 +2208,16 @@ function mapValues(obj, fn) {
 }
 function scriptDryError(kind, src, id, request) {
 	const events = request?.kind === "decision" ? ` Candidate events: ${request.events.map((e) => e.type).join(", ") || "(none)"}.` : "";
-	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add a '${kind}' entry for '${src}' to the script.${events}`);
+	const key = kind === "text" ? `text['${src}']` : kind === "decision" ? `decisions['${src}']` : src === USER_INPUT_SRC ? "userInput" : `invokes['${src}']`;
+	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add an entry to the script's \`${key}\` queue.${events}`);
 }
 const MAX_ADVANCE_STEPS = 1e3;
 async function explore(machine, options, stopWhen) {
 	const maxDepth = options.maxDepth ?? 8;
 	const maxPaths = options.maxPaths ?? 200;
-	const textOutputs = options.textOutputs ?? {};
+	const textScript = options.text ?? {};
+	const invokeOutputs = { ...options.invokes ?? {} };
+	if ("userInput" in options) invokeOutputs[USER_INPUT_SRC] = options.userInput;
 	const reachedStates = /* @__PURE__ */ new Set();
 	const reachedValues = [];
 	const terminals = [];
@@ -2102,22 +2242,22 @@ async function explore(machine, options, stopWhen) {
 			if (current.done) return { step: current };
 			const request = current.requests[0];
 			if (request && request.kind === "text") {
-				if (!(request.src in textOutputs)) return {
+				if (!(request.src in textScript)) return {
 					step: current,
 					blockedSrc: request.src
 				};
-				current = resolveAgentStep(machine, current, request, textOutputs[request.src]);
+				current = resolveAgentStep(machine, current, request, textScript[request.src]);
 				recordState(current.snapshot);
 				continue;
 			}
 			if (request && request.kind === "decision") return { step: current };
 			const [invoke] = pendingInvokes(current);
 			if (invoke) {
-				if (!(invoke.src in textOutputs)) return {
+				if (!(invoke.src in invokeOutputs)) return {
 					step: current,
 					blockedSrc: invoke.src
 				};
-				current = resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
+				current = resolveAgentStep(machine, current, invoke.id, invokeOutputs[invoke.src]);
 				recordState(current.snapshot);
 				continue;
 			}
@@ -2209,9 +2349,10 @@ async function explore(machine, options, stopWhen) {
 * depth, model-free, and reports which states are reached and how each path
 * terminates. At each decision request it forks one branch per candidate event
 * (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
-* an idle wait it forks per externally-accepted event. Text/`userInput` invokes
-* are resolved from `textOutputs` (a by-src canned-output map) — a missing src
-* halts that branch with a `needs-output` terminal rather than throwing.
+* an idle wait it forks per externally-accepted event. Text requests resolve
+* from `text`, other invokes from `invokes` (or `userInput` for
+* `agent.userInput`) — all by-src canned-output maps, and a missing src halts
+* that branch with a `needs-output` terminal rather than throwing.
 *
 * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
 * 200, reported via `hitPathCap`).
@@ -2227,13 +2368,14 @@ async function explorePaths(machine, options = {}) {
 }
 /**
 * Answers "can the machine reach `statePath`?" by exploring its branches (a
-* thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
-* with the event sequence that reaches it, or `{ canReach: false }`.
+* thin wrapper over {@link explorePaths}). Returns
+* `{ reachable: true, witness }` with the event sequence that reaches it, or
+* `{ reachable: false }`.
 *
 * @example
 * ```ts
-* const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
-* // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+* const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+* // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
 * ```
 */
 async function canReach(machine, statePath, options = {}) {
@@ -2245,9 +2387,9 @@ async function canReach(machine, statePath, options = {}) {
 		}
 	});
 	return witness !== void 0 ? {
-		canReach: true,
+		reachable: true,
 		witness
-	} : { canReach: false };
+	} : { reachable: false };
 }
 //#endregion
 //#region src/internal/is-record.ts
@@ -2408,7 +2550,8 @@ function matchesTrajectory(actual, expected, options = {}) {
 * Scripted executors — a keyless, deterministic stand-in for a model host.
 *
 * `createScriptedExecutors` builds a full `{ generateText, streamText, decide }`
-* set that plays back canned answers from FIFO queues, so `runAgent` (or
+* set (plus a `userInput` handler) that plays back canned answers from FIFO
+* queues, so `runAgent` (or
 * `provideExecutors`, or a bare `TextLogic.execute`) runs with no API key and no
 * network. It is the fastest way to see a machine run, and the least ceremonial
 * way to test one: same machine, same executor contract, scripted answers.
@@ -2484,15 +2627,27 @@ function emitScriptedChunk(result, info) {
 *   decisions: [(request) => ({ type: request.events[0]!.type })],
 * });
 * ```
+*
+* @example Scripted human input
+* ```ts
+* const scripted = createScriptedExecutors({ userInput: ['ship it'] });
+* await runAgent(machine, { executors: scripted, userInput: scripted.userInput });
+* ```
 */
 function createScriptedExecutors(script = {}) {
 	const decisions = [...script.decisions ?? []];
 	const text = [...script.text ?? []];
+	const userInput = [...script.userInput ?? []];
 	const nextText = async (request, info) => {
 		if (text.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending text request ${describeText(request)}. Add another entry to the script's \`text\` queue.`);
 		return resolveScriptedTextEntry(text.shift(), request, info);
 	};
 	return {
+		userInput: async (input) => {
+			if (userInput.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending userInput request (prompt: ${input.prompt ? `'${input.prompt}'` : "(none)"}). Add another entry to the script's \`userInput\` queue.`);
+			const entry = userInput.shift();
+			return typeof entry === "function" ? await entry(input) : entry;
+		},
 		generateText: nextText,
 		streamText: async (request, info) => {
 			const result = await nextText(request, info);
@@ -2566,22 +2721,22 @@ async function runSeam(machine, options) {
 	const queueKeyOf = (request) => request.name !== void 0 && queues.has(request.name) ? request.name : request.model;
 	/**
 	* Consumes this request's slot in the call plan, or resolves `undefined` when
-	* its queue is dry. The LAST entry repeats: a live seam that branches further
-	* still finds an answer instead of running dry.
+	* its queue is dry. With `repeatLast`, the last entry is replayed instead of
+	* running dry.
 	*/
 	const takeScriptedSlot = async (request, info) => {
 		const queue = queues.get(queueKeyOf(request));
 		if (!queue?.length) return;
-		return resolveScriptedTextEntry(queue.length === 1 ? queue[0] : queue.shift(), request, info);
+		return resolveScriptedTextEntry(options.repeatLast && queue.length === 1 ? queue[0] : queue.shift(), request, info);
 	};
 	const scriptedAnswer = async (request, info) => {
 		const scripted = await takeScriptedSlot(request, info);
-		if (!scripted) throw new AgentError("seam-script-exhausted", `runSeam: no scripted answer left for request ${describeText(request)}. Add an entry to \`scripts.${queueKeyOf(request)}\` — its last entry repeats, so one extra answer covers a longer branch.`);
+		if (!scripted) throw new AgentError("seam-script-exhausted", `runSeam: no scripted answer left for request ${describeText(request)}. Add an entry to \`scripts.${queueKeyOf(request)}\`, or pass \`repeatLast: true\` to replay its last entry down a longer branch.`);
 		return scripted;
 	};
 	const route = async (request, info) => {
 		const callIndex = calls++;
-		const isSeam = (seam.request !== void 0 ? request.name === seam.request : request.model === seam.model) && seamMatches++ === (seam.occurrence ?? 0);
+		const isSeam = request.name === seam.request && seamMatches++ === (seam.occurrence ?? 0);
 		if (isSeam && candidate) {
 			await takeScriptedSlot(request, info);
 			seamReached = true;
@@ -2619,7 +2774,7 @@ async function runSeam(machine, options) {
 		result = await runAgent(machine, {
 			...snapshot ? { snapshot } : { input: options.input },
 			...event ? { event } : {},
-			...options.isSuspended ? { isSuspended: options.isSuspended } : {},
+			...options.isIdle ? { isIdle: options.isIdle } : {},
 			...options.actors ? { actors: options.actors } : {},
 			events,
 			executors,
@@ -2672,4 +2827,4 @@ async function runSeam(machine, options) {
 	};
 }
 //#endregion
-export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentIdleError, AgentIllegalResumeEventError, AgentLintError, AgentReplayDivergenceError, AgentReplayMachineMismatchError, AgentSnapshotVersionMismatchError, NonSerializableAgentEventError, appendMessages, assertAgentLogEntry, assertAgentMachine, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getAgentSchemas, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage, verifyReplay };
+export { AGENT_EVENT_SCHEMA_VERSION, AGENT_INIT_EVENT_TYPE, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentIdleError, AgentIllegalResumeEventError, AgentLintError, AgentMaxModelCallsExceededError, AgentReplayDivergenceError, AgentReplayMachineMismatchError, AgentSnapshotVersionMismatchError, NonSerializableAgentEventError, appendMessages, assertAgentLogEntry, assertEventLogStoreConformance, assertJsonSerializable, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentActor, createAgentRun, createAgentSchemas, createInMemoryEventLogStore, createReplayEntry, createScriptedExecutors, createTextLogic, diffEventLogs, executeAgentRequest, explorePaths, generateResult, getAcceptedEvents, getAgentEffects, getAgentMessages, getAgentOutputMode, getAgentSchemas, getCallUsage, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getSnapshotNodes, getSnapshotRequests, getStateMeta, initEntry, inspectTransitions, isStandardSchema, lintAgentMachine, matchesTrajectory, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, provideExecutors, renderDecisionAttempts, replay, resolveDecision, runAgent, runSeam, serializeTraceEvent, setupAgent, simulateAgent, systemMessage, toolMessage, traceTransitions, userMessage };