@statelyai/agent 2.0.0-alpha.15 → 2.0.0-alpha.17

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { _ as resolveAgentStep, a as AgentReplayDivergenceError, b as messagesSchema, c as diffEventLogs, d as initEntry, f as replay, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_USAGE_EVENT_TYPE, l as getAgentEffects, m as executeAgentRequest, n as setupAgent, o as AgentReplayMachineMismatchError, p as verifyReplay, r as AGENT_INIT_EVENT_TYPE, s as createReplayEntry, t as createAgentSchemas, u as getCallUsage, v as transitionAgentStep, y as appendMessages } from "./setup-agent-DeHRW-qX.mjs";
-import { A as isUnboundPlaceholder, B as getStateMeta, C as parseStructuredEnvelope, D as getMachineStaticTransitionTargets, E as executorBoundLogics, F as findNonSerializableContextPaths, G as userMessage, H as persistSnapshot, I as getAgentMessages, K as validateSchemaSync, L as getJsonSchema, O as getMachineSuspensionPredicate, P as assistantMessage, R as getJsonSchemaSync, S as parseOutput, U as systemMessage, V as isStandardSchema, W as toolMessage, _ as extractCallUsage, 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, r as isDecisionLogic, s as parseAgentEvent, t as AgentDecisionExhaustedError, u as INTERPRET_SOURCE, v as getAgentOutputMode, x as parseModelRef, y as isTextLogic, z as getMachineStructuralHash } from "./decision-D9Zi7Xi5.mjs";
-import { a as assertEventLogStoreConformance, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as assertJsonSerializable, r as NonSerializableAgentEventError, s as createInMemoryEventLogStore, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-D7pWtIhb.mjs";
+import { _ as resolveAgentStep, a as AgentReplayDivergenceError, b as messagesSchema, c as diffEventLogs, d as replay, f as validateReplayEntries, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_USAGE_EVENT_TYPE, l as getAgentEffects, m as executeAgentRequest, n as setupAgent, o as AgentReplayMachineMismatchError, p as verifyReplay, r as AGENT_INIT_EVENT_TYPE, s as createReplayEntry, t as createAgentSchemas, u as initEntry, v as transitionAgentStep, y as appendMessages } from "./setup-agent-CTg57Pa4.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 { createActor, createAsyncLogic, getNextTransitions, isMachineSnapshot } from "xstate";
 //#region src/internal/state-request-pass.ts
 async function runTextPhase(stateRequest, baseMessages, deps) {
@@ -41,7 +41,7 @@ async function runTextPhase(stateRequest, baseMessages, deps) {
 		output = await normalizeGeneratorResult(raw, id, { request });
 		const rawReasoning = raw?.reasoning;
 		const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
-		const usage = extractCallUsage(raw);
+		const usage = getCallUsage(raw);
 		if (usage) deps.recordUsage?.(usage);
 		deps.onResult?.(agentRequest, {
 			output,
@@ -346,22 +346,22 @@ function isStateMachine(logic) {
 * its own executor (`.withExecutor(...)`, tracked in `executorBoundLogics`)
 * always runs itself; explicit binding shadows inheritance.
 */
-function assertBindable(machine, effectiveSources, options) {
-	assertMachineBindable(machine, effectiveSources, options, {
+function assertBindable(machine, effectiveSources, executors) {
+	assertMachineBindable(machine, effectiveSources, executors, {
 		isChild: false,
 		childPath: "",
 		rebindable: true,
 		visited: new Set([machine])
 	});
 }
-function assertMachineBindable(machine, effectiveSources, options, ctx) {
+function assertMachineBindable(machine, effectiveSources, executors, ctx) {
 	const invokes = [];
 	collectConfiguredInvokeSrcs(machine.config, machine.config.id ?? "(root)", invokes);
 	const where = ctx.isChild ? `child machine '${ctx.childPath}' state` : "state";
 	for (const { stateName, src } of invokes) {
 		if (typeof src !== "string") {
 			if (isStateMachine(src)) {
-				assertChildMachineBindable(src, src, stateName, options, ctx);
+				assertChildMachineBindable(src, src, stateName, executors, ctx);
 				continue;
 			}
 			if ((isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src)) throw new Error(`runAgent: ${where} '${stateName}' invokes a direct-object actor logic (kind: '${src.kind}'). Direct-object invoke srcs cannot be rebound by runAgent — either call '.withExecutor(...)' on the logic before invoking it, or register it as a string-keyed actor source instead (machine.provide({ actors: { name: logic } })) and invoke it by name.`);
@@ -370,21 +370,21 @@ function assertMachineBindable(machine, effectiveSources, options, 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)) {
-			assertChildMachineBindable(logic, src, stateName, options, ctx);
+			assertChildMachineBindable(logic, src, stateName, executors, ctx);
 			continue;
 		}
 		if (src === "agent.userInput") continue;
 		if (isDecisionLogic(logic)) {
 			if (executorBoundLogics.has(logic)) continue;
 			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, "decision");
-			if (!options.hasDecide) throw new Error(`runAgent: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to runAgent(...).`);
+			if (!executors.decide) throw new Error(`runAgent: ${where} '${stateName}' invokes decision source '${src}' but no 'decide' executor was provided to runAgent(...).`);
 			continue;
 		}
 		if (isTextLogic(logic)) {
 			if (executorBoundLogics.has(logic)) continue;
 			if (!ctx.rebindable) throw unrebindableChildRequestError(ctx.childPath, stateName, src, logic.mode === "stream" ? "streaming text" : "text");
-			if (logic.mode === "stream" && !options.hasStreamText) throw new Error(`runAgent: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to runAgent(...).`);
-			if (logic.mode !== "stream" && !options.hasGenerateText) throw new Error(`runAgent: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to runAgent(...).`);
+			if (logic.mode === "stream" && !executors.streamText) throw new Error(`runAgent: ${where} '${stateName}' invokes streaming text source '${src}' but no 'streamText' executor was provided to runAgent(...).`);
+			if (logic.mode !== "stream" && !executors.generateText) throw new Error(`runAgent: ${where} '${stateName}' invokes text source '${src}' but no 'generateText' executor was provided to runAgent(...).`);
 			continue;
 		}
 		if (isUnboundPlaceholder(logic)) throw new Error(`runAgent: ${where} '${stateName}' invokes actor source '${src}', which has no host execution. Provide it via machine.provide({ actors: { '${src}': ... } }) or runAgent(machine, { actors: { '${src}': ... } }).`);
@@ -392,12 +392,12 @@ function assertMachineBindable(machine, effectiveSources, options, ctx) {
 }
 /** Descends the bind-time walk into an invoked child state machine, guarding
 * against a machine that (transitively) invokes itself. */
-function assertChildMachineBindable(childMachine, childSrc, stateName, options, ctx) {
+function assertChildMachineBindable(childMachine, childSrc, stateName, executors, ctx) {
 	if (ctx.visited.has(childMachine)) return;
 	const childName = typeof childSrc === "string" ? childSrc : childMachine.config.id ?? "(child machine)";
 	const childPath = ctx.childPath ? `${ctx.childPath} > ${childName}` : childName;
 	const childSources = childMachine.sources.actors;
-	assertMachineBindable(childMachine, childSources, options, {
+	assertMachineBindable(childMachine, childSources, executors, {
 		isChild: true,
 		childPath,
 		rebindable: ctx.rebindable && typeof childSrc === "string",
@@ -428,12 +428,45 @@ function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
 function declaresUsageTransition(snapshot) {
 	return getNextTransitions(snapshot).some((transition) => transition.eventType === AGENT_USAGE_EVENT_TYPE);
 }
+/**
+* Builds the ONE place a trace payload is emitted: it hands the payload to the
+* envelope-stamping trace sink and, from that same payload, invokes the sugar
+* callbacks that are projections of it — {@link RunAgentOptions.onChunk},
+* {@link RunAgentOptions.onResult}, {@link RunAgentOptions.onTransition}. Each
+* keeps its historical position relative to the trace: `onResult` fires just
+* BEFORE its `request.end`, `onChunk`/`onTransition` just AFTER their
+* `stream.chunk`/`machine.transition`. Sugar dispatch never depends on whether
+* a trace sink is present, and the trace sink is never called when it is
+* absent — so an `onTrace`-less run still mints no envelope (and advances no
+* `seq`). @internal
+*/
+function createTraceDispatch(sinks) {
+	return (payload, self) => {
+		switch (payload.type) {
+			case "stream.chunk":
+				sinks.onTrace?.(payload, self);
+				sinks.onChunk?.(payload.chunk, { request: payload.request });
+				return;
+			case "request.end":
+				sinks.onResult?.(payload.request, {
+					output: payload.output,
+					raw: payload.raw
+				});
+				sinks.onTrace?.(payload, self);
+				return;
+			case "machine.transition":
+				sinks.onTrace?.(payload, self);
+				sinks.onTransition?.(payload.snapshot, payload.event);
+				return;
+			default: sinks.onTrace?.(payload, self);
+		}
+	};
+}
 /** Reads the durable invoke id/src off the async actor's own ref (`self`). */
 function selfIdAndSrc(self) {
-	const ref = self;
 	return {
-		id: typeof ref?.id === "string" ? ref.id : "",
-		src: typeof ref?.src === "string" ? ref.src : ""
+		id: typeof self?.id === "string" ? self.id : "",
+		src: typeof self?.src === "string" ? self.src : ""
 	};
 }
 /**
@@ -455,8 +488,9 @@ function invokingActorOf(self, runCtx) {
 * Used by both `runAgent` and `provideExecutors` so the two paths produce
 * identical event shapes by construction. @internal
 */
-function wrapTextLogicForRunAgent(logic, runCtx) {
-	return logic.withExecutor(async ({ request, self, signal }) => {
+function bindTextLogic(logic, runCtx) {
+	return logic.withExecutor(async ({ request, self: selfArg, signal }) => {
+		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.`);
@@ -474,19 +508,18 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 			events: []
 		};
 		runCtx.consumeModelCall();
-		runCtx.onTrace?.({
+		runCtx.emitTrace?.({
 			type: "request.start",
 			request: agentRequest
 		}, self);
 		try {
 			const raw = await executor(requestWithTools, {
 				onChunk: (chunk) => {
-					runCtx.onTrace?.({
+					runCtx.emitTrace?.({
 						type: "stream.chunk",
 						request: agentRequest,
 						chunk
 					}, self);
-					runCtx.onChunk?.(chunk, { request: agentRequest });
 				},
 				signal,
 				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
@@ -495,17 +528,16 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 			const output = await normalizeGeneratorResult(raw, id, {
 				request,
 				onChunk: (chunk) => {
-					runCtx.onTrace?.({
+					runCtx.emitTrace?.({
 						type: "stream.chunk",
 						request: agentRequest,
 						chunk
 					}, self);
-					runCtx.onChunk?.(chunk, { request: agentRequest });
 				}
 			});
 			const rawReasoning = raw?.reasoning;
 			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
-			const usage = extractCallUsage(raw);
+			const usage = getCallUsage(raw);
 			if (usage) runCtx.recordUsage?.(usage, {
 				kind: "text",
 				...id !== "" ? { id } : {},
@@ -513,11 +545,7 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 				model: request.model,
 				...request.name !== void 0 ? { name: request.name } : {}
 			}, self);
-			runCtx.onResult?.(agentRequest, {
-				output,
-				raw
-			});
-			runCtx.onTrace?.({
+			runCtx.emitTrace?.({
 				type: "request.end",
 				request: agentRequest,
 				output,
@@ -527,7 +555,7 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 			}, self);
 			return { output };
 		} catch (error) {
-			runCtx.onTrace?.({
+			runCtx.emitTrace?.({
 				type: "request.error",
 				request: agentRequest,
 				error
@@ -539,7 +567,7 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 function createCountingDecide(runCtx, self) {
 	return async (attemptRequest) => {
 		runCtx.consumeModelCall();
-		runCtx.onTrace?.({
+		runCtx.emitTrace?.({
 			type: "request.start",
 			request: attemptRequest
 		}, self);
@@ -548,7 +576,7 @@ function createCountingDecide(runCtx, self) {
 				...attemptRequest,
 				runId: runCtx.runId
 			} : attemptRequest);
-			const usage = extractCallUsage(result);
+			const usage = getCallUsage(result);
 			if (usage) {
 				const { src } = selfIdAndSrc(self);
 				runCtx.recordUsage?.(usage, {
@@ -558,11 +586,7 @@ function createCountingDecide(runCtx, self) {
 					model: attemptRequest.model
 				}, self);
 			}
-			runCtx.onResult?.(attemptRequest, {
-				output: result.event,
-				raw: result
-			});
-			runCtx.onTrace?.({
+			runCtx.emitTrace?.({
 				type: "request.end",
 				request: attemptRequest,
 				output: result.event,
@@ -571,7 +595,7 @@ function createCountingDecide(runCtx, self) {
 			}, self);
 			return result;
 		} catch (error) {
-			runCtx.onTrace?.({
+			runCtx.emitTrace?.({
 				type: "request.error",
 				request: attemptRequest,
 				error
@@ -595,9 +619,10 @@ function createCountingDecide(runCtx, self) {
 * send-then-complete note inside `run` for how exit-cancels-invoke interacts
 * with `onDone`.
 */
-function createRunAgentDecisionLogic(logic, runCtx) {
-	const decisionLogic = createAsyncLogic({ run: async ({ input, signal, 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.");
+		const self = selfArg;
 		const { id } = selfIdAndSrc(self);
 		const declaredEventTypes = logic.allowedEventTypes?.(input);
 		await Promise.resolve();
@@ -623,7 +648,7 @@ function createRunAgentDecisionLogic(logic, runCtx) {
 		kind: "statelyai.decisionLogic",
 		maxRetries: logic.maxRetries,
 		request: logic.request,
-		withExecutor: (nextExecute) => createRunAgentDecisionLogic(logic.withExecutor(nextExecute), runCtx)
+		withExecutor: (nextExecute) => bindDecisionLogic(logic.withExecutor(nextExecute), runCtx)
 	});
 }
 /**
@@ -646,8 +671,7 @@ let nextProvideRunId = 1;
 /** Walks `self._parent` from an invoked async leaf actor up to its root actor. */
 function rootActorOf(self) {
 	let ref = self;
-	if (!ref) return;
-	while (ref._parent) ref = ref._parent;
+	while (ref?._parent) ref = ref._parent;
 	return ref;
 }
 /** The per-root envelope state, minted on first use (runId `run_<n>`, matching runAgent). */
@@ -680,7 +704,7 @@ function stampRootTrace(root, payload) {
 		...payload
 	};
 }
-/** Adapts a public `onTrace` into the payload-level {@link RunAgentBindContext.onTrace} sink used by the shared emission helpers. */
+/** Adapts a public `onTrace` into the payload-level trace sink a {@link TraceDispatch} fans out to. */
 function provideTraceSink(onTrace) {
 	if (!onTrace) return;
 	return (payload, self) => {
@@ -699,43 +723,48 @@ function provideTraceSink(onTrace) {
 *
 * `recordUsage` has no run-level aggregate to fold into here (there is no
 * run), so it does one thing: deliver the reserved `@agent.usage` event, gated
-* exactly like runAgent's — see {@link deliverUsageToInvokingActor}.
+* exactly like runAgent's — see {@link deliverUsageEvent}.
 */
 function provideBindContext(machine, executors, options) {
+	const traceSink = provideTraceSink(options.onTrace);
+	const onChunk = options.onChunk;
 	return {
 		generateText: executors.generateText,
 		streamText: executors.streamText,
 		decide: executors.decide,
-		onChunk: options.onChunk ? (chunk) => options.onChunk(chunk) : void 0,
-		onTrace: provideTraceSink(options.onTrace),
+		emitTrace: traceSink || onChunk ? createTraceDispatch({
+			onTrace: traceSink,
+			onChunk: onChunk ? (chunk) => onChunk(chunk) : void 0
+		}) : void 0,
 		consumeModelCall: () => {},
 		recordUsage: (usage, source, self) => {
-			deliverUsageToInvokingActor(usage, source ?? {}, self);
+			deliverUsageEvent(usage, source ?? {}, () => self?._parent);
 		},
 		actorHolder: { actorRef: void 0 },
 		schemas: getRegisteredAgentExecutionOptions(machine).schemas
 	};
 }
 /**
-* `provideExecutors`' counterpart to runAgent's `deliverUsageEvent`: after a
-* bound call settles with reported usage, send the reserved
-* `@agent.usage` event to the machine actor that INVOKED the request — read
-* off the settling request actor's `self._parent`, which under a live
-* `createActor` tree is always the invoking machine (there is no run-scoped
-* root actor on this path).
+* The single reserved-`@agent.usage` delivery seam, shared by both bind paths:
+* after a bound call settles with reported usage, send the event to the machine
+* actor `resolveActorRef` names — the run's root actor on the `runAgent` path,
+* the settling request actor's `self._parent` (always the invoking machine
+* under a live `createActor` tree) on the `provideExecutors` path.
 *
-* Gated identically to runAgent: the invoking 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. There is no cycle to settle in
-* uncontrolled mode, so there are no dropped stragglers.
+* 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
+* 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.
 *
-* Delivery follows `provideExecutors`' binding boundary: only sources IT bound
-* report here, so an invoked child machine that was not itself passed through
+* Delivery follows each path's binding boundary: only sources IT bound report
+* here, so an invoked child machine that was not itself passed through
 * `provideExecutors` reports nothing. @internal
 */
-function deliverUsageToInvokingActor(usage, source, self) {
-	const actorRef = self?._parent;
+function deliverUsageEvent(usage, source, resolveActorRef, onDropped) {
+	const actorRef = resolveActorRef();
 	if (!actorRef) return;
 	const snapshot = actorRef.getSnapshot();
 	if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
@@ -744,17 +773,18 @@ function deliverUsageToInvokingActor(usage, source, self) {
 		...source,
 		usage
 	};
+	if (onDropped?.(event)) return;
 	if (!snapshot.can(event)) return;
 	actorRef.send(event);
 }
 /**
 * Host-binds one text/stream source for {@link provideExecutors} using the SAME
-* emission helper as `runAgent` ({@link wrapTextLogicForRunAgent}), so a bound
+* emission helper as `runAgent` ({@link bindTextLogic}), so a bound
 * text request emits request.start/stream.chunk/request.end/request.error with
 * identical shapes. @internal
 */
 function bindTextForProvide(machine, logic, executors, options) {
-	return wrapTextLogicForRunAgent(logic, provideBindContext(machine, executors, options));
+	return bindTextLogic(logic, provideBindContext(machine, executors, options));
 }
 /**
 * Host-binds one `DecisionLogic`/`agent.decide` source for
@@ -763,7 +793,7 @@ function bindTextForProvide(machine, logic, executors, options) {
 * request-level tracing runAgent emits, minus run-scoped counting. @internal
 */
 function bindDecisionForProvide(machine, logic, executors, options) {
-	return createRunAgentDecisionLogic(logic, provideBindContext(machine, executors, options));
+	return bindDecisionLogic(logic, provideBindContext(machine, executors, options));
 }
 /**
 * Validates `input` against the machine's registered input schema, returning
@@ -806,11 +836,11 @@ function rebindChildMachine(childMachine, runCtx, visited) {
 	const wrapped = {};
 	for (const [key, logic] of Object.entries(sources)) {
 		if (isDecisionLogic(logic)) {
-			if (!executorBoundLogics.has(logic)) wrapped[key] = createRunAgentDecisionLogic(logic, runCtx);
+			if (!executorBoundLogics.has(logic)) wrapped[key] = bindDecisionLogic(logic, runCtx);
 			continue;
 		}
 		if (isTextLogic(logic)) {
-			if (!executorBoundLogics.has(logic)) wrapped[key] = wrapTextLogicForRunAgent(logic, runCtx);
+			if (!executorBoundLogics.has(logic)) wrapped[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
 		if (isStateMachine(logic)) {
@@ -902,20 +932,22 @@ function createAgentSession(machine, options, lifecycle) {
 		machineId,
 		version: machineVersion
 	};
-	const stampAgentMeta = (snapshot) => {
-		if (snapshot && typeof snapshot === "object") snapshot.agentMeta = agentMeta;
-	};
-	const onTrace = (event) => {
-		options.onTrace?.({
-			schemaVersion: 1,
-			runId,
-			seq: ++traceSeq,
-			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-			machineId,
-			machineVersion,
-			...event
-		});
-	};
+	const onTrace = createTraceDispatch({
+		onTrace: (payload) => {
+			options.onTrace?.({
+				schemaVersion: 1,
+				runId,
+				seq: ++traceSeq,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				machineId,
+				machineVersion,
+				...payload
+			});
+		},
+		onChunk: options.onChunk,
+		onResult: options.onResult,
+		onTransition: options.onTransition
+	});
 	const consumeModelCall = () => {
 		if (budgetExceeded) throw new AgentMaxModelCallsExceededError();
 		if (modelCallCount + 1 > maxModelCalls) {
@@ -926,33 +958,20 @@ function createAgentSession(machine, options, lifecycle) {
 	};
 	const tokenTotals = {};
 	const cycleGate = { isResolved: () => false };
-	const deliverUsageEvent = (usage, source) => {
-		const actorRef = actorHolder.actorRef;
-		if (!actorRef) return;
-		const event = {
-			type: AGENT_USAGE_EVENT_TYPE,
-			...source,
-			usage
-		};
-		const snapshot = actorRef.getSnapshot();
-		if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
-		if (cycleGate.isResolved()) {
-			onTrace({
-				type: "usage.dropped",
-				event,
-				reason: "settled"
-			});
-			return;
-		}
-		if (!snapshot.can(event)) return;
-		actorRef.send(event);
-	};
 	const recordUsage = (usage, source = {}) => {
 		for (const field of AGENT_USAGE_TOKEN_FIELDS) {
 			const value = usage[field];
 			if (typeof value === "number" && Number.isFinite(value)) tokenTotals[field] = (tokenTotals[field] ?? 0) + value;
 		}
-		deliverUsageEvent(usage, source);
+		deliverUsageEvent(usage, source, () => actorHolder.actorRef, (event) => {
+			if (!cycleGate.isResolved()) return false;
+			onTrace({
+				type: "usage.dropped",
+				event,
+				reason: "settled"
+			});
+			return true;
+		});
 	};
 	const runUsage = () => ({
 		...tokenTotals,
@@ -972,20 +991,14 @@ function createAgentSession(machine, options, lifecycle) {
 	};
 	const provided = machine.provide({ actors: options.actors });
 	const effectiveSources = provided.sources.actors;
-	assertBindable(provided, effectiveSources, {
-		hasGenerateText: !!options.executors?.generateText,
-		hasDecide: !!options.executors?.decide,
-		hasStreamText: !!options.executors?.streamText
-	});
+	assertBindable(provided, effectiveSources, options.executors ?? {});
 	if (options.getRequests && !options.executors?.generateText && !options.executors?.decide) throw new Error("runAgent: 'getRequests' requires a 'generateText' and/or 'decide' executor — the returned requests run through them.");
 	const actorHolder = { actorRef: void 0 };
 	const runCtx = {
 		generateText: options.executors?.generateText,
 		streamText: options.executors?.streamText,
 		decide: options.executors?.decide,
-		onChunk: options.onChunk,
-		onResult: options.onResult,
-		onTrace,
+		emitTrace: onTrace,
 		consumeModelCall,
 		recordUsage,
 		actorHolder,
@@ -1006,11 +1019,11 @@ function createAgentSession(machine, options, lifecycle) {
 			continue;
 		}
 		if (isDecisionLogic(logic)) {
-			wrappedSources[key] = createRunAgentDecisionLogic(logic, runCtx);
+			wrappedSources[key] = bindDecisionLogic(logic, runCtx);
 			continue;
 		}
 		if (isTextLogic(logic)) {
-			if (!executorBoundLogics.has(logic)) wrappedSources[key] = wrapTextLogicForRunAgent(logic, runCtx);
+			if (!executorBoundLogics.has(logic)) wrappedSources[key] = bindTextLogic(logic, runCtx);
 			continue;
 		}
 		if (isStateMachine(logic)) {
@@ -1052,9 +1065,11 @@ function createAgentSession(machine, options, lifecycle) {
 	}
 	const priorMessages = getAgentMessages(effectiveSnapshot);
 	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
-	const stampMessages = (snapshot) => {
+	const stampSettledSnapshot = (snapshot) => {
+		if (!snapshot || typeof snapshot !== "object") return;
+		snapshot.agentMeta = agentMeta;
 		if (!options.getRequests && !options.messages && messages.length === 0) return;
-		if (snapshot && typeof snapshot === "object") snapshot.messages = [...messages];
+		snapshot.messages = [...messages];
 	};
 	if (effectiveSnapshot !== void 0 && options.event !== void 0 && (options.onIllegalResumeEvent ?? "throw") === "throw") {
 		const acceptedTypes = getAcceptedEvents(createActor(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
@@ -1062,21 +1077,11 @@ function createAgentSession(machine, options, lifecycle) {
 		if (!acceptedTypes.includes(eventType)) throw new AgentIllegalResumeEventError(eventType, acceptedTypes);
 	}
 	const replayEvents = [...resumeEvents ?? []];
-	const replayEventIds = /* @__PURE__ */ new Set();
-	for (let index = 0; index < replayEvents.length; index++) {
-		const entry = replayEvents[index];
-		assertAgentLogEntry(entry);
-		if (entry.index !== index) throw new Error(`runAgent events must be contiguous from index 0; found entry.index ${entry.index} at position ${index}.`);
-		if (entry.machineId !== machineId || entry.machineVersion !== machineVersion) throw new AgentReplayMachineMismatchError(entry.id, entry.index, {
-			machineId,
-			machineVersion
-		}, {
-			machineId: entry.machineId,
-			machineVersion: entry.machineVersion
-		});
-		if (replayEventIds.has(entry.id)) throw new Error(`runAgent events contain duplicate event id '${entry.id}'.`);
-		replayEventIds.add(entry.id);
-	}
+	validateReplayEntries(replayEvents, {
+		machineId,
+		machineVersion
+	}, "runAgent events");
+	const replayEventIds = new Set(replayEvents.map((entry) => entry.id));
 	const hasCompleteReplayHistory = replayEvents[0]?.event.type === "@agent.init" || effectiveSnapshot === void 0 && replayEvents.length === 0;
 	const appendReplayEvent = (event) => {
 		const entry = createReplayEntry(machine, replayEvents, event, {
@@ -1095,247 +1100,239 @@ function createAgentSession(machine, options, lifecycle) {
 		replayEvents.push(entry);
 		options.onEvent?.(entry);
 	}
-	return (() => {
-		let settled = false;
-		let finalized = false;
-		cycleGate.isResolved = () => settled;
-		let lastResult;
-		const waiters = [];
-		let idleTimer;
-		let actor;
-		let deliveringResumeEvent = options.event !== void 0;
-		const settle = (outcome) => {
-			if (settled) return;
-			settled = true;
-			const result = {
-				...outcome,
-				events: [...replayEvents],
-				usage: runUsage()
-			};
-			if (idleTimer !== void 0) clearTimeout(idleTimer);
-			stampAgentMeta(result.snapshot);
-			stampMessages(result.snapshot);
-			if ("persistedSnapshot" in result) {
-				stampAgentMeta(result.persistedSnapshot);
-				stampMessages(result.persistedSnapshot);
-			}
-			onTrace({
-				type: "run.end",
-				...outcome
-			});
-			if (lifecycle.oneShot || result.status !== "idle") {
-				finalized = true;
-				if (options.signal) options.signal.removeEventListener("abort", onAbort);
-				actor.stop();
-			}
-			lastResult = result;
-			for (const resolve of waiters.splice(0)) resolve(result);
+	let settled = false;
+	let finalized = false;
+	cycleGate.isResolved = () => settled;
+	let lastResult;
+	const waiters = [];
+	let idleTimer;
+	let actor;
+	let deliveringResumeEvent = options.event !== void 0;
+	const settle = (outcome) => {
+		if (settled) return;
+		settled = true;
+		const result = {
+			...outcome,
+			events: [...replayEvents],
+			usage: runUsage()
 		};
-		const onAbort = () => {
-			settle({
-				status: "error",
-				cause: "aborted",
-				error: options.signal?.reason ?? /* @__PURE__ */ new Error("Aborted"),
-				snapshot: actor.getSnapshot()
-			});
-		};
-		const settleIdle = (current) => {
-			warnNonSerializableContext(current);
-			const pendingUserInputs = userInputIsPlaceholder ? collectPendingUserInputs(current) : [];
-			settle({
-				status: "idle",
-				snapshot: current,
-				persistedSnapshot: actor.getPersistedSnapshot(),
-				...pendingUserInputs.length > 0 ? { pendingUserInputs } : {}
-			});
-		};
-		let interpreting = false;
-		let interpretSeq = 0;
-		const appendToLog = (...items) => {
-			messages.push(...items);
-			if (options.onMessage) {
-				const info = {
-					runId,
-					machineId,
-					machineVersion
-				};
-				for (const item of items) options.onMessage(item, info);
-			}
-		};
-		const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
-		const settleInterpretError = (error) => {
-			settle({
-				status: "error",
-				cause: runErrorCause(error),
-				error,
-				snapshot: actor.getSnapshot()
-			});
-		};
-		const passDeps = {
-			getSnapshot: () => actor.getSnapshot(),
-			send: (event) => actor.send(event),
-			isSettled: () => settled,
-			messages,
-			appendToLog,
-			generateText: runCtx.generateText,
-			decide: runCtx.decide ? createCountingDecide(runCtx, void 0) : void 0,
-			consumeModelCall,
-			recordUsage,
-			nextRequestId: () => `interpret_${++interpretSeq}`,
-			onTrace,
-			onResult: runCtx.onResult,
-			schemas: runCtx.schemas,
-			signal: options.signal
-		};
-		const maybeInterpret = (snapshot) => {
-			if (!options.getRequests || settled) return false;
-			if (interpreting) return true;
-			let requested;
-			try {
-				requested = options.getRequests(snapshot, { messages });
-			} catch (error) {
-				settleInterpretError(error);
-				return true;
-			}
-			const requests = (Array.isArray(requested) ? requested : requested ? [requested] : []).filter((stateRequest) => Boolean(stateRequest));
-			if (requests.length === 0) return false;
-			interpreting = true;
-			runStateRequestPass(requests, passDeps).then(({ sentAny }) => {
-				if (settled || sentAny) return;
-				const current = actor.getSnapshot();
-				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
-			}).catch((error) => settleInterpretError(error)).finally(() => {
-				interpreting = false;
-				if (!settled) scheduleIdleCheck();
-			});
+		if (idleTimer !== void 0) clearTimeout(idleTimer);
+		stampSettledSnapshot(result.snapshot);
+		if ("persistedSnapshot" in result) stampSettledSnapshot(result.persistedSnapshot);
+		onTrace({
+			type: "run.end",
+			...outcome
+		});
+		if (lifecycle.oneShot || result.status !== "idle") {
+			finalized = true;
+			if (options.signal) options.signal.removeEventListener("abort", onAbort);
+			actor.stop();
+		}
+		lastResult = result;
+		for (const resolve of waiters.splice(0)) resolve(result);
+	};
+	const onAbort = () => {
+		settle({
+			status: "error",
+			cause: "aborted",
+			error: options.signal?.reason ?? /* @__PURE__ */ new Error("Aborted"),
+			snapshot: actor.getSnapshot()
+		});
+	};
+	const settleIdle = (current) => {
+		warnNonSerializableContext(current);
+		const pendingUserInputs = userInputIsPlaceholder ? collectPendingUserInputs(current) : [];
+		settle({
+			status: "idle",
+			snapshot: current,
+			persistedSnapshot: actor.getPersistedSnapshot(),
+			...pendingUserInputs.length > 0 ? { pendingUserInputs } : {}
+		});
+	};
+	let interpreting = false;
+	let interpretSeq = 0;
+	const appendToLog = (...items) => {
+		messages.push(...items);
+		if (options.onMessage) {
+			const info = {
+				runId,
+				machineId,
+				machineVersion
+			};
+			for (const item of items) options.onMessage(item, info);
+		}
+	};
+	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
+	const settleInterpretError = (error) => {
+		settle({
+			status: "error",
+			cause: runErrorCause(error),
+			error,
+			snapshot: actor.getSnapshot()
+		});
+	};
+	const passDeps = {
+		getSnapshot: () => actor.getSnapshot(),
+		send: (event) => actor.send(event),
+		isSettled: () => settled,
+		messages,
+		appendToLog,
+		generateText: runCtx.generateText,
+		decide: runCtx.decide ? createCountingDecide(runCtx, void 0) : void 0,
+		consumeModelCall,
+		recordUsage,
+		nextRequestId: () => `interpret_${++interpretSeq}`,
+		onTrace,
+		schemas: runCtx.schemas,
+		signal: options.signal
+	};
+	const maybeInterpret = (snapshot) => {
+		if (!options.getRequests || settled) return false;
+		if (interpreting) return true;
+		let requested;
+		try {
+			requested = options.getRequests(snapshot, { messages });
+		} catch (error) {
+			settleInterpretError(error);
 			return true;
-		};
-		const scheduleIdleCheck = () => {
-			if (idleTimer !== void 0) clearTimeout(idleTimer);
-			idleTimer = setTimeout(() => {
-				idleTimer = void 0;
-				if (settled) return;
-				const current = actor.getSnapshot();
-				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-					if (!maybeInterpret(current)) {
-						if (!declaredSuspensionPredicate && 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').");
-						}
-						settleIdle(current);
+		}
+		const requests = (Array.isArray(requested) ? requested : requested ? [requested] : []).filter((stateRequest) => Boolean(stateRequest));
+		if (requests.length === 0) return false;
+		interpreting = true;
+		runStateRequestPass(requests, passDeps).then(({ sentAny }) => {
+			if (settled || sentAny) return;
+			const current = actor.getSnapshot();
+			if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) settleIdle(current);
+		}).catch((error) => settleInterpretError(error)).finally(() => {
+			interpreting = false;
+			if (!settled) scheduleIdleCheck();
+		});
+		return true;
+	};
+	const scheduleIdleCheck = () => {
+		if (idleTimer !== void 0) clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => {
+			idleTimer = void 0;
+			if (settled) return;
+			const current = actor.getSnapshot();
+			if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+				if (!maybeInterpret(current)) {
+					if (!declaredSuspensionPredicate && 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').");
 					}
+					settleIdle(current);
 				}
-			}, 0);
-		};
-		actor = createActor(boundMachine, {
-			input: resolvedInput,
-			snapshot: effectiveSnapshot,
-			inspect: (event) => {
-				if (typeof options.inspect === "function") options.inspect(event);
-				else options.inspect?.next?.(event);
-				if (event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
-				if (settled) {
-					if (finalized) return;
-					settled = false;
-					lastResult = void 0;
-				}
-				const snapshot = event.snapshot;
-				let eventId;
-				if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) eventId = appendReplayEvent(event.event).id;
-				else if (event.event.type === "@xstate.init") eventId = replayEvents[0]?.event.type === "@agent.init" ? replayEvents[0].id : void 0;
-				onTrace({
-					type: "machine.transition",
-					snapshot,
-					event: event.event,
-					...eventId !== void 0 ? { eventId } : {}
-				});
-				options.onTransition?.(snapshot, event.event);
-				if (snapshot.status === "done") {
-					settle({
-						status: "done",
-						output: snapshot.output,
-						snapshot
-					});
-					return;
-				}
-				if (snapshot.status === "error") {
-					settle({
-						status: "error",
-						cause: runErrorCause(snapshot.error),
-						error: snapshot.error,
-						snapshot
-					});
-					return;
-				}
-				if (snapshot.status === "stopped") {
-					settle({
-						status: "error",
-						cause: "stopped",
-						error: /* @__PURE__ */ new Error("Actor stopped externally."),
-						snapshot
-					});
-					return;
-				}
-				if (!deliveringResumeEvent && isSuspended(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-					queueMicrotask(() => {
-						if (settled) return;
-						const current = actor.getSnapshot();
-						if (isSuspended(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-							if (!maybeInterpret(current)) settleIdle(current);
-						} else scheduleIdleCheck();
-					});
-					return;
-				}
-				scheduleIdleCheck();
 			}
-		});
-		actorHolder.actorRef = actor;
-		actor.subscribe({ error: () => {} });
-		actor.on("*", (event) => {
+		}, 0);
+	};
+	actor = createActor(boundMachine, {
+		input: resolvedInput,
+		snapshot: effectiveSnapshot,
+		inspect: (event) => {
+			if (typeof options.inspect === "function") options.inspect(event);
+			else options.inspect?.next?.(event);
+			if (event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
+			if (settled) {
+				if (finalized) return;
+				settled = false;
+				lastResult = void 0;
+			}
+			const snapshot = event.snapshot;
+			let eventId;
+			if (event.event.type !== "@xstate.init" && (event.sourceRef !== event.actorRef || event.event.type === "xstate.timer")) eventId = appendReplayEvent(event.event).id;
+			else if (event.event.type === "@xstate.init") eventId = replayEvents[0]?.event.type === "@agent.init" ? replayEvents[0].id : void 0;
 			onTrace({
-				type: "emit",
-				event
+				type: "machine.transition",
+				snapshot,
+				event: event.event,
+				...eventId !== void 0 ? { eventId } : {}
 			});
-		});
-		for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
-		const sessionApi = {
-			actor,
-			get events() {
-				return replayEvents;
-			},
-			usage: runUsage,
-			settled: () => settled && lastResult !== void 0 ? Promise.resolve(lastResult) : new Promise((resolve) => {
-				waiters.push(resolve);
-			}),
-			stop: () => {
-				actor.stop();
+			if (snapshot.status === "done") {
+				settle({
+					status: "done",
+					output: snapshot.output,
+					snapshot
+				});
+				return;
 			}
-		};
-		if (options.signal) {
-			if (options.signal.aborted) {
+			if (snapshot.status === "error") {
 				settle({
 					status: "error",
-					cause: "aborted",
-					error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
-					snapshot: actor.getSnapshot()
+					cause: runErrorCause(snapshot.error),
+					error: snapshot.error,
+					snapshot
+				});
+				return;
+			}
+			if (snapshot.status === "stopped") {
+				settle({
+					status: "error",
+					cause: "stopped",
+					error: /* @__PURE__ */ new Error("Actor stopped externally."),
+					snapshot
+				});
+				return;
+			}
+			if (!deliveringResumeEvent && isSuspended(snapshot) && isIdleSnapshot(snapshot, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+				queueMicrotask(() => {
+					if (settled) return;
+					const current = actor.getSnapshot();
+					if (isSuspended(current) && isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
+						if (!maybeInterpret(current)) settleIdle(current);
+					} else scheduleIdleCheck();
 				});
-				return sessionApi;
+				return;
 			}
-			options.signal.addEventListener("abort", onAbort);
+			scheduleIdleCheck();
 		}
+	});
+	actorHolder.actorRef = actor;
+	actor.subscribe({ error: () => {} });
+	actor.on("*", (event) => {
 		onTrace({
-			type: "run.start",
-			...resolvedInput !== void 0 ? { input: resolvedInput } : {},
-			...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
-			...options.event !== void 0 ? { event: options.event } : {}
+			type: "emit",
+			event
 		});
-		actor.start();
-		if (options.event) {
-			deliveringResumeEvent = false;
-			actor.send(options.event);
+	});
+	for (const [type, handler] of Object.entries(options.on ?? {})) if (typeof handler === "function") actor.on(type, handler);
+	const sessionApi = {
+		actor,
+		get events() {
+			return replayEvents;
+		},
+		usage: runUsage,
+		settled: () => settled && lastResult !== void 0 ? Promise.resolve(lastResult) : new Promise((resolve) => {
+			waiters.push(resolve);
+		}),
+		stop: () => {
+			actor.stop();
+		}
+	};
+	if (options.signal) {
+		if (options.signal.aborted) {
+			settle({
+				status: "error",
+				cause: "aborted",
+				error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
+				snapshot: actor.getSnapshot()
+			});
+			return sessionApi;
 		}
-		return sessionApi;
-	})();
+		options.signal.addEventListener("abort", onAbort);
+	}
+	onTrace({
+		type: "run.start",
+		...resolvedInput !== void 0 ? { input: resolvedInput } : {},
+		...effectiveSnapshot !== void 0 ? { snapshot: effectiveSnapshot } : {},
+		...options.event !== void 0 ? { event: options.event } : {}
+	});
+	actor.start();
+	if (options.event) {
+		deliveringResumeEvent = false;
+		actor.send(options.event);
+	}
+	return sessionApi;
 }
 /**
 * Runs an agent machine to a **final state**, for run-to-done flows where an
@@ -1491,14 +1488,17 @@ function createAgentRun(machine, options) {
 		});
 		else buffer.push(event);
 	};
-	const close = () => {
-		if (closed) return;
-		closed = true;
+	const drain = () => {
 		while (resolvers.length > 0) resolvers.shift()({
 			value: void 0,
 			done: true
 		});
 	};
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		drain();
+	};
 	const userOnTrace = options.onTrace;
 	const result = runAgent(machine, {
 		...options,
@@ -1527,10 +1527,7 @@ function createAgentRun(machine, options) {
 			return() {
 				stopped = true;
 				buffer.length = 0;
-				while (resolvers.length > 0) resolvers.shift()({
-					value: void 0,
-					done: true
-				});
+				drain();
 				return Promise.resolve({
 					value: void 0,
 					done: true
@@ -1578,7 +1575,7 @@ function createAgentRun(machine, options) {
 * Throws at bind time if a source needs an executor kind that `executors` does
 * not provide.
 *
-* v1 does NOT descend into invoked child state machines: a string-keyed child
+* `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).
 */
@@ -1587,32 +1584,36 @@ function provideExecutors(machine, executors, options = {}) {
 		onChunk: options.onChunk,
 		onTrace: options.onTrace
 	};
-	const provided = options.actors ? machine.provide({ actors: options.actors }) : machine;
+	const withActors = (target, actors) => target.provide({ actors });
+	const provided = options.actors ? withActors(machine, options.actors) : machine;
 	const effectiveSources = provided.sources.actors;
 	const wrappedSources = {};
 	const invokedSrcs = getConfiguredInvokeSrcs(provided);
 	for (const [key, logic] of Object.entries(effectiveSources)) {
 		if (key === "agent.userInput") continue;
-		if (isDecisionLogic(logic)) {
-			if (executorBoundLogics.has(logic)) continue;
-			if (!executors.decide) {
-				if (invokedSrcs.has(key)) throw missingExecutorError(key, "decision", "decide");
-				continue;
-			}
-			wrappedSources[key] = bindDecisionForProvide(provided, logic, executors, bindOptions);
-			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 (isTextLogic(logic)) {
-			if (executorBoundLogics.has(logic)) continue;
-			if (!(logic.mode === "stream" ? executors.streamText : executors.generateText)) {
-				if (invokedSrcs.has(key)) throw logic.mode === "stream" ? missingExecutorError(key, "streaming text", "streamText") : missingExecutorError(key, "text", "generateText");
-				continue;
-			}
-			wrappedSources[key] = bindTextForProvide(provided, logic, executors, bindOptions);
+		if (!binding) continue;
+		if (executorBoundLogics.has(logic)) continue;
+		if (!executors[binding.executorKey]) {
+			if (invokedSrcs.has(key)) throw missingExecutorError(key, binding.kind, binding.executorKey);
 			continue;
 		}
+		wrappedSources[key] = binding.bind();
 	}
-	return provided.provide({ actors: wrappedSources });
+	return withActors(provided, wrappedSources);
 }
 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.`);
@@ -1632,10 +1633,8 @@ function buildStateIndex(rootConfig) {
 			const hasChildren = !!config.states && Object.keys(config.states).length > 0;
 			index.set(path, {
 				path,
-				name,
 				config,
 				parentPath,
-				type: config.type,
 				isFinal: config.type === "final",
 				isParallel: config.type === "parallel",
 				isCompound: hasChildren && config.type !== "parallel",
@@ -1753,36 +1752,20 @@ function ancestorChain(node, index) {
 function hasNonEmptyOn(config) {
 	return !!config.on && Object.keys(config.on).length > 0;
 }
-function decisionKindOf(src, actors) {
-	if (typeof src === "string") {
-		if (src === DECIDE_SRC) return "decision";
-		return isDecisionLogic(actors[src]) ? "decision" : void 0;
-	}
-	return isDecisionLogic(src) ? "decision" : void 0;
+function isDecisionInvoke(src, actors) {
+	if (typeof src === "string") return src === DECIDE_SRC || isDecisionLogic(actors[src]);
+	return isDecisionLogic(src);
 }
 function isAgentLogicNeedingBinding(src) {
 	return (isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src);
 }
-function schemaExposesJson(schema) {
-	if (!schema) return false;
-	try {
-		return getJsonSchemaSync(schema) !== void 0;
-	} catch {
-		return false;
-	}
-}
-function isDeclaredOutputSchema(schema) {
-	if (!schema) return false;
-	let json;
+function readJsonSchema(schema) {
+	if (!schema) return;
 	try {
-		json = getJsonSchemaSync(schema);
+		return getJsonSchemaSync(schema);
 	} catch {
-		return false;
+		return;
 	}
-	if (!json) return false;
-	const properties = json.properties;
-	const required = json.required;
-	return json.type === "object" && !!properties && Object.keys(properties).length > 0 || Array.isArray(required) && required.length > 0;
 }
 function checkUnreachableStates(ctx) {
 	const out = [];
@@ -1797,8 +1780,7 @@ function checkUnreachableStates(ctx) {
 function checkDecideWithoutEvents(ctx) {
 	const out = [];
 	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
-		const kind = decisionKindOf(invoke.src, ctx.actors);
-		if (!kind) continue;
+		if (!isDecisionInvoke(invoke.src, ctx.actors)) continue;
 		const selfHandles = hasNonEmptyOn(node.config);
 		const ancestorHandles = ancestorChain(node, ctx.index).some((ancestor) => hasNonEmptyOn(ancestor.config));
 		const invokeObserves = invoke.onDone !== void 0;
@@ -1808,7 +1790,7 @@ function checkDecideWithoutEvents(ctx) {
 			code: "decide-without-events",
 			severity: "error",
 			path: node.path,
-			message: `State '${node.path}' invokes ${kind} source '${srcName}', but neither it nor any ancestor handles any event (no 'on:'), so the ${kind}'s chosen event can never be delivered. Add an 'on:' handler for the candidate events.`
+			message: `State '${node.path}' invokes decision source '${srcName}', but neither it nor any ancestor handles any event (no 'on:'), so the decision's chosen event can never be delivered. Add an 'on:' handler for the candidate events.`
 		});
 	}
 	return out;
@@ -1816,7 +1798,7 @@ function checkDecideWithoutEvents(ctx) {
 function checkUnserializableContext(ctx) {
 	const contextSchema = ctx.schemas?.context;
 	if (!contextSchema) return [];
-	if (schemaExposesJson(contextSchema)) return [];
+	if (readJsonSchema(contextSchema)) return [];
 	return [{
 		code: "unserializable-context",
 		severity: "warning",
@@ -1840,7 +1822,10 @@ function checkDirectObjectSrc(ctx) {
 	return out;
 }
 function checkFinalWithoutOutput(ctx) {
-	if (!isDeclaredOutputSchema(ctx.schemas?.output)) return [];
+	const outputJson = readJsonSchema(ctx.schemas?.output);
+	const properties = outputJson?.properties;
+	const required = outputJson?.required;
+	if (!(outputJson?.type === "object" && !!properties && Object.keys(properties).length > 0 || Array.isArray(required) && required.length > 0)) return [];
 	if (ctx.config.output !== void 0) return [];
 	const out = [];
 	for (const node of ctx.index.values()) {
@@ -1934,7 +1919,6 @@ function lintAgentMachine(machine, options = {}) {
 	const reachable = computeReachable(config, index, getMachineStaticTransitionTargets(machine));
 	const registered = getRegisteredAgentExecutionOptions(machine);
 	const ctx = {
-		machine,
 		config,
 		index,
 		reachable,
@@ -2017,7 +2001,7 @@ function takeFromQueue(channel, src) {
 async function simulateAgent(machine, options) {
 	const maxSteps = options.maxSteps ?? 100;
 	const script = {
-		text: { ...options.script.text },
+		text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
 		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
 		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
 	};
@@ -2089,6 +2073,7 @@ 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 MAX_ADVANCE_STEPS = 1e3;
 async function explore(machine, options, stopWhen) {
 	const maxDepth = options.maxDepth ?? 8;
 	const maxPaths = options.maxPaths ?? 200;
@@ -2113,7 +2098,7 @@ async function explore(machine, options, stopWhen) {
 	if (stopWhen?.(initial.snapshot)) witness = [];
 	const advance = (step) => {
 		let current = step;
-		for (let i = 0; i < 1e3; i++) {
+		for (let i = 0; i < MAX_ADVANCE_STEPS; i++) {
 			if (current.done) return { step: current };
 			const request = current.requests[0];
 			if (request && request.kind === "text") {
@@ -2265,19 +2250,22 @@ async function canReach(machine, statePath, options = {}) {
 	} : { canReach: false };
 }
 //#endregion
-//#region src/trajectory.ts
-function isRecord$2(value) {
+//#region src/internal/is-record.ts
+/** True for a plain object-like value (arrays excluded). @internal */
+function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+//#endregion
+//#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
 * everything else is a state value. A snapshot is unwrapped to its `value`.
 * @internal
 */
 function normalize(item) {
-	if (isRecord$2(item)) {
+	if (isRecord(item)) {
 		const nested = item["event"];
-		if (isRecord$2(nested) && typeof nested["type"] === "string") return {
+		if (isRecord(nested) && typeof nested["type"] === "string") return {
 			kind: "event",
 			event: nested
 		};
@@ -2298,7 +2286,7 @@ function normalize(item) {
 /** Every leaf of a state value as a dot path (`{ review: 'editing' }` → `review.editing`). @internal */
 function statePaths(value) {
 	if (typeof value === "string") return [value];
-	if (!isRecord$2(value)) return [];
+	if (!isRecord(value)) return [];
 	return Object.entries(value).flatMap(([key, child]) => statePaths(child).map((path) => `${key}.${path}`));
 }
 /**
@@ -2311,12 +2299,13 @@ function stateMatchesPath(path, value) {
 function deepEqual(a, b) {
 	if (Object.is(a, b)) return true;
 	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
-	if (!isRecord$2(a) || !isRecord$2(b)) return false;
+	if (!isRecord(a) || !isRecord(b)) return false;
 	const keys = Object.keys(a);
 	return keys.length === Object.keys(b).length && keys.every((key) => deepEqual(a[key], b[key]));
 }
 /**
-* Does one actual item satisfy one expected item?
+* Normalizes ONE expected item into a predicate over actual items, so the
+* expectation is classified once instead of once per candidate:
 *
 * - A string expectation matches an event's `type`, or a state value it names.
 * - An event expectation matches an event with the same `type` whose other
@@ -2324,13 +2313,22 @@ function deepEqual(a, b) {
 * - A state-value expectation matches structurally.
 * @internal
 */
-function matchesItem(expected, actual) {
-	const actualItem = normalize(actual);
-	if (typeof expected === "string") return actualItem.kind === "event" ? actualItem.event.type === expected : stateMatchesPath(expected, actualItem.value);
+function matcherFor(expected) {
+	if (typeof expected === "string") return (actual) => {
+		const actualItem = normalize(actual);
+		return actualItem.kind === "event" ? actualItem.event.type === expected : stateMatchesPath(expected, actualItem.value);
+	};
 	const expectedItem = normalize(expected);
-	if (expectedItem.kind !== actualItem.kind) return false;
-	if (expectedItem.kind === "event" && actualItem.kind === "event") return Object.keys(expectedItem.event).every((key) => deepEqual(expectedItem.event[key], actualItem.event[key]));
-	return deepEqual(expectedItem.value, actualItem.value);
+	switch (expectedItem.kind) {
+		case "event": return (actual) => {
+			const actualItem = normalize(actual);
+			return actualItem.kind === "event" && Object.keys(expectedItem.event).every((key) => deepEqual(expectedItem.event[key], actualItem.event[key]));
+		};
+		case "state": return (actual) => {
+			const actualItem = normalize(actual);
+			return actualItem.kind === "state" && deepEqual(expectedItem.value, actualItem.value);
+		};
+	}
 }
 /**
 * Matches a run's trajectory against an expected one.
@@ -2367,59 +2365,41 @@ function matchesItem(expected, actual) {
 */
 function matchesTrajectory(actual, expected, options = {}) {
 	const expectedCount = expected.length;
-	if (options.exact) {
-		let matchedCount = 0;
-		let firstMiss;
-		for (let index = 0; index < expectedCount; index++) {
-			if (index < actual.length && matchesItem(expected[index], actual[index])) {
-				matchedCount++;
-				continue;
-			}
-			firstMiss = {
-				index,
-				expected: expected[index],
-				searchedFrom: index
-			};
-			break;
-		}
-		const matched = !firstMiss && actual.length === expectedCount;
-		const denominator = Math.max(expectedCount, actual.length);
-		return {
-			matched,
-			matchedCount,
-			expectedCount,
-			score: matched ? 1 : denominator === 0 ? 1 : matchedCount / denominator,
-			...firstMiss ? { firstMiss } : {}
-		};
-	}
+	const exact = options.exact === true;
 	let cursor = 0;
 	let matchedCount = 0;
+	let firstMiss;
 	for (let index = 0; index < expectedCount; index++) {
 		const want = expected[index];
+		const matches = matcherFor(want);
+		const searchedFrom = exact ? index : cursor;
 		let found = -1;
-		for (let at = cursor; at < actual.length; at++) if (matchesItem(want, actual[at])) {
-			found = at;
-			break;
+		for (let at = searchedFrom; at < actual.length; at++) {
+			if (matches(actual[at])) {
+				found = at;
+				break;
+			}
+			if (exact) break;
 		}
-		if (found === -1) return {
-			matched: false,
-			matchedCount,
-			expectedCount,
-			score: matchedCount / expectedCount,
-			firstMiss: {
+		if (found === -1) {
+			firstMiss = {
 				index,
 				expected: want,
-				searchedFrom: cursor
-			}
-		};
+				searchedFrom
+			};
+			break;
+		}
 		matchedCount++;
 		cursor = found + 1;
 	}
+	const matched = !firstMiss && (!exact || actual.length === expectedCount);
+	const denominator = exact ? Math.max(expectedCount, actual.length) : expectedCount;
 	return {
-		matched: true,
+		matched,
 		matchedCount,
 		expectedCount,
-		score: 1
+		score: matched ? 1 : denominator === 0 ? 1 : matchedCount / denominator,
+		...firstMiss ? { firstMiss } : {}
 	};
 }
 //#endregion
@@ -2432,17 +2412,9 @@ function matchesTrajectory(actual, expected, options = {}) {
 * `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.
+*
+* @module
 */
-/** Thrown when a scripted queue runs dry on a pending request. */
-var ScriptedExecutorsError = class extends AgentError {
-	constructor(message) {
-		super("scripted-executors-exhausted", message);
-		this.name = "ScriptedExecutorsError";
-	}
-};
-function isRecord$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /** The only own keys an executor-result envelope carries. @internal */
 const TEXT_ENVELOPE_KEYS = new Set([
 	"output",
@@ -2467,7 +2439,22 @@ function isTextEnvelope(value) {
 */
 async function resolveScriptedTextEntry(entry, request, info) {
 	const value = typeof entry === "function" ? await entry(request, info) : entry;
-	return isRecord$1(value) && isTextEnvelope(value) ? value : { output: value };
+	return isRecord(value) && isTextEnvelope(value) ? value : { output: value };
+}
+/**
+* Names a pending text request in an error message. Shared with `runSeam`.
+* @internal
+*/
+function describeText(request) {
+	return request.name ? `'${request.name}' (model '${request.model}')` : `(model '${request.model}')`;
+}
+/**
+* Stream semantics with no model: the whole text lands as one chunk. Shared
+* with `runSeam`, whose scripted answers stream the same way. @internal
+*/
+function emitScriptedChunk(result, info) {
+	const output = isRecord(result) ? result["output"] : void 0;
+	if (typeof output === "string") info?.onChunk?.(output);
 }
 /**
 * Keyless executors that replay a script instead of calling a model. Every
@@ -2502,45 +2489,26 @@ function createScriptedExecutors(script = {}) {
 	const decisions = [...script.decisions ?? []];
 	const text = [...script.text ?? []];
 	const nextText = async (request, info) => {
-		if (text.length === 0) throw new ScriptedExecutorsError(`createScriptedExecutors: script ran dry on a pending text request ${describeText(request)}. Add another entry to the script's \`text\` queue.`);
+		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 {
 		generateText: nextText,
 		streamText: async (request, info) => {
 			const result = await nextText(request, info);
-			if (typeof result.output === "string") info?.onChunk?.(result.output);
+			emitScriptedChunk(result, info);
 			return result;
 		},
 		decide: async (request) => {
-			if (decisions.length === 0) throw new ScriptedExecutorsError(`createScriptedExecutors: script ran dry on a pending decision request (id '${request.id}'). Add another entry to the script's \`decisions\` queue. Candidate events: ${request.events.map((event) => event.type).join(", ") || "(none)"}.`);
+			if (decisions.length === 0) throw new AgentError("scripted-executors-exhausted", `createScriptedExecutors: script ran dry on a pending decision request (id '${request.id}'). Add another entry to the script's \`decisions\` queue. Candidate events: ${request.events.map((event) => event.type).join(", ") || "(none)"}.`);
 			const entry = decisions.shift();
 			const value = typeof entry === "function" ? await entry(request) : entry;
-			return typeof value.type === "string" ? { event: value } : value;
+			return isRecord(value) && typeof value["type"] !== "string" && "event" in value ? value : { event: value };
 		}
 	};
 }
-function describeText(request) {
-	return request.name ? `'${request.name}'` : `(model '${request.model}')`;
-}
 //#endregion
 //#region src/seam.ts
-/** Thrown when the call plan runs dry on a request that is not the live seam. */
-var SeamScriptError = class extends AgentError {
-	constructor(message) {
-		super("seam-script-exhausted", message);
-		this.name = "SeamScriptError";
-	}
-};
-function seamKeyOf(seam) {
-	return seam.request ?? seam.model;
-}
-function describeRequest(request) {
-	return request.name ? `'${request.name}' (model '${request.model}')` : `(model '${request.model}')`;
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
 /**
 * The seam's own answer, for scoring. Our `{ output }` envelope is read
 * directly; a raw AI SDK `generateText` result contributes its `text`. A raw
@@ -2595,40 +2563,50 @@ async function runSeam(machine, options) {
 	let seamStateAt = 0;
 	let seamEventAt = 0;
 	let liveEvents = 0;
-	const scriptedAnswer = async (request, info, optional) => {
-		const key = request.name !== void 0 && queues.has(request.name) ? request.name : request.model;
-		const queue = queues.get(key);
-		if (!queue?.length) {
-			if (optional) return;
-			throw new SeamScriptError(`runSeam: no scripted answer left for request ${describeRequest(request)}. Add an entry to \`scripts.${key}\` — its last entry repeats, so one extra answer covers a longer branch.`);
-		}
+	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.
+	*/
+	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);
 	};
+	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.`);
+		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 scripted = await scriptedAnswer(request, info, isSeam && candidate !== void 0);
+		if (isSeam && candidate) {
+			await takeScriptedSlot(request, info);
+			seamReached = true;
+			callsBeforeSeam = callIndex;
+			seamStateAt = statePath.length;
+			seamEventAt = liveEvents;
+			const result = await candidate(request, info);
+			seamOutput = await seamOutputOf(result, request);
+			return result;
+		}
+		const scripted = await scriptedAnswer(request, info);
 		if (!isSeam) return scripted;
 		seamReached = true;
 		callsBeforeSeam = callIndex;
 		seamStateAt = statePath.length;
 		seamEventAt = liveEvents;
-		if (!candidate) {
-			if (!scripted) throw new SeamScriptError(`runSeam: the seam '${seamKeyOf(seam)}' has no candidate and no scripted answer. Pass \`candidate\`, or script the seam's key.`);
-			seamOutput = scripted.output;
-			return scripted;
-		}
-		const result = await candidate(request, info);
-		seamOutput = await seamOutputOf(result, request);
-		return result;
+		seamOutput = scripted.output;
+		return scripted;
 	};
 	const executors = {
 		...options.executors,
 		generateText: route,
 		streamText: async (request, info) => {
 			const result = await route(request, info);
-			const output = isRecord(result) ? result["output"] : void 0;
-			if (typeof output === "string") info?.onChunk?.(output);
+			emitScriptedChunk(result, info);
 			return result;
 		}
 	};