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

package/dist/{text-logic-hZSiRUo1.d.mts → text-logic-IjfYy9DP.d.cts}

@@ -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-tA3SdczG.mjs";
+import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-hR5f5YXa.cjs";
 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.
  */

package/dist/{text-logic-C8xyr6Ag.cjs → text-logic-f5F5sCdc.cjs}

@@ -126,7 +126,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.
@@ -137,7 +137,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
 */
@@ -328,7 +328,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}.
@@ -348,7 +348,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) {
@@ -358,24 +358,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) {
@@ -409,7 +394,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`.
@@ -431,7 +416,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
@@ -586,8 +571,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
@@ -640,7 +624,7 @@ function createTextLogic(config, execute) {
 	};
 	const logic = (0, xstate.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,
@@ -897,12 +881,6 @@ Object.defineProperty(exports, "djb2Hex", {
 		return djb2Hex;
 	}
 });
-Object.defineProperty(exports, "executeAgentTextRequest", {
-	enumerable: true,
-	get: function() {
-		return executeAgentTextRequest;
-	}
-});
 Object.defineProperty(exports, "executorBoundLogics", {
 	enumerable: true,
 	get: function() {
@@ -951,12 +929,6 @@ Object.defineProperty(exports, "getJsonSchemaSync", {
 		return getJsonSchemaSync;
 	}
 });
-Object.defineProperty(exports, "getMachineIdlePredicate", {
-	enumerable: true,
-	get: function() {
-		return getMachineIdlePredicate;
-	}
-});
 Object.defineProperty(exports, "getMachineStructuralHash", {
 	enumerable: true,
 	get: function() {
@@ -1005,12 +977,6 @@ Object.defineProperty(exports, "isUnboundPlaceholder", {
 		return isUnboundPlaceholder;
 	}
 });
-Object.defineProperty(exports, "machineIdlePredicates", {
-	enumerable: true,
-	get: function() {
-		return machineIdlePredicates;
-	}
-});
 Object.defineProperty(exports, "missingActor", {
 	enumerable: true,
 	get: function() {

package/dist/{types-B1Qs2q3q.d.cts → types-BgNbNKnJ.d.mts}

@@ -28,7 +28,7 @@ type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
  * passes in, before defaults are filled and transforms applied. Standard Schema
  * carries both sides (`~standard.types.input` / `.output`), so a schema
  * declaring a defaulted field makes that field optional here and required in
- * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * {@link InferOutput} — which is exactly the split between what a run
  * accepts as machine `input` and what the `context` factory then sees.
  */
 type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
@@ -39,7 +39,7 @@ type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
  * `createActor`'s `input` option and the `context: ({ input })` factory, so the
  * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
  * `createMachine` brands the machine's input type with the schema itself, which
- * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * lets `AgentInputFrom` recover the looser input side for a run's `input` while the
  * `context` factory keeps the strict validated side.
  *
  * The key is a `~`-prefixed phantom property (the same convention Standard
@@ -229,7 +229,7 @@ type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventW
  * omitting `allowedEvents` means "all currently-legal events." A resolver
  * function can therefore only ever narrow, never widen, the real surface.
  * Wildcards expand against the live snapshot, so they need a snapshot-aware
- * host (`runAgent` or the step path).
+ * host (`createAgentRuntime`).
  */
 type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
   input: TInput;

package/dist/{types-tA3SdczG.d.mts → types-hR5f5YXa.d.cts}

@@ -28,7 +28,7 @@ type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
  * passes in, before defaults are filled and transforms applied. Standard Schema
  * carries both sides (`~standard.types.input` / `.output`), so a schema
  * declaring a defaulted field makes that field optional here and required in
- * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * {@link InferOutput} — which is exactly the split between what a run
  * accepts as machine `input` and what the `context` factory then sees.
  */
 type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
@@ -39,7 +39,7 @@ type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
  * `createActor`'s `input` option and the `context: ({ input })` factory, so the
  * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
  * `createMachine` brands the machine's input type with the schema itself, which
- * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * lets `AgentInputFrom` recover the looser input side for a run's `input` while the
  * `context` factory keeps the strict validated side.
  *
  * The key is a `~`-prefixed phantom property (the same convention Standard
@@ -229,7 +229,7 @@ type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventW
  * omitting `allowedEvents` means "all currently-legal events." A resolver
  * function can therefore only ever narrow, never widen, the real surface.
  * Wildcards expand against the live snapshot, so they need a snapshot-aware
- * host (`runAgent` or the step path).
+ * host (`createAgentRuntime`).
  */
 type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
   input: TInput;

package/dist/{utils-C2DPqomn.d.mts → utils-_q7F-AZu.d.mts}

@@ -1,4 +1,4 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-tA3SdczG.mjs";
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-BgNbNKnJ.mjs";
 import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
 
 //#region src/utils.d.ts
@@ -13,7 +13,7 @@ declare function getMessageText(message: AgentMessage): string;
  * 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.

package/dist/{utils-ceStNCOh.d.cts → utils-o4YRdHJX.d.cts}

@@ -1,4 +1,4 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-B1Qs2q3q.cjs";
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-hR5f5YXa.cjs";
 import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
 
 //#region src/utils.d.ts
@@ -13,7 +13,7 @@ declare function getMessageText(message: AgentMessage): string;
  * 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.

package/dist/validate.cjs

@@ -81,14 +81,6 @@ var agent_workflow_default = {
 			"propertyNames": { "$ref": "#/$defs/Identifier" },
 			"additionalProperties": { "$ref": "#/$defs/State" }
 		},
-		"idleTags": {
-			"description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) idle predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
-			"type": "array",
-			"items": {
-				"type": "string",
-				"minLength": 1
-			}
-		},
 		"meta": { "$ref": "#/$defs/JsonObject" }
 	},
 	additionalProperties: false,

package/dist/validate.mjs

@@ -57,14 +57,6 @@ var agent_workflow_default = {
 			"propertyNames": { "$ref": "#/$defs/Identifier" },
 			"additionalProperties": { "$ref": "#/$defs/State" }
 		},
-		"idleTags": {
-			"description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) idle predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
-			"type": "array",
-			"items": {
-				"type": "string",
-				"minLength": 1
-			}
-		},
 		"meta": { "$ref": "#/$defs/JsonObject" }
 	},
 	additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.26",
+  "version": "2.0.0-alpha.28",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -144,7 +144,7 @@
     "typescript": "^5.9.3",
     "valibot": "^1.4.2",
     "vitest": "^4.1.11",
-    "xstate": "6.0.0-alpha.57",
+    "xstate": "6.0.0-alpha.64",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -152,7 +152,7 @@
     "ai": "^7.0.0",
     "ajv": "^8.20.0",
     "openai": ">=5.0.0 <8",
-    "xstate": ">=6.0.0-alpha.57 <6.0.0"
+    "xstate": "6.0.0-alpha.64"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {

package/readme.md

@@ -16,7 +16,7 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 
 ## Three starting points
 
-- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
+- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runToQuiescence`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
 - **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](docs/from-a-loop.md).
 - **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](docs/patterns.md).
 
@@ -25,9 +25,11 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 <!-- install command matching the package prerelease channel and package.json peers -->
 
 ```sh
-pnpm add @statelyai/agent@alpha xstate@alpha zod
+pnpm add @statelyai/agent@alpha xstate@6.0.0-alpha.64 zod
 ```
 
+XState is pinned while its experimental durable restoration API evolves.
+
 For the optional Vercel AI SDK executor:
 
 ```sh
@@ -50,12 +52,12 @@ Requirements:
 
 ## Quick start
 
-<!-- refund decision example using setupAgent, agent.decide, a machine guard, and the AI SDK runAgent host -->
+<!-- refund decision example using setupAgent, agent.decide, a machine guard, and the AI SDK runToQuiescence host -->
 
 This agent reviews refund requests. The model may propose an automatic refund, but the state machine owns the $100 limit.
 
 ```ts
-import { runAgent, setupAgent } from "@statelyai/agent";
+import { createAgentRuntime, runToQuiescence, setupAgent } from "@statelyai/agent";
 import { z } from "zod";
 
 const agentSetup = setupAgent({
@@ -106,15 +108,19 @@ const refundMachine = agentSetup.createMachine({
   },
 });
 
-const result = await runAgent(refundMachine, {
-  input: {
-    request: "I was charged twice for the same order.",
-    amount: 75,
+const result = await runToQuiescence(
+  createAgentRuntime(refundMachine, {
+    // An executor is a plain function, so this run needs no API key and no
+    // provider package.
+    executors: { decide: async () => ({ event: { type: "AUTO_REFUND" } }) },
+  }),
+  {
+    input: {
+      request: "I was charged twice for the same order.",
+      amount: 75,
+    },
   },
-  // An executor is a plain function, so this run needs no API key and no
-  // provider package.
-  executors: { decide: async () => ({ event: { type: "AUTO_REFUND" } }) },
-});
+);
 
 if (result.status === "done") {
   console.log(result.output);
@@ -135,10 +141,12 @@ To call a real model, leave the machine unchanged and swap the executors:
 import { openai } from "@ai-sdk/openai";
 import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
 
-const liveResult = await runAgent(refundMachine, {
-  input: { request: "I was charged twice for the same order.", amount: 75 },
-  executors: createAiSdkExecutors({ models: { fast: openai("gpt-5.4-mini") } }),
-});
+const liveResult = await runToQuiescence(
+  createAgentRuntime(refundMachine, {
+    executors: createAiSdkExecutors({ models: { fast: openai("gpt-5.4-mini") } }),
+  }),
+  { input: { request: "I was charged twice for the same order.", amount: 75 } },
+);
 ```
 
 For a machine with several requests, the executor routes on `request.name`, or `MockLanguageModelV3` from `ai/test` stands in for the provider behind `createAiSdkExecutors`. See [Evals](docs/evals.md#testing-without-a-provider).
@@ -149,7 +157,7 @@ Passing the same `models` map to `setupAgent({ models })` types the machine's mo
 
 ```mermaid
 flowchart LR
-  M["Agent machine<br/>states · guards · requests"] -->|request| R["runAgent"]
+  M["Agent machine<br/>states · guards · requests"] -->|request| R["runToQuiescence"]
   R -->|executor call| E["Host executors<br/>generateText · streamText · decide"]
   E -->|API call| L["Model"]
   L -->|result| E
@@ -171,7 +179,7 @@ The core concepts (machines owning control flow, bounded model decisions, typed
 - [Chameleon](examples/chameleon) combines hidden information, sequential turns, and a human vote.
 - [Snapshot migration](examples/snapshot-migration) uses XState's native `version` and `migrate` contract.
 - [Portable XState loop](examples/portable-xstate-loop) runs the artifact through native transitions and effects.
-- [Framework-owned storage](examples/file-snapshot-store) persists native XState snapshots in application code.
+- [Application-owned storage](examples/file-snapshot-store) persists native XState snapshots in application code.
 - [Tool calling](examples/review-tool-calls) keeps tools and message history in the AI SDK's native format.
 - [Ticket triage](examples/triage) returns structured data from a model request.
 - [JSON agent](examples/json-agent) runs a machine defined as data.

package/schemas/agent-workflow.json

@@ -71,14 +71,6 @@
         "$ref": "#/$defs/State"
       }
     },
-    "idleTags": {
-      "description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) idle predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
-      "type": "array",
-      "items": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
     "meta": {
       "$ref": "#/$defs/JsonObject"
     }

package/skills/generate-machine/SKILL.md

@@ -144,9 +144,7 @@ function validateGeneratedConfig(candidate: unknown): AgentWorkflowConfig {
   const result = validateAgentConfig(candidate);
   if (result.valid) return candidate as AgentWorkflowConfig;
   throw new Error(
-    result.errors
-      .map((error) => `${error.path || "(root)"} ${error.message}`)
-      .join("\n"),
+    result.errors.map((error) => `${error.path || "(root)"} ${error.message}`).join("\n"),
   );
 }
 ```
@@ -243,13 +241,13 @@ Keep the cap at ~3. A config that fails three schema-shaped repairs is usually a
 Deliver the config JSON plus how to run it:
 
 ```ts
-import { runAgent } from "@statelyai/agent";
+import { runToQuiescence } from "@statelyai/agent";
 import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
 
-const result = await runAgent(machine, {
-  input: { ticket: "Export downloads a 0-byte CSV on Safari." },
-  executors: createAiSdkExecutors({ resolveModel }),
-});
+const result = await runToQuiescence(
+  createAgentRuntime(machine, { executors: createAiSdkExecutors({ resolveModel }) }),
+  { input: { ticket: "Export downloads a 0-byte CSV on Safari." } },
+);
 ```
 
 Say which gates passed, list any warning-severity lint diagnostics, and report the dry-run status. Model refs are strings, so the host supplies `resolveModel`.