@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/testing.mjs

@@ -0,0 +1,1079 @@
+import { H as AgentError, P as getStateMeta, S as getRegisteredAgentExecutionOptions, d as getCallUsage, f as isTextLogic, p as normalizeGeneratorResult, y as executorBoundLogics } from "./text-logic-Bl_ZRxDi.mjs";
+import { a as isDecisionLogic, d as isRecord, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-DzSv1NpD.mjs";
+import { _ as rejectAgentStep, d as runAgent, g as initialAgentStep, h as getPendingInvokes, v as resolveAgentStep, y as transitionAgentStep } from "./run-agent-DvDQd4If.mjs";
+//#region src/verify.ts
+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 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 runAgent, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actors: { name: logic } })) and invoke it by name.`
+		});
+	}
+	return out;
+}
+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 maxRetries = (isDecisionLogic(invokeLogic) ? invokeLogic : resolveRegisteredDecisionLogic(machine, decisionSrc))?.maxRetries;
+	let chosen;
+	try {
+		chosen = await resolveDecision(request, { decide }, {
+			maxRetries,
+			canTake: (event) => step.snapshot.can(event)
+		});
+	} 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;
+function invokeFork(id, src, outputs) {
+	return src in outputs ? {
+		id,
+		src,
+		hasOutput: true,
+		output: outputs[src]
+	} : {
+		id,
+		src,
+		hasOutput: false
+	};
+}
+async function explore(machine, options, stopWhen) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxPaths = options.maxPaths ?? 200;
+	const textScript = options.text ?? {};
+	const invokeOutputs = { ...options.invokes };
+	const errorScript = options.errors ?? {};
+	const reachedStates = /* @__PURE__ */ new Set();
+	const reachedValues = [];
+	const terminals = [];
+	const unexplored = [];
+	let prunedByGuard = 0;
+	let pathsExplored = 0;
+	let hitPathCap = false;
+	let witness;
+	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") {
+				if (request.src in errorScript) return {
+					step: current,
+					fork: invokeFork(request.id, request.src, textScript)
+				};
+				if (!(request.src in textScript)) return {
+					step: current,
+					blockedSrc: request.src
+				};
+				current = resolveAgentStep(machine, current, request, asTextResult(textScript[request.src]));
+				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,
+						src: errorSrc,
+						hasOutput: false,
+						isDecision: true
+					}
+				} : { step: current };
+			}
+			const [invoke] = pendingInvokes(current);
+			if (invoke) {
+				if (invoke.src in errorScript) return {
+					step: current,
+					fork: invokeFork(invoke.id, invoke.src, invokeOutputs)
+				};
+				if (!(invoke.src in invokeOutputs)) return {
+					step: current,
+					blockedSrc: invoke.src
+				};
+				current = resolveAgentStep(machine, current, invoke.id, invokeOutputs[invoke.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			return { step: current };
+		}
+		return { step: current };
+	};
+	const visit = async (step, path, startDepth) => {
+		let depth = startDepth;
+		if (witness !== void 0) return;
+		if (pathsExplored >= maxPaths) {
+			hitPathCap = true;
+			return;
+		}
+		const { step: settled, blockedSrc, hit, fork } = advance(step);
+		if (hit) {
+			witness = path;
+			return;
+		}
+		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;
+			}
+			const failed = rejectAgentStep(machine, settled, fork.id, errorScript[fork.src]);
+			recordState(failed.snapshot);
+			await visit(failed, [...path, { type: `xstate.error.actor.${fork.id}` }], depth + 1);
+			if (!fork.isDecision) {
+				if (fork.hasOutput) {
+					const resolved = resolveAgentStep(machine, settled, fork.id, fork.output);
+					recordState(resolved.snapshot);
+					await visit(resolved, path, depth + 1);
+				}
+				return;
+			}
+			depth += 1;
+			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 canned output 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 branchEvents = request?.kind === "decision" ? request.events.map((descriptor) => ({ type: descriptor.type })) : getAcceptedEvents(settled.snapshot).map((descriptor) => ({ type: descriptor.type }));
+		if (branchEvents.length === 0) {
+			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;
+		}
+		for (const event of branchEvents) {
+			if (witness !== void 0 || pathsExplored >= maxPaths) {
+				if (pathsExplored >= maxPaths) hitPathCap = true;
+				return;
+			}
+			if (!settled.snapshot.can(event)) {
+				prunedByGuard++;
+				continue;
+			}
+			const next = transitionAgentStep(machine, settled, event);
+			recordState(next.snapshot);
+			await visit(next, [...path, event], depth + 1);
+		}
+	};
+	if (witness === void 0) await visit(initial, [], 0);
+	return {
+		report: {
+			reachedStates: reachedValues,
+			terminals,
+			prunedByGuard,
+			unexplored,
+			pathsExplored,
+			hitPathCap
+		},
+		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); at
+* an idle wait it forks per externally-accepted event. Text requests resolve
+* from `text`, other invokes from `invokes` — all by-src canned-output maps, 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.
+*
+* Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+* 200, 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 (await 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 }`.
+*
+* @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 } = await explore(machine, options, typeof target === "function" ? target : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget));
+	return witness !== void 0 ? {
+		reachable: true,
+		witness,
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	} : {
+		reachable: false,
+		...resolvedTarget ? { target: resolvedTarget } : {}
+	};
+}
+//#endregion
+//#region src/trajectory.ts
+/**
+* Classifies one item. Event-shaped things (log entries, events) become events;
+* everything else is a state value. A snapshot is unwrapped to its `value`.
+* @internal
+*/
+function normalize(item) {
+	if (isRecord(item)) {
+		const nested = item["event"];
+		if (isRecord(nested) && typeof nested["type"] === "string") return {
+			kind: "event",
+			event: nested
+		};
+		if (typeof item["type"] === "string") return {
+			kind: "event",
+			event: item
+		};
+		if ("value" in item) return {
+			kind: "state",
+			value: item["value"]
+		};
+	}
+	return {
+		kind: "state",
+		value: item
+	};
+}
+/** Every leaf of a state value as a dot path (`{ review: 'editing' }` → `review.editing`). @internal */
+function statePaths(value) {
+	if (typeof value === "string") return [value];
+	if (!isRecord(value)) return [];
+	return Object.entries(value).flatMap(([key, child]) => statePaths(child).map((path) => `${key}.${path}`));
+}
+/**
+* A string expectation matches a state value when it names one of its leaves or
+* an ancestor of one, so `'review'` matches `{ review: 'editing' }`. @internal
+*/
+function stateMatchesPath(path, value) {
+	return statePaths(value).some((leaf) => leaf === path || leaf.startsWith(`${path}.`));
+}
+function deepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+	if (!isRecord(a) || !isRecord(b)) return false;
+	const keys = Object.keys(a);
+	return keys.length === Object.keys(b).length && keys.every((key) => deepEqual(a[key], b[key]));
+}
+/**
+* Normalizes ONE expected item into a predicate over actual items, so the
+* expectation is classified once instead of once per candidate:
+*
+* - A string expectation matches an event's `type`, or a state value it names.
+* - An event expectation matches an event with the same `type` whose other
+*   declared keys deep-equal, so payload details are opt-in.
+* - A state-value expectation matches structurally.
+* @internal
+*/
+function matcherFor(expected) {
+	if (typeof expected === "string") return (actual) => {
+		const actualItem = normalize(actual);
+		return actualItem.kind === "event" ? actualItem.event.type === expected : stateMatchesPath(expected, actualItem.value);
+	};
+	const expectedItem = normalize(expected);
+	switch (expectedItem.kind) {
+		case "event": return (actual) => {
+			const actualItem = normalize(actual);
+			return actualItem.kind === "event" && Object.keys(expectedItem.event).every((key) => deepEqual(expectedItem.event[key], actualItem.event[key]));
+		};
+		case "state": return (actual) => {
+			const actualItem = normalize(actual);
+			return actualItem.kind === "state" && deepEqual(expectedItem.value, actualItem.value);
+		};
+	}
+}
+/**
+* Matches a run's trajectory against an expected one.
+*
+* Both trajectories may be state values or events collected from
+* `onTransition`;
+* items are compared by shape, so `['prompting', 'drafting']` scores a state
+* path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
+* call.
+*
+* Semantics are an ordered subsequence: every expected item must appear in
+* `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
+* equality instead.
+*
+* @example Trajectory assertions in a test
+* ```ts
+* const statePath: unknown[] = [];
+* const result = await runAgent(machine, {
+*   input,
+*   executors,
+*   onTransition: (snapshot) => statePath.push(snapshot.value),
+* });
+*
+* const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
+* expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
+* expect(matchesTrajectory(events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
+* ```
+*
+* @example Partial credit in an eval scorer
+* ```ts
+* const match = matchesTrajectory(output.statePath, expected.statePath);
+* return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
+* ```
+*/
+function matchesTrajectory(actual, expected, options = {}) {
+	const expectedCount = expected.length;
+	if (expectedCount === 0) throw new AgentError("empty-trajectory", "matchesTrajectory: expected trajectory must contain at least one item.");
+	const exact = options.exact === true;
+	let cursor = 0;
+	let matchedCount = 0;
+	let firstMiss;
+	for (let index = 0; index < expectedCount; index++) {
+		const want = expected[index];
+		const matches = matcherFor(want);
+		const searchedFrom = exact ? index : cursor;
+		let found = -1;
+		for (let at = searchedFrom; at < actual.length; at++) {
+			if (matches(actual[at])) {
+				found = at;
+				break;
+			}
+			if (exact) break;
+		}
+		if (found === -1) {
+			firstMiss = {
+				index,
+				expected: want,
+				searchedFrom
+			};
+			break;
+		}
+		matchedCount++;
+		cursor = found + 1;
+	}
+	const matched = !firstMiss && (!exact || actual.length === expectedCount);
+	const denominator = exact ? Math.max(expectedCount, actual.length) : expectedCount;
+	return {
+		matched,
+		matchedCount,
+		expectedCount,
+		score: matched ? 1 : denominator === 0 ? 1 : matchedCount / denominator,
+		...firstMiss ? { firstMiss } : {}
+	};
+}
+//#endregion
+//#region src/seam.ts
+/** The only own keys an executor result carries. @internal */
+const TEXT_RESULT_KEYS = new Set([
+	"result",
+	"messages",
+	"usage",
+	"raw"
+]);
+/**
+* True when a scripted entry is the executor result rather than the output
+* value: it owns a `result` key and owns NOTHING outside the result's own
+* vocabulary. Bare `'result' in value` would swallow an output object's
+* siblings (`{ result: 'draft', confidence: 0.9 }` would lose `confidence`)
+* and would also match an inherited `result`. @internal
+*/
+function isTextResult(value) {
+	return Object.hasOwn(value, "result") && Object.keys(value).every((key) => TEXT_RESULT_KEYS.has(key));
+}
+/**
+* Resolves ONE scripted entry to an executor result: a function entry is
+* called with the request, and the value is taken as the executor result only
+* when it is one (see {@link isTextResult}). @internal
+*/
+async function resolveSeamScriptEntry(entry, request, info) {
+	const value = typeof entry === "function" ? await entry(request, info) : entry;
+	return isRecord(value) && isTextResult(value) ? value : { result: value };
+}
+/** Names a pending text request in an error message. @internal */
+function describeText(request) {
+	return request.name ? `'${request.name}' (model '${request.model}')` : `(model '${request.model}')`;
+}
+/**
+* Stream semantics with no model: the whole text lands as one chunk. @internal
+*/
+function emitScriptedChunk(result, info) {
+	const text = isRecord(result) ? result["result"] : void 0;
+	if (typeof text === "string") info?.onChunk?.(text);
+}
+/**
+* The seam's own answer, for scoring: the executor result's `result`.
+* @internal
+*/
+async function seamOutputOf(result, request) {
+	if (!isRecord(result)) return;
+	return await normalizeGeneratorResult(result, `seam '${request.name ?? request.model}'`);
+}
+/**
+* Runs a machine end to end with one model call under test, and slices the run
+* at that call.
+*
+* The `before`/`after` slices are the point: `after.statePath` is the branch
+* the seam chose and `after.events` is the same question against the durable
+* log, both ready for `matchesTrajectory`. The state slice splits where the
+* state path stood when the seam answered; the event slice splits at the
+* seam's own effect completion (the first `xstate.done.*`/`xstate.error.*`
+* entry appended after the call was made).
+*
+* @example No API key: the seam is scripted too, so the whole thing runs offline.
+* ```ts
+* const run = await runSeam(emailDrafter, {
+*   scripts: { writeFollowUps: [followUps], emailDrafter: [draft] },
+*   seam: { request: 'writeFollowUps' },
+*   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
+* });
+*
+* matchesTrajectory(run.after.statePath, ['needsMoreInfo', 'drafting']);
+* ```
+*
+* @example A candidate prompt at the seam, scored against the same rows.
+* ```ts
+* const { generateText } = createAiSdkExecutors({ models });
+* const run = await runSeam(emailDrafter, { ...row, candidate: generateText });
+* ```
+*/
+async function runSeam(machine, options) {
+	const { seam, candidate } = options;
+	const queues = new Map(Object.entries(options.scripts ?? {}).map(([key, answers]) => [key, [...answers]]));
+	const statePath = [];
+	let calls = 0;
+	let seamMatches = 0;
+	let seamOutput;
+	let seamUsage;
+	const callLog = [];
+	let seamReached = false;
+	let callsBeforeSeam = -1;
+	let seamStateAt = 0;
+	let seamEventAt = 0;
+	let liveEvents = 0;
+	const queueKeyOf = (request) => request.name !== void 0 && queues.has(request.name) ? request.name : request.model;
+	/**
+	* Consumes this request's slot in the call plan, or resolves `undefined` when
+	* its queue is dry. With `repeatLast`, the last entry is replayed instead of
+	* running dry.
+	*/
+	const takeScriptedSlot = async (request, info) => {
+		const queue = queues.get(queueKeyOf(request));
+		if (!queue?.length) return;
+		return resolveSeamScriptEntry(options.repeatLast && queue.length === 1 ? queue[0] : queue.shift(), request, info);
+	};
+	const scriptedAnswer = async (request, info) => {
+		const scripted = await takeScriptedSlot(request, info);
+		if (!scripted) throw new AgentError("seam-script-exhausted", `runSeam: no scripted answer left for request ${describeText(request)}. Add an entry to \`scripts.${queueKeyOf(request)}\`, or pass \`repeatLast: true\` to replay its last entry down a longer branch.`);
+		return scripted;
+	};
+	const route = async (request, info) => {
+		const callIndex = calls++;
+		const isSeam = request.name === seam.request && seamMatches++ === (seam.occurrence ?? 0);
+		const ledger = (source) => {
+			callLog.push({
+				...request.name !== void 0 ? { name: request.name } : {},
+				model: request.model,
+				key: queueKeyOf(request),
+				source,
+				seam: isSeam
+			});
+		};
+		if (isSeam && candidate) {
+			await takeScriptedSlot(request, info);
+			seamReached = true;
+			callsBeforeSeam = callIndex;
+			seamStateAt = statePath.length;
+			seamEventAt = liveEvents;
+			const result = await candidate(request, info);
+			seamOutput = await seamOutputOf(result, request);
+			seamUsage = getCallUsage(result);
+			ledger("candidate");
+			return result;
+		}
+		const scripted = await scriptedAnswer(request, info);
+		ledger("script");
+		if (!isSeam) return scripted;
+		seamReached = true;
+		callsBeforeSeam = callIndex;
+		seamStateAt = statePath.length;
+		seamEventAt = liveEvents;
+		seamOutput = scripted.result;
+		seamUsage = scripted.usage;
+		return scripted;
+	};
+	const executors = {
+		...options.executors,
+		generateText: route,
+		streamText: async (request, info) => {
+			const result = await route(request, info);
+			emitScriptedChunk(result, info);
+			return result;
+		}
+	};
+	let snapshot;
+	let event;
+	const events = [];
+	let result;
+	const maxTurns = options.maxTurns ?? 12;
+	for (let turn = 0; turn <= maxTurns; turn++) {
+		result = await runAgent(machine, {
+			...snapshot ? { snapshot } : { input: options.input },
+			...event ? { event } : {},
+			...options.actors ? { actors: options.actors } : {},
+			executors,
+			onTransition: (next, causedBy) => {
+				if (turn > 0 && causedBy.type === "@xstate.init") return;
+				events.push(causedBy);
+				liveEvents = events.length;
+				statePath.push(next.value);
+			}
+		});
+		if (result.status !== "idle" || turn === maxTurns) break;
+		const next = options.respond?.({
+			snapshot: result.snapshot,
+			state: result.snapshot.value,
+			meta: getStateMeta(result.snapshot),
+			turn,
+			result
+		});
+		if (!next) break;
+		event = next;
+		snapshot = result.persist();
+	}
+	let splitAt = events.length;
+	if (seamReached) {
+		splitAt = seamEventAt;
+		for (let index = seamEventAt; index < events.length; index++) {
+			const type = events[index].type;
+			if (type.startsWith("xstate.done") || type.startsWith("xstate.error")) {
+				splitAt = index;
+				break;
+			}
+		}
+	}
+	const splitStateAt = seamReached ? seamStateAt : statePath.length;
+	return {
+		result,
+		seamOutput,
+		...seamUsage !== void 0 ? { seamUsage } : {},
+		callsBeforeSeam,
+		calls: callLog,
+		before: {
+			statePath: statePath.slice(0, splitStateAt),
+			events: events.slice(0, splitAt)
+		},
+		after: {
+			statePath: statePath.slice(splitStateAt),
+			events: events.slice(splitAt)
+		}
+	};
+}
+//#endregion
+export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };