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

package/dist/testing.mjs

@@ -1,971 +1,7 @@
-import { b as getRegisteredAgentExecutionOptions, d as isTextLogic, f as normalizeGeneratorResult, j as getStateMeta, u as getCallUsage, v as executorBoundLogics, z as AgentError } from "./text-logic-CIqHAmBi.mjs";
-import { a as isDecisionLogic, d as isRecord, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-RQ0iv0oZ.mjs";
-import { f as runToQuiescence, s as createAgentRuntime } from "./run-agent-xNTxpt82.mjs";
-import { 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 [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, 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
-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 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 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
+import { $ as getStateMeta, F as normalizeGeneratorResult, N as getCallUsage, st as AgentError } from "./event-log-DJCMHek_.mjs";
+import { m as isRecord } from "./decision-BHkvuImD.mjs";
+import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-BpHqkaZw.mjs";
+import { a as explorePaths, i as canReach, n as AgentUnknownStateError, o as lintAgentMachine, r as assertAgentMachine, s as simulateAgent, t as AgentLintError } from "./verify-COFWyprJ.mjs";
 //#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
@@ -994,17 +30,17 @@ function normalize(item) {
 	};
 }
 /** Every leaf of a state value as a dot path (`{ review: 'editing' }` → `review.editing`). @internal */
-function statePaths(value) {
+function statePaths$1(value) {
 	if (typeof value === "string") return [value];
 	if (!isRecord(value)) return [];
-	return Object.entries(value).flatMap(([key, child]) => statePaths(child).map((path) => `${key}.${path}`));
+	return Object.entries(value).flatMap(([key, child]) => statePaths$1(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}.`));
+	return statePaths$1(value).some((leaf) => leaf === path || leaf.startsWith(`${path}.`));
 }
 function deepEqual(a, b) {
 	if (Object.is(a, b)) return true;
@@ -1118,7 +154,7 @@ function matchesTrajectory(actual, expected, options = {}) {
 //#endregion
 //#region src/seam.ts
 /** The only own keys an executor result carries. @internal */
-const TEXT_RESULT_KEYS = new Set([
+const TEXT_RESULT_KEYS = /* @__PURE__ */ new Set([
 	"result",
 	"messages",
 	"usage",
@@ -1324,4 +360,186 @@ async function runSeam(machine, options) {
 	};
 }
 //#endregion
-export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+//#region src/fold-traces.ts
+/**
+* Folds many runs' traces into per-state stats: how many runs visited each
+* state, how many of those failed, and how many options the guards withheld
+* at decisions made there. Pure; reads only:
+*
+* - `machine.transition`: the run visited `from.value` and `snapshot.value`.
+* - `request.start` of a decision, first attempt only: its `request.withheld`
+*   counts toward the state the run was in, the `from.value` of the
+*   transition its choice causes.
+*
+* A trace is one run's events, live (`AgentTraceEvent`) or serialized
+* (`serializeTraceEvent`). A host-driven `decideNext` traces nothing; push
+* `{ type: 'request.start', request: result.request }` onto the trace before
+* sending its event. Parallel states count once per active leaf.
+*
+* @example
+* ```ts no-check
+* const stats = foldTraces(traces, {
+*   failed: (trace) => trace.at(-1)?.type === 'run.end' && trace.at(-1).status === 'error',
+* });
+* ```
+*/
+function foldTraces(traces, options) {
+	const stats = /* @__PURE__ */ new Map();
+	const statsFor = (state) => {
+		let entry = stats.get(state);
+		if (!entry) {
+			entry = {
+				state,
+				visits: 0,
+				failures: 0,
+				withheld: 0
+			};
+			stats.set(state, entry);
+		}
+		return entry;
+	};
+	for (const trace of traces) {
+		const visited = /* @__PURE__ */ new Set();
+		let current = [];
+		const visit = (state) => {
+			statsFor(state);
+			visited.add(state);
+		};
+		for (const event of trace) if (event.type === "machine.transition") {
+			for (const state of statePaths(valueOf(event.from))) visit(state);
+			current = statePaths(valueOf(event.snapshot));
+			for (const state of current) visit(state);
+		} else if (event.type === "request.start" && isFirstDecision(event.request)) {
+			const withheld = event.request.withheld;
+			if (!Array.isArray(withheld)) continue;
+			for (const state of current) statsFor(state).withheld += withheld.length;
+		}
+		const failed = options.failed(trace);
+		for (const state of visited) {
+			const entry = statsFor(state);
+			entry.visits++;
+			if (failed) entry.failures++;
+		}
+	}
+	return [...stats.values()];
+}
+function valueOf(holder) {
+	return isRecord(holder) ? holder.value : void 0;
+}
+function isFirstDecision(request) {
+	return isRecord(request) && request.kind === "decision" && (!Array.isArray(request.attempts) || request.attempts.length === 0);
+}
+function statePaths(value, prefix = "") {
+	if (typeof value === "string") return [prefix + value];
+	if (!isRecord(value)) return [];
+	const entries = Object.entries(value);
+	if (entries.length === 0) return prefix ? [prefix.slice(0, -1)] : [];
+	return entries.flatMap(([key, child]) => statePaths(child, `${prefix}${key}.`));
+}
+//#endregion
+//#region src/compare-runs.ts
+/**
+* Runs every scenario through a baseline and a candidate implementation and
+* labels each difference, so a port can show where it behaves like the code it
+* replaces and where it differs on purpose.
+*
+* Parity is outcome-level: the terminal outcome and the effects in the world,
+* not the sequence of tool calls, since a machine usually reorders steps. A
+* candidate that broke no rule where the baseline broke one is intended, even
+* when the outcome matches. A difference also counts as intended when only the
+* candidate reached the scenario's `expected` outcome. Every other difference,
+* and every candidate rule break, is a regression for a person to review.
+*
+* Runs are sequential, baseline first. A run that throws is recorded with
+* outcome `'threw'` and the error message as its `detail`. Parity holds for
+* these scenarios and these runs only; with a live model, run it more than once.
+*
+* @example
+* ```ts no-check
+* const report = await compareRuns({
+*   scenarios,
+*   baseline: async (s) => toParityRun(await runRawLoop(s)),
+*   candidate: async (s) => toParityRun(await runDesk(s)),
+* });
+* expect(report.ok).toBe(true);
+* ```
+*/
+async function compareRuns(options) {
+	const scenarios = [];
+	const counts = {
+		same: 0,
+		intended: 0,
+		regression: 0
+	};
+	for (const scenario of options.scenarios) {
+		const baseline = await settle(() => options.baseline(scenario));
+		const candidate = await settle(() => options.candidate(scenario));
+		const { label, reason } = labelRun(scenario.expected, baseline, candidate);
+		counts[label]++;
+		scenarios.push({
+			id: scenario.id,
+			scenario,
+			label,
+			reason,
+			baseline,
+			candidate
+		});
+	}
+	return {
+		scenarios,
+		counts,
+		ok: counts.regression === 0
+	};
+}
+async function settle(run) {
+	try {
+		return await run();
+	} catch (error) {
+		return {
+			outcome: "threw",
+			detail: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function labelRun(expected, baseline, candidate) {
+	if (candidate.violations?.length) return {
+		label: "regression",
+		reason: `candidate broke a rule: ${list(candidate.violations)}`
+	};
+	if (candidate.outcome === "threw") return {
+		label: "regression",
+		reason: `candidate threw: ${String(candidate.detail)}`
+	};
+	if (baseline.violations?.length) return {
+		label: "intended",
+		reason: `baseline broke a rule: ${list(baseline.violations)}`
+	};
+	const sameOutcome = baseline.outcome === candidate.outcome;
+	if (sameOutcome && structurallyEqual(baseline.effects, candidate.effects)) return {
+		label: "same",
+		reason: ""
+	};
+	if (expected !== void 0 && candidate.outcome === expected && baseline.outcome !== expected) return {
+		label: "intended",
+		reason: `only the candidate reached the expected '${expected}'`
+	};
+	return {
+		label: "regression",
+		reason: sameOutcome ? "effects differ" : `outcome differs: ${baseline.outcome} → ${candidate.outcome}`
+	};
+}
+function list(items) {
+	return items.map((item) => typeof item === "string" ? item : JSON.stringify(item)).join(", ");
+}
+function structurallyEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+	if (a instanceof Map || b instanceof Map) return a instanceof Map && b instanceof Map && structurallyEqual([...a], [...b]);
+	if (a instanceof Set || b instanceof Set) return a instanceof Set && b instanceof Set && structurallyEqual([...a], [...b]);
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => structurallyEqual(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) => Object.hasOwn(b, key) && structurallyEqual(a[key], b[key]));
+}
+//#endregion
+export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, compareRuns, explorePaths, foldTraces, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };