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

package/dist/{src-CEa947Dm.mjs → run-agent-7OaHM7SB.mjs}

@@ -1,5 +1,5 @@
-import { A as userInputActor, B as getAgentMessages, C as createTextLogic, D as isTextLogic, F as isUnboundPlaceholder, H as getJsonSchemaSync, I as machineSuspensionPredicates, L as missingActor, M as executorBoundLogics, N as getMachineSuspensionPredicate, O as normalizeGeneratorResult, P as getRegisteredAgentExecutionOptions, R as assistantMessage, S as builtinTextActors, U as getMachineStructuralHash, X as validateSchemaSync, Y as userMessage, _ as INTERPRET_SOURCE, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, j as agentExecutionOptions, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as PLAN_ACTOR, w as executeAgentTextRequest, y as USER_INPUT_ACTOR, z as findNonSerializableContextPaths } from "./decision-D1654JdD.mjs";
-import { createActor, createAsyncLogic, getNextTransitions, initialTransition, setup, transition } from "xstate";
+import { $ as validateSchemaSync, B as missingActor, C as createTextLogic, D as isTextLogic, F as getMachineSuspensionPredicate, H as findNonSerializableContextPaths, I as getRegisteredAgentExecutionOptions, K as getMachineStructuralHash, M as userInputActor, N as agentExecutionOptions, O as normalizeGeneratorResult, P as executorBoundLogics, Q as userMessage, R as isUnboundPlaceholder, S as builtinTextActors, U as getAgentMessages, V as assistantMessage, _ as INTERPRET_SOURCE, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as PLAN_ACTOR, y as USER_INPUT_ACTOR, z as machineSuspensionPredicates } from "./decision-CQdrKc8k.mjs";
+import { createActor, createAsyncLogic, getNextTransitions, setup } from "xstate";
 //#region src/messages.ts
 function addMessages(resolve) {
 	return (args) => {
@@ -260,6 +260,16 @@ function setupAgentFromConfig(config, options) {
 }
 //#endregion
 //#region src/setup-agent.ts
+const emptyEventSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return value !== null && typeof value === "object" && Object.keys(value).length === 0 ? { value: {} } : { issues: [{ message: "Expected an empty event payload" }] };
+	}
+} };
+function normalizeEventSchemas(events) {
+	return Object.fromEntries(Object.entries(events).map(([type, schema]) => [type, schema && typeof schema === "object" && "~standard" in schema ? schema : emptyEventSchema]));
+}
 /**
 * Builds a machine's {@link AgentSchemaPack} from a partial schema
 * declaration — only `context` is required; `events`/`input`/`output`/`meta`
@@ -271,13 +281,50 @@ function setupAgentFromConfig(config, options) {
 function createAgentSchemas(schemas) {
 	return {
 		context: schemas.context,
-		events: schemas.events ?? {},
+		events: normalizeEventSchemas(schemas.events ?? {}),
 		input: schemas.input,
 		output: schemas.output,
 		meta: schemas.meta,
 		emitted: schemas.emitted
 	};
 }
+function mergeContextSchema(base, fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			const baseResult = base["~standard"].validate(value);
+			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+			if (baseResult.issues) return baseResult;
+			const merged = { ...baseResult.value };
+			const issues = [];
+			for (const [key, fieldSchema] of Object.entries(fields)) {
+				const fieldResult = fieldSchema["~standard"].validate(value[key]);
+				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
+					...issue,
+					path: [key, ...issue.path ?? []]
+				})));
+				else merged[key] = fieldResult.value;
+			}
+			return issues.length > 0 ? { issues } : { value: merged };
+		}
+	} };
+}
+function resolveAgentStateSchemas(contextSchema, states) {
+	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
+		if (!state || typeof state !== "object") return [key, state];
+		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
+		if ("context" in state && state.context) return [key, {
+			schemas: { context: mergeContextSchema(contextSchema, state.context) },
+			...children ? { states: children } : {}
+		}];
+		return [key, children ? {
+			...state,
+			states: children
+		} : state];
+	}));
+}
 /**
 * Schema-first `setup(...)` for agent machines — the standard entry point
 * for authoring a machine (the blueprint) that this library then runs (via
@@ -358,7 +405,12 @@ function createRequestActors(requests) {
 	}));
 }
 function normalizeAgentSchemas(config) {
-	return "schemas" in config ? config.schemas : createAgentSchemas(config);
+	if ("schemas" in config && config.schemas) return config.schemas;
+	const loose = config;
+	return createAgentSchemas({
+		...loose,
+		context: loose.context
+	});
 }
 function normalizeAgentRequestInput(requests) {
 	return requests ?? {};
@@ -418,7 +470,7 @@ function createAgentSetupConfig(schemas, actorSources, config) {
 			meta: schemas.meta,
 			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
 		},
-		...config.states ? { states: config.states } : {},
+		...config.states ? { states: resolveAgentStateSchemas(schemas.context, config.states) } : {},
 		actorSources,
 		actions: config.actions,
 		guards: config.guards,
@@ -431,11 +483,12 @@ function createSetupAgent(config) {
 	const actorSources = createAgentActorSources(config.actorSources, requestActors);
 	const base = setup(createAgentSetupConfig(schemas, actorSources, config));
 	const createBaseMachine = base.createMachine.bind(base);
+	const models = config.models ?? {};
 	const machineOptions = {
 		schemas,
-		actorSources
+		actorSources,
+		models
 	};
-	const models = config.models ?? {};
 	return Object.assign(base, {
 		createMachine(machineConfig) {
 			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
@@ -455,370 +508,6 @@ function createSetupAgent(config) {
 	});
 }
 //#endregion
-//#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
-*/
-/**
-* 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) => {
-		if (action.type !== "xstate.spawnChild" && action.type !== "@xstate.start") return [];
-		const params = action.type === "@xstate.start" ? action : action.params;
-		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(action.logic) || isDecisionLogic(action.logic) ? action.logic : options.actorSources?.[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,
-				eventToolName: options.eventToolName
-			}) : [];
-			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: []
-		}];
-	}), ...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 (!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 = 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: PLAN_DONE_EVENT_TYPE,
-			toolName: sanitizeEventToolName(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 = 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));
-}
-/**
-* 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, {
-		...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 executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
-	const normalizedOutput = request.input.outputSchema ? 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 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 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 '${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 (!isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
-	Object.assign(childSnapshot, 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/internal/state-request-pass.ts
 async function runTextPhase(stateRequest, baseMessages, deps) {
 	const { model, system } = stateRequest;
@@ -1839,611 +1528,4 @@ function collectPendingUserInputs(snapshot) {
 	return pending;
 }
 //#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 (isDecisionLogic(logic)) return "decision";
-		if (isPlanLogic(logic)) return "plan";
-		return;
-	}
-	if (isDecisionLogic(src)) return "decision";
-	if (isPlanLogic(src)) return "plan";
-}
-function isAgentLogicNeedingBinding(src) {
-	return (isTextLogic(src) || isDecisionLogic(src) || isPlanLogic(src)) && !executorBoundLogics.has(src);
-}
-function schemaExposesJson(schema) {
-	if (!schema) return false;
-	try {
-		return getJsonSchemaSync(schema) !== void 0;
-	} catch {
-		return false;
-	}
-}
-function isDeclaredOutputSchema(schema) {
-	if (!schema) return false;
-	let json;
-	try {
-		json = 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 = 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 type = action.type;
-		if (type !== "xstate.spawnChild" && type !== "@xstate.start") continue;
-		const params = type === "@xstate.start" ? action : action.params ?? {};
-		if (typeof params.src === "string" && typeof params.id === "string") out.push({
-			id: params.id,
-			src: params.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 })) : 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
-export { createAgentSchemas as _, AgentIdleError as a, messagesSchema as b, inspectTransitions as c, executeAgentRequest as d, getAgentRequests as f, transitionAgentStep as g, resolveAgentStep as h, simulateAgent as i, runAgent as l, resolveAgentRequests as m, explorePaths as n, IllegalResumeEventError as o, initialAgentStep as p, lintAgentMachine as r, SnapshotVersionMismatchError as s, canReach as t, runAgentToCompletion as u, setupAgent as v, appendMessages as y };
+export { runAgent as a, setupAgent as c, inspectTransitions as i, appendMessages as l, IllegalResumeEventError as n, runAgentToCompletion as o, SnapshotVersionMismatchError as r, createAgentSchemas as s, AgentIdleError as t, messagesSchema as u };