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

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { u as ChosenEvent } from "./types-tA3SdczG.mjs";
-import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-hZSiRUo1.mjs";
-import { d as RunAgentOptions, f as RunAgentResult } from "./run-agent-CG343kFs.mjs";
-import { t as MetaOfSnapshot } from "./utils-C2DPqomn.mjs";
+import { u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
+import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-D-czVPYp.mjs";
+import { c as AgentRunResult, d as AgentRuntimeOptions, o as AgentRunInit } from "./run-agent-COXXc0RW.mjs";
+import { t as MetaOfSnapshot } from "./utils-_q7F-AZu.mjs";
 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;
   /**

package/dist/testing.mjs

@@ -1,6 +1,251 @@
-import { H as AgentError, P as getStateMeta, S as getRegisteredAgentExecutionOptions, d as getCallUsage, f as isTextLogic, p as normalizeGeneratorResult, y as executorBoundLogics } from "./text-logic-Bl_ZRxDi.mjs";
-import { a as isDecisionLogic, d as isRecord, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-DzSv1NpD.mjs";
-import { _ as rejectAgentStep, d as runAgent, g as initialAgentStep, h as getPendingInvokes, v as resolveAgentStep, y as transitionAgentStep } from "./run-agent-DvDQd4If.mjs";
+import { b as getRegisteredAgentExecutionOptions, d as isTextLogic, f as normalizeGeneratorResult, j as getStateMeta, u as getCallUsage, v as executorBoundLogics, z as AgentError } from "./text-logic-CIqHAmBi.mjs";
+import { a as isDecisionLogic, d as isRecord, l as getAcceptedEvents, s as resolveDecision, t as AgentDecisionExhaustedError } from "./decision-RQ0iv0oZ.mjs";
+import { f as runToQuiescence, s as createAgentRuntime } from "./run-agent-xNTxpt82.mjs";
+import { initialTransition, transition } from "xstate";
+//#region src/steps.ts
+/**
+* Internal: the pure `(state, event) => (nextState, requests)` view of an
+* agent machine, used by model-free simulation (`simulateAgent`) and tests.
+* An {@link AgentStep} is a snapshot plus the model requests the machine is
+* now waiting on; nothing here executes anything. Hosts use
+* `createAgentRuntime`.
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* The invokes a snapshot is still waiting on, lowered to the same spawn-effect
+* shape {@link getAgentRequests} reads. Derived from the snapshot's live
+* children rather than the last transition's actions, so a state that invokes
+* several actors at once (an `invoke: [...]` array, or parallel regions each
+* invoking) keeps reporting the siblings after the first one settles —
+* including when the settled invoke's `onDone` is targetless and starts
+* nothing new.
+*
+* Entries are ordered by invoke id, so a walker that resolves one invoke per
+* step is deterministic.
+*
+* @internal
+*/
+function getPendingInvokes(snapshot) {
+	const children = snapshot.children ?? {};
+	return Object.keys(children).sort().flatMap((id) => {
+		const child = children[id];
+		const childSnapshot = child?.getSnapshot?.();
+		if (!child || childSnapshot?.status !== "active") return [];
+		return [{
+			type: "@xstate.spawn",
+			id,
+			src: child.src,
+			input: childSnapshot.input,
+			logic: child.logic
+		}];
+	});
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. Pass `options.machine` to
+* pre-fill `schemas`/`actors` from the machine's registered `setupAgent`
+* options instead of passing them by hand.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequests(actions, { machine, ...options } = {}) {
+	if (machine) options = {
+		...getRegisteredAgentExecutionOptions(machine),
+		...options
+	};
+	return actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actors?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	});
+}
+/**
+* Builds the canonical `xstate.done.actor` event xstate's `transition()`
+* expects to resolve a spawned invoke — including the child session identity
+* that rejects a stale completion from an earlier incarnation.
+*
+* @internal
+*/
+function doneEvent(snapshot, request, output) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.done.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		output
+	};
+}
+/**
+* The `xstate.error.actor` counterpart of {@link doneEvent} — the event a
+* failed invoke delivers, which `onError` transitions observe. Carries the
+* same child session identity, so xstate does not discard it as stale.
+*
+* @internal
+*/
+function errorEvent(snapshot, request, error) {
+	const id = typeof request === "string" ? request : request.id;
+	const child = snapshot.children[id];
+	return {
+		type: "xstate.error.actor",
+		actorId: id,
+		...typeof child?.sessionId === "string" ? { sessionId: child.sessionId } : {},
+		error
+	};
+}
+/**
+* Applies a request's `output` as a done event (or, with `outcome: 'error'`,
+* its `output` as the invoke's error) via `transition(...)`, returning the raw
+* `[snapshot, actions]` tuple. Lower-level than {@link resolveAgentStep} /
+* {@link rejectAgentStep} — those helpers wrap this and also run
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output, outcome = "output") {
+	const event = outcome === "error" ? errorEvent(snapshot, request, output) : doneEvent(snapshot, request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Rejects a pending invoke — the failure counterpart of
+* {@link resolveAgentStep}. Delivers `error` as the invoke's
+* `xstate.error.actor` event, so the machine takes that invoke's `onError`
+* transition and returns the next {@link AgentStep}. With no `onError` in
+* scope the returned step's snapshot has `status: 'error'`, exactly as a live
+* run's failed invoke does.
+*
+* A durable host replays a failed call with this: the log says the call
+* failed, so the replay rejects the invoke instead of resolving it. Scripted
+* playthroughs use it too — see `simulateAgent`'s `script.errors`.
+*
+* `error` can be any value. An `Error` instance is the usual one, but a plain
+* object (`{ code: 'truncated' }`) reaches the `onError` transition as
+* `event.error` untouched, so a machine that branches on a failure code is
+* testable without constructing a provider's error class.
+*/
+function rejectAgentStep(machine, step, request, error, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, error, "error");
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequests(getPendingInvokes(snapshot), {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
 //#region src/verify.ts
 const DECIDE_SRC = "agent.decide";
 function normalizeInvokes(invoke) {
@@ -77,7 +322,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;
@@ -811,11 +1056,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);
@@ -1023,9 +1270,7 @@ async function runSeam(machine, options) {
 	let result;
 	const maxTurns = options.maxTurns ?? 12;
 	for (let turn = 0; turn <= maxTurns; turn++) {
-		result = await runAgent(machine, {
-			...snapshot ? { snapshot } : { input: options.input },
-			...event ? { event } : {},
+		result = await runToQuiescence(createAgentRuntime(machine, {
 			...options.actors ? { actors: options.actors } : {},
 			executors,
 			onTransition: (next, causedBy) => {
@@ -1034,6 +1279,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/{text-logic-Bl_ZRxDi.mjs → text-logic-CIqHAmBi.mjs}

@@ -125,7 +125,7 @@ function findNonSerializableContextPaths(context, limit = 5) {
 * their prompts or executors hash identically; adding/removing/retargeting a
 * state or transition changes the hash.
 *
-* Used by {@link runAgent} to stamp settled snapshots with a `version` and to
+* Used by {@link createAgentRuntime} to stamp settled snapshots with a `version` and to
 * detect a structurally-edited machine on resume. It is a change detector, not
 * a cryptographic digest — collisions are possible but unlikely for real
 * configs. Declare `createMachine({ version })` to pin an explicit version instead.
@@ -136,7 +136,7 @@ function getMachineStructuralHash(machine) {
 /**
 * The version a machine is stamped with everywhere: an explicitly declared
 * `createMachine({ version })` when present, else its
-* {@link getMachineStructuralHash}. Single source of truth so `runAgent`,
+* {@link getMachineStructuralHash}. Single source of truth so `createAgentRuntime`,
 * `provideExecutors`/`traceTransitions` trace envelopes agree.
 * @internal
 */
@@ -327,7 +327,7 @@ function validateSchemaSync(schema, value) {
 * Registered execution options, keyed on BOTH the machine object and its root
 * `config` object. `config` is shared by reference across `machine.provide(...)`
 * (unlike the machine itself), so the `config` key is what lets a machine
-* rebound by `runAgent` — or by any host `.provide(...)` — still resolve the
+* rebound by `createAgentRuntime` — or by any host `.provide(...)` — still resolve the
 * schemas/actors `setupAgent` registered. Always write through
 * {@link setAgentExecutionOptions} and read through
 * {@link getAgentExecutionOptions}.
@@ -347,7 +347,7 @@ function setAgentExecutionOptions(machine, options) {
 }
 /**
 * Reads the options registered for `machine`, falling back to the root `config`
-* key so a `.provide(...)`-rebound machine (e.g. the one behind a `runAgent`
+* key so a `.provide(...)`-rebound machine (e.g. the one behind a `runToQuiescence`
 * result snapshot) resolves the same pack.
 */
 function getAgentExecutionOptions(machine) {
@@ -357,24 +357,9 @@ function getAgentExecutionOptions(machine) {
 	const config = machineConfigKey(machine);
 	return config ? agentExecutionOptions.get(config) : void 0;
 }
-/**
-* Machine-carried wait-state predicates, keyed on the machine's root `config`
-* object. `config` is shared by reference across `machine.provide(...)` (unlike
-* the machine object itself), so a predicate registered here travels with the
-* machine through `.provide` — which is why it is keyed on `config`, not the
-* machine. Set by `setupAgent({ isIdle })` in `createMachine` and by
-* `setupAgent.fromConfig` (its `isIdle` option or the config's
-* `idleTags`), read by `runAgent` before its structural default.
-*/
-const machineIdlePredicates = /* @__PURE__ */ new WeakMap();
-/** Reads the {@link machineIdlePredicates} predicate carried by `machine` (via its root `config`), if any. */
-function getMachineIdlePredicate(machine) {
-	const config = machine.config;
-	return config ? machineIdlePredicates.get(config) : void 0;
-}
 const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
 /** Text/decision logics created WITH their own executor (withExecutor or the
-* factory's second arg) — these are runnable as-is, so runAgent's bind check
+* factory's second arg) — these are runnable as-is, so the runtime's bind check
 * must not reject them as direct-object invoke srcs. */
 const executorBoundLogics = /* @__PURE__ */ new WeakSet();
 function missingActor(src) {
@@ -408,7 +393,7 @@ const AGENT_FINISH_REASONS = new Set([
 /**
 * Reads a settled call's {@link AgentFinishReason} off a RAW executor result's
 * `finishReason` field — the finish-reason sibling of {@link getCallUsage},
-* applied by `runAgent` before it puts the reason on the `request.end` trace.
+* applied by the runtime before it puts the reason on the `request.end` trace.
 * A provider's `'error'` normalizes to `'other'`; anything else the union does
 * not name (an un-normalized provider string, a missing field) returns
 * `undefined`.
@@ -430,7 +415,7 @@ const AGENT_USAGE_TOKEN_FIELDS = [
 /**
 * Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
 * result's `usage` field, keeping only finite numbers — the same normalization
-* `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+* the runtime applies before it delivers `'@agent.usage'`. Returns `undefined`
 * when the result reports no usage at all. Works for our `{ result, usage }`
 * shape, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
 * the same flat field names), and for any custom executor that follows the
@@ -585,8 +570,7 @@ function resolveTextLogicValue(value, args) {
 * result under `actors:` and invoke it by name (equivalent to what
 * `setupAgent({ requests })` builds internally for each request entry). Pass
 * `execute` here, or bind it later with `.withExecutor(...)`, a runtime
-* adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
-* `streamText` options.
+* adapter's `machine.provide(...)`, or `createAgentRuntime`'s `executors`.
 *
 * @example
 * ```ts
@@ -639,7 +623,7 @@ function createTextLogic(config, execute) {
 	};
 	const logic = createAsyncLogic({ run: async ({ input, signal, system, self }, enq) => {
 		const resolvedRequest = request(input);
-		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or bind it through runAgent/provideExecutors, or execute the XState effect in your host.");
+		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or bind it through createAgentRuntime/provideExecutors, or execute the XState effect in your host.");
 		const result = await execute({
 			input,
 			request: resolvedRequest,
@@ -830,4 +814,4 @@ function invalidGeneratorResult(id) {
 	return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { result } (the text string or structured object as \`result\`, plus optional \`messages\`, \`usage\` and other passthrough fields). Wrap a raw SDK result with an adapter such as createAiSdkExecutors.`);
 }
 //#endregion
-export { getJsonSchema as A, userMessage as B, isUnboundPlaceholder as C, assistantMessage as D, setAgentExecutionOptions as E, getStatePath as F, AgentError as H, isStandardSchema as I, resolveMachineVersion as L, getMachineStructuralHash as M, getMessageText as N, djb2Hex as O, getStateMeta as P, systemMessage as R, getRegisteredAgentExecutionOptions as S, missingActor as T, AgentTruncatedError as U, validateSchemaSync as V, resolveTextLogicValue as _, bindRequestExecutor as a, getAgentExecutionOptions as b, executeAgentTextRequest as c, getCallUsage as d, isTextLogic as f, providerOutputSchema as g, parseProviderOutput as h, STREAM_TEXT_ACTOR as i, getJsonSchemaSync as j, findNonSerializableContextPaths as k, getAgentOutputMode as l, parseOutput as m, DECIDE_ACTOR as n, builtinTextActors as o, normalizeGeneratorResult as p, GENERATE_TEXT_ACTOR as r, createTextLogic as s, AGENT_USAGE_TOKEN_FIELDS as t, getCallFinishReason as u, responseMessagesOf as v, machineIdlePredicates as w, getMachineIdlePredicate as x, executorBoundLogics as y, toolMessage as z };
+export { getMessageText as A, AgentTruncatedError as B, setAgentExecutionOptions as C, getJsonSchema as D, findNonSerializableContextPaths as E, systemMessage as F, toolMessage as I, userMessage as L, getStatePath as M, isStandardSchema as N, getJsonSchemaSync as O, resolveMachineVersion as P, validateSchemaSync as R, missingActor as S, djb2Hex as T, responseMessagesOf as _, bindRequestExecutor as a, getRegisteredAgentExecutionOptions as b, getAgentOutputMode as c, isTextLogic as d, normalizeGeneratorResult as f, resolveTextLogicValue as g, providerOutputSchema as h, STREAM_TEXT_ACTOR as i, getStateMeta as j, getMachineStructuralHash as k, getCallFinishReason as l, parseProviderOutput as m, DECIDE_ACTOR as n, builtinTextActors as o, parseOutput as p, GENERATE_TEXT_ACTOR as r, createTextLogic as s, AGENT_USAGE_TOKEN_FIELDS as t, getCallUsage as u, executorBoundLogics as v, assistantMessage as w, isUnboundPlaceholder as x, getAgentExecutionOptions as y, AgentError as z };

package/dist/{text-logic-BFEOxyxv.d.cts → text-logic-D-czVPYp.d.mts}

@@ -1,4 +1,4 @@
-import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
+import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
 import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
 
 //#region src/errors.d.ts
@@ -77,7 +77,7 @@ interface AgentEventDescriptor {
 /** Registered schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
 interface AgentSchemas {
   events?: Record<string, StandardSchemaV1>;
-  /** Machine input schema; `runAgent` validates `options.input` against it. */
+  /** Machine input schema; the runtime validates the run's `input` against it. */
   input?: StandardSchemaV1;
 }
 /** Shared options threaded through step discovery ({@link getAgentRequests}/{@link getAcceptedEvents}) — snapshot for event legality, event schemas for payload validation/tool schemas, and registered actor source logics. */
@@ -94,7 +94,7 @@ type ParsedAgentEvent<TSource> = TSource extends AnyStateMachine ? EventFromLogi
 /**
  * Parses a wire payload (a request body, a socket frame) into an
  * event typed as the machine's event union, so it can go straight to
- * `runAgent({ event })` / `actor.send(...)` without a cast. Pass the machine
+ * `runToQuiescence(runtime, { event })` / `actor.send(...)` without a cast. Pass the machine
  * itself, or any snapshot of it.
  *
  * It checks exactly what a schema can check: the payload is an object with a
@@ -111,7 +111,8 @@ type ParsedAgentEvent<TSource> = TSource extends AnyStateMachine ? EventFromLogi
  * @example
  * ```ts
  * const event = parseAgentEvent(machine, await request.json());
- * const result = await runAgent(machine, { store, threadId, event, executors });
+ * const runtime = createAgentRuntime(machine, { store, threadId, executors });
+ * const result = await runToQuiescence(runtime, { event });
  * ```
  */
 declare function parseAgentEvent<TSource extends AnyStateMachine | AnyMachineSnapshot>(source: TSource, payload: unknown, options?: Pick<AgentRequestOptions, "events" | "schemas">): ParsedAgentEvent<TSource>;
@@ -190,7 +191,7 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
 }
 /**
  * Actor logic for a decision: an async effect that resolves to exactly one
- * currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
+ * currently-legal {@link ChosenEvent} (never a plain value). Under `createAgentRuntime`
  * the chosen event is delivered to the invoking actor automatically — the
  * transition it triggers usually exits the invoking state and ends the invoke.
  * Built by {@link createDecisionLogic}. Register it under `actors:` to reuse/export/
@@ -208,7 +209,7 @@ interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1
  * run, resolves to exactly one currently-legal {@link ChosenEvent} by
  * calling the host `decide` executor (passed here as `execute`, or supplied
  * later via {@link DecisionLogic.withExecutor}, `machine.provide(...)`, or
- * `runAgent`'s `decide` option). Register the result under `actors:` and
+ * `createAgentRuntime`'s `executors.decide`). Register the result under `actors:` and
  * invoke it by name; for a one-off, state-local decision, prefer the
  * `agent.decide` builtin invoke instead — it needs no separate declaration
  * and types `allowedEvents` against the machine's own event schemas.
@@ -264,10 +265,10 @@ interface AgentDecisionRequest {
   stopSequences?: string[];
   metadata?: Record<string, unknown>;
   /**
-   * The `runAgent` run this decision belongs to (`run_<n>`, matching trace
-   * events), injected by runAgent like `signal` (symmetric with the text
+   * The run this decision belongs to (`run_<n>`, matching trace
+   * events), injected by the runtime like `signal` (symmetric with the text
    * executors' `info.runId`). Runtime-only correlation for executor
-   * middleware; unset off the runAgent path. Per-attempt context is already
+   * middleware; unset off the runtime path. Per-attempt context is already
    * on the request: `id` is the durable invoke id and `attempts.length` is
    * the current attempt index.
    */
@@ -362,7 +363,7 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * `onResult`/event-sourcing but never affects validation. Like text
  * executors' `{ result, ...extras }`, any extra keys (finish reason,
  * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
- * report this attempt's tokens there and `runAgent` folds them into the run's
+ * report this attempt's tokens there and the runtime folds them into the run's
  * aggregated {@link AgentUsage}.
  */
 type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
@@ -493,7 +494,7 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>, TMessage = any>
    * `stopWhen: stepCountIs(maxSteps)`.
    *
    * This is a REQUEST budget, distinct from the machine-level `maxTurns` a
-   * preset uses for its own turn budget, and from `runAgent`'s run-wide
+   * preset uses for its own turn budget, and from `createAgentRuntime`'s run-wide
    * `maxModelCalls`.
    */
   maxSteps?: number;
@@ -506,9 +507,9 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>, TMessage = any>
   metadata?: TMetadata;
 }
 /**
- * Aggregated model-call usage for ONE `runAgent` call — the run-level total
- * attached to every settled {@link RunAgentResult} (and therefore to
- * `runAgent`'s `{ output, snapshot, persist, usage }`).
+ * Aggregated model-call usage for ONE run — the run-level total
+ * attached to every settled {@link AgentRunResult} (and therefore to
+ * `runToQuiescence`'s `{ output, snapshot, persist, usage }`).
  *
  * - `modelCalls` counts every model/decision call this run made (each decision
  *   retry counts separately) — the same seam `maxModelCalls` budgets. Always a
@@ -542,7 +543,7 @@ type AgentCallUsage = Omit<AgentUsage, "modelCalls">;
  * - `'content-filter'` — a safety filter stopped it.
  * - `'other'` — anything else, including a provider error the adapter mapped.
  *
- * Adapters set it on their executor result; `runAgent` copies it onto the
+ * Adapters set it on their executor result; the runtime copies it onto the
  * `request.end` trace event. A provider's own string stays on the result's
  * `raw`.
  */
@@ -550,7 +551,7 @@ type AgentFinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "
 /**
  * Reads a settled call's {@link AgentFinishReason} off a RAW executor result's
  * `finishReason` field — the finish-reason sibling of {@link getCallUsage},
- * applied by `runAgent` before it puts the reason on the `request.end` trace.
+ * applied by the runtime before it puts the reason on the `request.end` trace.
  * A provider's `'error'` normalizes to `'other'`; anything else the union does
  * not name (an un-normalized provider string, a missing field) returns
  * `undefined`.
@@ -559,7 +560,7 @@ declare function getCallFinishReason(raw: unknown): AgentFinishReason | undefine
 /**
  * Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
  * result's `usage` field, keeping only finite numbers — the same normalization
- * `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+ * the runtime applies before it delivers `'@agent.usage'`. Returns `undefined`
  * when the result reports no usage at all. Works for our `{ result, usage }`
  * shape, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
  * the same flat field names), and for any custom executor that follows the
@@ -689,8 +690,7 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
  * result under `actors:` and invoke it by name (equivalent to what
  * `setupAgent({ requests })` builds internally for each request entry). Pass
  * `execute` here, or bind it later with `.withExecutor(...)`, a runtime
- * adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
- * `streamText` options.
+ * adapter's `machine.provide(...)`, or `createAgentRuntime`'s `executors`.
  *
  * @example
  * ```ts
@@ -732,7 +732,7 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
  * without it is a runtime error.
  *
  * `usage` is the one passthrough field core reads: report this call's tokens
- * there and `runAgent` folds them into the run's aggregated
+ * there and the runtime folds them into the run's aggregated
  * {@link AgentUsage}. Optional — an executor that reports nothing still counts
  * toward `modelCalls`.
  */
@@ -744,16 +744,15 @@ type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
   [key: string]: unknown;
 };
 /**
- * Optional second argument passed to executors by `runAgent`. The step path
- * (`executeAgentRequest`) never passes this — chunk streaming only exists on
- * the live path, where `onChunk` (§3.1) needs a way to reach the executor.
+ * Optional second argument passed to executors by `createAgentRuntime`: the
+ * request's abort signal, and `onChunk` for streamed requests.
  */
 interface AgentRequestExecutorInfo {
   onChunk?: (chunk: string) => void;
   signal?: AbortSignal;
   /**
-   * The `runAgent` run this call belongs to (`run_<n>`, matching trace
-   * events). Undefined off the runAgent path (bare `provideExecutors` /
+   * The run this call belongs to (`run_<n>`, matching trace
+   * events). Undefined off the runtime path (bare `provideExecutors` /
    * direct `TextLogic.execute`). Lets executor middleware (caching, rate
    * limits, span parenting) correlate calls without side channels.
    */
@@ -780,7 +779,7 @@ interface AgentRequestExecutorInfo {
    * lineage id, so cache on `callKey` together with a fingerprint of the
    * request and reuse a cached result only when the request also matches.
    *
-   * Undefined off the `runAgent` path, and for a log with no `executionId`.
+   * Undefined off the `createAgentRuntime` path, and for a log with no `executionId`.
    */
   callKey?: string;
 }
@@ -803,11 +802,11 @@ type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentT
 type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => TResult | PromiseLike<TResult>;
 /**
  * The full set of host executors a machine's agent actors are resolved
- * with — passed to `runAgent`, `executeAgentRequest`, and
+ * with — passed to `createAgentRuntime`, `executeAgentRequest`, and
  * `TextLogic.execute`. Every slot is optional: `generateText` is needed only
  * if the machine has a `mode: 'generate'` text request, `streamText` only for
  * a `mode: 'stream'` request, and `decide` only for a decision — omitting
- * a slot the machine actually needs is a clear bind-time error (see `runAgent`
+ * a slot the machine actually needs is a clear bind-time error (see `createAgentRuntime`
  * and `provideExecutors`). Adapter result sets (`AiSdkExecutors`,
  * `OpenAiCompatExecutors`) re-require all three.
  */