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

package/dist/index.cjs

@@ -1,571 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_events = require("./events-CRQj3VtP.cjs");
-const require_decision = require("./decision-D8wJrM8W.cjs");
-const require_steps = require("./steps-CVe54GPP.cjs");
+const require_errors = require("./errors-DUBBzRLP.cjs");
+const require_setup_agent = require("./setup-agent-DP95MFrI.cjs");
+const require_decision = require("./decision-dWGhBh0P.cjs");
+const require_event_log_store = require("./event-log-store-CNT_7F0V.cjs");
 let xstate = require("xstate");
-//#region src/messages.ts
-function addMessages(resolve) {
-	return (args) => {
-		const resolved = typeof resolve === "function" ? resolve(args) : resolve;
-		return [...args.context.messages, ...Array.isArray(resolved) ? resolved : [resolved]];
-	};
-}
-/**
-* Builds a transition-function result that appends one or more
-* {@link AgentMessage}s to a context's `messages` array. `resolve` is either
-* a message (or array of messages) or a function of `{ context, event }`
-* returning them; the returned function is meant to be used directly as (or
-* composed into) a transition's result, e.g. `on: { USER_REPLIED:
-* agent.appendMessages(({ event }) => userMessage(event.text)) }`. Requires
-* `messages: AgentMessage[]` on context — see {@link messagesSchema} for a
-* ready-made schema for that field.
-*
-* @example
-* ```ts
-* on: {
-*   USER_REPLIED: appendMessages(({ event }) => userMessage(event.text)),
-* }
-* ```
-*/
-function appendMessages(resolve) {
-	return (args) => ({ context: { messages: addMessages(resolve)(args) } });
-}
-const KNOWN_PART_TYPES = new Set([
-	"text",
-	"image",
-	"file",
-	"tool-call",
-	"tool-result"
-]);
-function isKnownPart(part) {
-	return !!part && typeof part === "object" && KNOWN_PART_TYPES.has(part.type);
-}
-function validatePartsArray(content) {
-	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
-	for (const part of content) if (!isKnownPart(part)) {
-		const type = part && typeof part === "object" ? part.type : void 0;
-		return `Unknown message part type: ${JSON.stringify(type)}`;
-	}
-}
-/**
-* A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
-* checks that every message has a known `role` (`system`/`user`/`assistant`/
-* `tool`) and that `content` is either a string (where the role allows it) or
-* an array of parts with a known `type`. Use it directly as a context
-* schema's `messages` field when authoring with `createAgentSchemas`.
-*/
-const messagesSchema = { "~standard": {
-	version: 1,
-	vendor: "statelyai-agent",
-	validate(value) {
-		if (!Array.isArray(value)) return { issues: [{ message: "Expected an array of agent messages" }] };
-		for (const message of value) {
-			if (!message || typeof message !== "object") return { issues: [{ message: "Expected an array of agent messages" }] };
-			const role = message.role;
-			const content = message.content;
-			if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") return { issues: [{ message: `Unknown message role: ${JSON.stringify(role)}` }] };
-			if (role === "system") {
-				if (typeof content !== "string") return { issues: [{ message: "system message content must be a string" }] };
-				continue;
-			}
-			if (role === "tool") {
-				const error = validatePartsArray(content) ?? (content.some((part) => part.type !== "tool-result") ? "tool message content must contain only tool-result parts" : void 0);
-				if (error) return { issues: [{ message: error }] };
-				continue;
-			}
-			if (typeof content === "string") continue;
-			const error = validatePartsArray(content);
-			if (error) return { issues: [{ message: error }] };
-		}
-		return { value };
-	}
-} };
-//#endregion
-//#region src/workflow-config.ts
-const DECIDE_SRC$1 = "agent.decide";
-const workflowConfigWholeExpressionPattern = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
-const workflowConfigTemplateExpressionPattern = /\{\{\s*([\s\S]*?)\s*\}\}/g;
-function evaluateWorkflowConfigPath(expression, scope) {
-	const parts = expression.trim().split(".").filter(Boolean);
-	let current = scope;
-	for (const part of parts) {
-		if (!current || typeof current !== "object") return;
-		current = current[part];
-	}
-	return current;
-}
-function evaluateWorkflowConfigValue(value, scope) {
-	if (typeof value === "string") {
-		const wholeMatch = value.match(workflowConfigWholeExpressionPattern);
-		if (wholeMatch?.[1]) return evaluateWorkflowConfigPath(wholeMatch[1], scope);
-		return value.replace(workflowConfigTemplateExpressionPattern, (_match, expression) => {
-			const resolved = evaluateWorkflowConfigPath(expression, scope);
-			return resolved === void 0 || resolved === null ? "" : String(resolved);
-		});
-	}
-	if (Array.isArray(value)) return value.map((item) => evaluateWorkflowConfigValue(item, scope));
-	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, evaluateWorkflowConfigValue(item, scope)]));
-	return value;
-}
-function createSchemasFromWorkflowConfig(config, compileSchema) {
-	return createAgentSchemas({
-		context: compileSchema(config.schemas?.context ?? { type: "object" }, "context"),
-		events: Object.fromEntries(Object.entries(config.schemas?.events ?? {}).map(([key, schema]) => [key, compileSchema(schema, `event.${key}`)])),
-		emitted: Object.fromEntries(Object.entries(config.schemas?.emitted ?? {}).map(([key, schema]) => [key, compileSchema(schema, `emitted.${key}`)])),
-		input: compileSchema(config.schemas?.input ?? {}, "input"),
-		output: compileSchema(config.schemas?.output ?? {}, "output"),
-		meta: compileSchema(config.schemas?.meta ?? {}, "meta")
-	});
-}
-function createRequestsFromWorkflowConfig(config, compileSchema) {
-	return Object.fromEntries(Object.entries(config.requests ?? {}).map(([key, request]) => [key, {
-		mode: request.mode,
-		description: request.description,
-		schemas: {
-			input: compileSchema(request.input, `${key}.input`),
-			output: compileSchema(request.output, `${key}.output`)
-		},
-		model: ({ input }) => String(evaluateWorkflowConfigValue(request.model, { input }) ?? ""),
-		system: request.system === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.system, { input }),
-		prompt: request.prompt === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.prompt, { input }),
-		messages: request.messages === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.messages, { input }),
-		tools: request.tools,
-		toolChoice: request.toolChoice,
-		reasoning: request.reasoning,
-		temperature: request.temperature === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.temperature, { input }),
-		maxOutputTokens: request.maxOutputTokens === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.maxOutputTokens, { input }),
-		topP: request.topP === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topP, { input }),
-		topK: request.topK === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.topK, { input }),
-		seed: request.seed === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.seed, { input }),
-		stopSequences: request.stopSequences === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.stopSequences, { input }),
-		metadata: request.metadata === void 0 ? void 0 : ({ input }) => evaluateWorkflowConfigValue(request.metadata, { input })
-	}]));
-}
-function createActorPlaceholdersFromWorkflowConfig(config) {
-	return Object.fromEntries(Object.keys(config.actors ?? {}).map((key) => [key, require_events.missingActor(key)]));
-}
-function createAssignAction(assignConfig) {
-	return ({ context, event }) => ({ context: Object.fromEntries(Object.entries(assignConfig).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, {
-		context,
-		event
-	})])) });
-}
-function lowerWorkflowActions(actionConfig) {
-	if (!actionConfig) return;
-	const lowered = (Array.isArray(actionConfig) ? actionConfig : [actionConfig]).map((action) => {
-		if (action.assign !== void 0) return createAssignAction(action.assign);
-		if (action.emit !== void 0) return ({ context, event }, enq) => {
-			enq.emit(evaluateWorkflowConfigValue(action.emit, {
-				context,
-				event
-			}));
-		};
-		if (!action.type) throw new Error("setupAgent.fromConfig: action must declare 'type', 'assign', or 'emit'.");
-		return {
-			type: action.type,
-			params: ({ context, event }) => evaluateWorkflowConfigValue(action.params, {
-				context,
-				event
-			})
-		};
-	});
-	return Array.isArray(actionConfig) ? lowered : lowered[0];
-}
-function workflowTransitionMatches(transitionConfig, scope) {
-	if (transitionConfig.guard === void 0) return true;
-	if (typeof transitionConfig.guard === "string") return Boolean(evaluateWorkflowConfigValue(transitionConfig.guard, scope));
-	return typeof transitionConfig.guard === "function" ? transitionConfig.guard(scope) : false;
-}
-function applyWorkflowTransitionActions(actionConfig, scope, enq) {
-	if (!actionConfig) return;
-	const actions = Array.isArray(actionConfig) ? actionConfig : [actionConfig];
-	let assigned;
-	for (const action of actions) if (action.assign !== void 0) assigned = {
-		...assigned ?? {},
-		...Object.fromEntries(Object.entries(action.assign).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, scope)]))
-	};
-	else if (action.emit !== void 0) enq.emit(evaluateWorkflowConfigValue(action.emit, scope));
-	else if (action.type) throw new Error(`setupAgent.fromConfig: named action type '${action.type}' is not supported in a transition 'actions' entry (config lowering wires no action implementations). Use 'emit' or 'assign', or move it to a state 'entry'/'exit'.`);
-	else throw new Error("setupAgent.fromConfig: a transition action must declare 'emit', 'assign', or 'type'.");
-	return assigned;
-}
-function lowerWorkflowTransitionResult(transitionConfig, scope, enq) {
-	const actionAssign = applyWorkflowTransitionActions(transitionConfig.actions, scope, enq);
-	const configAssign = transitionConfig.assign ? Object.fromEntries(Object.entries(transitionConfig.assign).map(([key, value]) => [key, evaluateWorkflowConfigValue(value, scope)])) : void 0;
-	const context = configAssign || actionAssign ? {
-		...configAssign ?? {},
-		...actionAssign ?? {}
-	} : void 0;
-	return {
-		...transitionConfig.target !== void 0 ? { target: transitionConfig.target } : {},
-		...context ? { context } : {},
-		...transitionConfig.description !== void 0 ? { description: transitionConfig.description } : {},
-		...transitionConfig.reenter !== void 0 ? { reenter: transitionConfig.reenter } : {},
-		...transitionConfig.meta !== void 0 ? { meta: transitionConfig.meta } : {}
-	};
-}
-function lowerWorkflowTransition(transitionConfig) {
-	return ({ context, event }, enq) => {
-		const scope = {
-			context,
-			event
-		};
-		if (!workflowTransitionMatches(transitionConfig, scope)) return;
-		return lowerWorkflowTransitionResult(transitionConfig, scope, enq);
-	};
-}
-function lowerWorkflowTransitionOrArray(transitionConfig) {
-	if (!transitionConfig) return;
-	return Array.isArray(transitionConfig) ? ({ context, event }, enq) => {
-		const scope = {
-			context,
-			event
-		};
-		const transition = transitionConfig.find((candidate) => workflowTransitionMatches(candidate, scope));
-		if (!transition) return;
-		return lowerWorkflowTransitionResult(transition, scope, enq);
-	} : lowerWorkflowTransition(transitionConfig);
-}
-function lowerWorkflowInvoke(invokeConfig, stateKey) {
-	if (invokeConfig.src === DECIDE_SRC$1 && invokeConfig.onDone !== void 0) throw new Error(`setupAgent.fromConfig: state '${stateKey}' declares an 'onDone' on its 'agent.decide' invoke, which is always a config error. A decision has no output of its own — the chosen event is delivered automatically and handled by the state's 'on' transitions. Remove the 'onDone' (use 'on' for the chosen event; 'onError' still handles retries exhausted).`);
-	return {
-		...invokeConfig.id !== void 0 ? { id: invokeConfig.id } : {},
-		src: invokeConfig.src,
-		...invokeConfig.input !== void 0 ? { input: ({ context, event }) => evaluateWorkflowConfigValue(invokeConfig.input, {
-			context,
-			event
-		}) } : {},
-		...invokeConfig.onDone !== void 0 ? { onDone: lowerWorkflowTransitionOrArray(invokeConfig.onDone) } : {},
-		...invokeConfig.onError !== void 0 ? { onError: lowerWorkflowTransitionOrArray(invokeConfig.onError) } : {},
-		...invokeConfig.meta !== void 0 ? { meta: invokeConfig.meta } : {}
-	};
-}
-function assertValidTransitionTargets(stateKey, location, transitionConfig, siblingKeys) {
-	if (!transitionConfig) return;
-	const transitions = Array.isArray(transitionConfig) ? transitionConfig : [transitionConfig];
-	for (const transition of transitions) {
-		const targets = transition.target === void 0 ? [] : Array.isArray(transition.target) ? transition.target : [transition.target];
-		for (const target of targets) {
-			if (typeof target !== "string" || target.startsWith("#") || target.startsWith(".")) continue;
-			const head = target.split(".")[0];
-			if (!siblingKeys.has(head)) throw new Error(`setupAgent.fromConfig: state '${stateKey}' has a ${location} transition targeting '${target}', which is not a state at that level. Valid targets: ${[...siblingKeys].join(", ") || "(none)"}.`);
-		}
-	}
-}
-function assertStateTransitionTargets(stateKey, stateConfig, siblingKeys) {
-	for (const [eventType, transition] of Object.entries(stateConfig.on ?? {})) assertValidTransitionTargets(stateKey, `'on.${eventType}'`, transition, siblingKeys);
-	for (const [delay, transition] of Object.entries(stateConfig.after ?? {})) assertValidTransitionTargets(stateKey, `'after.${delay}'`, transition, siblingKeys);
-	assertValidTransitionTargets(stateKey, "'always'", stateConfig.always, siblingKeys);
-	assertValidTransitionTargets(stateKey, "'onDone'", stateConfig.onDone, siblingKeys);
-	assertValidTransitionTargets(stateKey, "'choice'", stateConfig.choice, siblingKeys);
-	const invokes = stateConfig.invoke ? Array.isArray(stateConfig.invoke) ? stateConfig.invoke : [stateConfig.invoke] : [];
-	for (const invoke of invokes) {
-		assertValidTransitionTargets(stateKey, "invoke 'onDone'", invoke.onDone, siblingKeys);
-		assertValidTransitionTargets(stateKey, "invoke 'onError'", invoke.onError, siblingKeys);
-	}
-}
-function lowerWorkflowState(stateKey, stateConfig, siblingKeys) {
-	assertStateTransitionTargets(stateKey, stateConfig, siblingKeys);
-	const childKeys = new Set(Object.keys(stateConfig.states ?? {}));
-	return {
-		...stateConfig.description !== void 0 ? { description: stateConfig.description } : {},
-		...stateConfig.type !== void 0 ? { type: stateConfig.type } : {},
-		...stateConfig.initial !== void 0 ? { initial: stateConfig.initial } : {},
-		...stateConfig.states !== void 0 ? { states: Object.fromEntries(Object.entries(stateConfig.states).map(([key, child]) => [key, lowerWorkflowState(key, child, childKeys)])) } : {},
-		...stateConfig.choice !== void 0 ? { choice: lowerWorkflowTransitionOrArray(stateConfig.choice) } : {},
-		...stateConfig.invoke !== void 0 ? { invoke: Array.isArray(stateConfig.invoke) ? stateConfig.invoke.map((invoke) => lowerWorkflowInvoke(invoke, stateKey)) : lowerWorkflowInvoke(stateConfig.invoke, stateKey) } : {},
-		...stateConfig.on !== void 0 ? { on: Object.fromEntries(Object.entries(stateConfig.on).map(([eventType, transitionConfig]) => [eventType, lowerWorkflowTransitionOrArray(transitionConfig)])) } : {},
-		...stateConfig.always !== void 0 ? { always: lowerWorkflowTransitionOrArray(stateConfig.always) } : {},
-		...stateConfig.onDone !== void 0 ? { onDone: lowerWorkflowTransitionOrArray(stateConfig.onDone) } : {},
-		...stateConfig.after !== void 0 ? { after: Object.fromEntries(Object.entries(stateConfig.after).map(([delay, transitionConfig]) => [delay, lowerWorkflowTransitionOrArray(transitionConfig)])) } : {},
-		...stateConfig.entry !== void 0 ? { entry: lowerWorkflowActions(stateConfig.entry) } : {},
-		...stateConfig.exit !== void 0 ? { exit: lowerWorkflowActions(stateConfig.exit) } : {},
-		...stateConfig.tags !== void 0 ? { tags: stateConfig.tags } : {},
-		...stateConfig.output !== void 0 ? { output: ({ context, event }) => evaluateWorkflowConfigValue(stateConfig.output, {
-			context,
-			event
-		}) } : {},
-		...stateConfig.meta !== void 0 ? { meta: stateConfig.meta } : {}
-	};
-}
-function setupAgentFromConfig(config, options) {
-	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
-	const { compileSchema } = options;
-	const schemas = createSchemasFromWorkflowConfig(config, compileSchema);
-	const requestActors = createRequestActors(createRequestsFromWorkflowConfig(config, compileSchema));
-	return setupAgent({
-		schemas,
-		actorSources: {
-			...createActorPlaceholdersFromWorkflowConfig(config),
-			...requestActors
-		}
-	}).createMachine({
-		...config.id !== void 0 ? { id: config.id } : {},
-		...config.description !== void 0 ? { description: config.description } : {},
-		...config.context !== void 0 ? { context: ({ input }) => require_events.validateSchemaSync(schemas.context, evaluateWorkflowConfigValue(config.context, { input })) } : {},
-		initial: config.initial,
-		states: (() => {
-			const rootKeys = new Set(Object.keys(config.states));
-			return Object.fromEntries(Object.entries(config.states).map(([key, state]) => [key, lowerWorkflowState(key, state, rootKeys)]));
-		})(),
-		...config.meta !== void 0 ? { meta: config.meta } : {}
-	});
-}
-//#endregion
-//#region src/setup-agent.ts
-const emptyEventSchema = { "~standard": {
-	version: 1,
-	vendor: "statelyai-agent",
-	validate(value) {
-		return value !== null && typeof value === "object" && Object.keys(value).length === 0 ? { value: {} } : { issues: [{ message: "Expected an empty event payload" }] };
-	}
-} };
-function normalizeEventSchemas(events) {
-	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
-}
-/**
-* Builds a machine's {@link AgentSchemaPack} from a partial schema
-* declaration — only `context` is required; `events`/`input`/`output`/`meta`
-* default to empty/unknown schemas when omitted. Pass the result as
-* `setupAgent({ schemas })`'s `schemas` (or spread the individual fields
-* directly into `setupAgent({ context, events, ... })` — both forms are
-* accepted).
-*/
-function createAgentSchemas(schemas) {
-	return {
-		context: schemas.context,
-		events: normalizeEventSchemas(schemas.events ?? {}),
-		input: schemas.input,
-		output: schemas.output,
-		meta: schemas.meta,
-		emitted: schemas.emitted
-	};
-}
-function mergeContextSchema(base, fields) {
-	return { "~standard": {
-		version: 1,
-		vendor: "statelyai-agent",
-		validate(value) {
-			const baseResult = base["~standard"].validate(value);
-			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
-			if (baseResult.issues) return baseResult;
-			const merged = { ...baseResult.value };
-			const issues = [];
-			for (const [key, fieldSchema] of Object.entries(fields)) {
-				const fieldResult = fieldSchema["~standard"].validate(value[key]);
-				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
-				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
-					...issue,
-					path: [key, ...issue.path ?? []]
-				})));
-				else merged[key] = fieldResult.value;
-			}
-			return issues.length > 0 ? { issues } : { value: merged };
-		}
-	} };
-}
-function resolveAgentStateSchemas(contextSchema, states) {
-	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
-		if (!state || typeof state !== "object") return [key, state];
-		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
-		if ("context" in state && state.context) return [key, {
-			schemas: { context: mergeContextSchema(contextSchema, state.context) },
-			...children ? { states: children } : {}
-		}];
-		return [key, children ? {
-			...state,
-			states: children
-		} : state];
-	}));
-}
-/**
-* Schema-first `setup(...)` for agent machines — the standard entry point
-* for authoring a machine (the blueprint) that this library then runs (via
-* {@link runAgent} or the step helpers) against host-supplied model/decision
-* executors. Context, events, machine input, machine output, and
-* state/transition meta are all standard schemas — no `{} as Type` casts —
-* and are retained on `result.schemas` for runtime validation. Also
-* registers the `agent.generateText`/`agent.streamText`/`agent.userInput`/
-* `agent.decide`/`agent.plan` builtin actors and lowers `requests`/`actorSources` into the
-* machine's actor sources. The result is the xstate `setup(...)` object with
-* a wrapped `result.createMachine(...)` plus `result.schemas`/`models`/
-* `requests`/`appendMessages` attached. Also has a
-* `setupAgent.fromConfig(...)` namespace member for building a machine from
-* a serializable {@link AgentWorkflowConfig} instead of this TS API.
-*
-* @example
-* ```ts
-* const schemas = createAgentSchemas({
-*   context: z.object({ topic: z.string(), joke: z.string().nullable() }),
-*   input: z.object({ topic: z.string() }),
-*   output: z.object({ joke: z.string() }),
-* });
-*
-* const agent = setupAgent({
-*   schemas,
-*   actorSources: { tellJoke },
-* });
-*
-* const jokeMachine = agent.createMachine({
-*   context: ({ input }) => ({ topic: input.topic, joke: null }),
-*   initial: 'telling',
-*   states: {
-*     telling: {
-*       invoke: {
-*         id: 'joke',
-*         src: 'tellJoke',
-*         input: ({ context }) => ({ topic: context.topic }),
-*         onDone: ({ output }) => ({ target: 'done', context: { joke: output } }),
-*       },
-*     },
-*     done: { type: 'final', output: ({ context }) => ({ joke: context.joke ?? '' }) },
-*   },
-* });
-* ```
-*/
-function setupAgent(config) {
-	return createSetupAgent(config);
-}
-function collectFinalStateOutputs(states, outputs = []) {
-	for (const state of Object.values(states ?? {})) {
-		if (state?.type === "final" && state.output !== void 0) outputs.push(state.output);
-		collectFinalStateOutputs(state?.states, outputs);
-	}
-	return outputs;
-}
-function withRootOutputFromSingleFinal(config) {
-	if (!config || typeof config !== "object" || "output" in config || !("states" in config)) return config;
-	const outputs = collectFinalStateOutputs(config.states);
-	return outputs.length === 1 ? {
-		...config,
-		output: outputs[0]
-	} : config;
-}
-(function(_setupAgent) {
-	function fromConfig(config, options) {
-		return setupAgentFromConfig(config, options);
-	}
-	_setupAgent.fromConfig = fromConfig;
-})(setupAgent || (setupAgent = {}));
-/** Builds one TextLogic actor per `setupAgent({ requests })` entry. @internal */
-function createRequestActors(requests) {
-	return Object.fromEntries(Object.entries(requests).map(([key, request]) => {
-		return [key, require_events.createTextLogic({
-			...request,
-			name: key,
-			mode: request.mode ?? "generate"
-		})];
-	}));
-}
-function normalizeAgentSchemas(config) {
-	if ("schemas" in config && config.schemas) return config.schemas;
-	const loose = config;
-	return createAgentSchemas({
-		...loose,
-		context: loose.context
-	});
-}
-function normalizeAgentRequestInput(requests) {
-	return requests ?? {};
-}
-/**
-* Runtime guard: a key appearing in both `actorSources`/`requests` is almost
-* certainly a mistake (whichever spread applies last would silently win) —
-* fail fast with a clear message rather than let one implementation shadow
-* another.
-*/
-function assertNoActorKeyCollisions(actorSources, requests) {
-	const seenIn = /* @__PURE__ */ new Map();
-	const groups = [["actorSources", actorSources], ["requests", requests]];
-	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
-		const existingGroup = seenIn.get(key);
-		if (existingGroup) throw new Error(`setupAgent: key '${key}' is defined in both '${existingGroup}' and '${groupName}'. Each actor source key must be unique across 'actorSources' and 'requests'.`);
-		seenIn.set(key, groupName);
-	}
-}
-const RESERVED_AGENT_ACTOR_KEYS = [
-	...Object.keys(require_events.builtinTextActors),
-	require_events.USER_INPUT_ACTOR,
-	require_events.DECIDE_ACTOR,
-	require_events.PLAN_ACTOR
-];
-/**
-* Rejects a user-supplied `actorSources`/`requests` key in the reserved
-* `agent.*` builtin namespace. Without this, the builtins-first spread in
-* {@link createAgentActorSources} lets such a key overwrite the builtin
-* (`agent.decide`, `agent.plan`, …) silently. Deliberate override of a builtin
-* is still possible after the machine is created, via
-* `machine.provide({ actorSources: { 'agent.decide': ... } })`.
-*/
-function assertNoReservedAgentKeys(actorSources, requests) {
-	const groups = [["actorSources", actorSources], ["requests", requests]];
-	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) if (RESERVED_AGENT_ACTOR_KEYS.includes(key)) throw new Error(`setupAgent: '${groupName}' key '${key}' is a reserved builtin agent actor and cannot be redefined here (it would silently clobber the builtin). Reserved keys: ${RESERVED_AGENT_ACTOR_KEYS.join(", ")}. To deliberately override a builtin, do it on the created machine instead: machine.provide({ actorSources: { '${key}': ... } }).`);
-}
-function createAgentActorSources(actorSources, requestActors) {
-	assertNoActorKeyCollisions(actorSources, requestActors);
-	assertNoReservedAgentKeys(actorSources, requestActors);
-	return {
-		...require_events.builtinTextActors,
-		[require_events.USER_INPUT_ACTOR]: require_events.userInputActor,
-		[require_events.DECIDE_ACTOR]: require_decision.createDecideActor(),
-		[require_events.PLAN_ACTOR]: require_decision.createPlanActor(),
-		...actorSources,
-		...requestActors
-	};
-}
-function createAgentSetupConfig(schemas, actorSources, config) {
-	return {
-		schemas: {
-			context: schemas.context,
-			events: schemas.events,
-			input: schemas.input,
-			output: schemas.output,
-			meta: schemas.meta,
-			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
-		},
-		...config.states ? { states: resolveAgentStateSchemas(schemas.context, config.states) } : {},
-		actorSources,
-		actions: config.actions,
-		guards: config.guards,
-		delays: config.delays
-	};
-}
-function createSetupAgent(config) {
-	const schemas = normalizeAgentSchemas(config);
-	const requestActors = createRequestActors(normalizeAgentRequestInput(config.requests));
-	const actorSources = createAgentActorSources(config.actorSources, requestActors);
-	const base = (0, xstate.setup)(createAgentSetupConfig(schemas, actorSources, config));
-	const createBaseMachine = base.createMachine.bind(base);
-	const models = config.models ?? {};
-	const machineOptions = {
-		schemas,
-		actorSources,
-		models
-	};
-	return Object.assign(base, {
-		createMachine(machineConfig) {
-			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
-			require_events.agentExecutionOptions.set(machine, machineOptions);
-			if (config.isSuspended) {
-				const rootConfig = machine.config;
-				if (rootConfig) require_events.machineSuspensionPredicates.set(rootConfig, config.isSuspended);
-			}
-			return machine;
-		},
-		schemas,
-		models,
-		requests: requestActors,
-		appendMessages(resolve) {
-			return appendMessages(resolve);
-		}
-	});
-}
-//#endregion
 //#region src/internal/state-request-pass.ts
 async function runTextPhase(stateRequest, baseMessages, deps) {
 	const { model, system } = stateRequest;
 	const id = stateRequest.id ?? deps.nextRequestId();
-	const promptMessage = require_events.userMessage(stateRequest.prompt);
+	const promptMessage = require_decision.userMessage(stateRequest.prompt);
 	if (stateRequest.kind === "decision") return {
 		stateRequest,
 		id,
@@ -582,7 +25,7 @@ async function runTextPhase(stateRequest, baseMessages, deps) {
 	const agentRequest = {
 		kind: "text",
 		id,
-		src: require_events.INTERPRET_SOURCE,
+		src: require_decision.INTERPRET_SOURCE,
 		mode: "generate",
 		input: request,
 		tools: {},
@@ -596,9 +39,11 @@ async function runTextPhase(stateRequest, baseMessages, deps) {
 	let output;
 	try {
 		const raw = await deps.generateText(request, { signal: deps.signal });
-		output = await require_events.normalizeGeneratorResult(raw, id, { request });
+		output = await require_decision.normalizeGeneratorResult(raw, id, { request });
 		const rawReasoning = raw?.reasoning;
 		const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+		const usage = require_decision.extractCallUsage(raw);
+		if (usage) deps.recordUsage?.(usage);
 		deps.onResult?.(agentRequest, {
 			output,
 			raw
@@ -608,7 +53,8 @@ async function runTextPhase(stateRequest, baseMessages, deps) {
 			request: agentRequest,
 			output,
 			raw,
-			...reasoning !== void 0 ? { reasoning } : {}
+			...reasoning !== void 0 ? { reasoning } : {},
+			...usage !== void 0 ? { usage } : {}
 		});
 	} catch (error) {
 		deps.onTrace?.({
@@ -622,7 +68,7 @@ async function runTextPhase(stateRequest, baseMessages, deps) {
 		stateRequest,
 		id,
 		output,
-		appended: [promptMessage, require_events.assistantMessage(typeof output === "string" ? output : JSON.stringify(output))]
+		appended: [promptMessage, require_decision.assistantMessage(typeof output === "string" ? output : JSON.stringify(output))]
 	};
 }
 async function runAdvancePhase(plan, deps) {
@@ -637,13 +83,13 @@ async function runAdvancePhase(plan, deps) {
 			messages: deps.messages
 		}) : stateRequest.onDone;
 		if (!resolved) return false;
-		const acceptedTypes = require_events.getAcceptedEvents(snapshot, { schemas: deps.schemas }).map((descriptor) => descriptor.type);
+		const acceptedTypes = require_decision.getAcceptedEvents(snapshot, { schemas: deps.schemas }).map((descriptor) => descriptor.type);
 		if (!acceptedTypes.includes(resolved.type)) throw new Error(`runAgent: getRequests request '${id}' resolved onDone to event '${resolved.type}', which the current state does not accept. Accepted: ${acceptedTypes.join(", ") || "(none)"}.`);
 		if (!snapshot.can(resolved)) return false;
 		deps.send(resolved);
 		return true;
 	}
-	const events = require_events.getAcceptedEvents(deps.getSnapshot(), {
+	const events = require_decision.getAcceptedEvents(deps.getSnapshot(), {
 		schemas: deps.schemas,
 		...stateRequest.allowedEvents ? { eventTypes: stateRequest.allowedEvents } : {}
 	});
@@ -662,7 +108,7 @@ async function runAdvancePhase(plan, deps) {
 		canTake: (event) => deps.getSnapshot().can(event)
 	});
 	if (deps.isSettled()) return false;
-	deps.appendToLog(require_events.assistantMessage(`[chose: ${chosen.type}]`));
+	deps.appendToLog(require_decision.assistantMessage(`[chose: ${chosen.type}]`));
 	deps.send(chosen);
 	return true;
 }
@@ -696,12 +142,12 @@ async function runStateRequestPass(requests, deps) {
 * machine simply takes no transition). Opt out with
 * {@link RunAgentOptions.onIllegalResumeEvent} `'ignore'`.
 */
-var IllegalResumeEventError = class extends Error {
+var AgentIllegalResumeEventError = class extends require_errors.AgentError {
 	eventType;
 	acceptedTypes;
 	constructor(eventType, acceptedTypes) {
-		super(`runAgent: cannot resume with event '${eventType}' — the restored state does not accept it. Accepted event types: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
-		this.name = "IllegalResumeEventError";
+		super("illegal-resume-event", `runAgent: cannot resume with event '${eventType}' — the restored state does not accept it. Accepted event types: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
+		this.name = "AgentIllegalResumeEventError";
 		this.eventType = eventType;
 		this.acceptedTypes = acceptedTypes;
 	}
@@ -715,30 +161,30 @@ var IllegalResumeEventError = class extends Error {
 * the snapshot may no longer resume cleanly. `from` is the snapshot's version,
 * `to` the current machine's.
 */
-var SnapshotVersionMismatchError = class extends Error {
+var AgentSnapshotVersionMismatchError = class extends require_errors.AgentError {
 	from;
 	to;
 	machineId;
 	constructor(from, to, machineId) {
-		super(`runAgent: cannot resume snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${to}' — the machine's structure changed since the snapshot was persisted. Provide options.migrateSnapshot to adapt it, or set options.onVersionMismatch to 'warn'/'ignore' to proceed anyway.`);
-		this.name = "SnapshotVersionMismatchError";
+		super("snapshot-version-mismatch", `runAgent: cannot resume snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${to}' — the machine's structure changed since the snapshot was persisted. Provide options.migrateSnapshot to adapt it, or set options.onVersionMismatch to 'warn'/'ignore' to proceed anyway.`);
+		this.name = "AgentSnapshotVersionMismatchError";
 		this.from = from;
 		this.to = to;
 		this.machineId = machineId;
 	}
 };
 /**
-* Thrown by {@link runAgentToCompletion} when the run settles `idle` instead of
+* Thrown by {@link generateResult} when the run settles `idle` instead of
 * `done`: the machine paused for external input. Carries the idle `snapshot`
 * and `acceptedTypes` (the event types that could resume it, via
 * {@link getAcceptedEvents}). Use {@link runAgent} directly when idle is an
 * expected outcome you handle.
 */
-var AgentIdleError = class extends Error {
+var AgentIdleError = class extends require_errors.AgentError {
 	snapshot;
 	acceptedTypes;
 	constructor(snapshot, acceptedTypes) {
-		super(`runAgentToCompletion: the machine paused (idle) instead of completing. Resume it by calling runAgent with one of these events: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
+		super("agent-idle", `generateResult: the machine paused (idle) instead of completing. Resume it by calling runAgent with one of these events: ${acceptedTypes.length > 0 ? acceptedTypes.join(", ") : "(none)"}.`);
 		this.name = "AgentIdleError";
 		this.snapshot = snapshot;
 		this.acceptedTypes = acceptedTypes;
@@ -752,17 +198,104 @@ var AgentIdleError = class extends Error {
 * {@link traceTransitions}.
 */
 const AGENT_TRACE_SCHEMA_VERSION = 1;
+const TRACE_ENVELOPE_KEYS = [
+	"schemaVersion",
+	"runId",
+	"seq",
+	"timestamp",
+	"machineId",
+	"machineVersion",
+	"type",
+	"status",
+	"cause",
+	"eventId",
+	"reasoning",
+	"chunk"
+];
+/**
+* Best-effort JSON projection of an arbitrary value. Never throws: functions,
+* symbols, `undefined`, and cyclic back-references are DROPPED (array holes
+* become `null`), non-finite numbers become `null`, `bigint`s become strings,
+* `Error`s become `{ name, message, stack?, code? }`, and anything with a
+* `toJSON()` (e.g. `Date`) is projected through it — the same losses a
+* `JSON.parse(JSON.stringify(...))` round-trip incurs, minus the throws.
+*/
+function toJsonValue(value, ancestors) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "string" || type === "boolean") return value;
+	if (type === "number") return Number.isFinite(value) ? value : null;
+	if (type === "bigint") return value.toString();
+	if (type !== "object") return;
+	const object = value;
+	if (ancestors.includes(object)) return;
+	const nextAncestors = [...ancestors, object];
+	if (object instanceof Error) {
+		const serialized = {
+			name: object.name,
+			message: object.message
+		};
+		if (typeof object.stack === "string") serialized.stack = object.stack;
+		const code = object.code;
+		if (typeof code === "string") serialized.code = code;
+		const cause = toJsonValue(object.cause, nextAncestors);
+		if (cause !== void 0) serialized.cause = cause;
+		return serialized;
+	}
+	const toJSON = object.toJSON;
+	if (typeof toJSON === "function") return toJsonValue(toJSON.call(object), nextAncestors);
+	if (Array.isArray(object)) return object.map((item) => toJsonValue(item, nextAncestors) ?? null);
+	const out = {};
+	for (const [key, item] of Object.entries(object)) {
+		const serializedItem = toJsonValue(item, nextAncestors);
+		if (serializedItem !== void 0) out[key] = serializedItem;
+	}
+	return out;
+}
+/**
+* Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
+* the form the trace stream is actually sold for (one `JSON.stringify` per line
+* 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
+*   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
+*   else.
+* - Non-serializable values anywhere (functions, symbols, `undefined`, cyclic
+*   back-references) are dropped; `Error`s become `{ name, message, stack?,
+*   code? }` instead of `{}`. Nothing throws.
+*
+* @example
+* ```ts
+* await appendFile('trace.jsonl', JSON.stringify(serializeTraceEvent(event)) + '\n');
+* ```
+*/
+function serializeTraceEvent(event, options = {}) {
+	const out = {};
+	for (const [key, value] of Object.entries(event)) {
+		if (key === "raw" && !options.includeRaw) continue;
+		if (TRACE_ENVELOPE_KEYS.includes(key)) {
+			if (value !== void 0) out[key] = value;
+			continue;
+		}
+		const serialized = toJsonValue(value, []);
+		if (serialized !== void 0) out[key] = serialized;
+	}
+	return out;
+}
 let nextRunAgentTraceId = 1;
-var MaxModelCallsExceededError = class extends Error {
+var AgentMaxModelCallsExceededError = class extends require_errors.AgentError {
 	constructor() {
-		super("runAgent exceeded maxModelCalls.");
-		this.name = "MaxModelCallsExceededError";
+		super("max-model-calls-exceeded", "runAgent exceeded maxModelCalls.");
+		this.name = "AgentMaxModelCallsExceededError";
 	}
 };
 function wrapsDecisionExhausted(error) {
 	let current = error;
 	for (let depth = 0; depth < 10 && current != null; depth++) {
-		if (current instanceof require_decision.DecisionExhaustedError) return true;
+		if (current instanceof require_decision.AgentDecisionExhaustedError) return true;
 		current = current.cause;
 	}
 	return false;
@@ -790,14 +323,14 @@ function collectConfiguredInvokeSrcs(stateConfig, stateName, out) {
 /**
 * Duck-types a state machine actor logic (an invoked child machine) vs. any
 * other actor logic. xstate's `StateMachine` carries `.config`, `.root`, and
-* a `.provide(...)` method plus an `implementations.actorSources` map — this
+* a `.provide(...)` method plus a `sources.actors` map — this
 * combination is unique to machines and survives the dual-package/version
 * boundary an `instanceof` check would not. Used to descend the bind-time
 * walk into invoked child machines (their internal agent requests are opaque
 * to the parent-level source walk otherwise).
 */
 function isStateMachine(logic) {
-	return !!logic && typeof logic === "object" && "config" in logic && "root" in logic && typeof logic.provide === "function" && typeof logic.implementations === "object" && !!logic.implementations?.actorSources;
+	return !!logic && typeof logic === "object" && "config" in logic && "root" in logic && typeof logic.provide === "function" && typeof logic.sources === "object" && !!logic.sources?.actors;
 }
 /**
 * Fails fast (throws) at bind time — before any actor runs — when the
@@ -832,18 +365,18 @@ function assertMachineBindable(machine, effectiveSources, options, ctx) {
 				assertChildMachineBindable(src, src, stateName, options, ctx);
 				continue;
 			}
-			if ((require_events.isTextLogic(src) || require_decision.isDecisionLogic(src) || require_decision.isPlanLogic(src)) && !require_events.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({ actorSources: { name: logic } })) and invoke it by name.`);
+			if ((require_decision.isTextLogic(src) || require_decision.isDecisionLogic(src) || require_decision.isPlanLogic(src)) && !require_decision.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.`);
 			continue;
 		}
 		const logic = effectiveSources[src];
-		if (logic === void 0) throw new Error(`runAgent: ${where} '${stateName}' invokes unregistered actor source '${src}'. Provide it via machine.provide({ actorSources: { '${src}': ... } }) or runAgent(machine, { actorSources: { '${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);
 			continue;
 		}
 		if (src === "agent.userInput") continue;
 		if (require_decision.isDecisionLogic(logic)) {
-			if (require_events.executorBoundLogics.has(logic)) continue;
+			if (require_decision.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(...).`);
 			continue;
@@ -853,14 +386,14 @@ function assertMachineBindable(machine, effectiveSources, options, ctx) {
 			if (!options.hasDecide) throw new Error(`runAgent: ${where} '${stateName}' invokes plan source '${src}' but no 'decide' executor was provided to runAgent(...).`);
 			continue;
 		}
-		if (require_events.isTextLogic(logic)) {
-			if (require_events.executorBoundLogics.has(logic)) continue;
+		if (require_decision.isTextLogic(logic)) {
+			if (require_decision.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(...).`);
 			continue;
 		}
-		if (require_events.isUnboundPlaceholder(logic)) throw new Error(`runAgent: ${where} '${stateName}' invokes actor source '${src}', which has no host execution. Provide it via machine.provide({ actorSources: { '${src}': ... } }) or runAgent(machine, { actorSources: { '${src}': ... } }).`);
+		if (require_decision.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}': ... } }).`);
 	}
 }
 /** Descends the bind-time walk into an invoked child state machine, guarding
@@ -869,7 +402,7 @@ function assertChildMachineBindable(childMachine, childSrc, stateName, options,
 	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.implementations.actorSources;
+	const childSources = childMachine.sources.actors;
 	assertMachineBindable(childMachine, childSources, options, {
 		isChild: true,
 		childPath,
@@ -885,7 +418,21 @@ function assertChildMachineBindable(childMachine, childSrc, stateName, options,
 * runAgent's executors — this error is only for the unrebindable direct-object
 * case. */
 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({ actorSources: { <child>: childMachine } })) and invoke it by name.`);
+	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
+*/
+function declaresUsageTransition(snapshot) {
+	return (0, xstate.getNextTransitions)(snapshot).some((transition) => transition.eventType === require_setup_agent.AGENT_USAGE_EVENT_TYPE);
 }
 /** Reads the durable invoke id/src off the async actor's own ref (`self`). */
 function selfIdAndSrc(self) {
@@ -947,9 +494,11 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 					}, self);
 					runCtx.onChunk?.(chunk, { request: agentRequest });
 				},
-				signal
+				signal,
+				...runCtx.runId !== void 0 ? { runId: runCtx.runId } : {},
+				...id !== "" ? { requestId: id } : {}
 			});
-			const output = await require_events.normalizeGeneratorResult(raw, id, {
+			const output = await require_decision.normalizeGeneratorResult(raw, id, {
 				request,
 				onChunk: (chunk) => {
 					runCtx.onTrace?.({
@@ -962,6 +511,14 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 			});
 			const rawReasoning = raw?.reasoning;
 			const reasoning = typeof rawReasoning === "string" ? rawReasoning : void 0;
+			const usage = require_decision.extractCallUsage(raw);
+			if (usage) runCtx.recordUsage?.(usage, {
+				kind: "text",
+				...id !== "" ? { id } : {},
+				...src !== "" ? { src } : {},
+				model: request.model,
+				...request.name !== void 0 ? { name: request.name } : {}
+			}, self);
 			runCtx.onResult?.(agentRequest, {
 				output,
 				raw
@@ -971,7 +528,8 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 				request: agentRequest,
 				output,
 				raw,
-				...reasoning !== void 0 ? { reasoning } : {}
+				...reasoning !== void 0 ? { reasoning } : {},
+				...usage !== void 0 ? { usage } : {}
 			}, self);
 			return { output };
 		} catch (error) {
@@ -984,7 +542,7 @@ function wrapTextLogicForRunAgent(logic, runCtx) {
 		}
 	});
 }
-function createCountingDecide(runCtx, self) {
+function createCountingDecide(runCtx, self, kind = "decision") {
 	return async (attemptRequest) => {
 		runCtx.consumeModelCall();
 		runCtx.onTrace?.({
@@ -992,7 +550,20 @@ function createCountingDecide(runCtx, self) {
 			request: attemptRequest
 		}, self);
 		try {
-			const result = await runCtx.decide(attemptRequest);
+			const result = await runCtx.decide(runCtx.runId !== void 0 ? {
+				...attemptRequest,
+				runId: runCtx.runId
+			} : attemptRequest);
+			const usage = require_decision.extractCallUsage(result);
+			if (usage) {
+				const { src } = selfIdAndSrc(self);
+				runCtx.recordUsage?.(usage, {
+					kind,
+					...attemptRequest.id ? { id: attemptRequest.id } : {},
+					...src !== "" ? { src } : {},
+					model: attemptRequest.model
+				}, self);
+			}
 			runCtx.onResult?.(attemptRequest, {
 				output: result.event,
 				raw: result
@@ -1001,7 +572,8 @@ function createCountingDecide(runCtx, self) {
 				type: "request.end",
 				request: attemptRequest,
 				output: result.event,
-				raw: result
+				raw: result,
+				...usage !== void 0 ? { usage } : {}
 			}, self);
 			return result;
 		} catch (error) {
@@ -1036,7 +608,7 @@ function createRunAgentDecisionLogic(logic, runCtx) {
 		const declaredEventTypes = logic.allowedEventTypes?.(input);
 		await Promise.resolve();
 		const actorRef = invokingActorOf(self, runCtx);
-		const events = actorRef ? require_events.getAcceptedEvents(actorRef.getSnapshot(), {
+		const events = actorRef ? require_decision.getAcceptedEvents(actorRef.getSnapshot(), {
 			schemas: runCtx.schemas,
 			eventTypes: declaredEventTypes
 		}) : [];
@@ -1079,7 +651,7 @@ function createRunAgentPlanLogic(logic, runCtx) {
 		if (!runCtx.decide) throw new Error("runAgent: no 'decide' executor provided.");
 		const { id } = selfIdAndSrc(self);
 		const stopOn = new Set(input.stopOn ?? []);
-		const countingDecide = createCountingDecide(runCtx, self);
+		const countingDecide = createCountingDecide(runCtx, self, "plan");
 		const base = logic.request(input);
 		let ledger = require_decision.initialPlanLedger(logic, input);
 		const end = (stopped) => {
@@ -1094,14 +666,14 @@ function createRunAgentPlanLogic(logic, runCtx) {
 		while (ledger.context.stepsRemaining > 0) {
 			const actorRef = invokingActor;
 			if (!actorRef || signal.aborted) break;
-			const machineEvents = require_events.getAcceptedEvents(actorRef.getSnapshot(), {
+			const machineEvents = require_decision.getAcceptedEvents(actorRef.getSnapshot(), {
 				schemas: runCtx.schemas,
 				eventTypes: logic.allowedEventTypes(input)
 			});
 			if (machineEvents.length === 0) return end("no-legal-events");
 			const doneDescriptor = {
 				type: require_decision.PLAN_DONE_EVENT_TYPE,
-				toolName: require_events.sanitizeEventToolName(require_decision.PLAN_DONE_EVENT_TYPE)
+				toolName: require_decision.sanitizeEventToolName(require_decision.PLAN_DONE_EVENT_TYPE)
 			};
 			const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, doneDescriptor];
 			const applied = ledger.context.applied;
@@ -1169,7 +741,7 @@ function rootTraceState(root) {
 	if (!state) {
 		const logic = root.logic;
 		const machineId = (logic?.config)?.id ?? logic?.id ?? "(machine)";
-		const machineVersion = logic ? require_events.getMachineStructuralHash(logic) : "";
+		const machineVersion = logic ? require_decision.getMachineStructuralHash(logic) : "";
 		state = {
 			runId: `run_${nextProvideRunId++}`,
 			seq: 0,
@@ -1209,6 +781,10 @@ function provideTraceSink(onTrace) {
 * actor off `self._parent`, always present under a live `createActor` tree.
 * `onTrace` (when given) mints a per-root-actor envelope. `schemas` come from
 * the machine's registered `setupAgent` execution options.
+*
+* `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}.
 */
 function provideBindContext(machine, executors, options) {
 	return {
@@ -1218,9 +794,43 @@ function provideBindContext(machine, executors, options) {
 		onChunk: options.onChunk ? (chunk) => options.onChunk(chunk) : void 0,
 		onTrace: provideTraceSink(options.onTrace),
 		consumeModelCall: () => {},
+		recordUsage: (usage, source, self) => {
+			deliverUsageToInvokingActor(usage, source ?? {}, self);
+		},
 		actorHolder: { actorRef: void 0 },
-		schemas: require_events.getRegisteredAgentExecutionOptions(machine).schemas
+		schemas: require_decision.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).
+*
+* 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.
+*
+* Delivery follows `provideExecutors`' 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;
+	if (!actorRef) return;
+	const snapshot = actorRef.getSnapshot();
+	if (snapshot?.status !== "active" || !declaresUsageTransition(snapshot)) return;
+	const event = {
+		type: require_setup_agent.AGENT_USAGE_EVENT_TYPE,
+		...source,
+		usage
 	};
+	if (!snapshot.can(event)) return;
+	actorRef.send(event);
 }
 /**
 * Host-binds one text/stream source for {@link provideExecutors} using the SAME
@@ -1265,19 +875,19 @@ function bindPlanForProvide(machine, logic, executors, options) {
 function rebindChildMachine(childMachine, runCtx, visited) {
 	if (visited.has(childMachine)) return childMachine;
 	const childVisited = new Set([...visited, childMachine]);
-	const sources = childMachine.implementations.actorSources;
+	const sources = childMachine.sources.actors;
 	const wrapped = {};
 	for (const [key, logic] of Object.entries(sources)) {
 		if (require_decision.isDecisionLogic(logic)) {
-			if (!require_events.executorBoundLogics.has(logic)) wrapped[key] = createRunAgentDecisionLogic(logic, runCtx);
+			if (!require_decision.executorBoundLogics.has(logic)) wrapped[key] = createRunAgentDecisionLogic(logic, runCtx);
 			continue;
 		}
 		if (require_decision.isPlanLogic(logic)) {
 			wrapped[key] = createRunAgentPlanLogic(logic, runCtx);
 			continue;
 		}
-		if (require_events.isTextLogic(logic)) {
-			if (!require_events.executorBoundLogics.has(logic)) wrapped[key] = wrapTextLogicForRunAgent(logic, runCtx);
+		if (require_decision.isTextLogic(logic)) {
+			if (!require_decision.executorBoundLogics.has(logic)) wrapped[key] = wrapTextLogicForRunAgent(logic, runCtx);
 			continue;
 		}
 		if (isStateMachine(logic)) {
@@ -1286,7 +896,7 @@ function rebindChildMachine(childMachine, runCtx, visited) {
 			continue;
 		}
 	}
-	return Object.keys(wrapped).length > 0 ? childMachine.provide({ actorSources: wrapped }) : childMachine;
+	return Object.keys(wrapped).length > 0 ? childMachine.provide({ actors: wrapped }) : childMachine;
 }
 /**
 * Runs an agent machine to completion or idle: a `createActor` host that
@@ -1303,7 +913,7 @@ function rebindChildMachine(childMachine, runCtx, visited) {
 *
 * Binding happens **before** the actor starts: every invoke the machine
 * could reach is walked and checked against the effective actor sources
-* (`options.actorSources` merged onto the machine), so a missing
+* (`options.actors` merged onto the machine), so a missing
 * `streamText`/`decide` executor or any other unbound actor source throws
 * immediately — a bind-time error, not a mid-run failure. The one exception
 * is `agent.userInput`: unhandled, it binds as a pending placeholder that
@@ -1328,14 +938,42 @@ function rebindChildMachine(childMachine, runCtx, visited) {
 * lives in an adapter — use `createAiSdkExecutors` from '@statelyai/agent/ai-sdk'.
 */
 async function runAgent(machine, options) {
+	return createAgentSession(machine, options, { oneShot: true }).settled();
+}
+/**
+* Session mode: {@link runAgent}'s engine with a long-lived actor. Use it when
+* the agent is a *session* fed by external events (chat turns, device or
+* timer events, a socket) rather than a one-shot job — you keep the log,
+* budget, traces, and idle semantics that bare `provideExecutors` +
+* `createActor` would forfeit.
+*
+* ```ts
+* const session = createAgentActor(machine, { input, executors });
+* let result = await session.settled();          // first quiescence
+* while (result.status === "idle") {
+*   session.actor.send(await nextUserEvent(result.snapshot));
+*   result = await session.settled();            // next quiescence, same log
+* }
+* session.stop();
+* ```
+*
+* Accepts the same options as {@link runAgent} (including `snapshot`/`events`
+* resume). Not yet supported in session mode: `getRequests` re-interpretation
+* across cycles behaves per-cycle exactly as in `runAgent`.
+*/
+function createAgentActor(machine, options) {
+	return createAgentSession(machine, options, { oneShot: false });
+}
+function createAgentSession(machine, options, lifecycle) {
 	const maxModelCalls = options.maxModelCalls ?? 100;
 	let modelCallCount = 0;
 	let budgetExceeded = false;
 	let warnedNonSerializable = false;
+	let warnedHeuristicIdle = false;
 	const runId = `run_${nextRunAgentTraceId++}`;
 	let traceSeq = 0;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
-	const machineVersion = options.machineVersion ?? require_events.getMachineStructuralHash(machine);
+	const machineVersion = options.machineVersion ?? machine.version ?? require_decision.getMachineStructuralHash(machine);
 	const agentMeta = {
 		machineId,
 		version: machineVersion
@@ -1355,18 +993,52 @@ async function runAgent(machine, options) {
 		});
 	};
 	const consumeModelCall = () => {
-		if (budgetExceeded) throw new MaxModelCallsExceededError();
-		modelCallCount += 1;
-		if (modelCallCount > maxModelCalls) {
+		if (budgetExceeded) throw new AgentMaxModelCallsExceededError();
+		if (modelCallCount + 1 > maxModelCalls) {
 			budgetExceeded = true;
-			throw new MaxModelCallsExceededError();
+			throw new AgentMaxModelCallsExceededError();
 		}
+		modelCallCount += 1;
+	};
+	const tokenTotals = {};
+	const cycleGate = { isResolved: () => false };
+	const deliverUsageEvent = (usage, source) => {
+		const actorRef = actorHolder.actorRef;
+		if (!actorRef) return;
+		const event = {
+			type: require_setup_agent.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 require_decision.AGENT_USAGE_TOKEN_FIELDS) {
+			const value = usage[field];
+			if (typeof value === "number" && Number.isFinite(value)) tokenTotals[field] = (tokenTotals[field] ?? 0) + value;
+		}
+		deliverUsageEvent(usage, source);
+	};
+	const runUsage = () => ({
+		...tokenTotals,
+		modelCalls: modelCallCount
+	});
 	const warnNonSerializableContext = (snapshot) => {
 		if (warnedNonSerializable || process.env.NODE_ENV === "production") return;
 		let offending = [];
 		try {
-			offending = require_events.findNonSerializableContextPaths(snapshot.context);
+			offending = require_decision.findNonSerializableContextPaths(snapshot.context);
 		} catch {
 			return;
 		}
@@ -1374,8 +1046,8 @@ async function runAgent(machine, options) {
 		warnedNonSerializable = true;
 		console.warn(`runAgent: context holds value(s) that will not survive snapshot persist/resume (JSON round-trip): ${offending.join(", ")}. Persist only JSON-serializable context, or convert these before the run settles.`);
 	};
-	const provided = machine.provide({ actorSources: options.actorSources });
-	const effectiveSources = provided.implementations.actorSources;
+	const provided = machine.provide({ actors: options.actors });
+	const effectiveSources = provided.sources.actors;
 	assertBindable(provided, effectiveSources, {
 		hasGenerateText: !!options.executors?.generateText,
 		hasDecide: !!options.executors?.decide,
@@ -1391,8 +1063,10 @@ async function runAgent(machine, options) {
 		onResult: options.onResult,
 		onTrace,
 		consumeModelCall,
+		recordUsage,
 		actorHolder,
-		schemas: require_events.getRegisteredAgentExecutionOptions(machine).schemas
+		runId,
+		schemas: require_decision.getRegisteredAgentExecutionOptions(machine).schemas
 	};
 	let userInputIsPlaceholder = false;
 	const wrappedSources = {};
@@ -1401,7 +1075,7 @@ async function runAgent(machine, options) {
 			if (options.userInput) {
 				const userInput = options.userInput;
 				wrappedSources[key] = (0, xstate.createAsyncLogic)({ run: async ({ input }) => await userInput(input) });
-			} else if (require_events.isUnboundPlaceholder(logic)) {
+			} else if (require_decision.isUnboundPlaceholder(logic)) {
 				userInputIsPlaceholder = true;
 				wrappedSources[key] = (0, xstate.createAsyncLogic)({ run: () => new Promise(() => {}) });
 			}
@@ -1415,8 +1089,8 @@ async function runAgent(machine, options) {
 			wrappedSources[key] = createRunAgentPlanLogic(logic, runCtx);
 			continue;
 		}
-		if (require_events.isTextLogic(logic)) {
-			if (!require_events.executorBoundLogics.has(logic)) wrappedSources[key] = wrapTextLogicForRunAgent(logic, runCtx);
+		if (require_decision.isTextLogic(logic)) {
+			if (!require_decision.executorBoundLogics.has(logic)) wrappedSources[key] = wrapTextLogicForRunAgent(logic, runCtx);
 			continue;
 		}
 		if (isStateMachine(logic)) {
@@ -1425,11 +1099,12 @@ async function runAgent(machine, options) {
 			continue;
 		}
 	}
-	const boundMachine = provided.provide({ actorSources: wrappedSources });
-	const isSuspended = options.isSuspended ?? require_events.getMachineSuspensionPredicate(machine) ?? (() => false);
+	const boundMachine = provided.provide({ actors: wrappedSources });
+	const declaredSuspensionPredicate = options.isSuspended ?? require_decision.getMachineSuspensionPredicate(machine);
+	const isSuspended = declaredSuspensionPredicate ?? (() => false);
 	let effectiveSnapshot = options.snapshot;
 	if (effectiveSnapshot !== void 0) {
-		const from = effectiveSnapshot.agentMeta?.version;
+		const from = effectiveSnapshot.agentMeta?.version ?? effectiveSnapshot.version;
 		if (from !== void 0 && from !== machineVersion) {
 			const info = {
 				from,
@@ -1438,32 +1113,86 @@ async function runAgent(machine, options) {
 			if (options.migrateSnapshot) effectiveSnapshot = options.migrateSnapshot(effectiveSnapshot, info);
 			else {
 				const mode = options.onVersionMismatch ?? "throw";
-				if (mode === "throw") throw new SnapshotVersionMismatchError(from, machineVersion, machineId);
+				if (mode === "throw") throw new AgentSnapshotVersionMismatchError(from, machineVersion, machineId);
 				if (mode === "warn") console.warn(`runAgent: resuming a snapshot stamped with machine version '${from}' against machine '${machineId}' at version '${machineVersion}'. Structural changes may not resume cleanly.`);
 			}
 		}
 	}
-	const priorMessages = require_events.getAgentMessages(effectiveSnapshot);
+	const resumeEvents = options.events;
+	if (effectiveSnapshot === void 0 && options.events !== void 0 && options.events[0]?.event.type === "@agent.init") {
+		const { snapshot: replayedSnapshot } = require_setup_agent.replay(machine, resumeEvents, { machineVersion });
+		effectiveSnapshot = machine.getPersistedSnapshot(replayedSnapshot);
+	}
+	const machineOwnVersion = machine.version;
+	if (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;
+		effectiveSnapshot = aligned;
+	}
+	const priorMessages = require_decision.getAgentMessages(effectiveSnapshot);
 	const messages = typeof options.messages === "function" ? [...options.messages([...priorMessages])] : [...priorMessages, ...options.messages ?? []];
 	const stampMessages = (snapshot) => {
 		if (!options.getRequests && !options.messages && messages.length === 0) return;
 		if (snapshot && typeof snapshot === "object") snapshot.messages = [...messages];
 	};
 	if (effectiveSnapshot !== void 0 && options.event !== void 0 && (options.onIllegalResumeEvent ?? "throw") === "throw") {
-		const acceptedTypes = require_events.getAcceptedEvents((0, xstate.createActor)(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
+		const acceptedTypes = require_decision.getAcceptedEvents((0, xstate.createActor)(boundMachine, { snapshot: effectiveSnapshot }).getSnapshot(), { schemas: runCtx.schemas }).map((descriptor) => descriptor.type);
 		const eventType = options.event.type;
-		if (!acceptedTypes.includes(eventType)) throw new IllegalResumeEventError(eventType, acceptedTypes);
+		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];
+		require_event_log_store.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 require_setup_agent.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);
 	}
-	return new Promise((resolvePromise) => {
+	const hasCompleteReplayHistory = replayEvents[0]?.event.type === "@agent.init" || effectiveSnapshot === void 0 && replayEvents.length === 0;
+	const appendReplayEvent = (event) => {
+		const entry = require_setup_agent.createReplayEntry(machine, replayEvents, event, {
+			machineVersion,
+			verification: hasCompleteReplayHistory
+		});
+		if (replayEventIds.has(entry.id)) throw new Error(`runAgent generated duplicate event id '${entry.id}'.`);
+		replayEventIds.add(entry.id);
+		replayEvents.push(entry);
+		options.onEvent?.(entry);
+		return entry;
+	};
+	if (replayEvents.length === 0 && effectiveSnapshot === void 0) {
+		const entry = require_setup_agent.initEntry(machine, options.input, { machineVersion });
+		replayEventIds.add(entry.id);
+		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 = (result) => {
+		const settle = (outcome) => {
 			if (settled) return;
 			settled = true;
+			const result = {
+				...outcome,
+				events: [...replayEvents],
+				usage: runUsage()
+			};
 			if (idleTimer !== void 0) clearTimeout(idleTimer);
-			if (options.signal) options.signal.removeEventListener("abort", onAbort);
 			stampAgentMeta(result.snapshot);
 			stampMessages(result.snapshot);
 			if ("persistedSnapshot" in result) {
@@ -1472,10 +1201,15 @@ async function runAgent(machine, options) {
 			}
 			onTrace({
 				type: "run.end",
-				...result
+				...outcome
 			});
-			actor.stop();
-			resolvePromise(result);
+			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({
@@ -1528,6 +1262,7 @@ async function runAgent(machine, options) {
 			generateText: runCtx.generateText,
 			decide: runCtx.decide ? createCountingDecide(runCtx, void 0) : void 0,
 			consumeModelCall,
+			recordUsage,
 			nextRequestId: () => `interpret_${++interpretSeq}`,
 			onTrace,
 			onResult: runCtx.onResult,
@@ -1564,7 +1299,13 @@ async function runAgent(machine, options) {
 				if (settled) return;
 				const current = actor.getSnapshot();
 				if (isIdleSnapshot(current, { ignoreUserInputChildren: userInputIsPlaceholder })) {
-					if (!maybeInterpret(current)) settleIdle(current);
+					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);
 		};
@@ -1574,12 +1315,21 @@ async function runAgent(machine, options) {
 			inspect: (event) => {
 				if (typeof options.inspect === "function") options.inspect(event);
 				else options.inspect?.next?.(event);
-				if (settled || event.type !== "@xstate.transition" || event.actorRef !== actor.ref) return;
+				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
+					event: event.event,
+					...eventId !== void 0 ? { eventId } : {}
 				});
 				options.onTransition?.(snapshot, event.event);
 				if (snapshot.status === "done") {
@@ -1624,6 +1374,19 @@ async function runAgent(machine, options) {
 			});
 		});
 		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({
@@ -1632,7 +1395,7 @@ async function runAgent(machine, options) {
 					error: options.signal.reason ?? /* @__PURE__ */ new Error("Aborted"),
 					snapshot: actor.getSnapshot()
 				});
-				return;
+				return sessionApi;
 			}
 			options.signal.addEventListener("abort", onAbort);
 		}
@@ -1647,13 +1410,17 @@ async function runAgent(machine, options) {
 			deliveringResumeEvent = false;
 			actor.send(options.event);
 		}
-	});
+		return sessionApi;
+	})();
 }
 /**
-* Runs an agent machine to a **final state** and returns its output, for
-* run-to-done flows where an idle pause is unexpected. Wraps {@link runAgent}:
+* Runs an agent machine to a **final state**, for run-to-done flows where an
+* idle pause is unexpected. Wraps {@link runAgent}:
 *
-* - `done` → resolves with `result.output` (the machine's `OutputFrom`).
+* - `done` → resolves with the done result: `result.output` (the machine's
+*   `OutputFrom`) plus metadata — `result.snapshot`, the replayable
+*   `result.events`, and the aggregated `result.usage` — the same shape
+*   `generateText` users expect (`text` + call metadata).
 * - `idle` → throws {@link AgentIdleError} carrying the idle snapshot and the
 *   event types that could resume it.
 * - `error` → throws `result.error` when it is an `Error`; otherwise wraps it
@@ -1661,18 +1428,18 @@ async function runAgent(machine, options) {
 *   `.error` is the raw thrown value.
 *
 * Use {@link runAgent} directly when idle is an expected outcome you handle
-* (human-in-the-loop, resumable flows); use `runAgentToCompletion` when the
+* (human-in-the-loop, resumable flows); use `generateResult` when the
 * machine is meant to run straight through to a final state.
 */
-async function runAgentToCompletion(machine, options) {
+async function generateResult(machine, options) {
 	const result = await runAgent(machine, options);
-	if (result.status === "done") return result.output;
+	if (result.status === "done") return result;
 	if (result.status === "idle") {
-		const acceptedTypes = require_events.getAcceptedEvents(result.snapshot, { schemas: require_events.getRegisteredAgentExecutionOptions(machine).schemas }).map((descriptor) => descriptor.type);
+		const acceptedTypes = require_decision.getAcceptedEvents(result.snapshot, { schemas: require_decision.getRegisteredAgentExecutionOptions(machine).schemas }).map((descriptor) => descriptor.type);
 		throw new AgentIdleError(result.snapshot, acceptedTypes);
 	}
 	if (result.error instanceof Error) throw result.error;
-	const wrapped = /* @__PURE__ */ new Error(`runAgentToCompletion: run failed with cause '${result.cause}'.`);
+	const wrapped = /* @__PURE__ */ new Error(`generateResult: run failed with cause '${result.cause}'.`);
 	wrapped.cause = result.cause;
 	wrapped.error = result.error;
 	throw wrapped;
@@ -1751,6 +1518,105 @@ function collectPendingUserInputs(snapshot) {
 	return pending;
 }
 //#endregion
+//#region src/agent-run.ts
+/**
+* Wraps {@link runAgent} in a canonical run-stream handle: the run's trace
+* events as a pull-based {@link AgentRun.events} async iterator, alongside the
+* unchanged {@link AgentRun.result} promise.
+*
+* Semantics:
+*
+* 1. **Starts immediately.** The underlying `runAgent` is invoked on this call,
+*    not on the first `events` iteration — work is already in flight when
+*    `createAgentRun` returns.
+* 2. **Buffer, don't stall.** Events are queued in an unbounded in-memory
+*    buffer as the run emits them; a slow or absent consumer never applies
+*    backpressure to the run. Once `run.end` is delivered, the iterator
+*    completes.
+* 3. **Composes `onTrace`.** If `options.onTrace` is passed, it still fires for
+*    every event — the wrapper adds queue delivery, it does not replace the
+*    caller's sink.
+* 4. **`result` mirrors `runAgent`.** Same resolution and rejection behavior
+*    (see {@link AgentRun.result}). A no-op rejection handler is attached
+*    internally so a caller who reads only `events` never trips an unhandled
+*    rejection on a bind-time throw; the returned promise still rejects for a
+*    caller who awaits it.
+* 5. **Resume is identical.** Options pass straight through, so starting from a
+*    persisted `snapshot` (+ resume `event`) streams that run's events from its
+*    own `run.start`, exactly as `runAgent` would run it.
+* 6. **Early termination does not cancel the run.** Breaking out of a
+*    `for await` (or calling `events.return()`) stops delivery, but the run
+*    keeps going and `result` still settles. Cancelling the run itself is
+*    future work — pass `options.signal` to abort it.
+* 7. **`events` is single-consumer.** See {@link AgentRun.events}.
+*/
+function createAgentRun(machine, options) {
+	const buffer = [];
+	const resolvers = [];
+	let closed = false;
+	let stopped = false;
+	const push = (event) => {
+		if (closed || stopped) return;
+		const resolve = resolvers.shift();
+		if (resolve) resolve({
+			value: event,
+			done: false
+		});
+		else buffer.push(event);
+	};
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		while (resolvers.length > 0) resolvers.shift()({
+			value: void 0,
+			done: true
+		});
+	};
+	const userOnTrace = options.onTrace;
+	const result = runAgent(machine, {
+		...options,
+		onTrace: (event) => {
+			push(event);
+			userOnTrace?.(event);
+			if (event.type === "run.end") close();
+		}
+	});
+	result.then(close, close);
+	return {
+		events: {
+			next() {
+				if (buffer.length > 0) return Promise.resolve({
+					value: buffer.shift(),
+					done: false
+				});
+				if (closed || stopped) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				return new Promise((resolve) => {
+					resolvers.push(resolve);
+				});
+			},
+			return() {
+				stopped = true;
+				buffer.length = 0;
+				while (resolvers.length > 0) resolvers.shift()({
+					value: void 0,
+					done: true
+				});
+				return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		},
+		result
+	};
+}
+//#endregion
 //#region src/provide-executors.ts
 /**
 * Binds a machine's agent actor sources to a set of host `executors` in one
@@ -1765,8 +1631,8 @@ function collectPendingUserInputs(snapshot) {
 *
 * behaves like a normal XState actor whose agent invokes now reach real models.
 *
-* Binding pass over `machine.implementations.actorSources` (after merging
-* `options.actorSources`):
+* Binding pass over `machine.sources.actors` (after merging
+* `options.actors`):
 * - `mode: 'generate'` text source → `executors.generateText`
 * - `mode: 'stream'` text source → `executors.streamText`
 * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
@@ -1780,7 +1646,7 @@ function collectPendingUserInputs(snapshot) {
 *
 * A source that already carries its own executor (`.withExecutor(...)`) is left
 * as-is. `agent.userInput` is left UNBOUND — an uncontrolled host handles idle
-* itself, so supply a handler via `options.actorSources` if the machine uses it.
+* itself, so supply a handler via `options.actors` if the machine uses it.
 * Non-agent actors are untouched.
 *
 * Throws at bind time if a source needs an executor kind that `executors` does
@@ -1795,14 +1661,14 @@ function provideExecutors(machine, executors, options = {}) {
 		onChunk: options.onChunk,
 		onTrace: options.onTrace
 	};
-	const provided = options.actorSources ? machine.provide({ actorSources: options.actorSources }) : machine;
-	const effectiveSources = provided.implementations.actorSources;
+	const provided = options.actors ? machine.provide({ actors: 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 (require_decision.isDecisionLogic(logic)) {
-			if (require_events.executorBoundLogics.has(logic)) continue;
+			if (require_decision.executorBoundLogics.has(logic)) continue;
 			if (!executors.decide) {
 				if (invokedSrcs.has(key)) throw missingExecutorError(key, "decision", "decide");
 				continue;
@@ -1818,8 +1684,8 @@ function provideExecutors(machine, executors, options = {}) {
 			wrappedSources[key] = bindPlanForProvide(provided, logic, executors, bindOptions);
 			continue;
 		}
-		if (require_events.isTextLogic(logic)) {
-			if (require_events.executorBoundLogics.has(logic)) continue;
+		if (require_decision.isTextLogic(logic)) {
+			if (require_decision.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;
@@ -1828,7 +1694,7 @@ function provideExecutors(machine, executors, options = {}) {
 			continue;
 		}
 	}
-	return provided.provide({ actorSources: wrappedSources });
+	return provided.provide({ actors: 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.`);
@@ -1884,8 +1750,15 @@ function collectTransitionTargets(value, fromNode, index, out) {
 		return;
 	}
 	if (typeof value === "object") {
-		const target = value.target;
-		if (target !== void 0) collectTransitionTargets(target, fromNode, index, out);
+		const { target, to } = value;
+		if (target !== void 0) {
+			collectTransitionTargets(target, fromNode, index, out);
+			return;
+		}
+		if (to !== void 0) {
+			collectTransitionTargets(to, fromNode, index, out);
+			return;
+		}
 	}
 }
 function resolveTargetString(target, fromNode, index, out) {
@@ -1897,12 +1770,16 @@ function resolveTargetString(target, fromNode, index, out) {
 	if (index.has(resolved)) out.targets.push(resolved);
 	else out.opaque = true;
 }
-function outgoingTargets(node, index) {
+function outgoingTargets(node, index, staticTargets) {
 	const out = {
 		targets: [],
 		opaque: false
 	};
 	const { config } = node;
+	if (staticTargets) {
+		for (const target of staticTargets[node.path] ?? []) resolveTargetString(target, node, index, out);
+		return out;
+	}
 	for (const value of Object.values(config.on ?? {})) collectTransitionTargets(value, node, index, out);
 	collectTransitionTargets(config.always, node, index, out);
 	collectTransitionTargets(config.choice, node, index, out);
@@ -1914,7 +1791,7 @@ function outgoingTargets(node, index) {
 	}
 	return out;
 }
-function computeReachable(rootConfig, index) {
+function computeReachable(rootConfig, index, staticTargets) {
 	const reachable = /* @__PURE__ */ new Set();
 	const queue = [];
 	const markAncestors = (path) => {
@@ -1939,7 +1816,7 @@ function computeReachable(rootConfig, index) {
 	while (queue.length > 0) {
 		const node = index.get(queue.shift());
 		if (!node) continue;
-		const { targets, opaque } = outgoingTargets(node, index);
+		const { targets, opaque } = outgoingTargets(node, index, staticTargets);
 		for (const target of targets) enter(target);
 		if (opaque) for (const sibling of childrenOf(index, node.parentPath)) enter(sibling.path);
 	}
@@ -1959,11 +1836,11 @@ function ancestorChain(node, index) {
 function hasNonEmptyOn(config) {
 	return !!config.on && Object.keys(config.on).length > 0;
 }
-function decisionKindOf(src, actorSources) {
+function decisionKindOf(src, actors) {
 	if (typeof src === "string") {
 		if (src === DECIDE_SRC) return "decision";
 		if (src === PLAN_SRC) return "plan";
-		const logic = actorSources[src];
+		const logic = actors[src];
 		if (require_decision.isDecisionLogic(logic)) return "decision";
 		if (require_decision.isPlanLogic(logic)) return "plan";
 		return;
@@ -1972,12 +1849,12 @@ function decisionKindOf(src, actorSources) {
 	if (require_decision.isPlanLogic(src)) return "plan";
 }
 function isAgentLogicNeedingBinding(src) {
-	return (require_events.isTextLogic(src) || require_decision.isDecisionLogic(src) || require_decision.isPlanLogic(src)) && !require_events.executorBoundLogics.has(src);
+	return (require_decision.isTextLogic(src) || require_decision.isDecisionLogic(src) || require_decision.isPlanLogic(src)) && !require_decision.executorBoundLogics.has(src);
 }
 function schemaExposesJson(schema) {
 	if (!schema) return false;
 	try {
-		return require_events.getJsonSchemaSync(schema) !== void 0;
+		return require_decision.getJsonSchemaSync(schema) !== void 0;
 	} catch {
 		return false;
 	}
@@ -1986,7 +1863,7 @@ function isDeclaredOutputSchema(schema) {
 	if (!schema) return false;
 	let json;
 	try {
-		json = require_events.getJsonSchemaSync(schema);
+		json = require_decision.getJsonSchemaSync(schema);
 	} catch {
 		return false;
 	}
@@ -2008,7 +1885,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.actorSources);
+		const kind = decisionKindOf(invoke.src, ctx.actors);
 		if (!kind) continue;
 		const selfHandles = hasNonEmptyOn(node.config);
 		const ancestorHandles = ancestorChain(node, ctx.index).some((ancestor) => hasNonEmptyOn(ancestor.config));
@@ -2045,7 +1922,7 @@ function checkDirectObjectSrc(ctx) {
 			code: "direct-object-src",
 			severity: "warning",
 			path: node.path,
-			message: `State '${node.path}' invokes a direct-object agent logic. Direct-object invoke srcs cannot be rebound by runAgent, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actorSources: { name: logic } })) and invoke it by name.`
+			message: `State '${node.path}' invokes a direct-object agent logic. Direct-object invoke srcs cannot be rebound by runAgent, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actors: { name: logic } })) and invoke it by name.`
 		});
 	}
 	return out;
@@ -2089,8 +1966,8 @@ function isBuiltinOrWildcardEvent(eventType) {
 }
 function checkUndeclaredEvents(ctx) {
 	const declared = ctx.schemas?.events;
-	if (!declared || Object.keys(declared).length === 0) return [];
-	const declaredTypes = new Set(Object.keys(declared));
+	const declaredTypes = new Set(Object.keys(declared ?? {}));
+	if ([...declaredTypes].every((type) => type.startsWith("@agent."))) return [];
 	const out = [];
 	for (const node of ctx.index.values()) for (const eventType of Object.keys(node.config.on ?? {})) {
 		if (declaredTypes.has(eventType) || isBuiltinOrWildcardEvent(eventType)) continue;
@@ -2142,15 +2019,15 @@ const LINT_CHECKS = [
 function lintAgentMachine(machine, options = {}) {
 	const config = machine.config ?? {};
 	const index = buildStateIndex(config);
-	const reachable = computeReachable(config, index);
-	const registered = require_events.getRegisteredAgentExecutionOptions(machine);
+	const reachable = computeReachable(config, index, require_decision.getMachineStaticTransitionTargets(machine));
+	const registered = require_decision.getRegisteredAgentExecutionOptions(machine);
 	const ctx = {
 		machine,
 		config,
 		index,
 		reachable,
 		schemas: registered.schemas,
-		actorSources: registered.actorSources ?? machine.implementations?.actorSources ?? {}
+		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));
@@ -2160,11 +2037,11 @@ function lintAgentMachine(machine, options = {}) {
 * `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.
 */
-var AgentLintError = class extends Error {
+var AgentLintError = class extends require_errors.AgentError {
 	diagnostics;
 	constructor(machineId, diagnostics) {
 		const lines = diagnostics.map((d) => `  ${d.severity === "error" ? "error" : "warn "}  ${d.code}  ${d.path}\n         ${d.message}`);
-		super(`Agent machine '${machineId}' failed lint (${diagnostics.length} finding(s)):\n${lines.join("\n")}`);
+		super("lint-failed", `Agent machine '${machineId}' failed lint (${diagnostics.length} finding(s)):\n${lines.join("\n")}`);
 		this.name = "AgentLintError";
 		this.diagnostics = diagnostics;
 	}
@@ -2190,7 +2067,7 @@ function assertAgentMachine(machine, options = {}) {
 function pendingInvokes(step) {
 	const out = [];
 	for (const action of step.actions) {
-		const metadata = require_steps.getInvokeEffectMetadata(action);
+		const metadata = require_setup_agent.getInvokeEffectMetadata(action);
 		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
 			id: metadata.id,
 			src: metadata.src
@@ -2232,7 +2109,7 @@ async function simulateAgent(machine, options) {
 		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
 		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr])
 	};
-	let step = require_steps.initialAgentStep(machine, options.input);
+	let step = require_setup_agent.initialAgentStep(machine, options.input);
 	const trail = [];
 	for (let i = 0; i < maxSteps; i++) {
 		if (step.done) return {
@@ -2246,7 +2123,7 @@ async function simulateAgent(machine, options) {
 				const decisionSrc = new Map(pendingInvokes(step).map((invoke) => [invoke.id, invoke.src])).get(request.id) ?? request.id;
 				const taken = takeFromQueue(script.decisions, decisionSrc);
 				if (!taken.found) throw scriptDryError("decision", decisionSrc, request.id, request);
-				step = require_steps.transitionAgentStep(machine, step, taken.value);
+				step = require_setup_agent.transitionAgentStep(machine, step, taken.value);
 				trail.push({
 					state: step.snapshot.value,
 					appliedEvent: taken.value
@@ -2257,7 +2134,7 @@ async function simulateAgent(machine, options) {
 				const taken = takeFromQueue(script.decisions, request.src);
 				if (!taken.found) throw scriptDryError("decision", request.src, request.id, request);
 				const event = taken.value;
-				step = await require_steps.resolveAgentRequests(machine, step, { decide: async () => ({ event }) });
+				step = await require_setup_agent.resolveAgentRequests(machine, step, { decide: async () => ({ event }) });
 				trail.push({
 					state: step.snapshot.value,
 					appliedEvent: taken.value
@@ -2266,7 +2143,7 @@ async function simulateAgent(machine, options) {
 			}
 			const taken = takeFromQueue(script.text, request.src);
 			if (!taken.found) throw scriptDryError("text", request.src, request.id);
-			step = require_steps.resolveAgentStep(machine, step, request, taken.value);
+			step = require_setup_agent.resolveAgentStep(machine, step, request, taken.value);
 			trail.push({
 				state: step.snapshot.value,
 				resolvedRequest: {
@@ -2281,7 +2158,7 @@ async function simulateAgent(machine, options) {
 		if (invoke) {
 			const taken = takeFromQueue(script.invokes, invoke.src);
 			if (!taken.found) throw scriptDryError("userInput", invoke.src, invoke.id);
-			step = require_steps.resolveAgentStep(machine, step, invoke.id, taken.value);
+			step = require_setup_agent.resolveAgentStep(machine, step, invoke.id, taken.value);
 			trail.push({
 				state: step.snapshot.value,
 				resolvedRequest: {
@@ -2330,7 +2207,7 @@ async function explore(machine, options, stopWhen) {
 			reachedValues.push(snapshot.value);
 		}
 	};
-	const initial = require_steps.initialAgentStep(machine, options.input);
+	const initial = require_setup_agent.initialAgentStep(machine, options.input);
 	recordState(initial.snapshot);
 	if (stopWhen?.(initial.snapshot)) witness = [];
 	const advance = (step) => {
@@ -2343,7 +2220,7 @@ async function explore(machine, options, stopWhen) {
 					step: current,
 					blockedSrc: request.src
 				};
-				current = require_steps.resolveAgentStep(machine, current, request, textOutputs[request.src]);
+				current = require_setup_agent.resolveAgentStep(machine, current, request, textOutputs[request.src]);
 				recordState(current.snapshot);
 				continue;
 			}
@@ -2354,7 +2231,7 @@ async function explore(machine, options, stopWhen) {
 					step: current,
 					blockedSrc: invoke.src
 				};
-				current = require_steps.resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
+				current = require_setup_agent.resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
 				recordState(current.snapshot);
 				continue;
 			}
@@ -2395,7 +2272,7 @@ async function explore(machine, options, stopWhen) {
 		}
 		const request = settled.requests[0];
 		const isPlan = request?.kind === "plan";
-		const branchEvents = request?.kind === "decision" || request?.kind === "plan" ? request.events.map((descriptor) => ({ type: descriptor.type })) : require_events.getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
+		const branchEvents = request?.kind === "decision" || request?.kind === "plan" ? request.events.map((descriptor) => ({ type: descriptor.type })) : require_decision.getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
 		if (branchEvents.length === 0) {
 			pathsExplored++;
 			terminals.push({
@@ -2424,7 +2301,7 @@ async function explore(machine, options, stopWhen) {
 				prunedByGuard++;
 				continue;
 			}
-			const next = isPlan ? await require_steps.resolveAgentRequests(machine, settled, { decide: async () => ({ event }) }) : require_steps.transitionAgentStep(machine, settled, event);
+			const next = isPlan ? await require_setup_agent.resolveAgentRequests(machine, settled, { decide: async () => ({ event }) }) : require_setup_agent.transitionAgentStep(machine, settled, event);
 			recordState(next.snapshot);
 			await visit(next, [...path, event], depth + 1);
 		}
@@ -2491,38 +2368,506 @@ async function canReach(machine, statePath, options = {}) {
 	} : { canReach: false };
 }
 //#endregion
+//#region src/trajectory.ts
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 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)) {
+		const nested = item["event"];
+		if (isRecord$2(nested) && typeof nested["type"] === "string") return {
+			kind: "event",
+			event: nested
+		};
+		if (typeof item["type"] === "string") return {
+			kind: "event",
+			event: item
+		};
+		if ("value" in item && "status" in item) return {
+			kind: "state",
+			value: item["value"]
+		};
+	}
+	return {
+		kind: "state",
+		value: 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 [];
+	return Object.entries(value).flatMap(([key, child]) => statePaths(child).map((path) => `${key}.${path}`));
+}
+/**
+* A string expectation matches a state value when it names one of its leaves or
+* an ancestor of one, so `'review'` matches `{ review: 'editing' }`. @internal
+*/
+function stateMatchesPath(path, value) {
+	return statePaths(value).some((leaf) => leaf === path || leaf.startsWith(`${path}.`));
+}
+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;
+	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?
+*
+* - 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
+*   declared keys deep-equal, so payload details are opt-in.
+* - 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);
+	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);
+}
+/**
+* Matches a run's trajectory against an expected one.
+*
+* Both trajectories may be state values (collected from `onTransition`) or
+* events (`result.events`, whose {@link AgentLogEntry} envelopes are unwrapped);
+* items are compared by shape, so `['prompting', 'drafting']` scores a state
+* path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
+* call.
+*
+* Semantics are an ordered subsequence: every expected item must appear in
+* `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
+* equality instead.
+*
+* @example Trajectory assertions in a test
+* ```ts
+* const statePath: unknown[] = [];
+* const result = await runAgent(machine, {
+*   input,
+*   executors,
+*   onTransition: (snapshot) => statePath.push(snapshot.value),
+* });
+*
+* const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
+* expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
+* expect(matchesTrajectory(result.events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+* ```
+*
+* @example Partial credit in an eval scorer
+* ```ts
+* const match = matchesTrajectory(output.statePath, expected.statePath);
+* return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
+* ```
+*/
+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 } : {}
+		};
+	}
+	let cursor = 0;
+	let matchedCount = 0;
+	for (let index = 0; index < expectedCount; index++) {
+		const want = expected[index];
+		let found = -1;
+		for (let at = cursor; at < actual.length; at++) if (matchesItem(want, actual[at])) {
+			found = at;
+			break;
+		}
+		if (found === -1) return {
+			matched: false,
+			matchedCount,
+			expectedCount,
+			score: matchedCount / expectedCount,
+			firstMiss: {
+				index,
+				expected: want,
+				searchedFrom: cursor
+			}
+		};
+		matchedCount++;
+		cursor = found + 1;
+	}
+	return {
+		matched: true,
+		matchedCount,
+		expectedCount,
+		score: 1
+	};
+}
+//#endregion
+//#region src/scripted-executors.ts
+/**
+* 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
+* `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.
+*/
+/** Thrown when a scripted queue runs dry on a pending request. */
+var ScriptedExecutorsError = class extends require_errors.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",
+	"usage",
+	"raw"
+]);
+/**
+* True when a scripted entry is the executor envelope rather than the output
+* value: it owns an `output` key and owns NOTHING outside the envelope's own
+* vocabulary. Bare `'output' in value` would swallow an output object's
+* siblings (`{ output: 'draft', confidence: 0.9 }` would lose `confidence`)
+* and would also match an inherited `output`. @internal
+*/
+function isTextEnvelope(value) {
+	return Object.hasOwn(value, "output") && Object.keys(value).every((key) => TEXT_ENVELOPE_KEYS.has(key));
+}
+/**
+* Resolves ONE scripted text entry to an executor result: a function entry is
+* called with the request, and the value is taken as the raw envelope only when
+* it is one (see {@link isTextEnvelope}). Shared with `runSeam`, whose routed
+* queues follow the same entry conventions. @internal
+*/
+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 };
+}
+/**
+* Keyless executors that replay a script instead of calling a model. Every
+* slot is provided, so any machine binds; a request with no entry left throws a
+* descriptive error naming what was pending.
+*
+* Queues are consumed FIFO and are copied on creation, so the caller's arrays
+* are never mutated and each call builds a fresh, independent playthrough.
+* Entries may be plain values or functions of the request, which is how one
+* script serves a machine that loops or branches: route on `request.name` (the
+* `setupAgent({ requests })` key) or on the decision's candidate `events`.
+*
+* @example
+* ```ts
+* const result = await runAgent(moderationMachine, {
+*   input: { comment: 'honestly this update is terrible', trust: 20 },
+*   executors: createScriptedExecutors({
+*     decisions: [{ type: 'FLAG', reason: 'Borderline tone.' }],
+*   }),
+* });
+* ```
+*
+* @example Dynamic entries
+* ```ts
+* createScriptedExecutors({
+*   text: [(request) => `Draft about ${request.prompt}`],
+*   decisions: [(request) => ({ type: request.events[0]!.type })],
+* });
+* ```
+*/
+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.`);
+		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);
+			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)"}.`);
+			const entry = decisions.shift();
+			const value = typeof entry === "function" ? await entry(request) : entry;
+			return typeof value.type === "string" ? { event: value } : 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 require_errors.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
+* STREAM result is left alone — the machine consumes that stream, and reading
+* it here would steal the chunks — so `seamOutput` is `undefined` for a
+* streaming candidate that returns one. Score its trajectory instead.
+* @internal
+*/
+async function seamOutputOf(result, request) {
+	if (!isRecord(result)) return;
+	if ("output" in result) return await result["output"];
+	if ("textStream" in result) return;
+	return await require_decision.normalizeGeneratorResult(result, `seam '${request.name ?? request.model}'`, { request });
+}
+/**
+* Runs a machine end to end with one model call under test, and slices the run
+* at that call.
+*
+* The `before`/`after` slices are the point: `after.statePath` is the branch
+* the seam chose and `after.events` is the same question against the durable
+* log, both ready for `matchesTrajectory`. The state slice splits where the
+* state path stood when the seam answered; the event slice splits at the
+* seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
+* entry appended after the call was made).
+*
+* @example Keyless: the seam is scripted too, so the whole thing runs offline.
+* ```ts
+* const run = await runSeam(emailDrafter, {
+*   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
+*   seam: { request: 'evaluatePrompt' },
+*   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
+* });
+*
+* matchesTrajectory(run.after.statePath, ['needsMoreInfo', 'drafting']);
+* ```
+*
+* @example A candidate prompt at the seam, scored against the same rows.
+* ```ts
+* const { generateText } = createAiSdkExecutors({ models });
+* const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
+* ```
+*/
+async function runSeam(machine, options) {
+	const { seam, candidate } = options;
+	const queues = new Map(Object.entries(options.scripts ?? {}).map(([key, answers]) => [key, [...answers]]));
+	const statePath = [];
+	let calls = 0;
+	let seamMatches = 0;
+	let seamOutput;
+	let seamReached = false;
+	let callsBeforeSeam = -1;
+	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.`);
+		}
+		return resolveScriptedTextEntry(queue.length === 1 ? queue[0] : queue.shift(), request, info);
+	};
+	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) 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;
+	};
+	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);
+			return result;
+		}
+	};
+	let snapshot;
+	let event;
+	let events = [];
+	let result;
+	const maxTurns = options.maxTurns ?? 12;
+	for (let turn = 0; turn <= maxTurns; turn++) {
+		result = await runAgent(machine, {
+			...snapshot ? { snapshot } : { input: options.input },
+			...event ? { event } : {},
+			...options.isSuspended ? { isSuspended: options.isSuspended } : {},
+			...options.actors ? { actors: options.actors } : {},
+			events,
+			executors,
+			onEvent: () => {
+				liveEvents++;
+			},
+			onTransition: (next, causedBy) => {
+				if (turn > 0 && causedBy.type === "@xstate.init") return;
+				statePath.push(next.value);
+			}
+		});
+		events = result.events;
+		liveEvents = events.length;
+		if (result.status !== "idle" || turn === maxTurns) break;
+		const next = options.respond?.({
+			snapshot: result.snapshot,
+			state: result.snapshot.value,
+			meta: require_decision.getStateMeta(result.snapshot),
+			turn,
+			result
+		});
+		if (!next) break;
+		event = next;
+		snapshot = result.snapshot;
+	}
+	let splitAt = events.length;
+	if (seamReached) {
+		splitAt = seamEventAt;
+		for (let index = seamEventAt; index < events.length; index++) {
+			const type = events[index].event.type;
+			if (type.startsWith("xstate.done") || type.startsWith("xstate.error")) {
+				splitAt = index;
+				break;
+			}
+		}
+	}
+	const splitStateAt = seamReached ? seamStateAt : statePath.length;
+	return {
+		result,
+		seamOutput,
+		callsBeforeSeam,
+		before: {
+			statePath: statePath.slice(0, splitStateAt),
+			events: events.slice(0, splitAt)
+		},
+		after: {
+			statePath: statePath.slice(splitStateAt),
+			events: events.slice(splitAt)
+		}
+	};
+}
+//#endregion
+exports.AGENT_EVENT_SCHEMA_VERSION = require_event_log_store.AGENT_EVENT_SCHEMA_VERSION;
+exports.AGENT_INIT_EVENT_TYPE = require_setup_agent.AGENT_INIT_EVENT_TYPE;
 exports.AGENT_TRACE_SCHEMA_VERSION = AGENT_TRACE_SCHEMA_VERSION;
+exports.AGENT_USAGE_EVENT_TYPE = require_setup_agent.AGENT_USAGE_EVENT_TYPE;
+exports.AgentDecisionExhaustedError = require_decision.AgentDecisionExhaustedError;
+exports.AgentError = require_errors.AgentError;
+exports.AgentEventLogConflictError = require_event_log_store.AgentEventLogConflictError;
 exports.AgentIdleError = AgentIdleError;
+exports.AgentIllegalResumeEventError = AgentIllegalResumeEventError;
 exports.AgentLintError = AgentLintError;
-exports.DecisionExhaustedError = require_decision.DecisionExhaustedError;
-exports.IllegalResumeEventError = IllegalResumeEventError;
-exports.SnapshotVersionMismatchError = SnapshotVersionMismatchError;
-exports.appendMessages = appendMessages;
+exports.AgentReplayDivergenceError = require_setup_agent.AgentReplayDivergenceError;
+exports.AgentReplayMachineMismatchError = require_setup_agent.AgentReplayMachineMismatchError;
+exports.AgentSnapshotVersionMismatchError = AgentSnapshotVersionMismatchError;
+exports.NonSerializableAgentEventError = require_event_log_store.NonSerializableAgentEventError;
+exports.PLAN_DONE_EVENT_TYPE = require_decision.PLAN_DONE_EVENT_TYPE;
+exports.appendMessages = require_setup_agent.appendMessages;
+exports.assertAgentLogEntry = require_event_log_store.assertAgentLogEntry;
 exports.assertAgentMachine = assertAgentMachine;
-exports.assistantMessage = require_events.assistantMessage;
+exports.assertEventLogStoreConformance = require_event_log_store.assertEventLogStoreConformance;
+exports.assertJsonSerializable = require_event_log_store.assertJsonSerializable;
+exports.assistantMessage = require_decision.assistantMessage;
+exports.bindRequestExecutor = require_decision.bindRequestExecutor;
+exports.buildEnvelopeSchema = require_decision.buildEnvelopeSchema;
 exports.canReach = canReach;
-exports.createAgentSchemas = createAgentSchemas;
-exports.createTextLogic = require_events.createTextLogic;
+exports.createAgentActor = createAgentActor;
+exports.createAgentRun = createAgentRun;
+exports.createAgentSchemas = require_setup_agent.createAgentSchemas;
+exports.createInMemoryEventLogStore = require_event_log_store.createInMemoryEventLogStore;
+exports.createReplayEntry = require_setup_agent.createReplayEntry;
+exports.createScriptedExecutors = createScriptedExecutors;
+exports.createTextLogic = require_decision.createTextLogic;
+exports.diffEventLogs = require_setup_agent.diffEventLogs;
+exports.executeAgentRequest = require_setup_agent.executeAgentRequest;
 exports.explorePaths = explorePaths;
-exports.getAcceptedEvents = require_events.getAcceptedEvents;
-exports.getAgentMessages = require_events.getAgentMessages;
-exports.getStateMeta = require_events.getStateMeta;
+exports.generateResult = generateResult;
+exports.getAcceptedEvents = require_decision.getAcceptedEvents;
+exports.getAgentEffects = require_setup_agent.getAgentEffects;
+exports.getAgentMessages = require_decision.getAgentMessages;
+exports.getAgentOutputMode = require_decision.getAgentOutputMode;
+exports.getCallUsage = require_setup_agent.getCallUsage;
+exports.getJsonSchema = require_decision.getJsonSchema;
+exports.getJsonSchemaSync = require_decision.getJsonSchemaSync;
+exports.getMachineStructuralHash = require_decision.getMachineStructuralHash;
+exports.getStateMeta = require_decision.getStateMeta;
+exports.initEntry = require_setup_agent.initEntry;
 exports.inspectTransitions = inspectTransitions;
+exports.isStandardSchema = require_decision.isStandardSchema;
 exports.lintAgentMachine = lintAgentMachine;
-exports.messagesSchema = messagesSchema;
-exports.parseAgentEvent = require_events.parseAgentEvent;
-exports.persistSnapshot = require_events.persistSnapshot;
+exports.matchesTrajectory = matchesTrajectory;
+exports.messagesSchema = require_setup_agent.messagesSchema;
+exports.parseAgentEvent = require_decision.parseAgentEvent;
+exports.parseModelRef = require_decision.parseModelRef;
+exports.parseOutput = require_decision.parseOutput;
+exports.parseStructuredEnvelope = require_decision.parseStructuredEnvelope;
+exports.persistSnapshot = require_decision.persistSnapshot;
 exports.provideExecutors = provideExecutors;
+exports.renderDecisionAttempts = require_decision.renderDecisionAttempts;
+exports.replay = require_setup_agent.replay;
+exports.resolveDecision = require_decision.resolveDecision;
 exports.runAgent = runAgent;
-exports.runAgentToCompletion = runAgentToCompletion;
+exports.runSeam = runSeam;
+exports.serializeTraceEvent = serializeTraceEvent;
 Object.defineProperty(exports, "setupAgent", {
 	enumerable: true,
 	get: function() {
-		return setupAgent;
+		return require_setup_agent.setupAgent;
 	}
 });
 exports.simulateAgent = simulateAgent;
-exports.systemMessage = require_events.systemMessage;
-exports.toolMessage = require_events.toolMessage;
+exports.systemMessage = require_decision.systemMessage;
+exports.toolMessage = require_decision.toolMessage;
 exports.traceTransitions = traceTransitions;
-exports.userMessage = require_events.userMessage;
+exports.userMessage = require_decision.userMessage;
+exports.verifyReplay = require_setup_agent.verifyReplay;