@statelyai/agent 2.0.0-alpha.29 → 2.0.0-alpha.31

package/dist/{run-agent-cToZ3K42.cjs → run-agent-tmk58M0x.cjs}

@@ -1,6 +1,6 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
-const require_event_log_store = require("./event-log-store-bCdskPNS.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
+const require_event_log_store = require("./event-log-store-BWMLi6oh.cjs");
 let xstate = require("xstate");
 let xstate_durable = require("xstate/durable");
 //#region src/run-agent.ts
@@ -290,6 +290,13 @@ function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
 function declaresUsageTransition(snapshot) {
 	return (0, xstate.getNextTransitions)(snapshot).some((transition) => transition.eventType === "@agent.usage" || transition.eventType === "*");
 }
+function observe(name, call) {
+	try {
+		call();
+	} catch (error) {
+		console.error(`@statelyai/agent: ${name} threw; the run continues.`, error);
+	}
+}
 /**
 * Builds the ONE place a trace payload is emitted: it hands the payload to the
 * envelope-stamping trace sink and, from that same payload, invokes the sugar
@@ -306,21 +313,21 @@ function createTraceDispatch(sinks) {
 	return (payload, self) => {
 		switch (payload.type) {
 			case "stream.chunk":
-				sinks.onTrace?.(payload, self);
-				sinks.onChunk?.(payload.chunk, { request: payload.request });
+				observe("onTrace", () => sinks.onTrace?.(payload, self));
+				observe("onChunk", () => sinks.onChunk?.(payload.chunk, { request: payload.request }));
 				return;
 			case "request.end":
-				sinks.onResult?.(payload.request, {
+				observe("onResult", () => sinks.onResult?.(payload.request, {
 					result: payload.output,
 					raw: payload.raw
-				});
-				sinks.onTrace?.(payload, self);
+				}));
+				observe("onTrace", () => sinks.onTrace?.(payload, self));
 				return;
 			case "machine.transition":
-				sinks.onTrace?.(payload, self);
-				sinks.onTransition?.(payload.snapshot, payload.event);
+				observe("onTrace", () => sinks.onTrace?.(payload, self));
+				observe("onTransition", () => sinks.onTransition?.(payload.snapshot, payload.event));
 				return;
-			default: sinks.onTrace?.(payload, self);
+			default: observe("onTrace", () => sinks.onTrace?.(payload, self));
 		}
 	};
 }
@@ -509,6 +516,11 @@ function bindDecisionLogic(logic, runCtx) {
 			schemas: runCtx.schemas,
 			eventTypes: declaredEventTypes
 		}) : [];
+		const agentCan = (event) => {
+			if (!actorRef) return true;
+			const snapshot = actorRef.getSnapshot();
+			return !require_decision.getHumanEventTypes(snapshot).has(event.type) && snapshot.can(event);
+		};
 		const lowered = logic.request(input);
 		const request = {
 			...lowered,
@@ -521,7 +533,7 @@ function bindDecisionLogic(logic, runCtx) {
 		const options = require_decision.acceptedDecisionOptions(request, (event) => {
 			let accepted;
 			try {
-				accepted = actorRef ? actorRef.getSnapshot().can(event) : true;
+				accepted = agentCan(event);
 			} catch {
 				accepted = false;
 			}
@@ -532,6 +544,10 @@ function bindDecisionLogic(logic, runCtx) {
 			request.options = options;
 			request.withheld = withheld;
 		}
+		if (actorRef) {
+			const humanEventTypes = require_decision.getHumanEventTypes(actorRef.getSnapshot());
+			request.events = events.filter((event) => !humanEventTypes.has(event.type));
+		}
 		if (options?.length === 0) {
 			const error = new require_decision.AgentDecisionExhaustedError([]);
 			error.message = `Decision '${request.name}' has no offered option the current snapshot accepts; no model call was made.`;
@@ -554,7 +570,7 @@ function bindDecisionLogic(logic, runCtx) {
 		} }, {
 			maxRetries: lowered.maxRetries ?? logic.maxRetries,
 			signal,
-			canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
+			canTake: agentCan
 		});
 		if (priorAttempts.length > 0) runCtx.noteDecision?.(chosen, priorAttempts);
 		actorRef?.send(chosen);
@@ -918,6 +934,8 @@ function createAgentRuntime(machine, options = {}) {
 	let traceSeq = 0;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
 	const machineVersion = require_event_log.resolveMachineVersion(machine);
+	if (options.metadata !== void 0) require_event_log.assertJsonSerializable(options.metadata, "metadata");
+	const initMetadata = options.metadata === void 0 ? void 0 : structuredClone(options.metadata);
 	const onTrace = createTraceDispatch({
 		onTrace: (payload) => {
 			options.onTrace?.({
@@ -998,13 +1016,32 @@ function createAgentRuntime(machine, options = {}) {
 	let loggingEnabled = true;
 	const attemptsByEvent = /* @__PURE__ */ new WeakMap();
 	let logFold;
+	const stopLogging = (error) => {
+		if (!loggingEnabled) return;
+		loggingEnabled = false;
+		if (store !== void 0) {
+			journalError ??= error;
+			stopRun({
+				cause: "journal",
+				error
+			});
+			return;
+		}
+		console.warn(`@statelyai/agent: this run's log stopped at entry ${logEntries.length}, so result.events is incomplete: ${error instanceof Error ? error.message : String(error)}. Pass input and events that JSON can hold.`);
+	};
 	const appendLogEntry = (event, attempts) => {
 		if (!loggingEnabled) return;
-		const entry = require_event_log.createReplayEntry(logMachine, logEntries, event, {
-			machineVersion,
-			verification: false,
-			...attempts !== void 0 ? { attempts } : {}
-		});
+		let entry;
+		try {
+			entry = require_event_log.createReplayEntry(logMachine, logEntries, event, {
+				machineVersion,
+				verification: false,
+				...attempts !== void 0 ? { attempts } : {}
+			});
+		} catch (error) {
+			stopLogging(error);
+			return;
+		}
 		if (verificationEnabled && logFold !== null) try {
 			logFold ??= require_event_log.foldLog(logMachine, logEntries, {
 				machineVersion,
@@ -1016,7 +1053,7 @@ function createAgentRuntime(machine, options = {}) {
 		}
 		logEntries.push(entry);
 		journalEntry(entry);
-		options.onEvent?.(entry);
+		observe("onEvent", () => options.onEvent?.(entry));
 		return entry;
 	};
 	const recordUsage = (usage, source = {}) => {
@@ -1191,8 +1228,8 @@ function createAgentRuntime(machine, options = {}) {
 			event
 		});
 		const on = options.on ?? {};
-		on[event.type]?.(event);
-		if (event.type !== "*") on["*"]?.(event);
+		observe(`on['${event.type}']`, () => on[event.type]?.(event));
+		if (event.type !== "*") observe("on['*']", () => on["*"]?.(event));
 	};
 	const inspect = options.inspect === void 0 ? void 0 : (event) => {
 		if (typeof options.inspect === "function") options.inspect(event);
@@ -1246,14 +1283,15 @@ function createAgentRuntime(machine, options = {}) {
 		}
 	}, inspect ? { inspect } : void 0);
 	const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
-	const commit = (snapshot, event) => {
+	const commit = (snapshot, event, ignored = false) => {
 		const from = { value: (current ?? snapshot).value };
 		current = snapshot;
 		onTrace({
 			type: "machine.transition",
 			from,
 			snapshot,
-			event
+			event,
+			...ignored ? { ignored: true } : {}
 		});
 	};
 	/** True for a child completion/failure whose child is no longer running under the current state. */
@@ -1267,14 +1305,23 @@ function createAgentRuntime(machine, options = {}) {
 			if (started) throw new require_event_log.AgentError("runtime-started", "createAgentRuntime: `start` was already called.");
 			started = true;
 			let resumeEvents = init.events;
+			let resumedFromStore = false;
 			if (store !== void 0) {
 				const storedThread = await store.read(threadId);
 				if (resumeEvents !== void 0) {
 					if (storedThread.length !== resumeEvents.length) throw new require_event_log_store.AgentEventLogConflictError(threadId, resumeEvents.length, storedThread.length);
 					assertThreadMatchesEvents(threadId, storedThread, resumeEvents);
-				} else if (storedThread.length > 0) resumeEvents = storedThread;
+					resumedFromStore = storedThread.length > 0;
+				} else if (storedThread.length > 0) {
+					resumeEvents = storedThread;
+					resumedFromStore = true;
+				}
 			}
 			const resolvedInput = resolveMachineInput(machine, init.input);
+			const threadInit = resumeEvents?.[0]?.event;
+			if (resumedFromStore && init.input !== void 0 && threadInit !== void 0 && Object.hasOwn(threadInit, "input")) {
+				if (require_event_log.canonicalJson(threadInit.input) !== require_event_log.canonicalJson(resolvedInput)) throw new require_event_log.AgentError("thread-input-mismatch", `createAgentRuntime: thread '${threadId}' was started with different input. A thread that already has entries is resumed, not restarted; give a new run a new threadId.`);
+			}
 			let effectiveSnapshot = init.snapshot;
 			let seedInitEntry;
 			const restoredPersistedSnapshot = () => {
@@ -1292,18 +1339,25 @@ function createAgentRuntime(machine, options = {}) {
 			* run WITHOUT a log rather than failing it.
 			*/
 			const appendInitEntry = (candidates, metadata) => {
-				for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
-					const entry = require_event_log.initEntry(logMachine, candidate, {
-						machineVersion,
-						verification,
-						metadata
-					});
+				let lastError;
+				for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) {
+					let entry;
+					try {
+						entry = require_event_log.initEntry(logMachine, candidate, {
+							machineVersion,
+							verification,
+							metadata
+						});
+					} catch (error) {
+						lastError = error;
+						continue;
+					}
 					logEntries.push(entry);
 					journalEntry(entry);
-					options.onEvent?.(entry);
+					observe("onEvent", () => options.onEvent?.(entry));
 					return;
-				} catch {}
-				loggingEnabled = false;
+				}
+				stopLogging(lastError);
 			};
 			/** Init forms for a snapshot resume, most faithful first. */
 			const snapshotInitCandidates = () => {
@@ -1370,16 +1424,23 @@ function createAgentRuntime(machine, options = {}) {
 						logIndex: resumeEvents.length
 					};
 					seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+						...initMetadata,
 						...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
 						migratedFrom
 					});
 				}
 			} else if (init.snapshot !== void 0) {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			} else {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			}
 			const resumedHistory = [...logEntries];
 			const siteCallCounts = /* @__PURE__ */ new Map();
@@ -1447,9 +1508,11 @@ function createAgentRuntime(machine, options = {}) {
 			const attempts = transitionOptions?.attempts ?? attemptsByEvent.get(event);
 			if (transitionOptions?.attempts !== void 0) require_event_log.assertJsonSerializable(transitionOptions.attempts, "attempts");
 			const [next, effects] = execution.transition(state, event);
-			if (!fromMailbox.has(event) && next === state && effects.length === 0) ignoredEvent = event;
+			const ignored = !fromMailbox.has(event) && next === state && effects.length === 0;
+			if (ignored) ignoredEvent = event;
 			appendLogEntry(event, attempts);
-			commit(next, event);
+			if (stopReason !== void 0) return [state, []];
+			commit(next, event, ignored);
 			return [next, effects];
 		},
 		async execute(effects) {

package/dist/{setup-agent-DniLvDu7.mjs → setup-agent-BaffhCcM.mjs}

@@ -1,5 +1,5 @@
-import { A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, G as missingActor, H as getAgentExecutionOptions, K as setAgentExecutionOptions, T as DECIDE_ACTOR, k as builtinTextActors, ot as validateSchemaSync } from "./event-log-GPZO9p7_.mjs";
-import { r as createDecideActor } from "./decision-Bl_rKQnU.mjs";
+import { A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, G as missingActor, H as getAgentExecutionOptions, K as setAgentExecutionOptions, T as DECIDE_ACTOR, ct as isPlainObject, k as builtinTextActors, ot as validateSchemaSync, ut as AgentError } from "./event-log-DE430ZCa.mjs";
+import { r as createDecideActor } from "./decision-DqO018Tp.mjs";
 import { machineFromJSON, setup } from "xstate";
 //#region src/workflow-config.ts
 /**
@@ -387,7 +387,27 @@ function withAgentUsageEventSchema(events) {
 	};
 }
 function normalizeEventSchemas(events) {
-	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
+	return Object.fromEntries(Object.entries(events).map(([type, schema]) => {
+		if (schema && typeof schema === "object" && "~standard" in schema) return [type, schema];
+		if (!(isPlainObject(schema) && Object.keys(schema).length === 0)) assertStandardSchema(schema, `events.${type}`);
+		return [type, emptyEventSchema];
+	}));
+}
+/**
+* Throws for a declared schema without the Standard Schema `~standard`
+* property. Such a schema would otherwise be skipped, so values it should
+* reject would pass unchecked. Zod 3.23 and earlier are the usual cause.
+*/
+function assertStandardSchema(schema, where) {
+	if (schema === void 0 || typeof schema === "object" && schema !== null && "~standard" in schema) return;
+	throw new AgentError("invalid-schema", `setupAgent: '${where}' is not a Standard Schema (it has no '~standard' property), so it cannot be used to validate. Use zod 4 or zod 3.24 and later, Valibot, ArkType, or any other Standard Schema library; zod 3.23 and earlier do not implement it.`);
+}
+function assertStateSchemasAreStandard(states, path = []) {
+	for (const [key, state] of Object.entries(states ?? {})) {
+		const statePath = [...path, key];
+		for (const [name, schema] of Object.entries(state?.schemas ?? {})) assertStandardSchema(schema, `states.${statePath.join(".states.")}.schemas.${name}`);
+		assertStateSchemasAreStandard(state?.states, statePath);
+	}
 }
 /**
 * Builds a machine's {@link AgentSchemaPack} from a partial schema
@@ -454,8 +474,23 @@ function createAgentSchemas(schemas) {
 */
 function setupAgent(config) {
 	const schemas = normalizeAgentSchemas(config);
+	for (const key of [
+		"context",
+		"input",
+		"output",
+		"meta"
+	]) assertStandardSchema(schemas[key], key);
+	for (const [type, schema] of Object.entries(schemas.emitted ?? {})) assertStandardSchema(schema, `emitted.${type}`);
+	assertStateSchemasAreStandard(config.states);
 	const requestActors = createRequestActors(config.requests ?? {});
 	const actors = createAgentActors(config.actors, requestActors);
+	for (const [name, request] of Object.entries(config.requests ?? {})) {
+		const source = request;
+		if (source.prompt === void 0 && source.messages === void 0) throw new AgentError("invalid-request", `setupAgent: request '${name}' has neither \`prompt\` nor \`messages\`, so every call to it fails. A request whose executor builds its own model call still needs one: pass the conversation as \`messages: ({ input }) => input.messages\` (or a \`prompt\`) and read it in the executor.`);
+		const requestSchemas = request.schemas;
+		assertStandardSchema(requestSchemas?.input, `requests.${name}.schemas.input`);
+		assertStandardSchema(requestSchemas?.output, `requests.${name}.schemas.output`);
+	}
 	const setupConfig = {
 		schemas: {
 			context: schemas.context,

package/dist/{setup-agent-tsc3vm5I.d.mts → setup-agent-CPyg2ic7.d.mts}

@@ -1,6 +1,6 @@
 import { _ as StandardSchemaV1, d as EventUnion, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, m as InferInput, s as AgentTools, t as AgentEventSchemaInputMap, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.mjs";
-import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-BDbGjYMh.mjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-D8UphgEA.mjs";
+import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-BwdrDpO9.mjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-Bl4nK8D-.mjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
 //#region src/interaction.d.ts
 interface AgentInteractionEvent<TType extends string = string> {
@@ -84,13 +84,21 @@ interface AgentInteractionDescriptor<TEvent extends string = string> {
  */
 interface AgentInteractionMeta<TEvent extends string = string> {
   interaction?: AgentInteractionDescriptor<TEvent>;
+  /**
+   * On a transition: `"human"` means a person sends its event, never a model.
+   * Model-facing decisions (`agent.decide`, `decideNext`) withhold an event a
+   * state handles through a transition tagged this way. Read from object
+   * transitions only; a transition written as a function cannot be tagged.
+   */
+  actor?: "human";
 }
 /**
  * A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
  * reads: an object whose optional `interaction` declares a `label` (a string
  * with `{context.path}` interpolation, or a function of the context), an
  * `events` map of choices, payload `choices` (an array, or a context path to
- * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
+ * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers; and
+ * an optional `actor: "human"`, which tags a transition as sent by a person. This is
  * the default `meta` type `setupAgent` gives a machine; pass it to
  * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
  * schema pack by hand.

package/dist/{setup-agent-DTF3NQg3.cjs → setup-agent-D0L8Anl_.cjs}

@@ -1,5 +1,5 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
 let xstate = require("xstate");
 //#region src/workflow-config.ts
 /**
@@ -387,7 +387,27 @@ function withAgentUsageEventSchema(events) {
 	};
 }
 function normalizeEventSchemas(events) {
-	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
+	return Object.fromEntries(Object.entries(events).map(([type, schema]) => {
+		if (schema && typeof schema === "object" && "~standard" in schema) return [type, schema];
+		if (!(require_event_log.isPlainObject(schema) && Object.keys(schema).length === 0)) assertStandardSchema(schema, `events.${type}`);
+		return [type, emptyEventSchema];
+	}));
+}
+/**
+* Throws for a declared schema without the Standard Schema `~standard`
+* property. Such a schema would otherwise be skipped, so values it should
+* reject would pass unchecked. Zod 3.23 and earlier are the usual cause.
+*/
+function assertStandardSchema(schema, where) {
+	if (schema === void 0 || typeof schema === "object" && schema !== null && "~standard" in schema) return;
+	throw new require_event_log.AgentError("invalid-schema", `setupAgent: '${where}' is not a Standard Schema (it has no '~standard' property), so it cannot be used to validate. Use zod 4 or zod 3.24 and later, Valibot, ArkType, or any other Standard Schema library; zod 3.23 and earlier do not implement it.`);
+}
+function assertStateSchemasAreStandard(states, path = []) {
+	for (const [key, state] of Object.entries(states ?? {})) {
+		const statePath = [...path, key];
+		for (const [name, schema] of Object.entries(state?.schemas ?? {})) assertStandardSchema(schema, `states.${statePath.join(".states.")}.schemas.${name}`);
+		assertStateSchemasAreStandard(state?.states, statePath);
+	}
 }
 /**
 * Builds a machine's {@link AgentSchemaPack} from a partial schema
@@ -454,8 +474,23 @@ function createAgentSchemas(schemas) {
 */
 function setupAgent(config) {
 	const schemas = normalizeAgentSchemas(config);
+	for (const key of [
+		"context",
+		"input",
+		"output",
+		"meta"
+	]) assertStandardSchema(schemas[key], key);
+	for (const [type, schema] of Object.entries(schemas.emitted ?? {})) assertStandardSchema(schema, `emitted.${type}`);
+	assertStateSchemasAreStandard(config.states);
 	const requestActors = createRequestActors(config.requests ?? {});
 	const actors = createAgentActors(config.actors, requestActors);
+	for (const [name, request] of Object.entries(config.requests ?? {})) {
+		const source = request;
+		if (source.prompt === void 0 && source.messages === void 0) throw new require_event_log.AgentError("invalid-request", `setupAgent: request '${name}' has neither \`prompt\` nor \`messages\`, so every call to it fails. A request whose executor builds its own model call still needs one: pass the conversation as \`messages: ({ input }) => input.messages\` (or a \`prompt\`) and read it in the executor.`);
+		const requestSchemas = request.schemas;
+		assertStandardSchema(requestSchemas?.input, `requests.${name}.schemas.input`);
+		assertStandardSchema(requestSchemas?.output, `requests.${name}.schemas.output`);
+	}
 	const setupConfig = {
 		schemas: {
 			context: schemas.context,

package/dist/{setup-agent-DlbgwsIJ.d.cts → setup-agent-yFFVXf5s.d.cts}

@@ -1,6 +1,6 @@
 import { _ as StandardSchemaV1, d as EventUnion, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, m as InferInput, s as AgentTools, t as AgentEventSchemaInputMap, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.cjs";
-import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-9fv1i9aK.cjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-R1NTmLxY.cjs";
+import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-j9hShB7d.cjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BYqv7VBw.cjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
 //#region src/interaction.d.ts
 interface AgentInteractionEvent<TType extends string = string> {
@@ -84,13 +84,21 @@ interface AgentInteractionDescriptor<TEvent extends string = string> {
  */
 interface AgentInteractionMeta<TEvent extends string = string> {
   interaction?: AgentInteractionDescriptor<TEvent>;
+  /**
+   * On a transition: `"human"` means a person sends its event, never a model.
+   * Model-facing decisions (`agent.decide`, `decideNext`) withhold an event a
+   * state handles through a transition tagged this way. Read from object
+   * transitions only; a transition written as a function cannot be tagged.
+   */
+  actor?: "human";
 }
 /**
  * A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
  * reads: an object whose optional `interaction` declares a `label` (a string
  * with `{context.path}` interpolation, or a function of the context), an
  * `events` map of choices, payload `choices` (an array, or a context path to
- * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
+ * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers; and
+ * an optional `actor: "human"`, which tags a transition as sent by a person. This is
  * the default `meta` type `setupAgent` gives a machine; pass it to
  * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
  * schema pack by hand.

package/dist/tanstack-ai.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
-const require_model_source = require("./model-source-DjJPjGSP.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
+const require_model_source = require("./model-source-DQ7KgJaT.cjs");
 let _tanstack_ai = require("@tanstack/ai");
 //#region src/tanstack-ai/index.ts
 /**

package/dist/tanstack-ai.d.cts

@@ -1,5 +1,5 @@
 import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
-import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-9fv1i9aK.cjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-j9hShB7d.cjs";
 import { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -195,7 +195,7 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
  * ```ts
  * import { openaiText } from '@tanstack/ai-openai';
  *
- * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-5.4-mini') } });
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */

package/dist/tanstack-ai.d.mts

@@ -1,5 +1,5 @@
 import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
-import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BDbGjYMh.mjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BwdrDpO9.mjs";
 import { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -195,7 +195,7 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
  * ```ts
  * import { openaiText } from '@tanstack/ai-openai';
  *
- * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-5.4-mini') } });
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */

package/dist/tanstack-ai.mjs

@@ -1,6 +1,6 @@
-import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, ct as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-GPZO9p7_.mjs";
-import { c as renderDecisionAttempts } from "./decision-Bl_rKQnU.mjs";
-import { t as resolveModelSource } from "./model-source-C7FFP2Sj.mjs";
+import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, dt as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-DE430ZCa.mjs";
+import { c as renderDecisionAttempts } from "./decision-DqO018Tp.mjs";
+import { t as resolveModelSource } from "./model-source-CXsSZPq0.mjs";
 import { chat, maxIterations } from "@tanstack/ai";
 //#region src/tanstack-ai/index.ts
 /**