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

package/dist/{setup-agent-CFW-jPI8.mjs → setup-agent-BuanDXeh.mjs}

@@ -1,5 +1,5 @@
-import { E as setAgentExecutionOptions, T as missingActor, V as validateSchemaSync, b as getAgentExecutionOptions, n as DECIDE_ACTOR, o as builtinTextActors, s as createTextLogic, w as machineIdlePredicates } from "./text-logic-Bl_ZRxDi.mjs";
-import { n as createDecideActor } from "./decision-DzSv1NpD.mjs";
+import { C as setAgentExecutionOptions, R as validateSchemaSync, S as missingActor, n as DECIDE_ACTOR, o as builtinTextActors, s as createTextLogic, y as getAgentExecutionOptions } from "./text-logic-CIqHAmBi.mjs";
+import { n as createDecideActor } from "./decision-RQ0iv0oZ.mjs";
 import { t as AGENT_USAGE_EVENT_TYPE } from "./usage-BdEjFuIi.mjs";
 import { createMachineFromConfig, setup } from "xstate";
 //#region src/workflow-config.ts
@@ -273,22 +273,6 @@ function translateWorkflowConfig(config, translation) {
 	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
 	return json;
 }
-function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
-	for (const state of Object.values(states ?? {})) {
-		for (const tag of state.tags ?? []) tags.add(tag);
-		collectDeclaredStateTags(state.states, tags);
-	}
-	return tags;
-}
-function resolveIdlePredicate(config, options) {
-	if (options.isIdle) return options.isIdle;
-	const idleTags = config.idleTags ?? [];
-	if (!idleTags.length) return;
-	const declaredTags = collectDeclaredStateTags(config.states);
-	const unknown = idleTags.filter((tag) => !declaredTags.has(tag));
-	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'idleTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
-	return (snapshot) => idleTags.some((tag) => snapshot.hasTag(tag));
-}
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
 	const { compileSchema } = options;
@@ -310,16 +294,14 @@ function setupAgentFromConfig(config, options) {
 			event: args.event
 		}))])),
 		...options.actions ? { actions: options.actions } : {},
-		actors: Object.fromEntries(Object.keys(actors).map((key) => [key, key])),
+		actors,
 		evaluators: { [AGENT_EXPRESSION_LANG]: createWorkflowConfigEvaluator(schemas.context) }
-	}).provide({ actors });
+	});
 	setAgentExecutionOptions(machine, {
 		schemas,
 		actors,
 		models: {}
 	});
-	const isIdle = resolveIdlePredicate(config, options);
-	if (isIdle && machine.config) machineIdlePredicates.set(machine.config, isIdle);
 	return {
 		machine,
 		schemas
@@ -388,7 +370,7 @@ const agentUsageEventSchema = { "~standard": {
 * Adds the reserved `'@agent.usage'` schema to an authored event map. A
 * user-declared entry under that key is rejected: the `@agent.*` namespace
 * belongs to the library (same rule as the reserved `agent.*` actor keys), and
-* a custom payload schema would silently disagree with what `runAgent`
+* a custom payload schema would silently disagree with what the runtime
 * delivers.
 */
 function withAgentUsageEventSchema(events) {
@@ -423,7 +405,7 @@ function createAgentSchemas(schemas) {
 /**
 * Schema-first `setup(...)` for agent machines — the standard entry point
 * for authoring a machine (the blueprint) that this library then runs (via
-* {@link runAgent} or the step helpers) against host-supplied model/decision
+* {@link createAgentRuntime}) against host-supplied model/decision
 * executors. Context, events, machine input, machine output, and
 * state/transition meta are all standard schemas — no `{} as Type` casts —
 * and are retained on `result.schemas` for runtime validation. Also
@@ -496,10 +478,6 @@ function setupAgent(config) {
 			assertStateSchemaKeysExist(config.states, machineConfig?.states);
 			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
 			setAgentExecutionOptions(machine, machineOptions);
-			if (config.isIdle) {
-				const rootConfig = machine.config;
-				if (rootConfig) machineIdlePredicates.set(rootConfig, config.isIdle);
-			}
 			return machine;
 		},
 		schemas,

package/dist/{setup-agent-CPf7MxnG.cjs → setup-agent-DV4cTou-.cjs}

@@ -1,5 +1,5 @@
-const require_text_logic = require("./text-logic-C8xyr6Ag.cjs");
-const require_decision = require("./decision-CM9CYZ6t.cjs");
+const require_text_logic = require("./text-logic-f5F5sCdc.cjs");
+const require_decision = require("./decision-CmM8-HHz.cjs");
 const require_usage = require("./usage-efOQPdf_.cjs");
 require("./validate.cjs");
 let xstate = require("xstate");
@@ -274,22 +274,6 @@ function translateWorkflowConfig(config, translation) {
 	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
 	return json;
 }
-function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
-	for (const state of Object.values(states ?? {})) {
-		for (const tag of state.tags ?? []) tags.add(tag);
-		collectDeclaredStateTags(state.states, tags);
-	}
-	return tags;
-}
-function resolveIdlePredicate(config, options) {
-	if (options.isIdle) return options.isIdle;
-	const idleTags = config.idleTags ?? [];
-	if (!idleTags.length) return;
-	const declaredTags = collectDeclaredStateTags(config.states);
-	const unknown = idleTags.filter((tag) => !declaredTags.has(tag));
-	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'idleTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
-	return (snapshot) => idleTags.some((tag) => snapshot.hasTag(tag));
-}
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
 	const { compileSchema } = options;
@@ -311,16 +295,14 @@ function setupAgentFromConfig(config, options) {
 			event: args.event
 		}))])),
 		...options.actions ? { actions: options.actions } : {},
-		actors: Object.fromEntries(Object.keys(actors).map((key) => [key, key])),
+		actors,
 		evaluators: { [AGENT_EXPRESSION_LANG]: createWorkflowConfigEvaluator(schemas.context) }
-	}).provide({ actors });
+	});
 	require_text_logic.setAgentExecutionOptions(machine, {
 		schemas,
 		actors,
 		models: {}
 	});
-	const isIdle = resolveIdlePredicate(config, options);
-	if (isIdle && machine.config) require_text_logic.machineIdlePredicates.set(machine.config, isIdle);
 	return {
 		machine,
 		schemas
@@ -389,7 +371,7 @@ const agentUsageEventSchema = { "~standard": {
 * Adds the reserved `'@agent.usage'` schema to an authored event map. A
 * user-declared entry under that key is rejected: the `@agent.*` namespace
 * belongs to the library (same rule as the reserved `agent.*` actor keys), and
-* a custom payload schema would silently disagree with what `runAgent`
+* a custom payload schema would silently disagree with what the runtime
 * delivers.
 */
 function withAgentUsageEventSchema(events) {
@@ -424,7 +406,7 @@ function createAgentSchemas(schemas) {
 /**
 * Schema-first `setup(...)` for agent machines — the standard entry point
 * for authoring a machine (the blueprint) that this library then runs (via
-* {@link runAgent} or the step helpers) against host-supplied model/decision
+* {@link createAgentRuntime}) against host-supplied model/decision
 * executors. Context, events, machine input, machine output, and
 * state/transition meta are all standard schemas — no `{} as Type` casts —
 * and are retained on `result.schemas` for runtime validation. Also
@@ -497,10 +479,6 @@ function setupAgent(config) {
 			assertStateSchemaKeysExist(config.states, machineConfig?.states);
 			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
 			require_text_logic.setAgentExecutionOptions(machine, machineOptions);
-			if (config.isIdle) {
-				const rootConfig = machine.config;
-				if (rootConfig) require_text_logic.machineIdlePredicates.set(rootConfig, config.isIdle);
-			}
 			return machine;
 		},
 		schemas,

package/dist/testing.cjs

@@ -1,7 +1,253 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_text_logic = require("./text-logic-C8xyr6Ag.cjs");
-const require_decision = require("./decision-CM9CYZ6t.cjs");
-const require_run_agent = require("./run-agent-Cb1-LS5P.cjs");
+const require_text_logic = require("./text-logic-f5F5sCdc.cjs");
+const require_decision = require("./decision-CmM8-HHz.cjs");
+const require_run_agent = require("./run-agent-Dmf8GV2d.cjs");
+require("./validate.cjs");
+let xstate = require("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 = {
+		...require_text_logic.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 = require_text_logic.isTextLogic(params.logic) || require_decision.isDecisionLogic(params.logic) ? params.logic : options.actors?.[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
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = require_text_logic.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 = (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_text_logic.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_text_logic.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_text_logic.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, require_text_logic.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) {
@@ -78,7 +324,7 @@ function checkDirectObjectSrc(ctx) {
 			code: "direct-object-src",
 			severity: "warning",
 			path: node.path,
-			message: `State '${node.path}' invokes a direct-object agent logic. Direct-object invoke srcs cannot be rebound by runAgent, so they inherit no host executors — call '.withExecutor(...)' on the logic, or register it as a string-keyed actor source (machine.provide({ actors: { name: logic } })) and invoke it by name.`
+			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;
@@ -192,7 +438,7 @@ function assertAgentMachine(machine, options = {}) {
 }
 function pendingInvokes(step) {
 	const out = [];
-	for (const metadata of require_run_agent.getPendingInvokes(step.snapshot)) if (typeof metadata.src === "string") out.push({
+	for (const metadata of getPendingInvokes(step.snapshot)) if (typeof metadata.src === "string") out.push({
 		id: metadata.id,
 		src: metadata.src
 	});
@@ -252,7 +498,7 @@ async function simulateAgent(machine, options) {
 		errors: mapValues(options.script.errors ?? {}, (arr) => [...arr]),
 		events: [...options.script.events ?? []]
 	};
-	let step = require_run_agent.initialAgentStep(machine, options.input);
+	let step = initialAgentStep(machine, options.input);
 	const trail = [{ state: step.snapshot.value }];
 	for (let i = 0; i < maxSteps; i++) {
 		if (step.done) return {
@@ -290,7 +536,7 @@ async function simulateAgent(machine, options) {
 			}
 			const taken = takeFromQueue(script.text, request.src);
 			if (!taken.found) throw scriptDryError("text", request.src, request.id);
-			step = require_run_agent.resolveAgentStep(machine, step, request, asTextResult(taken.value));
+			step = resolveAgentStep(machine, step, request, asTextResult(taken.value));
 			trail.push({
 				state: step.snapshot.value,
 				resolvedRequest: {
@@ -315,7 +561,7 @@ async function simulateAgent(machine, options) {
 			}
 			const taken = takeFromQueue(script.invokes, invoke.src);
 			if (!taken.found) throw scriptDryError("invoke", invoke.src, invoke.id);
-			step = require_run_agent.resolveAgentStep(machine, step, invoke.id, taken.value);
+			step = resolveAgentStep(machine, step, invoke.id, taken.value);
 			trail.push({
 				state: step.snapshot.value,
 				resolvedRequest: {
@@ -331,7 +577,7 @@ async function simulateAgent(machine, options) {
 		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 = require_run_agent.transitionAgentStep(machine, step, event);
+			step = transitionAgentStep(machine, step, event);
 			trail.push({
 				state: step.snapshot.value,
 				appliedEvent: event,
@@ -356,7 +602,7 @@ function queueKey(channel, src, id) {
 }
 function rejectScriptedRequest(machine, step, request, error, entry) {
 	const id = typeof request === "string" ? request : request.id;
-	const next = require_run_agent.rejectAgentStep(machine, step, request, error);
+	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,
@@ -394,7 +640,7 @@ async function applyScriptedDecision(machine, step, request, decisionSrc, invoke
 		});
 	} catch (error) {
 		if (!(error instanceof require_decision.AgentDecisionExhaustedError)) throw error;
-		const next = require_run_agent.rejectAgentStep(machine, step, request.id, error);
+		const next = rejectAgentStep(machine, step, request.id, error);
 		if (next.snapshot.status === "error") throw error;
 		trail.push({
 			state: next.snapshot.value,
@@ -402,7 +648,7 @@ async function applyScriptedDecision(machine, step, request, decisionSrc, invoke
 		});
 		return next;
 	}
-	const next = require_run_agent.transitionAgentStep(machine, step, chosen);
+	const next = transitionAgentStep(machine, step, chosen);
 	const rejected = dequeued.slice(0, -1);
 	trail.push({
 		state: next.snapshot.value,
@@ -412,7 +658,7 @@ async function applyScriptedDecision(machine, step, request, decisionSrc, invoke
 	return next;
 }
 function findInvokeMetadata(step, id) {
-	for (const metadata of require_run_agent.getPendingInvokes(step.snapshot)) {
+	for (const metadata of getPendingInvokes(step.snapshot)) {
 		if (metadata.id !== id) continue;
 		return {
 			...typeof metadata.src === "string" ? { src: metadata.src } : {},
@@ -472,7 +718,7 @@ async function explore(machine, options, stopWhen) {
 			reachedValues.push(snapshot.value);
 		}
 	};
-	const initial = require_run_agent.initialAgentStep(machine, options.input);
+	const initial = initialAgentStep(machine, options.input);
 	recordState(initial.snapshot);
 	if (stopWhen?.(initial.snapshot)) witness = [];
 	const advance = (step) => {
@@ -493,7 +739,7 @@ async function explore(machine, options, stopWhen) {
 					step: current,
 					blockedSrc: request.src
 				};
-				current = require_run_agent.resolveAgentStep(machine, current, request, asTextResult(textScript[request.src]));
+				current = resolveAgentStep(machine, current, request, asTextResult(textScript[request.src]));
 				recordState(current.snapshot);
 				continue;
 			}
@@ -520,7 +766,7 @@ async function explore(machine, options, stopWhen) {
 					step: current,
 					blockedSrc: invoke.src
 				};
-				current = require_run_agent.resolveAgentStep(machine, current, invoke.id, invokeOutputs[invoke.src]);
+				current = resolveAgentStep(machine, current, invoke.id, invokeOutputs[invoke.src]);
 				recordState(current.snapshot);
 				continue;
 			}
@@ -551,12 +797,12 @@ async function explore(machine, options, stopWhen) {
 				unexplored.push(`max-depth: stopped at path [${path.map((e) => e.type).join(", ")}]`);
 				return;
 			}
-			const failed = require_run_agent.rejectAgentStep(machine, settled, fork.id, errorScript[fork.src]);
+			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 = require_run_agent.resolveAgentStep(machine, settled, fork.id, fork.output);
+					const resolved = resolveAgentStep(machine, settled, fork.id, fork.output);
 					recordState(resolved.snapshot);
 					await visit(resolved, path, depth + 1);
 				}
@@ -625,7 +871,7 @@ async function explore(machine, options, stopWhen) {
 				prunedByGuard++;
 				continue;
 			}
-			const next = require_run_agent.transitionAgentStep(machine, settled, event);
+			const next = transitionAgentStep(machine, settled, event);
 			recordState(next.snapshot);
 			await visit(next, [...path, event], depth + 1);
 		}
@@ -812,11 +1058,13 @@ function matcherFor(expected) {
 * @example Trajectory assertions in a test
 * ```ts
 * const statePath: unknown[] = [];
-* const result = await runAgent(machine, {
-*   input,
-*   executors,
-*   onTransition: (snapshot) => statePath.push(snapshot.value),
-* });
+* const result = await runToQuiescence(
+*   createAgentRuntime(machine, {
+*     executors,
+*     onTransition: (snapshot) => statePath.push(snapshot.value),
+*   }),
+*   { input },
+* );
 *
 * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
 * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
@@ -1024,9 +1272,7 @@ async function runSeam(machine, options) {
 	let result;
 	const maxTurns = options.maxTurns ?? 12;
 	for (let turn = 0; turn <= maxTurns; turn++) {
-		result = await require_run_agent.runAgent(machine, {
-			...snapshot ? { snapshot } : { input: options.input },
-			...event ? { event } : {},
+		result = await require_run_agent.runToQuiescence(require_run_agent.createAgentRuntime(machine, {
 			...options.actors ? { actors: options.actors } : {},
 			executors,
 			onTransition: (next, causedBy) => {
@@ -1035,6 +1281,9 @@ async function runSeam(machine, options) {
 				liveEvents = events.length;
 				statePath.push(next.value);
 			}
+		}), {
+			...snapshot ? { snapshot } : { input: options.input },
+			...event ? { event } : {}
 		});
 		if (result.status !== "idle" || turn === maxTurns) break;
 		const next = options.respond?.({

package/dist/testing.d.cts

@@ -1,7 +1,7 @@
-import { u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
-import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BFEOxyxv.cjs";
-import { d as RunAgentOptions, f as RunAgentResult } from "./run-agent-BOfoJg5B.cjs";
-import { t as MetaOfSnapshot } from "./utils-ceStNCOh.cjs";
+import { u as ChosenEvent } from "./types-hR5f5YXa.cjs";
+import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-IjfYy9DP.cjs";
+import { c as AgentRunResult, d as AgentRuntimeOptions, o as AgentRunInit } from "./run-agent-ByO-Bxyd.cjs";
+import { t as MetaOfSnapshot } from "./utils-o4YRdHJX.cjs";
 import { AnyMachineSnapshot, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/verify.d.ts
@@ -415,11 +415,13 @@ interface TrajectoryMatch {
  * @example Trajectory assertions in a test
  * ```ts
  * const statePath: unknown[] = [];
- * const result = await runAgent(machine, {
- *   input,
- *   executors,
- *   onTransition: (snapshot) => statePath.push(snapshot.value),
- * });
+ * const result = await runToQuiescence(
+ *   createAgentRuntime(machine, {
+ *     executors,
+ *     onTransition: (snapshot) => statePath.push(snapshot.value),
+ *   }),
+ *   { input },
+ * );
  *
  * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
  * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
@@ -480,7 +482,7 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   /** 0-based index of this pause within the run. */
   turn: number;
   /** The `idle` result that produced the pause. */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
 }
 /**
  * One text call in a {@link runSeam} run's ledger, in call order — the receipt
@@ -511,7 +513,7 @@ interface SeamSlice {
 }
 /** Options for {@link runSeam}. */
 interface RunSeamOptions<TMachine extends AnyStateMachine> {
-  /** Machine input, passed straight through to `runAgent`. */
+  /** Machine input, passed straight through to `runToQuiescence`. */
   input?: InputFrom<TMachine>;
   /**
    * The call plan: scripted answers per key, consumed in order. A key is a
@@ -554,15 +556,15 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * Text slots are always owned by the routing.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /** Passed through to `runAgent`: actor implementations merged onto the machine. */
-  actors?: RunAgentOptions<TMachine>["actors"];
+  /** Passed through to `createAgentRuntime`: actor implementations merged onto the machine. */
+  actors?: (AgentRuntimeOptions<TMachine> & AgentRunInit<TMachine>)["actors"];
 }
 /** What {@link runSeam} returns: the seam's own answer, plus the run it caused. */
 interface RunSeamResult<TMachine extends AnyStateMachine> {
   /**
-   * The final `runAgent` result. `usage` accounts for the last leg.
+   * The final `runToQuiescence` result. `usage` accounts for the last leg.
    */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
   /** What the seam call returned, or `undefined` when the run never reached it. */
   seamOutput: unknown;
   /**