@statelyai/agent 2.0.0-alpha.30 → 2.0.0-alpha.32

package/dist/{event-log-DJCMHek_.mjs → event-log-DAqsalT1.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;
@@ -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;
 }
 /**
@@ -1199,8 +1239,8 @@ function isSnapshotInitEntry(entry) {
 * Minted once per run and inherited verbatim by every resume of that log, so
 * it names one lineage rather than one process. Entry ids cannot serve this
 * role — the built-in ids are index-derived, so every log's init entry is
-* `evt_00000000`. A fork copies the init entry, so it shares its parent's
-* execution id by construction.
+* `evt_00000000`. A fork ({@link forkEventLog}, `store.fork`) mints its own
+* and records the parent's in `metadata.forkedFrom`.
 *
 * Returns `undefined` for a log with no init entry and for one written without
 * the field — callers must treat the id as optional.
@@ -1248,12 +1288,31 @@ function validateReplayEntries(entries, options = {}) {
 /**
 * The prefix `[0, upToIndex)` of a log, as a new log. `upToIndex` is exclusive
 * and must leave the init entry in place, so the fork is still self-contained.
+*
+* The fork is its own lineage: its init entry gets a fresh
+* `metadata.executionId` and `metadata.forkedFrom: { executionId?, logIndex }`:
+* the cutoff, and the parent's id when it had one. Call keys derive
+* from the execution id, so a fork's calls never collide with its parent's.
+* Every other entry is copied as is.
 */
 function forkEventLog(entries, upToIndex) {
 	if (!Number.isInteger(upToIndex) || upToIndex < 1 || upToIndex > entries.length) throw new AgentEventLogError(`forkEventLog: upToIndex must be an integer in [1, ${entries.length}]; got ${String(upToIndex)}.`);
 	const forked = entries.slice(0, upToIndex);
 	if (!isInitEntry(forked[0])) throw new AgentEventLogError(`forkEventLog: the forked prefix must start with the reserved '${AGENT_INIT_EVENT_TYPE}' entry.`);
-	return forked;
+	const [init, ...rest] = forked;
+	const parentExecutionId = getLogExecutionId(forked);
+	const forkedFrom = {
+		...parentExecutionId !== void 0 ? { executionId: parentExecutionId } : {},
+		logIndex: upToIndex
+	};
+	return [{
+		...init,
+		metadata: {
+			...init.metadata,
+			executionId: crypto.randomUUID(),
+			forkedFrom
+		}
+	}, ...rest];
 }
 const DONE_ACTOR_EVENT_TYPE = "xstate.done.actor";
 const ERROR_ACTOR_EVENT_TYPE = "xstate.error.actor";
@@ -1359,12 +1418,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 +1492,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 +1570,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-DsP6GCRh.mjs → event-log-store-BGehvVTb.mjs}

@@ -1,4 +1,4 @@
-import { c as assertAgentLogEntry, st as AgentError } from "./event-log-DJCMHek_.mjs";
+import { c as assertAgentLogEntry, p as forkEventLog, ut as AgentError } from "./event-log-DAqsalT1.mjs";
 //#region src/event-log-store.ts
 /**
 * Durable storage for {@link AgentLogEntry} logs: the one interface a host
@@ -65,7 +65,7 @@ function createInMemoryEventLogStore() {
 			if (!source) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
 			const upTo = upToIndex ?? source.length;
 			if (!Number.isInteger(upTo) || upTo < 1 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: upToIndex must be an integer in [1, ${source.length}] on thread "${threadId}"; got ${String(upTo)}.`);
-			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
+			threads.set(newThreadId, forkEventLog(source, upTo).map((entry) => clone(entry)));
 		},
 		async listThreads(options = {}) {
 			const { prefix = "", limit, cursor } = options;

package/dist/{event-log-store-CIIJohjj.d.mts → event-log-store-C2NjVlWU.d.mts}

@@ -1,4 +1,4 @@
-import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-BRYOPWvY.mjs";
+import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-DuK9HIFM.mjs";
 import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
 //#region src/event-log.d.ts
 /** The durable entry envelope version. */
@@ -186,8 +186,8 @@ declare function initEntry(machine: AnyStateMachine, init?: AgentLogInit, option
  * Minted once per run and inherited verbatim by every resume of that log, so
  * it names one lineage rather than one process. Entry ids cannot serve this
  * role — the built-in ids are index-derived, so every log's init entry is
- * `evt_00000000`. A fork copies the init entry, so it shares its parent's
- * execution id by construction.
+ * `evt_00000000`. A fork ({@link forkEventLog}, `store.fork`) mints its own
+ * and records the parent's in `metadata.forkedFrom`.
  *
  * Returns `undefined` for a log with no init entry and for one written without
  * the field — callers must treat the id as optional.
@@ -210,6 +210,12 @@ declare function validateReplayEntries(entries: readonly AgentLogEntry[], option
 /**
  * The prefix `[0, upToIndex)` of a log, as a new log. `upToIndex` is exclusive
  * and must leave the init entry in place, so the fork is still self-contained.
+ *
+ * The fork is its own lineage: its init entry gets a fresh
+ * `metadata.executionId` and `metadata.forkedFrom: { executionId?, logIndex }`:
+ * the cutoff, and the parent's id when it had one. Call keys derive
+ * from the execution id, so a fork's calls never collide with its parent's.
+ * Every other entry is copied as is.
  */
 declare function forkEventLog(entries: readonly AgentLogEntry[], upToIndex: number): AgentLogEntry[];
 /**
@@ -380,8 +386,10 @@ interface AgentEventLogStore {
    * init entry and stays a self-contained log. The fork then appends
    * independently. Rejects (plain `Error`) if `newThreadId` already has
    * entries, the source is unknown, or `upToIndex` is out of range.
-   * Implementations may copy-on-write or physically copy; observable behavior
-   * must match a full copy.
+   *
+   * The fork is its own lineage: store what {@link forkEventLog} returns for
+   * the prefix, whose init entry carries a fresh `metadata.executionId` and
+   * `metadata.forkedFrom`. Every other entry must match the source.
    */
   fork(input: {
     threadId: string;

package/dist/{event-log-store-DZR4IIWe.cjs → event-log-store-DKyE7JKr.cjs}

@@ -1,4 +1,4 @@
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
+const require_event_log = require("./event-log-CKWeC7H-.cjs");
 //#region src/event-log-store.ts
 /**
 * Durable storage for {@link AgentLogEntry} logs: the one interface a host
@@ -65,7 +65,7 @@ function createInMemoryEventLogStore() {
 			if (!source) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
 			const upTo = upToIndex ?? source.length;
 			if (!Number.isInteger(upTo) || upTo < 1 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: upToIndex must be an integer in [1, ${source.length}] on thread "${threadId}"; got ${String(upTo)}.`);
-			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
+			threads.set(newThreadId, require_event_log.forkEventLog(source, upTo).map((entry) => clone(entry)));
 		},
 		async listThreads(options = {}) {
 			const { prefix = "", limit, cursor } = options;

package/dist/{event-log-store-CLAC9q2Y.d.cts → event-log-store-s73r1Hxf.d.cts}

@@ -1,4 +1,4 @@
-import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-DmciuVUQ.cjs";
+import { I as DecisionAttempt, Q as AgentError, t as AgentCallUsage } from "./text-logic-CYP502VT.cjs";
 import { Actor, AnyMachineSnapshot, AnyStateMachine, EventObject, Snapshot, SnapshotFrom } from "xstate";
 //#region src/event-log.d.ts
 /** The durable entry envelope version. */
@@ -186,8 +186,8 @@ declare function initEntry(machine: AnyStateMachine, init?: AgentLogInit, option
  * Minted once per run and inherited verbatim by every resume of that log, so
  * it names one lineage rather than one process. Entry ids cannot serve this
  * role — the built-in ids are index-derived, so every log's init entry is
- * `evt_00000000`. A fork copies the init entry, so it shares its parent's
- * execution id by construction.
+ * `evt_00000000`. A fork ({@link forkEventLog}, `store.fork`) mints its own
+ * and records the parent's in `metadata.forkedFrom`.
  *
  * Returns `undefined` for a log with no init entry and for one written without
  * the field — callers must treat the id as optional.
@@ -210,6 +210,12 @@ declare function validateReplayEntries(entries: readonly AgentLogEntry[], option
 /**
  * The prefix `[0, upToIndex)` of a log, as a new log. `upToIndex` is exclusive
  * and must leave the init entry in place, so the fork is still self-contained.
+ *
+ * The fork is its own lineage: its init entry gets a fresh
+ * `metadata.executionId` and `metadata.forkedFrom: { executionId?, logIndex }`:
+ * the cutoff, and the parent's id when it had one. Call keys derive
+ * from the execution id, so a fork's calls never collide with its parent's.
+ * Every other entry is copied as is.
  */
 declare function forkEventLog(entries: readonly AgentLogEntry[], upToIndex: number): AgentLogEntry[];
 /**
@@ -380,8 +386,10 @@ interface AgentEventLogStore {
    * init entry and stays a self-contained log. The fork then appends
    * independently. Rejects (plain `Error`) if `newThreadId` already has
    * entries, the source is unknown, or `upToIndex` is out of range.
-   * Implementations may copy-on-write or physically copy; observable behavior
-   * must match a full copy.
+   *
+   * The fork is its own lineage: store what {@link forkEventLog} returns for
+   * the prefix, whose init entry carries a fresh `metadata.executionId` and
+   * `metadata.forkedFrom`. Every other entry must match the source.
    */
   fork(input: {
     threadId: string;

package/dist/index.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_decision = require("./decision-CIb7ddIv.cjs");
-const require_setup_agent = require("./setup-agent-DoUk7EdC.cjs");
-const require_event_log_store = require("./event-log-store-DZR4IIWe.cjs");
-const require_run_agent = require("./run-agent-ctLCvNgL.cjs");
+const require_event_log = require("./event-log-CKWeC7H-.cjs");
+const require_decision = require("./decision-BPdEaxPf.cjs");
+const require_setup_agent = require("./setup-agent-CwUJyqKB.cjs");
+const require_event_log_store = require("./event-log-store-DKyE7JKr.cjs");
+const require_run_agent = require("./run-agent-Cg0xd3K-.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"])] };
@@ -460,10 +463,36 @@ function guardText(guard) {
 */
 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();
@@ -476,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);
@@ -500,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`;
@@ -552,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}`;
 }
@@ -589,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),
@@ -635,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
@@ -670,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,
@@ -742,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;
 	}
@@ -757,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";
 }
@@ -772,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
@@ -901,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;