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

package/dist/{event-log-GPZO9p7_.mjs → event-log-DE430ZCa.mjs}

@@ -54,6 +54,31 @@ var AgentTruncatedError = class extends AgentError {
 	}
 };
 //#endregion
+//#region src/internal/is-record.ts
+/** True for a plain object-like value (arrays excluded). @internal */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* True for an object whose prototype is `null` or some realm's
+* `Object.prototype`. Comparing against this realm's `Object.prototype` alone
+* rejects plain objects built in another realm: a jest test file's vm
+* context, or `structuredClone`'s output inside one. @internal
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+/** True for an `Error` from any realm, where `instanceof Error` sees only this one. @internal */
+function isError(value) {
+	return value instanceof Error || Object.prototype.toString.call(value) === "[object Error]";
+}
+/** JSON text with object keys sorted and `undefined` fields dropped, for comparing JSON-like values. @internal */
+function canonicalJson(value) {
+	return JSON.stringify(value, (_key, item) => isPlainObject(item) ? Object.fromEntries(Object.keys(item).sort().map((key) => [key, item[key]])) : item) ?? "undefined";
+}
+//#endregion
 //#region src/utils.ts
 /** Returns the human-readable text carried by a message, ignoring non-text parts. */
 function getMessageText(message) {
@@ -103,8 +128,7 @@ function findNonSerializableContextPaths(context, limit = 5) {
 			seen.delete(obj);
 			return;
 		}
-		const proto = Object.getPrototypeOf(value);
-		if (proto === Object.prototype || proto === null) {
+		if (isPlainObject(value)) {
 			seen.add(obj);
 			for (const [key, item] of Object.entries(value)) walk(item, `${path}.${key}`);
 			seen.delete(obj);
@@ -456,7 +480,7 @@ function responseMessagesOf(raw) {
 }
 function dropUndefined(value) {
 	if (Array.isArray(value)) return value.map(dropUndefined);
-	if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+	if (isPlainObject(value)) {
 		const out = {};
 		for (const [key, entry] of Object.entries(value)) if (entry !== void 0) out[key] = dropUndefined(entry);
 		return out;
@@ -577,7 +601,7 @@ function resolveTextLogicValue(value, args) {
 * export const tellJoke = createTextLogic({
 *   mode: 'stream',
 *   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
-*   model: 'openai/gpt-5.4-mini',
+*   model: 'openai/gpt-6-luna',
 *   system: 'You tell short, punchy jokes.',
 *   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
 * });
@@ -932,8 +956,7 @@ function assertJsonSerializable(value, path = "entry", ancestors = /* @__PURE__
 			assertNoHiddenKeys(value, path, (key) => key === "length" || arrayIndexPattern.test(key));
 			return;
 		}
-		const prototype = Object.getPrototypeOf(value);
-		if (prototype !== Object.prototype && prototype !== null) throw new NonSerializableAgentEventError(path, value.constructor?.name ?? "object");
+		if (!isPlainObject(value)) throw new NonSerializableAgentEventError(path, value.constructor?.name ?? "object");
 		assertNoHiddenKeys(value, path);
 		for (const [key, child] of Object.entries(value)) assertJsonSerializable(child, `${path}.${key}`, ancestors);
 	} finally {
@@ -990,22 +1013,32 @@ function exhaustedAttemptsOf(error) {
 	return Array.isArray(attempts) && isJsonSerializable(attempts) ? attempts : void 0;
 }
 /**
-* Replaces `Error` instances with plain `{ name, message, cause? }` objects so
-* an `xstate.error.actor` payload survives the log's JSON round-trip. A
-* decision-exhausted error also keeps its `code` and `attempts`. Cycles
+* Marks an object {@link normalizeEventErrors} made from an `Error`, so replay
+* restores that object, and only that one, as an `Error`: a thrown plain
+* `{ name, message }` stays a plain object.
+*/
+const NORMALIZED_ERROR_KEY = "@error";
+/**
+* Replaces `Error` instances with plain `{ name, message, code?, cause?,
+* "@error": true }` objects so an `xstate.error.actor` payload survives the
+* log's JSON round-trip. `code` is kept when it is a string or a number; a
+* decision-exhausted error also keeps its `attempts`. Replay turns the
+* object back into an `Error` (see `restoreJournaledEvent`). Cycles
 * are preserved by identity; non-plain objects are left alone (and are then
 * rejected by {@link assertJsonSerializable}).
 */
 function normalizeEventErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
-	if (value instanceof Error) {
+	if (isError(value)) {
 		const normalized = {
 			name: value.name,
-			message: value.message
+			message: value.message,
+			[NORMALIZED_ERROR_KEY]: true
 		};
 		seen.set(value, normalized);
 		if (value.cause !== void 0) normalized.cause = normalizeEventErrors(value.cause, seen);
-		if (value.code === DECISION_EXHAUSTED_CODE) {
-			normalized.code = DECISION_EXHAUSTED_CODE;
+		const code = value.code;
+		if (typeof code === "string" || typeof code === "number" && Number.isFinite(code)) normalized.code = code;
+		if (code === DECISION_EXHAUSTED_CODE) {
 			const attempts = exhaustedAttemptsOf(value);
 			if (attempts !== void 0) normalized.attempts = structuredClone(attempts);
 		}
@@ -1020,8 +1053,7 @@ function normalizeEventErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
 		for (const item of value) result.push(normalizeEventErrors(item, seen));
 		return result;
 	}
-	const prototype = Object.getPrototypeOf(value);
-	if (prototype !== Object.prototype && prototype !== null) return value;
+	if (!isPlainObject(value)) return value;
 	const result = {};
 	seen.set(value, result);
 	for (const [key, item] of Object.entries(value)) result[key] = normalizeEventErrors(item, seen);
@@ -1046,7 +1078,7 @@ function canonicalizeForHash(value, seen = /* @__PURE__ */ new WeakSet(), positi
 	if (typeof value === "symbol") return `[symbol:${String(value)}]`;
 	if (value === null || typeof value !== "object") return value;
 	if (value instanceof Date) return `[Date:${value.toISOString()}]`;
-	if (value instanceof Error) {
+	if (isError(value)) {
 		if (seen.has(value)) return "[circular]";
 		seen.add(value);
 		try {
@@ -1141,7 +1173,7 @@ function createReplayEntry(machine, entries, event, options = {}) {
 		recordedAt: options.recordedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 		machineId: machineIdOf(machine),
 		machineVersion,
-		event: normalizeDoneActorEvent(normalizeEventErrors(event)),
+		event: normalizeDoneActorEvent(pruneUndefined(normalizeEventErrors(event))),
 		...options.causationId !== void 0 ? { causationId: options.causationId } : {},
 		...options.metadata !== void 0 ? { metadata: options.metadata } : {},
 		...options.attempts !== void 0 && options.attempts.length > 0 ? { attempts: options.attempts } : {}
@@ -1154,15 +1186,23 @@ function createReplayEntry(machine, entries, event, options = {}) {
 	}).persistedSnapshot) };
 	return entry;
 }
-function pruneUndefined(value) {
-	if (Array.isArray(value)) return value.map(pruneUndefined);
+function pruneUndefined(value, ancestors = /* @__PURE__ */ new WeakSet()) {
 	if (value === null || typeof value !== "object") return value;
-	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return value;
+	if (ancestors.has(value)) return value;
+	if (Array.isArray(value)) {
+		ancestors.add(value);
+		const result = value.map((item) => pruneUndefined(item, ancestors));
+		ancestors.delete(value);
+		return result;
+	}
+	if (!isPlainObject(value)) return value;
+	ancestors.add(value);
 	const result = {};
 	for (const [key, child] of Object.entries(value)) {
 		if (child === void 0) continue;
-		result[key] = pruneUndefined(child);
+		result[key] = pruneUndefined(child, ancestors);
 	}
+	ancestors.delete(value);
 	return result;
 }
 /**
@@ -1359,12 +1399,33 @@ function rebindActorSession(event, snapshot, sessions) {
 		sessionId
 	};
 }
-function restoreDoneActorOutput(event) {
-	if (event.type !== DONE_ACTOR_EVENT_TYPE || Object.hasOwn(event, "output")) return event;
-	return {
+/**
+* The event as the machine received it live: a done event's dropped
+* `undefined` output restored, and an error event's normalized error turned
+* back into an `Error`, so `error instanceof Error` holds on replay too.
+*/
+function restoreJournaledEvent(event) {
+	if (event.type === DONE_ACTOR_EVENT_TYPE && !Object.hasOwn(event, "output")) return {
 		...event,
 		output: void 0
 	};
+	if (event.type.startsWith(ERROR_ACTOR_EVENT_TYPE)) {
+		const error = event.error;
+		if (isNormalizedError(error)) return {
+			...event,
+			error: toError(error)
+		};
+	}
+	return event;
+}
+function isNormalizedError(value) {
+	return isPlainObject(value) && value[NORMALIZED_ERROR_KEY] === true && typeof value.name === "string" && typeof value.message === "string";
+}
+function toError(normalized) {
+	const { name, message, cause, [NORMALIZED_ERROR_KEY]: _marker, ...rest } = normalized;
+	const error = new Error(message, cause === void 0 ? void 0 : { cause: isNormalizedError(cause) ? toError(cause) : cause });
+	error.name = name;
+	return Object.assign(error, rest);
 }
 function verifyEntry(entry, persisted, mode) {
 	if (mode === false) return;
@@ -1412,7 +1473,7 @@ function foldLog(machine, entries, options = {}) {
 	verifyEntry(entries[0], persisted, options.verify);
 	const sessions = /* @__PURE__ */ new Map();
 	const apply = (entry) => {
-		const event = restoreDoneActorOutput(rebindActorSession(entry.event, snapshot, sessions));
+		const event = restoreJournaledEvent(rebindActorSession(entry.event, snapshot, sessions));
 		[snapshot] = transition(machine, snapshot, event);
 		persisted = machine.getPersistedSnapshot(snapshot);
 		return persisted;
@@ -1490,4 +1551,4 @@ function recordLog(actor) {
 	};
 }
 //#endregion
-export { getStateMeta as $, createTextLogic as A, responseMessagesOf as B, AGENT_USAGE_EVENT_TYPE as C, STREAM_TEXT_ACTOR as D, GENERATE_TEXT_ACTOR as E, normalizeGeneratorResult as F, missingActor as G, getAgentExecutionOptions as H, parseOutput as I, findNonSerializableContextPaths as J, setAgentExecutionOptions as K, parseProviderOutput as L, getCallFinishReason as M, getCallUsage as N, bindRequestExecutor as O, isTextLogic as P, getMessageText as Q, providerOutputSchema as R, validateReplayEntries as S, DECIDE_ACTOR as T, getRegisteredAgentExecutionOptions as U, executorBoundLogics as V, isUnboundPlaceholder as W, getJsonSchemaSync as X, getJsonSchema as Y, getMachineStructuralHash as Z, getUsageFromEvents as _, AgentReplayDivergenceError as a, userMessage as at, recordLog as b, assertAgentLogEntry as c, AgentTruncatedError as ct, createReplayEntry as d, getStatePath as et, foldLog as f, getSnapshotStateHash as g, getLogExecutionId as h, AgentMachineVersionMismatchError as i, toolMessage as it, getAgentOutputMode as j, builtinTextActors as k, assertJsonSerializable as l, getDecisionAttempts as m, AGENT_INIT_EVENT_TYPE as n, resolveMachineVersion as nt, NonSerializableAgentEventError as o, validateSchemaSync as ot, forkEventLog as p, assistantMessage as q, AgentEventLogError as r, systemMessage as rt, agentCallOccurrence as s, AgentError as st, AGENT_EVENT_SCHEMA_VERSION as t, isStandardSchema as tt, canonicalEventJson as u, initEntry as v, AGENT_USAGE_TOKEN_FIELDS as w, replay as x, rebindActorSession as y, resolveTextLogicValue as z };
+export { getStateMeta as $, createTextLogic as A, responseMessagesOf as B, AGENT_USAGE_EVENT_TYPE as C, STREAM_TEXT_ACTOR as D, GENERATE_TEXT_ACTOR as E, normalizeGeneratorResult as F, missingActor as G, getAgentExecutionOptions as H, parseOutput as I, findNonSerializableContextPaths as J, setAgentExecutionOptions as K, parseProviderOutput as L, getCallFinishReason as M, getCallUsage as N, bindRequestExecutor as O, isTextLogic as P, getMessageText as Q, providerOutputSchema as R, validateReplayEntries as S, DECIDE_ACTOR as T, getRegisteredAgentExecutionOptions as U, executorBoundLogics as V, isUnboundPlaceholder as W, getJsonSchemaSync as X, getJsonSchema as Y, getMachineStructuralHash as Z, getUsageFromEvents as _, AgentReplayDivergenceError as a, userMessage as at, recordLog as b, assertAgentLogEntry as c, isPlainObject as ct, createReplayEntry as d, AgentTruncatedError as dt, getStatePath as et, foldLog as f, getSnapshotStateHash as g, getLogExecutionId as h, AgentMachineVersionMismatchError as i, toolMessage as it, getAgentOutputMode as j, builtinTextActors as k, assertJsonSerializable as l, isRecord as lt, getDecisionAttempts as m, AGENT_INIT_EVENT_TYPE as n, resolveMachineVersion as nt, NonSerializableAgentEventError as o, validateSchemaSync as ot, forkEventLog as p, assistantMessage as q, AgentEventLogError as r, systemMessage as rt, agentCallOccurrence as s, canonicalJson as st, AGENT_EVENT_SCHEMA_VERSION as t, isStandardSchema as tt, canonicalEventJson as u, AgentError as ut, initEntry as v, AGENT_USAGE_TOKEN_FIELDS as w, replay as x, rebindActorSession as y, resolveTextLogicValue as z };

package/dist/{event-log-store-bCdskPNS.cjs → event-log-store-BWMLi6oh.cjs}

@@ -1,4 +1,4 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
 //#region src/event-log-store.ts
 /**
 * Durable storage for {@link AgentLogEntry} logs: the one interface a host

package/dist/{event-log-store-yalq8C77.mjs → event-log-store-CCWdTPEP.mjs}

@@ -1,4 +1,4 @@
-import { c as assertAgentLogEntry, st as AgentError } from "./event-log-GPZO9p7_.mjs";
+import { c as assertAgentLogEntry, ut as AgentError } from "./event-log-DE430ZCa.mjs";
 //#region src/event-log-store.ts
 /**
 * Durable storage for {@link AgentLogEntry} logs: the one interface a host

package/dist/{event-log-store-CN9ygggF.d.cts → event-log-store-DTf_OzB-.d.cts}

@@ -1,4 +1,4 @@
-import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-9fv1i9aK.cjs";
+import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-j9hShB7d.cjs";
 import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
 //#region src/event-log.d.ts
 /** The durable entry envelope version. */

package/dist/{event-log-store-DS836wch.d.mts → event-log-store-RziIobdW.d.mts}

@@ -1,4 +1,4 @@
-import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-BDbGjYMh.mjs";
+import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-BwdrDpO9.mjs";
 import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
 //#region src/event-log.d.ts
 /** The durable entry envelope version. */

package/dist/index.cjs

@@ -1,9 +1,9 @@
 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_setup_agent = require("./setup-agent-DTF3NQg3.cjs");
-const require_event_log_store = require("./event-log-store-bCdskPNS.cjs");
-const require_run_agent = require("./run-agent-cToZ3K42.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
+const require_setup_agent = require("./setup-agent-D0L8Anl_.cjs");
+const require_event_log_store = require("./event-log-store-BWMLi6oh.cjs");
+const require_run_agent = require("./run-agent-tmk58M0x.cjs");
 let xstate = require("xstate");
 //#region src/messages.ts
 const KNOWN_PART_TYPES = /* @__PURE__ */ new Set([
@@ -168,7 +168,8 @@ function validateChoice(value, path) {
 * 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.
@@ -178,6 +179,8 @@ const interactionMetaSchema = { "~standard": {
 	vendor: "statelyai-agent",
 	validate(value) {
 		if (!value || typeof value !== "object" || Array.isArray(value)) return { issues: [{ message: "Expected a state meta object" }] };
+		const actor = value["actor"];
+		if (actor !== void 0 && actor !== "human") return { issues: [issue("Expected \"human\"", ["actor"])] };
 		const interaction = value["interaction"];
 		if (interaction === void 0) return { value };
 		if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) return { issues: [issue("Expected an interaction descriptor object", ["interaction"])] };
@@ -452,13 +455,44 @@ function guardText(guard) {
 	if (isObject(decoded) && typeof decoded.type === "string") return decoded.type.startsWith("__fromConfigGuard") ? "guarded" : decoded.type;
 	return "guarded";
 }
-/** True when a transition function's source has a path that returns no transition, so it may not be taken. */
-const mayDecline = (code) => /\bundefined\b|\bnull\b|\breturn\s*;|\bif\s*\(|\s\?\s|&&/.test(code);
+/**
+* True when a transition function's source has a path that returns no
+* transition, so it may not be taken. Matches minified source too: `void 0`
+* for `undefined`, and a ternary `?` with no spaces (but not `?.` or `??`).
+* String and template literals are blanked first, so their text never counts.
+*/
+const mayDecline = (code) => /\bundefined\b|\bnull\b|\bvoid 0\b|\breturn\s*;|\bif\s*\(|(?<!\?)\?(?![.?])|&&/.test(code.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, "\"\""));
+/**
+* True when the function returns a call's result (`=> next(ctx)`, `return
+* pick(x)`), so its target is not in its own source. Reads only the
+* function's own returned expressions, not those of callbacks nested in it.
+*/
+function returnsCall(code) {
+	const text = code.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, "\"\"");
+	const startsWithCall = (at) => /^[\s(]*[A-Za-z_$][\w$.]*\s*\(/.test(text.slice(at));
+	let parens = 0;
+	let body = -1;
+	for (let i = 0; i < text.length && body < 0; i++) {
+		const char = text[i];
+		if (char === "(") parens++;
+		else if (char === ")") parens--;
+		else if (parens === 0 && char === "=" && text[i + 1] === ">") body = i + 2;
+		else if (parens === 0 && char === "{") body = i;
+	}
+	if (body < 0) return false;
+	while (/\s/.test(text[body] ?? "")) body++;
+	if (text[body] !== "{") return startsWithCall(body);
+	let depth = 0;
+	for (let i = body; i < text.length; i++) if (text[i] === "{") depth++;
+	else if (text[i] === "}" && --depth === 0) return false;
+	else if (depth === 1 && text.startsWith("return", i) && !/[\w$]/.test(text[i - 1] ?? "") && !/[\w$]/.test(text[i + 6] ?? "") && startsWithCall(i + 6)) return true;
+	return false;
+}
 /**
 * Where a transition written as a function goes: every string literal after a
 * `target:` that names a real state node, `(conditional)` when it may decline
 * or pick among several, `(stays)` when its source has no `target`, `?` when
-* it names none that resolves.
+* it names none that resolves or returns a helper call's result.
 */
 function targetsInSource(source, code, choice) {
 	const found = /* @__PURE__ */ new Set();
@@ -471,14 +505,15 @@ function targetsInSource(source, code, choice) {
 		const conditional = names.length > 1 || !choice && mayDecline(code);
 		return `${names.join(", ")}${conditional ? " (conditional)" : ""}`;
 	}
-	return /\btarget\s*:/.test(code) ? "?" : "(stays)";
+	return /\btarget\s*:/.test(code) || returnsCall(code) ? "?" : "(stays)";
 }
-/** One transition, as a line: `on GO if context.ready → review; sets draft — description`. */
+/** One transition, as a line: `on GO (human) if context.ready → review; sets draft — description`. */
 function transitionLine(source, head, transition, options = {}) {
 	const code = codeOf(transition);
 	let to;
 	let guard;
 	let description;
+	let human = false;
 	let sets;
 	if (typeof transition === "string") {
 		const node = resolveTarget(source, transition);
@@ -495,12 +530,13 @@ function transitionLine(source, head, transition, options = {}) {
 		}).join(", ") : "(stays)";
 		guard = guardText(transition[options.guardKey ?? "guard"]);
 		description = typeof transition.description === "string" ? transition.description : void 0;
+		human = isObject(transition.meta) && transition.meta.actor === "human";
 		sets = contextKeys(transition, void 0);
 	} else {
 		to = "?";
 		sets = [];
 	}
-	return `${head}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` — ${oneLine(description)}` : ""}`;
+	return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` — ${oneLine(description)}` : ""}`;
 }
 function formatMs(ms) {
 	if (ms < 1e3) return `${ms}ms`;
@@ -547,7 +583,7 @@ function stateLine(node, json) {
 	else if (node.type === "compound" && typeof json.initial === "string") marker = ` (initial: ${json.initial})`;
 	const tags = node.tags.length ? ` [tags: ${node.tags.join(", ")}]` : "";
 	const interaction = node.meta?.interaction;
-	const label = typeof interaction?.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : "";
+	const label = !interaction ? "" : typeof interaction.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : typeof interaction.label === "function" ? " [interaction: computed label]" : " [interaction]";
 	const description = node.description ? ` — ${oneLine(node.description)}` : "";
 	return `${node.key}${marker}${tags}${label}${description}`;
 }
@@ -584,9 +620,10 @@ function eventLines(machine) {
 * label and description (`*` marks the active ones when `snapshot` is given),
 * and under it every transition leaving it, one per line: `on EVENT`,
 * `always`, `after <delay>`, invoke `done`/`error`, and `choice` branches,
-* each with its guard (`if …`), where it goes (`→ review`), and what it sets
-* in context (`sets draft, attempts`). An `Events` section lists the
-* machine's event schemas with their descriptions and fields.
+* each with `(human)` when its `meta.actor` is `"human"`, its guard (`if …`),
+* where it goes (`→ review`), and what it sets in context (`sets draft,
+* attempts`). An `Events` section lists the machine's event schemas with their
+* descriptions and fields.
 *
 * A transition written as a function shows the targets its source names
 * (`→ review (conditional)` when it may decline or pick among several),
@@ -630,7 +667,8 @@ function describeMachine(machine, options = {}) {
 * Asks a model to choose the next event for ANY XState snapshot, including a
 * machine built with plain `createMachine`/`setup` that knows nothing about AI.
 * The candidates are the `allowedEvents` an active state handles, one option per
-* payload, kept only where `snapshot.can(event)` is true; the rest come back as
+* payload, kept only where `snapshot.can(event)` is true and no transition
+* tagged `meta: { actor: "human" }` handles the type; the rest come back as
 * `withheld`. Each option is
 * described from the transition's `description`, else the event schema's,
 * plus (with `lookahead`) what it changes. The chosen event must equal one
@@ -665,19 +703,21 @@ function describeMachine(machine, options = {}) {
 async function decideNext(snapshot, options) {
 	const patterns = typeof options.allowedEvents === "string" ? [options.allowedEvents] : options.allowedEvents;
 	const schemas = snapshot.machine.schemas?.events;
-	const events = require_decision.getAcceptedEvents(snapshot, {
+	const candidates = require_decision.getAcceptedEvents(snapshot, {
 		events: schemas,
 		eventTypes: patterns
 	}).filter((event) => !require_decision.isEventPattern(event.type));
+	const humanEventTypes = require_decision.getHumanEventTypes(snapshot);
+	const events = candidates.filter((event) => !humanEventTypes.has(event.type));
 	const payloads = options.payloads?.(snapshot) ?? {};
 	const accepted = [];
 	const withheld = [];
-	for (const { type } of events) for (const payload of payloads[type] ?? [{}]) {
+	for (const { type } of candidates) for (const payload of payloads[type] ?? [{}]) {
 		const event = {
 			...payload,
 			type
 		};
-		(safeCan(snapshot, event) ? accepted : withheld).push(event);
+		(!humanEventTypes.has(type) && safeCan(snapshot, event) ? accepted : withheld).push(event);
 	}
 	const offered = accepted.map((event) => ({
 		event,
@@ -737,7 +777,7 @@ function schemaDescription(schema) {
 	if (typeof direct === "string") return direct;
 	try {
 		const json = schema["~standard"].jsonSchema?.input?.({ target: "draft-2020-12" });
-		return require_decision.isRecord(json) && typeof json.description === "string" ? json.description : void 0;
+		return require_event_log.isRecord(json) && typeof json.description === "string" ? json.description : void 0;
 	} catch {
 		return;
 	}
@@ -752,8 +792,8 @@ function describeEffect(snapshot, event, keys) {
 	}
 	const changes = [];
 	if (require_event_log.canonicalEventJson(snapshot.value) !== require_event_log.canonicalEventJson(next.value)) changes.push(`state: ${short(snapshot.value, maxLength)} → ${short(next.value, maxLength)}`);
-	const before = require_decision.isRecord(snapshot.context) ? snapshot.context : {};
-	const after = require_decision.isRecord(next.context) ? next.context : {};
+	const before = require_event_log.isRecord(snapshot.context) ? snapshot.context : {};
+	const after = require_event_log.isRecord(next.context) ? next.context : {};
 	for (const key of keys ?? /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) if (require_event_log.canonicalEventJson(before[key]) !== require_event_log.canonicalEventJson(after[key])) changes.push(`${key}: ${short(before[key], maxLength)} → ${short(after[key], maxLength)}`);
 	return changes.length ? changes.join("; ") : "nothing changes";
 }
@@ -767,6 +807,78 @@ function short(value, max = 60) {
 	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 //#endregion
+//#region src/policy-decider.ts
+/**
+* Runs a policy machine as a decide executor: each decision request starts one
+* run of `policy`, and its output is the chosen event. The policy can answer
+* with a rule (a `choice` over the facts, no model call) and invoke
+* `agent.decide` for the rest, answered by `options.executors`.
+*
+* The environment still judges the event: one it does not accept is retried
+* like any other decider's choice. The policy's input must be JSON (it opens
+* the policy run's event log): the default drops keys whose value is
+* `undefined`, and any other value that is not JSON throws before the run. The policy's token usage is reported on the
+* result, and left out when the policy made no model call. A run that does not
+* end `done` with an event throws `AgentError` with code `policy-not-done`.
+*
+* @example
+* ```ts no-check
+* const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
+* await runAgent(deskMachine, { input, executors: { ...modelExecutors, decide } });
+* ```
+*/
+function createPolicyDecider(policy, options = {}) {
+	const { input = defaultInput, threadId, ...runOptions } = options;
+	const id = policy.config.id ?? policy.id;
+	return async (request, info) => {
+		const policyInput = input(request);
+		require_event_log.assertJsonSerializable(policyInput, "policy input");
+		const thread = runOptions.store === void 0 ? void 0 : await policyThread(request, policyInput, info);
+		const result = await require_run_agent.runAgent(policy, {
+			...runOptions,
+			input: policyInput,
+			...thread === void 0 ? {} : { threadId: thread },
+			...info?.signal ? { signal: info.signal } : {}
+		});
+		if (result.status !== "done") {
+			const why = result.status === "error" ? `: ${String(result.error)}` : "";
+			throw new require_event_log.AgentError("policy-not-done", `policy '${id}' settled '${result.status}'${why}`, { cause: result.status === "error" ? result.error : void 0 });
+		}
+		const event = result.output;
+		if (!require_event_log.isRecord(event) || typeof event.type !== "string") throw new require_event_log.AgentError("policy-not-done", `policy '${id}' output is not an event: ${JSON.stringify(event)}`);
+		const { modelCalls, ...usage } = result.usage;
+		return {
+			event,
+			...modelCalls > 0 ? { usage } : {}
+		};
+	};
+	async function policyThread(request, policyInput, info) {
+		if (threadId) return threadId(request, info);
+		if (info?.callKey) return `policy:${info.callKey}:${await sha256(require_event_log.canonicalEventJson(policyInput))}`;
+		throw new require_event_log.AgentError("missing-thread-id", `policy '${id}' has a store but no threadId, and the decision came with no callKey to derive one from`);
+	}
+}
+function defaultInput(request) {
+	const facts = request.metadata?.facts;
+	return withoutUndefinedKeys({
+		facts,
+		options: (request.options ?? []).map((option) => option.event),
+		system: request.system,
+		prompt: request.prompt
+	});
+}
+/** A copy of `value` with every object key whose value is `undefined` removed, at any depth. */
+function withoutUndefinedKeys(value) {
+	if (Array.isArray(value)) return value.map(withoutUndefinedKeys);
+	if (!require_event_log.isRecord(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return value;
+	return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, withoutUndefinedKeys(child)]));
+}
+/** Hex SHA-256 of `text`, with Web Crypto (Node, browsers, workers). */
+async function sha256(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
 //#region src/provide-executors.ts
 /**
 * Binds a machine's agent actor sources to a set of host `executors` in one
@@ -896,6 +1008,7 @@ exports.createAgentRuntime = require_run_agent.createAgentRuntime;
 exports.createAgentSchemas = require_setup_agent.createAgentSchemas;
 exports.createDecisionLogic = require_decision.createDecisionLogic;
 exports.createDecisionRequest = require_decision.createDecisionRequest;
+exports.createPolicyDecider = createPolicyDecider;
 exports.createTextLogic = require_event_log.createTextLogic;
 exports.decideNext = decideNext;
 exports.describeMachine = describeMachine;