@statelyai/agent 2.0.0-alpha.25 → 2.0.0-alpha.27

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

@@ -1,106 +1,6 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-tA3SdczG.mjs";
-import { M as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-hZSiRUo1.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/scripted-executors.d.ts
-/**
- * A scripted `decide` answer: either the {@link ChosenEvent} itself (an object
- * with a string `type`), or the executor result `{ event, reason?, usage? }`
- * when the entry also reports a `reason` or token `usage`.
- */
-type ScriptedDecisionValue = ChosenEvent | {
-  event: ChosenEvent;
-  reason?: string;
-  usage?: AgentCallUsage;
-};
-/**
- * One scripted `decide` answer, or a function of the
- * {@link AgentDecisionRequest} returning one (for choices that depend on the
- * prompt, the candidate `events`, or the prior failed `attempts`).
- */
-type ScriptedDecisionEntry = ScriptedDecisionValue | ((request: AgentDecisionRequest) => ScriptedDecisionValue | PromiseLike<ScriptedDecisionValue>);
-/**
- * One scripted text answer: the request's output value (a string, or the
- * object a structured request declares), or a function of the
- * {@link AgentTextRequest} returning one.
- *
- * An entry is taken as the executor result (instead of the value itself)
- * only when its OWN keys are a `result` plus, optionally, `messages`/`usage`/
- * `raw` — that is how an entry reports token `usage`. Anything else, including
- * an object that merely happens to have a `result` key alongside its own data
- * (`{ result: 'draft', confidence: 0.9 }`), is the output value. For a
- * structured request whose declared output is exactly `{ result }` (or
- * `{ result, usage }`), wrap it once more: `{ result: { result: '…' } }`.
- */
-type ScriptedTextEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
-/**
- * A request-name keyed script. The key is the request's resolved `name` — the
- * authored name, else the invoke `id`. `"*"` is the fallback route.
- */
-type ScriptedByName<TEntry> = Record<string, TEntry | TEntry[]>;
-/** One scripted stream call: chunks, or a function producing chunks. */
-type ScriptedStreamEntry = string | readonly string[] | ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => string | readonly string[] | PromiseLike<string | readonly string[]>);
-/** A call observed by {@link createScriptedExecutors}. */
-interface ScriptedExecutorCall {
-  kind: "generateText" | "streamText" | "decide";
-  name: string;
-  input: unknown;
-  request: AgentTextRequest | AgentDecisionRequest;
-}
-/**
- * The script {@link createScriptedExecutors} plays back. Every channel is
- * keyed by request name and consumed in order; the last entry for a name
- * repeats forever.
- */
-interface ScriptedExecutorsScript {
-  /** Answers for `decide` requests, keyed by request name. */
-  decisions?: ScriptedByName<ScriptedDecisionEntry>;
-  /** Answers for generate requests, keyed by request name. */
-  text?: ScriptedByName<ScriptedTextEntry>;
-  /** Stream chunks keyed by request name. */
-  stream?: Record<string, ScriptedStreamEntry>;
-  /** Default usage attached when an entry does not provide its own. */
-  usage?: AgentCallUsage;
-}
-/** What {@link createScriptedExecutors} returns: the full executor set plus the calls it observed. */
-type ScriptedExecutors = Required<AgentRequestExecutors> & {
-  calls: ScriptedExecutorCall[];
-};
-/**
- * Executors that replay a script instead of calling a model. Every slot is
- * provided, so any machine binds.
- *
- * Answers are keyed by the request's resolved name — its authored `name`, else
- * the invoke `id` — and `"*"` serves anything unmatched.
- * Entries for a name are consumed in order and the last one repeats forever, so
- * a looping machine needs no extra option. A request the script has no route
- * for throws an ordinary `Error` from inside the executor, which reaches the
- * machine as an actor error.
- *
- * Queues are copied on creation, so the caller's arrays are never mutated and
- * each call builds a fresh, independent playthrough. Entries may be plain
- * values or functions of the request.
- *
- * @example
- * ```ts
- * const result = await runAgent(moderationMachine, {
- *   input: { comment: 'honestly this update is terrible', trust: 20 },
- *   executors: createScriptedExecutors({
- *     decisions: { moderate: [{ type: 'FLAG', reason: 'Borderline tone.' }] },
- *   }),
- * });
- * ```
- *
- * @example Dynamic entries
- * ```ts
- * createScriptedExecutors({
- *   text: { draft: (request) => `Draft about ${request.prompt}` },
- *   decisions: { route: (request) => ({ type: request.events[0]!.type }) },
- * });
- * ```
- */
-declare function createScriptedExecutors(script?: ScriptedExecutorsScript): ScriptedExecutors;
-//#endregion
 //#region src/utils.d.ts
 /** Returns the human-readable text carried by a message, ignoring non-text parts. */
 declare function getMessageText(message: AgentMessage): string;
@@ -113,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.
@@ -206,4 +106,4 @@ declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string
  */
 declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
 //#endregion
-export { ScriptedExecutorsScript as _, getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, ScriptedExecutors as g, ScriptedDecisionValue as h, getJsonSchemaSync as i, isStandardSchema as l, ScriptedDecisionEntry as m, assistantMessage as n, getMessageText as o, ScriptedByName as p, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u, ScriptedTextEntry as v, createScriptedExecutors as y };
+export { getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, getJsonSchemaSync as i, isStandardSchema as l, assistantMessage as n, getMessageText as o, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u };

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

@@ -1,106 +1,6 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-B1Qs2q3q.cjs";
-import { M as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BFEOxyxv.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/scripted-executors.d.ts
-/**
- * A scripted `decide` answer: either the {@link ChosenEvent} itself (an object
- * with a string `type`), or the executor result `{ event, reason?, usage? }`
- * when the entry also reports a `reason` or token `usage`.
- */
-type ScriptedDecisionValue = ChosenEvent | {
-  event: ChosenEvent;
-  reason?: string;
-  usage?: AgentCallUsage;
-};
-/**
- * One scripted `decide` answer, or a function of the
- * {@link AgentDecisionRequest} returning one (for choices that depend on the
- * prompt, the candidate `events`, or the prior failed `attempts`).
- */
-type ScriptedDecisionEntry = ScriptedDecisionValue | ((request: AgentDecisionRequest) => ScriptedDecisionValue | PromiseLike<ScriptedDecisionValue>);
-/**
- * One scripted text answer: the request's output value (a string, or the
- * object a structured request declares), or a function of the
- * {@link AgentTextRequest} returning one.
- *
- * An entry is taken as the executor result (instead of the value itself)
- * only when its OWN keys are a `result` plus, optionally, `messages`/`usage`/
- * `raw` — that is how an entry reports token `usage`. Anything else, including
- * an object that merely happens to have a `result` key alongside its own data
- * (`{ result: 'draft', confidence: 0.9 }`), is the output value. For a
- * structured request whose declared output is exactly `{ result }` (or
- * `{ result, usage }`), wrap it once more: `{ result: { result: '…' } }`.
- */
-type ScriptedTextEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
-/**
- * A request-name keyed script. The key is the request's resolved `name` — the
- * authored name, else the invoke `id`. `"*"` is the fallback route.
- */
-type ScriptedByName<TEntry> = Record<string, TEntry | TEntry[]>;
-/** One scripted stream call: chunks, or a function producing chunks. */
-type ScriptedStreamEntry = string | readonly string[] | ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => string | readonly string[] | PromiseLike<string | readonly string[]>);
-/** A call observed by {@link createScriptedExecutors}. */
-interface ScriptedExecutorCall {
-  kind: "generateText" | "streamText" | "decide";
-  name: string;
-  input: unknown;
-  request: AgentTextRequest | AgentDecisionRequest;
-}
-/**
- * The script {@link createScriptedExecutors} plays back. Every channel is
- * keyed by request name and consumed in order; the last entry for a name
- * repeats forever.
- */
-interface ScriptedExecutorsScript {
-  /** Answers for `decide` requests, keyed by request name. */
-  decisions?: ScriptedByName<ScriptedDecisionEntry>;
-  /** Answers for generate requests, keyed by request name. */
-  text?: ScriptedByName<ScriptedTextEntry>;
-  /** Stream chunks keyed by request name. */
-  stream?: Record<string, ScriptedStreamEntry>;
-  /** Default usage attached when an entry does not provide its own. */
-  usage?: AgentCallUsage;
-}
-/** What {@link createScriptedExecutors} returns: the full executor set plus the calls it observed. */
-type ScriptedExecutors = Required<AgentRequestExecutors> & {
-  calls: ScriptedExecutorCall[];
-};
-/**
- * Executors that replay a script instead of calling a model. Every slot is
- * provided, so any machine binds.
- *
- * Answers are keyed by the request's resolved name — its authored `name`, else
- * the invoke `id` — and `"*"` serves anything unmatched.
- * Entries for a name are consumed in order and the last one repeats forever, so
- * a looping machine needs no extra option. A request the script has no route
- * for throws an ordinary `Error` from inside the executor, which reaches the
- * machine as an actor error.
- *
- * Queues are copied on creation, so the caller's arrays are never mutated and
- * each call builds a fresh, independent playthrough. Entries may be plain
- * values or functions of the request.
- *
- * @example
- * ```ts
- * const result = await runAgent(moderationMachine, {
- *   input: { comment: 'honestly this update is terrible', trust: 20 },
- *   executors: createScriptedExecutors({
- *     decisions: { moderate: [{ type: 'FLAG', reason: 'Borderline tone.' }] },
- *   }),
- * });
- * ```
- *
- * @example Dynamic entries
- * ```ts
- * createScriptedExecutors({
- *   text: { draft: (request) => `Draft about ${request.prompt}` },
- *   decisions: { route: (request) => ({ type: request.events[0]!.type }) },
- * });
- * ```
- */
-declare function createScriptedExecutors(script?: ScriptedExecutorsScript): ScriptedExecutors;
-//#endregion
 //#region src/utils.d.ts
 /** Returns the human-readable text carried by a message, ignoring non-text parts. */
 declare function getMessageText(message: AgentMessage): string;
@@ -113,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.
@@ -206,4 +106,4 @@ declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string
  */
 declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
 //#endregion
-export { ScriptedExecutorsScript as _, getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, ScriptedExecutors as g, ScriptedDecisionValue as h, getJsonSchemaSync as i, isStandardSchema as l, ScriptedDecisionEntry as m, assistantMessage as n, getMessageText as o, ScriptedByName as p, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u, ScriptedTextEntry as v, createScriptedExecutors as y };
+export { getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, getJsonSchemaSync as i, isStandardSchema as l, assistantMessage as n, getMessageText as o, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u };

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.25",
+  "version": "2.0.0-alpha.27",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -115,6 +115,7 @@
   },
   "devDependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@ai-sdk/typesafe-ai": "3.0.6",
     "@anthropic-ai/sdk": "^0.120.0",
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.31.1",
@@ -128,7 +129,7 @@
     "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@types/node": "^20.19.43",
     "@types/react": "^19.2.18",
-    "ai": "^7.0.0",
+    "ai": "^7.0.113",
     "ajv": "^8.20.0",
     "braintrust": "^3.28.0",
     "dotenv": "^16.6.1",
@@ -143,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": {
@@ -151,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

@@ -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
@@ -40,6 +42,8 @@ For the optional raw OpenAI SDK executor (`@statelyai/agent/openai`):
 pnpm add openai
 ```
 
+Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_evaluate` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](docs/judgments.md).
+
 Requirements:
 
 - Node 22.18 or newer, and XState v6 alpha.46 or newer.
@@ -139,7 +143,7 @@ const liveResult = await runAgent(refundMachine, {
 });
 ```
 
-For a machine with several requests, `createScriptedExecutors` from `@statelyai/agent/testing` holds ordered answers keyed by request name. See [Evals](docs/evals.md#scripted-executors).
+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).
 
 Passing the same `models` map to `setupAgent({ models })` types the machine's model refs. Executors are always explicit, and core does not import the AI SDK. See [Hosts and executors](docs/hosts.md).
 
@@ -155,7 +159,7 @@ flowchart LR
   R -->|event or output| M
 ```
 
-The machine never talks to a model directly, so swapping `createAiSdkExecutors` for `createScriptedExecutors` (or your own functions) changes nothing about the agent.
+The machine never talks to a model directly, so swapping `createAiSdkExecutors` for your own functions changes nothing about the agent.
 
 The example above has one model decision and two final outcomes. Real machines add approval states, retries, parallel work, child agents, and long-running waits without changing how control flow is represented.
 
@@ -169,7 +173,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"
     }