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

package/dist/verify-B5qGC5WN.mjs

@@ -0,0 +1,1181 @@
+import { P as isTextLogic, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, X as getJsonSchemaSync, st as AgentError } from "./event-log-GPZO9p7_.mjs";
+import { d as getAcceptedEvents, l as resolveDecision, m as isRecord, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-Bl_rKQnU.mjs";
+import { getNextTransitions, initialTransition, transition } from "xstate";
+//#region src/steps.ts
+/**
+* Internal: the pure `(state, event) => (nextState, requests)` view of an
+* agent machine, used by model-free simulation (`simulateAgent`) and tests.
+* An {@link AgentStep} is a snapshot plus the model requests the machine is
+* now waiting on; nothing here executes anything. Hosts use
+* `createAgentRuntime`.
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* The invokes a snapshot is still waiting on, lowered to the same spawn-effect
+* shape {@link getAgentRequests} reads. Derived from the snapshot's live
+* children rather than the last transition's actions, so a state that invokes
+* several actors at once (an `invoke: [...]` array, or parallel regions each
+* invoking) keeps reporting the siblings after the first one settles —
+* including when the settled invoke's `onDone` is targetless and starts
+* nothing new.
+*
+* Entries are ordered by invoke id, so a walker that resolves one invoke per
+* step is deterministic.
+*
+* @internal
+*/
+function getPendingInvokes(snapshot) {
+	const children = snapshot.children ?? {};
+	return Object.keys(children).sort().flatMap((id) => {
+		const child = children[id];
+		const childSnapshot = child?.getSnapshot?.();
+		if (!child || childSnapshot?.status !== "active") return [];
+		return [{
+			type: "@xstate.spawn",
+			id,
+			src: child.src,
+			input: childSnapshot.input,
+			logic: child.logic
+		}];
+	});
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. Pass `options.machine` to
+* pre-fill `schemas`/`actors` from the machine's registered `setupAgent`
+* options instead of passing them by hand.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequests(actions, { machine, ...options } = {}) {
+	if (machine) options = {
+		...getRegisteredAgentExecutionOptions(machine),
+		...options
+	};
+	return actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	});
+}
+/**
+* Builds the canonical `xstate.done.actor` event xstate's `transition()`
+* expects to resolve a spawned invoke — including the child session identity
+* that rejects a stale completion from an earlier incarnation.
+*
+* @internal
+*/
+function doneEvent(snapshot, request, output) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.done.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		output
+	};
+}
+/**
+* The `xstate.error.actor` counterpart of {@link doneEvent} — the event a
+* failed invoke delivers, which `onError` transitions observe. Carries the
+* same child session identity, so xstate does not discard it as stale.
+*
+* @internal
+*/
+function errorEvent(snapshot, request, error) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.error.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		error
+	};
+}
+/**
+* Applies a request's `output` as a done event (or, with `outcome: 'error'`,
+* its `output` as the invoke's error) via `transition(...)`, returning the raw
+* `[snapshot, actions]` tuple. Lower-level than {@link resolveAgentStep} /
+* {@link rejectAgentStep} — those helpers wrap this and also run
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output, outcome = "output") {
+	const event = outcome === "error" ? errorEvent(snapshot, request, output) : doneEvent(snapshot, request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const snapshot = isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep;
+	const [nextSnapshot, actions] = transition(machine, snapshot, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Rejects a pending invoke — the failure counterpart of
+* {@link resolveAgentStep}. Delivers `error` as the invoke's
+* `xstate.error.actor` event, so the machine takes that invoke's `onError`
+* transition and returns the next {@link AgentStep}. With no `onError` in
+* scope the returned step's snapshot has `status: 'error'`, exactly as a live
+* run's failed invoke does.
+*
+* A durable host replays a failed call with this: the log says the call
+* failed, so the replay rejects the invoke instead of resolving it. Scripted
+* playthroughs use it too — see `simulateAgent`'s `script.errors`.
+*
+* `error` can be any value. An `Error` instance is the usual one, but a plain
+* object (`{ code: 'truncated' }`) reaches the `onError` transition as
+* `event.error` untouched, so a machine that branches on a failure code is
+* testable without constructing a provider's error class.
+*/
+function rejectAgentStep(machine, step, request, error, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, error, "error");
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequests(getPendingInvokes(snapshot), {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+//#region src/verify.ts
+/**
+* Provider-free verification for agent machines — static lint checks plus
+* model-free simulation over the pure step path. Coding agents generate these
+* machines; this module lets them close the loop and self-verify WITHOUT any
+* API keys or model calls.
+*
+* - {@link lintAgentMachine} — static structural checks over a built machine
+*   (works for TS-authored and `setupAgent.fromConfig`-compiled machines).
+* - {@link simulateAgent} — a deterministic, scripted playthrough.
+* - {@link explorePaths} — enumerates decision/external branches to a bounded
+*   depth and reports reached states and terminal outcomes.
+* - {@link canReach} — a thin wrapper over {@link explorePaths} answering
+*   "can this state (or snapshot predicate) be reached?" with a witness path.
+*
+* @module
+*/
+const DECIDE_SRC = "agent.decide";
+function normalizeInvokes(invoke) {
+	if (invoke === void 0 || invoke === null) return [];
+	return Array.isArray(invoke) ? invoke : [invoke];
+}
+function buildStateIndex(rootConfig) {
+	const index = /* @__PURE__ */ new Map();
+	const walk = (states, parentPath) => {
+		for (const [name, config] of Object.entries(states ?? {})) {
+			const path = parentPath ? `${parentPath}.${name}` : name;
+			const hasChildren = !!config.states && Object.keys(config.states).length > 0;
+			index.set(path, {
+				path,
+				config,
+				parentPath,
+				isFinal: config.type === "final",
+				isParallel: config.type === "parallel",
+				isCompound: hasChildren && config.type !== "parallel",
+				invokes: normalizeInvokes(config.invoke)
+			});
+			if (hasChildren) walk(config.states, path);
+		}
+	};
+	walk(rootConfig.states, "");
+	return index;
+}
+function ancestorChain(node, index) {
+	const chain = [];
+	let parent = node.parentPath;
+	while (parent) {
+		const parentNode = index.get(parent);
+		if (!parentNode) break;
+		chain.push(parentNode);
+		parent = parentNode.parentPath;
+	}
+	return chain;
+}
+function hasNonEmptyOn(config) {
+	return !!config.on && Object.keys(config.on).length > 0;
+}
+function isDecisionInvoke(src, actors) {
+	if (typeof src === "string") return src === DECIDE_SRC || isDecisionLogic(actors[src]);
+	return isDecisionLogic(src);
+}
+function isAgentLogicNeedingBinding(src) {
+	return (isTextLogic(src) || isDecisionLogic(src)) && !executorBoundLogics.has(src);
+}
+function safeJsonSchema(schema) {
+	try {
+		return getJsonSchemaSync(schema);
+	} catch {
+		return;
+	}
+}
+function checkDecideWithoutEvents(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		if (!isDecisionInvoke(invoke.src, ctx.actors)) continue;
+		const selfHandles = hasNonEmptyOn(node.config);
+		const ancestorHandles = ancestorChain(node, ctx.index).some((ancestor) => hasNonEmptyOn(ancestor.config));
+		const invokeObserves = invoke.onDone !== void 0;
+		if (selfHandles || ancestorHandles || invokeObserves) continue;
+		const srcName = typeof invoke.src === "string" ? invoke.src : "(inline logic)";
+		out.push({
+			code: "decide-without-events",
+			severity: "error",
+			path: node.path,
+			message: `State '${node.path}' invokes decision source '${srcName}', but neither it nor any ancestor handles any event (no 'on:'), so the decision's chosen event can never be delivered. Add an 'on:' handler for the candidate events.`
+		});
+	}
+	return out;
+}
+function checkDirectObjectSrc(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		const src = invoke.src;
+		if (typeof src === "string" || !src || typeof src !== "object") continue;
+		if (!isAgentLogicNeedingBinding(src)) continue;
+		out.push({
+			code: "direct-object-src",
+			severity: "warning",
+			path: node.path,
+			message: `State '${node.path}' invokes a direct-object agent logic. Direct-object invoke srcs cannot be rebound by the agent runtime, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actors: { name: logic } })) and invoke it by name.`
+		});
+	}
+	return out;
+}
+function handlesActorError(config) {
+	if (config["onError"] !== void 0) return true;
+	return Object.keys(config.on ?? {}).some((type) => type === "*" || type.startsWith("xstate.error"));
+}
+function checkInvokeWithoutOnError(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		if (invoke.onError !== void 0 || handlesActorError(node.config)) continue;
+		if (handlesActorError(ctx.config) || ancestorChain(node, ctx.index).some((ancestor) => handlesActorError(ancestor.config))) continue;
+		const srcName = typeof invoke.src === "string" ? invoke.src : "(inline logic)";
+		out.push({
+			code: "invoke-without-on-error",
+			severity: "warning",
+			path: node.path,
+			message: `State '${node.path}' invokes '${srcName}' with no 'onError' transition, and no ancestor handles an actor error. A rejected request or actor puts the machine in an error state with no modeled recovery. Add 'onError' (a 'failed' final state, or a bounded retry).`
+		});
+	}
+	return out;
+}
+const LINT_CHECKS = [
+	checkDecideWithoutEvents,
+	checkDirectObjectSrc,
+	checkInvokeWithoutOnError
+];
+/**
+* Runs static structural checks over a built agent machine and returns the
+* findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+* TS-authored (`setupAgent(...).createMachine(...)`) and
+* `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+* plus the schemas/actor sources the library already retains per machine.
+*
+* No model calls, no API keys — a coding agent that emits an agent machine can
+* call this to catch agent-specific mistakes such as undeliverable decisions,
+* un-rebindable request sources, and an unhandled transcript event. General
+* state-machine lint belongs to XState tooling.
+*
+* Pass `{ throw: true }` for the one-liner form used in tests and generation
+* loops: it returns silently when the machine is clean and throws
+* {@link AgentLintError} (findings on `.diagnostics`) on error-severity
+* findings, or on warnings too with `{ throw: true, warnings: true }`.
+*
+* @example
+* ```ts
+* const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+* if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+* ```
+*
+* @example Throwing form
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   lintAgentMachine(machine, { throw: true });
+* });
+* ```
+*/
+function lintAgentMachine(machine, options = {}) {
+	const config = machine.config ?? {};
+	const index = buildStateIndex(config);
+	const registered = getRegisteredAgentExecutionOptions(machine);
+	const ctx = {
+		config,
+		index,
+		schemas: registered.schemas,
+		actors: registered.actors ?? machine.sources?.actors ?? {}
+	};
+	const disabled = new Set(options.disable ?? []);
+	const diagnostics = LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+	if (options.throw) {
+		const failing = options.warnings ? diagnostics : diagnostics.filter((d) => d.severity === "error");
+		if (failing.length > 0) throw new AgentLintError(machine.id ?? "(machine)", failing);
+	}
+	return diagnostics;
+}
+/**
+* Thrown by `lintAgentMachine(machine, { throw: true })` (and its
+* {@link assertAgentMachine} alias) when lint finds failing diagnostics.
+* `diagnostics` holds the findings; the message lists them one per finding,
+* so a test runner's failure output reads like the CLI's lint report.
+*/
+var AgentLintError = class extends AgentError {
+	diagnostics;
+	constructor(machineId, diagnostics) {
+		const lines = diagnostics.map((d) => `  ${d.severity === "error" ? "error" : "warn "}  ${d.code}  ${d.path}\n         ${d.message}`);
+		super("lint-failed", `Agent machine '${machineId}' failed lint (${diagnostics.length} finding(s)):\n${lines.join("\n")}`);
+		this.name = "AgentLintError";
+		this.diagnostics = diagnostics;
+	}
+};
+/**
+* Asserts a machine passes {@link lintAgentMachine}: returns silently when
+* clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+* otherwise — sugar for `lintAgentMachine(machine, { ...options, throw: true })`.
+* Fails on error-severity findings; set `warnings: true` to fail on warnings
+* too. The one-liner for tests and generation loops:
+*
+* @example
+* ```ts
+* test('agent machine is structurally sound', () => {
+*   assertAgentMachine(machine);
+* });
+* ```
+*/
+function assertAgentMachine(machine, options = {}) {
+	lintAgentMachine(machine, {
+		...options,
+		throw: true
+	});
+}
+function pendingInvokes(step) {
+	const out = [];
+	for (const metadata of getPendingInvokes(step.snapshot)) if (typeof metadata.src === "string") out.push({
+		id: metadata.id,
+		src: metadata.src
+	});
+	return out;
+}
+function takeFromQueue(channel, src) {
+	const queue = channel?.[src];
+	if (queue && queue.length > 0) return {
+		found: true,
+		value: queue.shift()
+	};
+	return { found: false };
+}
+/**
+* Deterministically plays a machine through, resolving each request from a
+* {@link SimulationScript} instead of a model — no API keys, no model calls.
+* Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+* the real transition logic. Returns the terminal `status`, final `snapshot`,
+* and a `trail` of every step taken.
+*
+* Decisions run through the live run's own validation/retry core,
+* {@link resolveDecision}, with the script standing in for the model: each
+* attempt consumes the next queued {@link ChosenEvent} for that src, so an
+* unknown, payload-invalid, or guard-rejected event is NOT silently swallowed
+* — the next queued decision is tried, exactly as a live run re-asks the
+* model. The decision logic's `maxRetries` caps attempts as it would live;
+* when retries continue past the end of the queue, the last queued decision
+* repeats (a scripted model that insists). The repeat applies only within one
+* decision request's retries — each new decision request must have its own
+* queued entry, or the dry-script error throws as usual. Exhausting all
+* attempts delivers
+* the resulting {@link AgentDecisionExhaustedError} to the machine as the
+* decision invoke's error (so an `onError` transition observes it, as it
+* would live); with no `onError` to catch it, it is thrown.
+*
+* Throws a descriptive error when the script runs dry mid-request, naming the
+* pending request's kind, src, and id so the missing scripted response is
+* obvious.
+*
+* @example
+* ```ts
+* const { status, snapshot } = simulateAgent(machine, {
+*   input: { topic: 'state machines' },
+*   script: {
+*     decisions: { 'agent.decide': [{ type: 'ESCALATE' }] },
+*     events: [{ type: 'APPROVE' }], // crosses the human gate
+*   },
+* });
+* ```
+*/
+async function simulateAgent(machine, options) {
+	const maxSteps = options.maxSteps ?? 100;
+	const script = {
+		text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
+		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
+		invokes: mapValues(options.script.invokes ?? {}, (arr) => [...arr]),
+		errors: mapValues(options.script.errors ?? {}, (arr) => [...arr]),
+		events: [...options.script.events ?? []]
+	};
+	let step = initialAgentStep(machine, options.input);
+	const trail = [{ state: step.snapshot.value }];
+	for (let i = 0; i < maxSteps; i++) {
+		if (step.done) return {
+			status: "done",
+			snapshot: step.snapshot,
+			trail
+		};
+		const request = step.requests[0];
+		if (request) {
+			if (request.kind === "decision") {
+				const invokeMeta = findInvokeMetadata(step, request.id);
+				const src = invokeMeta?.src ?? request.id;
+				const decisionSrc = src in (script.decisions ?? {}) ? src : request.id in (script.decisions ?? {}) ? request.id : src;
+				const errorSrc = queueKey(script.errors, src, request.id);
+				const failure = takeFromQueue(script.errors, errorSrc);
+				if (failure.found) {
+					step = rejectScriptedRequest(machine, step, request.id, failure.value, {
+						kind: "decision",
+						src: errorSrc,
+						trail
+					});
+					continue;
+				}
+				step = await applyScriptedDecision(machine, step, request, decisionSrc, invokeMeta?.logic, script, trail);
+				continue;
+			}
+			const failure = takeFromQueue(script.errors, request.src);
+			if (failure.found) {
+				step = rejectScriptedRequest(machine, step, request, failure.value, {
+					kind: "text",
+					src: request.src,
+					trail
+				});
+				continue;
+			}
+			const taken = takeFromQueue(script.text, request.src);
+			if (!taken.found) throw scriptDryError("text", request.src, request.id);
+			step = resolveAgentStep(machine, step, request, asTextResult(taken.value));
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "text",
+					src: request.src,
+					id: request.id,
+					outcome: "output"
+				}
+			});
+			continue;
+		}
+		const [invoke] = pendingInvokes(step);
+		if (invoke) {
+			const failure = takeFromQueue(script.errors, invoke.src);
+			if (failure.found) {
+				step = rejectScriptedRequest(machine, step, invoke.id, failure.value, {
+					kind: "invoke",
+					src: invoke.src,
+					trail
+				});
+				continue;
+			}
+			const taken = takeFromQueue(script.invokes, invoke.src);
+			if (!taken.found) throw scriptDryError("invoke", invoke.src, invoke.id);
+			step = resolveAgentStep(machine, step, invoke.id, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "invoke",
+					src: invoke.src,
+					id: invoke.id,
+					outcome: "output"
+				}
+			});
+			continue;
+		}
+		const external = script.events;
+		if (external.length > 0) {
+			const event = external.shift();
+			if (!step.snapshot.can(event)) throw new Error(`simulateAgent: scripted external event '${event.type}' cannot be taken in state ${JSON.stringify(step.snapshot.value)} (no handler, or its guard rejected it). A live run's send would be silently dropped here; fix the script's \`events\` queue.`);
+			step = transitionAgentStep(machine, step, event);
+			trail.push({
+				state: step.snapshot.value,
+				appliedEvent: event,
+				external: true
+			});
+			continue;
+		}
+		return {
+			status: "idle",
+			snapshot: step.snapshot,
+			trail
+		};
+	}
+	return {
+		status: "exhausted",
+		snapshot: step.snapshot,
+		trail
+	};
+}
+function queueKey(channel, src, id) {
+	return channel && !(src in channel) && id in channel ? id : src;
+}
+function rejectScriptedRequest(machine, step, request, error, entry) {
+	const id = typeof request === "string" ? request : request.id;
+	const next = rejectAgentStep(machine, step, request, error);
+	if (next.snapshot.status === "error") throw unhandledScriptedError(error, entry.kind, entry.src, id);
+	entry.trail.push({
+		state: next.snapshot.value,
+		resolvedRequest: {
+			kind: entry.kind,
+			src: entry.src,
+			id,
+			outcome: "error",
+			error
+		}
+	});
+	return next;
+}
+function unhandledScriptedError(error, kind, src, id) {
+	if (error instanceof Error) return error;
+	return new Error(`simulateAgent: the scripted error for the ${kind} request '${src}' (id '${id}') reached no onError transition, so the machine errored. Add an onError to that invoke, or drop the errors['${src}'] entry.`, { cause: error });
+}
+async function applyScriptedDecision(machine, step, request, decisionSrc, invokeLogic, script, trail) {
+	const dequeued = [];
+	const decide = async () => {
+		const taken = takeFromQueue(script.decisions, decisionSrc);
+		if (taken.found) {
+			dequeued.push(taken.value);
+			return { event: taken.value };
+		}
+		if (dequeued.length === 0) throw scriptDryError("decision", decisionSrc, request.id, request);
+		return { event: dequeued[dequeued.length - 1] };
+	};
+	const logic = isDecisionLogic(invokeLogic) ? invokeLogic : resolveRegisteredDecisionLogic(machine, decisionSrc);
+	const maxRetries = request.maxRetries ?? logic?.maxRetries;
+	const can = (event) => step.snapshot.can(event);
+	const options = acceptedDecisionOptions(request, can);
+	const offered = options ? {
+		...request,
+		options
+	} : request;
+	let chosen;
+	try {
+		chosen = await resolveDecision(offered, { decide }, {
+			maxRetries,
+			canTake: can
+		});
+	} catch (error) {
+		if (!(error instanceof AgentDecisionExhaustedError)) throw error;
+		const next = rejectAgentStep(machine, step, request.id, error);
+		if (next.snapshot.status === "error") throw error;
+		trail.push({
+			state: next.snapshot.value,
+			rejectedEvents: dequeued
+		});
+		return next;
+	}
+	const next = transitionAgentStep(machine, step, chosen);
+	const rejected = dequeued.slice(0, -1);
+	trail.push({
+		state: next.snapshot.value,
+		appliedEvent: chosen,
+		...rejected.length > 0 ? { rejectedEvents: rejected } : {}
+	});
+	return next;
+}
+function findInvokeMetadata(step, id) {
+	for (const metadata of getPendingInvokes(step.snapshot)) {
+		if (metadata.id !== id) continue;
+		return {
+			...typeof metadata.src === "string" ? { src: metadata.src } : {},
+			logic: metadata.logic ?? (typeof metadata.src === "object" ? metadata.src : void 0)
+		};
+	}
+}
+function resolveRegisteredDecisionLogic(machine, src) {
+	const candidate = getRegisteredAgentExecutionOptions(machine).actors?.[src] ?? machine.sources?.actors?.[src];
+	return isDecisionLogic(candidate) ? candidate : void 0;
+}
+function asTextResult(value) {
+	return {
+		result: value,
+		messages: []
+	};
+}
+function mapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value)]));
+}
+function scriptDryError(kind, src, id, request) {
+	const events = request?.kind === "decision" ? ` Candidate events: ${request.events.map((e) => e.type).join(", ") || "(none)"}.` : "";
+	const key = kind === "text" ? `text['${src}']` : kind === "decision" ? `decisions['${src}']` : `invokes['${src}']`;
+	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add an entry to the script's \`${key}\` queue.${events}`);
+}
+const MAX_ADVANCE_STEPS = 1e3;
+const FINITE_PAYLOAD_CAP = 64;
+const DEFAULT_MAX_NODES = 1e5;
+function finiteDomain(schema) {
+	if (!isRecord(schema)) return;
+	if ("const" in schema) return [schema["const"]];
+	if (Array.isArray(schema["enum"])) return schema["enum"];
+	const union = schema["anyOf"] ?? schema["oneOf"];
+	if (Array.isArray(union)) {
+		const parts = union.map(finiteDomain);
+		return parts.every((part) => part !== void 0) ? [...new Set(parts.flat())] : void 0;
+	}
+	const types = Array.isArray(schema["type"]) ? schema["type"] : [schema["type"]];
+	if (types.every((type) => type === "boolean" || type === "null")) return types.flatMap((type) => type === "boolean" ? [true, false] : [null]);
+}
+const OMITTED = Symbol("omitted");
+function finitePayloads(jsonSchema) {
+	const bare = {
+		payloads: [{}],
+		complete: false
+	};
+	if (!isRecord(jsonSchema) || jsonSchema["type"] !== "object" && !isRecord(jsonSchema["properties"])) return bare;
+	const properties = isRecord(jsonSchema["properties"]) ? jsonSchema["properties"] : {};
+	const required = new Set(Array.isArray(jsonSchema["required"]) ? jsonSchema["required"] : []);
+	if ([...required].some((key) => key !== "type" && !(key in properties))) return bare;
+	let product = [{}];
+	let complete = true;
+	for (const [key, schema] of Object.entries(properties)) {
+		if (key === "type") continue;
+		const domain = finiteDomain(schema);
+		if (!domain || domain.length === 0) {
+			if (required.has(key)) return bare;
+			complete = false;
+			continue;
+		}
+		const choices = required.has(key) ? domain : [OMITTED, ...domain];
+		if (product.length * choices.length > FINITE_PAYLOAD_CAP) return bare;
+		product = product.flatMap((payload) => choices.map((value) => value === OMITTED ? payload : {
+			...payload,
+			[key]: value
+		}));
+	}
+	return {
+		payloads: product,
+		complete
+	};
+}
+function mayReadPayload(snapshot, type) {
+	return getNextTransitions(snapshot).some((transition) => transition.eventType === type && (transition.to !== void 0 || transition.guard !== void 0 || transition.matches !== void 0 || typeof transition.context === "function"));
+}
+function explore(machine, options, stopWhen) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxPaths = options.maxPaths ?? 200;
+	const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+	const errorScript = options.errors ?? {};
+	const outputScript = options.outputs ?? {};
+	const eventSchemas = getRegisteredAgentExecutionOptions(machine).schemas?.events ?? machine.schemas?.events ?? {};
+	const finiteCache = /* @__PURE__ */ new Map();
+	const schemaPayloads = (type, snapshot) => {
+		const schema = eventSchemas[type];
+		let fill = finiteCache.get(type);
+		if (schema && !fill) {
+			fill = finitePayloads(safeJsonSchema(schema));
+			finiteCache.set(type, fill);
+		}
+		fill ??= {
+			payloads: [{}],
+			complete: !mayReadPayload(snapshot, type)
+		};
+		if (!fill.complete && !unexpanded.has(type)) {
+			unexpanded.add(type);
+			unexplored.push(schema ? `unexpanded: event '${type}' has payload fields the schema fill cannot enumerate; add a payloads entry for it` : `unexpanded: event '${type}' has no schema and a transition that may read its payload; add a payloads entry for it`);
+		}
+		return fill.payloads;
+	};
+	const variantsOf = (type, snapshot, table, requestOptions) => {
+		const listed = table[type];
+		if (listed) return listed.map((payload) => ({
+			...payload,
+			type
+		}));
+		if (requestOptions) return requestOptions.filter((option) => option.event.type === type).map((option) => option.event);
+		return schemaPayloads(type, snapshot).map((payload) => ({
+			...payload,
+			type
+		}));
+	};
+	const settleFor = (id, src, isText) => {
+		const outputs = outputScript[src] ?? [];
+		if (src in errorScript || outputs.length > 1) return { fork: {
+			id,
+			...src in errorScript ? { errorKey: src } : {},
+			outputs,
+			isText
+		} };
+		return outputs.length === 1 ? { output: outputs[0] } : { blocked: true };
+	};
+	const reachedStates = /* @__PURE__ */ new Set();
+	const reachedValues = [];
+	const terminals = [];
+	const unexplored = [];
+	const unexpanded = /* @__PURE__ */ new Set();
+	let prunedByGuard = 0;
+	let pathsExplored = 0;
+	let nodesExpanded = 0;
+	let hitPathCap = false;
+	const capped = () => {
+		if (pathsExplored >= maxPaths || nodesExpanded >= maxNodes) hitPathCap = true;
+		return hitPathCap;
+	};
+	let witness;
+	const visited = /* @__PURE__ */ new Map();
+	const recordState = (snapshot) => {
+		const key = JSON.stringify(snapshot.value);
+		if (!reachedStates.has(key)) {
+			reachedStates.add(key);
+			reachedValues.push(snapshot.value);
+		}
+	};
+	const initial = initialAgentStep(machine, options.input);
+	recordState(initial.snapshot);
+	if (stopWhen?.(initial.snapshot)) witness = [];
+	const advance = (step) => {
+		let current = step;
+		for (let i = 0; i < MAX_ADVANCE_STEPS; i++) {
+			if (stopWhen?.(current.snapshot)) return {
+				step: current,
+				hit: true
+			};
+			if (current.done) return { step: current };
+			const request = current.requests[0];
+			if (request && request.kind === "text") {
+				const settle = settleFor(request.id, request.src, true);
+				if ("fork" in settle) return {
+					step: current,
+					fork: settle.fork
+				};
+				if ("blocked" in settle) return {
+					step: current,
+					blockedSrc: request.src
+				};
+				current = resolveAgentStep(machine, current, request, asTextResult(settle.output));
+				recordState(current.snapshot);
+				continue;
+			}
+			if (request && request.kind === "decision") {
+				const src = findInvokeMetadata(current, request.id)?.src;
+				const errorSrc = src !== void 0 && src in errorScript ? src : request.id in errorScript ? request.id : void 0;
+				return errorSrc !== void 0 ? {
+					step: current,
+					fork: {
+						id: request.id,
+						errorKey: errorSrc,
+						outputs: [],
+						isDecision: true
+					}
+				} : { step: current };
+			}
+			const [invoke] = pendingInvokes(current);
+			if (invoke) {
+				const settle = settleFor(invoke.id, invoke.src, false);
+				if ("fork" in settle) return {
+					step: current,
+					fork: settle.fork
+				};
+				if ("blocked" in settle) return {
+					step: current,
+					blockedSrc: invoke.src
+				};
+				current = resolveAgentStep(machine, current, invoke.id, settle.output);
+				recordState(current.snapshot);
+				continue;
+			}
+			return { step: current };
+		}
+		return { step: current };
+	};
+	function* expand({ step, path, depth }) {
+		if (witness !== void 0 || capped()) return;
+		nodesExpanded++;
+		const { step: settled, blockedSrc, hit, fork } = advance(step);
+		if (hit) {
+			witness = path;
+			return;
+		}
+		if (options.dedupeBy) {
+			const key = options.dedupeBy(settled.snapshot);
+			const seenAt = visited.get(key);
+			if (seenAt !== void 0 && seenAt <= depth) return;
+			visited.set(key, depth);
+		}
+		if (fork) {
+			if (depth >= maxDepth) {
+				pathsExplored++;
+				terminals.push({
+					status: "max-depth",
+					path,
+					state: settled.snapshot.value
+				});
+				unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
+				return;
+			}
+			if (fork.errorKey !== void 0) {
+				const failed = rejectAgentStep(machine, settled, fork.id, errorScript[fork.errorKey]);
+				recordState(failed.snapshot);
+				yield {
+					step: failed,
+					path: [...path, { type: `xstate.error.actor.${fork.id}` }],
+					depth: depth + 1
+				};
+			}
+			if (!fork.isDecision) {
+				for (const output of fork.outputs) {
+					if (witness !== void 0 || capped()) return;
+					const resolved = resolveAgentStep(machine, settled, fork.id, fork.isText ? asTextResult(output) : output);
+					recordState(resolved.snapshot);
+					yield {
+						step: resolved,
+						path: [...path, {
+							type: `xstate.done.actor.${fork.id}`,
+							output
+						}],
+						depth: depth + 1
+					};
+				}
+				return;
+			}
+			if (witness !== void 0) return;
+		}
+		if (blockedSrc) {
+			pathsExplored++;
+			terminals.push({
+				status: "needs-output",
+				path,
+				state: settled.snapshot.value,
+				missingSrc: blockedSrc
+			});
+			unexplored.push(`needs-output: no \`outputs\` entry for src '${blockedSrc}' at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		if (settled.done) {
+			pathsExplored++;
+			terminals.push({
+				status: "done",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		if (settled.snapshot.status === "error") {
+			pathsExplored++;
+			terminals.push({
+				status: "error",
+				path,
+				state: settled.snapshot.value,
+				error: settled.snapshot.error
+			});
+			return;
+		}
+		const request = settled.requests[0];
+		const snapshot = settled.snapshot;
+		const table = options.payloads?.(snapshot) ?? {};
+		const requestOptions = request?.kind === "decision" ? acceptedDecisionOptions(request, () => true) : void 0;
+		const branchEvents = request?.kind === "decision" ? request.events.flatMap((descriptor) => variantsOf(descriptor.type, snapshot, table, requestOptions)) : getAcceptedEvents(snapshot).flatMap((descriptor) => {
+			if (table[descriptor.type]?.length === 0) {
+				unexpanded.add(descriptor.type);
+				unexplored.push(`skipped: payloads lists no ${descriptor.type} at path [${path.map((e) => e.type).join(", ")}], so its branches were not explored`);
+			}
+			return variantsOf(descriptor.type, snapshot, table);
+		});
+		if (branchEvents.length === 0 && request?.kind !== "decision") {
+			pathsExplored++;
+			terminals.push({
+				status: "idle",
+				path,
+				state: settled.snapshot.value
+			});
+			return;
+		}
+		if (depth >= maxDepth) {
+			pathsExplored++;
+			terminals.push({
+				status: "max-depth",
+				path,
+				state: settled.snapshot.value
+			});
+			unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
+			return;
+		}
+		let taken = 0;
+		for (const event of branchEvents) {
+			if (witness !== void 0 || capped()) return;
+			if (!snapshot.can(event)) {
+				prunedByGuard++;
+				continue;
+			}
+			taken++;
+			const next = transitionAgentStep(machine, settled, event);
+			recordState(next.snapshot);
+			yield {
+				step: next,
+				path: [...path, event],
+				depth: depth + 1
+			};
+		}
+		if (request?.kind !== "decision" && taken === 0 && witness === void 0 && !capped()) {
+			pathsExplored++;
+			terminals.push({
+				status: "idle",
+				path,
+				state: settled.snapshot.value
+			});
+			const refused = [...new Set(branchEvents.map((event) => event.type))];
+			for (const type of refused) unexpanded.add(type);
+			unexplored.push(`stuck: every offered ${refused.join(", ")} event at path [${path.map((e) => e.type).join(", ")}] was refused by the machine's guards; add a payloads entry it accepts`);
+			return;
+		}
+		if (request?.kind === "decision" && taken === 0) {
+			if (witness !== void 0 || capped()) return;
+			const exhausted = new AgentDecisionExhaustedError([]);
+			exhausted.message = `Decision '${request.name ?? request.id}' has no candidate the current snapshot accepts (explored, no model call).`;
+			const failed = rejectAgentStep(machine, settled, request.id, exhausted);
+			recordState(failed.snapshot);
+			yield {
+				step: failed,
+				path: [...path, { type: `xstate.error.actor.${request.id}` }],
+				depth: depth + 1
+			};
+		}
+	}
+	const root = {
+		step: initial,
+		path: [],
+		depth: 0
+	};
+	if (witness === void 0 && stopWhen) {
+		const levels = [[root]];
+		search: for (let length = 0; length < levels.length; length++) {
+			const level = levels[length] ?? [];
+			for (let i = 0; i < level.length; i++) {
+				const node = level[i];
+				level[i] = void 0;
+				for (const child of expand(node)) (levels[child.path.length] ??= []).push(child);
+				if (witness !== void 0 || hitPathCap) break search;
+			}
+			levels[length] = [];
+		}
+	} else if (witness === void 0) {
+		const visit = (node) => {
+			for (const child of expand(node)) visit(child);
+		};
+		visit(root);
+	}
+	return {
+		report: {
+			reachedStates: reachedValues,
+			terminals,
+			prunedByGuard,
+			unexplored,
+			pathsExplored,
+			hitPathCap,
+			unexpandedEvents: [...unexpanded]
+		},
+		witness
+	};
+}
+/**
+* Enumerates a machine's decision and external-event branches to a bounded
+* depth, model-free, and reports which states are reached and how each path
+* terminates. At each decision request it forks one branch per candidate event
+* (guard-rejected candidates are counted in `prunedByGuard`, not explored); a
+* decision with no takeable candidate exhausts as it does live, taking its
+* `onError` (an `error` terminal without one). At an idle wait it forks per
+* externally-accepted event. Text requests and other
+* invokes resolve from `outputs`, a by-src map of outputs to try (a
+* one-element list is a canned output; several fork one branch each), and a
+* missing src halts that branch with a `needs-output` terminal rather than
+* throwing. A src in
+* `errors` forks an extra branch where that invoke is rejected, so states
+* behind an `onError` are explored too.
+*
+* Events are applied as `{ type }` unless a payload is known: `payloads`
+* forks a type once per listed payload, a decide input's own `payloads`
+* become the branch set, and an event schema whose fields are finite (enums,
+* booleans, consts) expands to their product, each optional field also
+* omitted. A type that could not be fully expanded is listed in
+* `unexpandedEvents`, as is a type with no schema whose transition could read
+* the payload (a function transition, guard, `matches`, or context mapper).
+* `dedupeBy` explores each projected snapshot once, which keeps a large
+* payload table tractable.
+*
+* Combinatorics are bounded by `maxDepth` (default 8), `maxPaths` (default
+* 200), and `maxNodes` (default 100,000), the last two reported via
+* `hitPathCap`.
+*
+* @example
+* ```ts
+* const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+* // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+* ```
+*/
+async function explorePaths(machine, options = {}) {
+	return explore(machine, options).report;
+}
+/** Thrown when a string reachability target is not a state in the machine. */
+var AgentUnknownStateError = class extends AgentError {
+	target;
+	constructor(machineId, target) {
+		super("unknown-state", `canReach: machine '${machineId}' has no state matching '${target}'.`);
+		this.name = "AgentUnknownStateError";
+		this.target = target;
+	}
+};
+function resolveStateTarget(machine, target) {
+	const stack = [machine.root];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (node.id === target.replace(/^#/, "") || node.path.join(".") === target) return node.id;
+		stack.push(...Object.values(node.states));
+	}
+	throw new AgentUnknownStateError(machine.id, target);
+}
+/**
+* Answers "can the machine reach this?" by exploring its branches (a thin
+* wrapper over {@link explorePaths}). The target is either a state path string
+* (`snapshot.matches(...)` semantics) or a snapshot predicate — the predicate
+* form checks any property (a context invariant, a tag, a state+context
+* combination) without reifying a sentinel state for it. Returns
+* `{ reachable: true, witness }` with the event sequence that reaches it, or
+* `{ reachable: false }`. Check `complete` before treating `reachable: false`
+* as a proof: it is false when a cap or `maxDepth` cut exploration short, a
+* branch needed an `outputs` entry it did not have, or an event's payloads were
+* not all tried.
+*
+* @example
+* ```ts
+* const { reachable, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+* // reachable → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+* ```
+*
+* @example Predicate target — a violation property, no sentinel state needed
+* ```ts
+* const violation = await canReach(
+*   refundMachine,
+*   (snapshot) => snapshot.matches('issued') && !snapshot.context.approved,
+*   { input: { amount: 5000 } },
+* );
+* // violation.reachable → false is the safety proof
+* ```
+*/
+async function canReach(machine, target, options = {}) {
+	const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
+	const { witness, report } = explore(machine, options, typeof target === "function" ? target : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget));
+	if (witness !== void 0) return {
+		reachable: true,
+		witness,
+		complete: true,
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	};
+	return {
+		reachable: false,
+		complete: !report.hitPathCap && report.unexpandedEvents.length === 0 && report.terminals.every((terminal) => terminal.status === "done" || terminal.status === "idle" || terminal.status === "error"),
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	};
+}
+//#endregion
+export { explorePaths as a, canReach as i, AgentUnknownStateError as n, lintAgentMachine as o, assertAgentMachine as r, simulateAgent as s, AgentLintError as t };