@statelyai/agent 2.0.0-alpha.7 → 2.0.0-alpha.8

package/dist/src-CFtSqm-c.cjs

@@ -0,0 +1,1043 @@
+require("./run-agent-BQ3vV7UI.cjs");
+const require_decision = require("./decision-b-lkcs4L.cjs");
+let xstate = require("xstate");
+//#region src/steps.ts
+/**
+* The step path: durable, per-model-call-checkpoint hosting of an agent
+* machine. Public vocabulary — `initialAgentStep`, `transitionAgentStep`,
+* `resolveAgentStep`, `getAgentRequests`, `executeAgentRequest`,
+* `resolveAgentRequests`.
+* @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;
+}
+/**
+* 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}. The hand-passed-schemas
+* implementation detail behind the public {@link getAgentRequests} — it needs
+* `schemas`/`actorSources` passed explicitly, whereas `getAgentRequests`
+* pre-fills them from the machine's registered `setupAgent` options.
+* `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 getAgentRequestsWith(actions, 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 = require_decision.isTextLogic(params.logic) || require_decision.isDecisionLogic(params.logic) ? params.logic : options.actorSources?.[params.src];
+		if (require_decision.isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? require_decision.getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = require_decision.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: []
+		}];
+	}), ...getActivePlanRequests(options)];
+}
+/**
+* Scans the live snapshot's children for active `agent.plan` (plan-logic)
+* invokes and lowers each into an {@link AgentPlanRequest} — the re-surfacing
+* half of plan discovery. Reads the applied-event trail and remaining budget
+* from the child's own ledger `context` ({@link PlanLedgerContext}), recomputes
+* the currently-legal candidates (∩ declared `allowedEvents`) plus the reserved
+* `agent.plan.done` move, and takes `stepsRemaining` from the ledger (falling
+* back to `maxSteps - applied.length` for a snapshot with no context yet).
+* Returns `[]` when no snapshot is available (candidates need a live snapshot).
+*
+* @internal
+*/
+function getActivePlanRequests(options) {
+	const snapshot = options.snapshot;
+	if (!snapshot) return [];
+	const children = snapshot.children;
+	if (!children) return [];
+	const requests = [];
+	for (const [id, child] of Object.entries(children)) {
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const src = typeof ref.src === "string" ? ref.src : void 0;
+		const logic = (src ? options.actorSources?.[src] : void 0) ?? ref.logic;
+		if (!require_decision.isPlanLogic(logic)) continue;
+		const childSnapshot = ref.getSnapshot();
+		if (childSnapshot?.status !== "active") continue;
+		const input = childSnapshot.input ?? {};
+		const maxSteps = input.maxSteps ?? 8;
+		const ledger = childSnapshot.context ?? {};
+		const applied = ledger.applied ?? [];
+		const stepsRemaining = ledger.stepsRemaining ?? maxSteps - applied.length;
+		const machineEvents = require_decision.getAcceptedEvents(snapshot, {
+			events: options.events,
+			schemas: options.schemas,
+			eventTypes: logic.allowedEventTypes(input) ?? void 0,
+			eventToolName: options.eventToolName
+		});
+		const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, {
+			type: require_decision.PLAN_DONE_EVENT_TYPE,
+			toolName: require_decision.sanitizeEventToolName(require_decision.PLAN_DONE_EVENT_TYPE)
+		}];
+		requests.push({
+			kind: "plan",
+			id,
+			src: src ?? "",
+			input,
+			events,
+			applied,
+			stepsRemaining: Math.max(0, stepsRemaining)
+		});
+	}
+	return requests;
+}
+/**
+* Builds the synthetic `xstate.done.actor.<id>` event xstate's `transition()`
+* expects to resolve a spawned invoke — the event {@link resolveAgentStep}
+* applies internally.
+*
+* @internal
+*/
+function doneEvent(request, output) {
+	return {
+		type: `xstate.done.actor.${typeof request === "string" ? request : request.id}`,
+		output
+	};
+}
+/**
+* Applies a request's `output` as a done event via `transition(...)`,
+* returning the raw `[snapshot, actions]` tuple. Lower-level than
+* {@link resolveAgentStep} — that helper wraps this and also runs
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output) {
+	const event = doneEvent(request, output);
+	const result = (0, xstate.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] = (0, xstate.initialTransition)(machine, input);
+	return createAgentStep(machine, snapshot, actions, require_decision.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] = (0, xstate.transition)(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, require_decision.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, require_decision.getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Snapshot in, requests out: scans executable actions for spawned agent
+* invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+* the machine's registered `setupAgent` schemas/actorSources (so callers
+* don't pass them by hand each call) — merged with any `options` passed here,
+* which take precedence. The step path's public discovery primitive;
+* `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+* internally to populate `AgentStep.requests`.
+*/
+function getAgentRequests(machine, actions, snapshot, options = {}) {
+	return getAgentRequestsWith(actions, {
+		...require_decision.getRegisteredAgentExecutionOptions(machine, options),
+		...options,
+		snapshot
+	});
+}
+async function executeAgentRequest(request, executors, options) {
+	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	assertTextExecutor(request, executors);
+	const { output, raw } = await require_decision.executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	const normalizedOutput = request.input.outputSchema ? require_decision.validateSchemaSync(request.input.outputSchema, output) : output;
+	return options?.verbose ? {
+		output: normalizedOutput,
+		raw
+	} : normalizedOutput;
+}
+/**
+* Resolves the current step's pending requests and returns the next
+* {@link AgentStep} — one iteration of the durable step loop, collapsing the
+* manual `request.kind` dispatch a host would otherwise write by hand.
+*
+* For each pending request, in order: a `kind: 'text'` request is run with
+* {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+* `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+* `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+* applied with {@link transitionAgentStep}. The **current** step is re-read
+* after each application — the machine may advance and its `requests` change —
+* so this always resolves against the live step, never a stale list.
+*
+* A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+* step per call. It resolves a single decision from `request.events` (wiring
+* `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+* move and `stopOn` events), then either applies the chosen machine event and
+* lets the next step re-surface the plan, or completes the plan (feeding its
+* `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+* exhausted budget / no legal events. The plan's applied trail is carried in
+* the invoke child's snapshot, so persisting the step between calls resumes the
+* plan identically.
+*
+* Missing the executor a request needs throws a clear error
+* (`generateText`/`streamText` for text, `decide` for decisions and plans).
+*
+* A complete durable host is two lines:
+*
+* ```ts
+* let step = initialAgentStep(machine, input);
+* while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+* ```
+*
+* All pending **text** requests of a step are resolved in parallel
+* (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+* their model calls run concurrently — then their outputs apply in
+* **request-array order** (deterministic for durable replay regardless of which
+* call finishes first). Decisions and plans stay **one at a time**: applying
+* either changes the set of legal candidates for what follows, so they cannot be
+* resolved against a stale snapshot. A host that instead wants strictly
+* sequential text resolution loops the manual per-request helpers
+* ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+*/
+async function resolveAgentRequests(machine, step, executors, options) {
+	const [request] = step.requests;
+	if (!request) return step;
+	if (request.kind === "decision") {
+		if (!executors.decide) throw new Error(`this step's decision request '${request.id}' needs a 'decide' executor but none was provided.`);
+		return transitionAgentStep(machine, step, await require_decision.resolveDecision(request, executors.decide, {
+			canTake: (event) => step.snapshot.can(event),
+			maxRetries: options?.maxRetries
+		}), options);
+	}
+	if (request.kind === "plan") return resolvePlanRequest(machine, step, request, executors, options);
+	const textRequests = step.requests.filter((candidate) => candidate.kind === "text");
+	for (const textRequest of textRequests) assertTextExecutor(textRequest, executors);
+	const outputs = await Promise.all(textRequests.map((textRequest) => executeAgentRequest(textRequest, executors)));
+	let next = step;
+	for (let index = 0; index < textRequests.length; index++) next = resolveAgentStep(machine, next, textRequests[index], outputs[index], options);
+	return next;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+async function resolvePlanRequest(machine, step, request, executors, options) {
+	if (!executors.decide) throw new Error(`this step's plan request '${request.src}' needs a 'decide' executor but none was provided.`);
+	const stopOn = new Set(request.input.stopOn ?? []);
+	if (request.stepsRemaining <= 0) return completePlan(machine, step, request.id, request.applied, "max-steps", options);
+	if (request.events.filter((event) => event.type !== "agent.plan.done").length === 0) return completePlan(machine, step, request.id, request.applied, "no-legal-events", options);
+	const chosen = await require_decision.resolveDecision(planStepDecisionRequest(request), executors.decide, {
+		maxRetries: options?.maxRetries,
+		canTake: (event) => {
+			if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+			return step.snapshot.can(event);
+		}
+	});
+	if (chosen.type === "agent.plan.done") return completePlan(machine, step, request.id, request.applied, "done", options);
+	const applied = [...request.applied, chosen];
+	advancePlanChildLedger(step.snapshot, request.id, {
+		type: "plan.applied",
+		event: chosen
+	});
+	const next = transitionAgentStep(machine, step, chosen, options);
+	if (stopOn.has(chosen.type)) {
+		if (isPlanActive(next.snapshot, request.id)) return completePlan(machine, next, request.id, applied, "stop-event", options);
+	}
+	return next;
+}
+function completePlan(machine, step, id, steps, stopped, options) {
+	return resolveAgentStep(machine, step, { id }, {
+		steps,
+		stopped
+	}, options);
+}
+function planStepDecisionRequest(request) {
+	const { input, applied, events, id } = request;
+	const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+	const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${require_decision.PLAN_DONE_EVENT_TYPE}'.`;
+	return {
+		kind: "decision",
+		id: `${id}[${applied.length}]`,
+		model: input.model,
+		system: input.system,
+		prompt: `${input.prompt ?? ""}${trail}${doneHint}`,
+		messages: input.messages,
+		events,
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function advancePlanChildLedger(snapshot, id, event) {
+	const child = snapshot.children?.[id];
+	const childSnapshot = child?.getSnapshot?.();
+	if (!require_decision.isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
+	Object.assign(childSnapshot, require_decision.advancePlanLedger(child.logic, childSnapshot, event));
+}
+function isPlanActive(snapshot, id) {
+	return (snapshot.children?.[id])?.getSnapshot?.()?.status === "active";
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequestsWith(actions, {
+			...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";
+const PLAN_SRC = "agent.plan";
+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,
+				name,
+				config,
+				parentPath,
+				type: config.type,
+				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 childrenOf(index, parentPath) {
+	const out = [];
+	for (const node of index.values()) if (node.parentPath === parentPath) out.push(node);
+	return out;
+}
+function collectTransitionTargets(value, fromNode, index, out) {
+	if (value === void 0 || value === null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) collectTransitionTargets(item, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "function") {
+		out.opaque = true;
+		return;
+	}
+	if (typeof value === "string") {
+		resolveTargetString(value, fromNode, index, out);
+		return;
+	}
+	if (typeof value === "object") {
+		const target = value.target;
+		if (target !== void 0) collectTransitionTargets(target, fromNode, index, out);
+	}
+}
+function resolveTargetString(target, fromNode, index, out) {
+	if (target.startsWith("#")) {
+		out.opaque = true;
+		return;
+	}
+	const resolved = target.startsWith(".") ? `${fromNode.path}.${target.slice(1)}` : fromNode.parentPath ? `${fromNode.parentPath}.${target}` : target;
+	if (index.has(resolved)) out.targets.push(resolved);
+	else out.opaque = true;
+}
+function outgoingTargets(node, index) {
+	const out = {
+		targets: [],
+		opaque: false
+	};
+	const { config } = node;
+	for (const value of Object.values(config.on ?? {})) collectTransitionTargets(value, node, index, out);
+	collectTransitionTargets(config.always, node, index, out);
+	collectTransitionTargets(config.choice, node, index, out);
+	for (const value of Object.values(config.after ?? {})) collectTransitionTargets(value, node, index, out);
+	collectTransitionTargets(config.onDone, node, index, out);
+	for (const invoke of node.invokes) {
+		collectTransitionTargets(invoke.onDone, node, index, out);
+		collectTransitionTargets(invoke.onError, node, index, out);
+	}
+	return out;
+}
+function computeReachable(rootConfig, index) {
+	const reachable = /* @__PURE__ */ new Set();
+	const queue = [];
+	const markAncestors = (path) => {
+		let parent = index.get(path)?.parentPath ?? "";
+		while (parent) {
+			reachable.add(parent);
+			parent = index.get(parent)?.parentPath ?? "";
+		}
+	};
+	const enter = (path) => {
+		if (reachable.has(path)) return;
+		const node = index.get(path);
+		if (!node) return;
+		reachable.add(path);
+		queue.push(path);
+		markAncestors(path);
+		if (node.isParallel) for (const child of childrenOf(index, path)) enter(child.path);
+		else if (node.isCompound && node.config.initial) enter(`${path}.${node.config.initial}`);
+	};
+	if (rootConfig.type === "parallel") for (const child of childrenOf(index, "")) enter(child.path);
+	else if (rootConfig.initial) enter(rootConfig.initial);
+	while (queue.length > 0) {
+		const node = index.get(queue.shift());
+		if (!node) continue;
+		const { targets, opaque } = outgoingTargets(node, index);
+		for (const target of targets) enter(target);
+		if (opaque) for (const sibling of childrenOf(index, node.parentPath)) enter(sibling.path);
+	}
+	return reachable;
+}
+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 decisionKindOf(src, actorSources) {
+	if (typeof src === "string") {
+		if (src === DECIDE_SRC) return "decision";
+		if (src === PLAN_SRC) return "plan";
+		const logic = actorSources[src];
+		if (require_decision.isDecisionLogic(logic)) return "decision";
+		if (require_decision.isPlanLogic(logic)) return "plan";
+		return;
+	}
+	if (require_decision.isDecisionLogic(src)) return "decision";
+	if (require_decision.isPlanLogic(src)) return "plan";
+}
+function isAgentLogicNeedingBinding(src) {
+	return (require_decision.isTextLogic(src) || require_decision.isDecisionLogic(src) || require_decision.isPlanLogic(src)) && !require_decision.executorBoundLogics.has(src);
+}
+function schemaExposesJson(schema) {
+	if (!schema) return false;
+	try {
+		return require_decision.getJsonSchemaSync(schema) !== void 0;
+	} catch {
+		return false;
+	}
+}
+function isDeclaredOutputSchema(schema) {
+	if (!schema) return false;
+	let json;
+	try {
+		json = require_decision.getJsonSchemaSync(schema);
+	} catch {
+		return false;
+	}
+	if (!json) return false;
+	const properties = json.properties;
+	const required = json.required;
+	return json.type === "object" && !!properties && Object.keys(properties).length > 0 || Array.isArray(required) && required.length > 0;
+}
+function checkUnreachableStates(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) if (!ctx.reachable.has(node.path)) out.push({
+		code: "unreachable-state",
+		severity: "error",
+		path: node.path,
+		message: `State '${node.path}' is unreachable: no transition, always, onDone, or onError target (from any reachable state) leads to it. Remove it or add a transition.`
+	});
+	return out;
+}
+function checkDecideWithoutEvents(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
+		const kind = decisionKindOf(invoke.src, ctx.actorSources);
+		if (!kind) 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 ${kind} source '${srcName}', but neither it nor any ancestor handles any event (no 'on:'), so the ${kind}'s chosen event can never be delivered. Add an 'on:' handler for the candidate events.`
+		});
+	}
+	return out;
+}
+function checkUnserializableContext(ctx) {
+	const contextSchema = ctx.schemas?.context;
+	if (!contextSchema) return [];
+	if (schemaExposesJson(contextSchema)) return [];
+	return [{
+		code: "unserializable-context",
+		severity: "warning",
+		path: "context",
+		message: "The context schema does not expose a JSON schema (e.g. a `z.custom` without a `jsonSchema` extension, such as a messages array), so its fields cannot be statically checked for JSON persist/resume round-tripping. This is expected for message transcripts; verify any other custom-typed context is JSON-serializable."
+	}];
+}
+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({ actorSources: { name: logic } })) and invoke it by name.`
+		});
+	}
+	return out;
+}
+function checkFinalWithoutOutput(ctx) {
+	if (!isDeclaredOutputSchema(ctx.schemas?.output)) return [];
+	if (ctx.config.output !== void 0) return [];
+	const out = [];
+	for (const node of ctx.index.values()) {
+		if (node.parentPath !== "" || !node.isFinal) continue;
+		if (node.config.output === void 0) out.push({
+			code: "final-without-output",
+			severity: "error",
+			path: node.path,
+			message: `The machine declares an output schema, but top-level final state '${node.path}' has no 'output'. Its snapshot output will be undefined and fail the schema. Add an 'output' to this final state (or a root 'output').`
+		});
+	}
+	return out;
+}
+function outputFnReadsEvent(fn) {
+	return /\bevent\s*(?:\.|\?\.|\[)/.test(fn.toString());
+}
+function checkFinalOutputReadsEvent(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) {
+		if (node.parentPath !== "" || !node.isFinal) continue;
+		const output = node.config.output;
+		if (typeof output !== "function") continue;
+		if (!outputFnReadsEvent(output)) continue;
+		out.push({
+			code: "final-output-reads-event",
+			severity: "warning",
+			path: node.path,
+			message: `Final state '${node.path}' has an 'output' function that reads 'event'. Final-state 'output' functions are evaluated more than once with different events (the entering event, then the machine-done computation) under current xstate behavior, so 'event' is unreliable here. Read 'context' only; capture what you need from the entering event into context in the transition that targets this state. (This guard can relax if xstate guarantees a stable entering event across evaluations.)`
+		});
+	}
+	return out;
+}
+function checkMissingFinal(ctx) {
+	for (const node of ctx.index.values()) if (node.isFinal && ctx.reachable.has(node.path)) return [];
+	return [{
+		code: "missing-final",
+		severity: "warning",
+		path: "(root)",
+		message: "The machine has no reachable final state, so a run can never settle 'done' (only idle/looping). This is legal for agents that only idle, but verify it is intended."
+	}];
+}
+const LINT_CHECKS = [
+	checkUnreachableStates,
+	checkDecideWithoutEvents,
+	checkUnserializableContext,
+	checkDirectObjectSrc,
+	checkFinalWithoutOutput,
+	checkFinalOutputReadsEvent,
+	checkMissingFinal
+];
+/**
+* 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 dead states, undeliverable decisions, un-rebindable
+* invoke srcs, and output-contract gaps before ever running it.
+*
+* @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'));
+* ```
+*/
+function lintAgentMachine(machine, options = {}) {
+	const config = machine.config ?? {};
+	const index = buildStateIndex(config);
+	const reachable = computeReachable(config, index);
+	const registered = require_decision.getRegisteredAgentExecutionOptions(machine);
+	const ctx = {
+		machine,
+		config,
+		index,
+		reachable,
+		schemas: registered.schemas,
+		actorSources: registered.actorSources ?? machine.implementations?.actorSources ?? {}
+	};
+	const disabled = new Set(options.disable ?? []);
+	return LINT_CHECKS.flatMap((check) => check(ctx)).filter((d) => !disabled.has(d.code));
+}
+function pendingInvokes(step) {
+	const out = [];
+	for (const action of step.actions) {
+		const metadata = getInvokeEffectMetadata(action);
+		if (typeof metadata?.src === "string" && typeof metadata.id === "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.
+*
+* 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: 'END' }] } },
+* });
+* ```
+*/
+async function simulateAgent(machine, options) {
+	const maxSteps = options.maxSteps ?? 100;
+	const script = {
+		text: { ...options.script.text },
+		decisions: mapValues(options.script.decisions ?? {}, (arr) => [...arr]),
+		userInput: mapValues(options.script.userInput ?? {}, (arr) => [...arr])
+	};
+	let step = initialAgentStep(machine, options.input);
+	const trail = [];
+	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 decisionSrc = new Map(pendingInvokes(step).map((invoke) => [invoke.id, invoke.src])).get(request.id) ?? request.id;
+				const taken = takeFromQueue(script.decisions, decisionSrc);
+				if (!taken.found) throw scriptDryError("decision", decisionSrc, request.id, request);
+				step = transitionAgentStep(machine, step, taken.value);
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			if (request.kind === "plan") {
+				const taken = takeFromQueue(script.decisions, request.src);
+				if (!taken.found) throw scriptDryError("decision", request.src, request.id, request);
+				const event = taken.value;
+				step = await resolveAgentRequests(machine, step, { decide: async () => ({ event }) });
+				trail.push({
+					state: step.snapshot.value,
+					appliedEvent: taken.value
+				});
+				continue;
+			}
+			const taken = takeFromQueue(script.text, request.src);
+			if (!taken.found) throw scriptDryError("text", request.src, request.id);
+			step = resolveAgentStep(machine, step, request, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "text",
+					src: request.src,
+					id: request.id
+				}
+			});
+			continue;
+		}
+		const [invoke] = pendingInvokes(step);
+		if (invoke) {
+			const taken = takeFromQueue(script.userInput, invoke.src);
+			if (!taken.found) throw scriptDryError("userInput", invoke.src, invoke.id);
+			step = resolveAgentStep(machine, step, invoke.id, taken.value);
+			trail.push({
+				state: step.snapshot.value,
+				resolvedRequest: {
+					kind: "userInput",
+					src: invoke.src,
+					id: invoke.id
+				}
+			});
+			continue;
+		}
+		return {
+			status: "idle",
+			snapshot: step.snapshot,
+			trail
+		};
+	}
+	return {
+		status: "exhausted",
+		snapshot: step.snapshot,
+		trail
+	};
+}
+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)"}.` : "";
+	return /* @__PURE__ */ new Error(`simulateAgent: script ran dry on a pending ${kind} request for src '${src}' (id '${id}'). Add a '${kind}' entry for '${src}' to the script.${events}`);
+}
+async function explore(machine, options, stopWhen) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxPaths = options.maxPaths ?? 200;
+	const textOutputs = options.textOutputs ?? {};
+	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 < 1e3; i++) {
+			if (current.done) return { step: current };
+			const request = current.requests[0];
+			if (request && request.kind === "text") {
+				if (!(request.src in textOutputs)) return {
+					step: current,
+					blockedSrc: request.src
+				};
+				current = resolveAgentStep(machine, current, request, textOutputs[request.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			if (request && (request.kind === "decision" || request.kind === "plan")) return { step: current };
+			const [invoke] = pendingInvokes(current);
+			if (invoke) {
+				if (!(invoke.src in textOutputs)) return {
+					step: current,
+					blockedSrc: invoke.src
+				};
+				current = resolveAgentStep(machine, current, invoke.id, textOutputs[invoke.src]);
+				recordState(current.snapshot);
+				continue;
+			}
+			return { step: current };
+		}
+		return { step: current };
+	};
+	const visit = async (step, path, depth) => {
+		if (witness !== void 0) return;
+		if (pathsExplored >= maxPaths) {
+			hitPathCap = true;
+			return;
+		}
+		const { step: settled, blockedSrc } = advance(step);
+		if (stopWhen?.(settled.snapshot)) {
+			witness = path;
+			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;
+		}
+		const request = settled.requests[0];
+		const isPlan = request?.kind === "plan";
+		const branchEvents = request?.kind === "decision" || request?.kind === "plan" ? request.events.map((descriptor) => ({ type: descriptor.type })) : require_decision.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 (!(isPlan && event.type === "agent.plan.done") && !settled.snapshot.can(event)) {
+				prunedByGuard++;
+				continue;
+			}
+			const next = isPlan ? await resolveAgentRequests(machine, settled, { decide: async () => ({ event }) }) : 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. A `agent.plan` request
+* forks the same way — one branch per candidate, including the reserved
+* `agent.plan.done` move — advancing each branch through the real plan protocol
+* (`resolveAgentRequests`), so a plan can consume several depth units. Text/`userInput` invokes
+* are resolved from `textOutputs` (a by-src canned-output map) — a missing src
+* halts that branch with a `needs-output` terminal rather than throwing.
+*
+* 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;
+}
+/**
+* Answers "can the machine reach `statePath`?" by exploring its branches (a
+* thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
+* with the event sequence that reaches it, or `{ canReach: false }`.
+*
+* @example
+* ```ts
+* const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+* // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+* ```
+*/
+async function canReach(machine, statePath, options = {}) {
+	const { witness } = await explore(machine, options, (snapshot) => {
+		try {
+			return snapshot.matches(statePath);
+		} catch {
+			return false;
+		}
+	});
+	return witness !== void 0 ? {
+		canReach: true,
+		witness
+	} : { canReach: false };
+}
+//#endregion
+Object.defineProperty(exports, "canReach", {
+	enumerable: true,
+	get: function() {
+		return canReach;
+	}
+});
+Object.defineProperty(exports, "executeAgentRequest", {
+	enumerable: true,
+	get: function() {
+		return executeAgentRequest;
+	}
+});
+Object.defineProperty(exports, "explorePaths", {
+	enumerable: true,
+	get: function() {
+		return explorePaths;
+	}
+});
+Object.defineProperty(exports, "getAgentRequests", {
+	enumerable: true,
+	get: function() {
+		return getAgentRequests;
+	}
+});
+Object.defineProperty(exports, "initialAgentStep", {
+	enumerable: true,
+	get: function() {
+		return initialAgentStep;
+	}
+});
+Object.defineProperty(exports, "lintAgentMachine", {
+	enumerable: true,
+	get: function() {
+		return lintAgentMachine;
+	}
+});
+Object.defineProperty(exports, "resolveAgentRequests", {
+	enumerable: true,
+	get: function() {
+		return resolveAgentRequests;
+	}
+});
+Object.defineProperty(exports, "resolveAgentStep", {
+	enumerable: true,
+	get: function() {
+		return resolveAgentStep;
+	}
+});
+Object.defineProperty(exports, "simulateAgent", {
+	enumerable: true,
+	get: function() {
+		return simulateAgent;
+	}
+});
+Object.defineProperty(exports, "transitionAgentStep", {
+	enumerable: true,
+	get: function() {
+		return transitionAgentStep;
+	}
+});