@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.24

package/readme.md

@@ -25,7 +25,19 @@ 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 ai@^7 @ai-sdk/openai@^4
+pnpm add @statelyai/agent@alpha xstate@alpha zod
+```
+
+For the optional Vercel AI SDK executor:
+
+```sh
+pnpm add ai@^7 @ai-sdk/openai@^4
+```
+
+For the optional raw OpenAI SDK executor (`@statelyai/agent/openai`):
+
+```sh
+pnpm add openai
 ```
 
 Requirements:
@@ -41,17 +53,10 @@ Requirements:
 This agent reviews refund requests. The model may propose an automatic refund, but the state machine owns the $100 limit.
 
 ```ts
-import { openai } from "@ai-sdk/openai";
 import { runAgent, setupAgent } from "@statelyai/agent";
-import { createAiSdkExecutors, defineModels } from "@statelyai/agent/ai-sdk";
 import { z } from "zod";
 
-const models = defineModels({
-  fast: openai("gpt-5.4-mini"),
-});
-
 const agentSetup = setupAgent({
-  models,
   context: z.object({
     request: z.string(),
     amount: z.number(),
@@ -104,7 +109,9 @@ const result = await runAgent(refundMachine, {
     request: "I was charged twice for the same order.",
     amount: 75,
   },
-  executors: createAiSdkExecutors({ models }),
+  // 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") {
@@ -120,16 +127,21 @@ When the machine reaches `refunded`, the result is:
 
 The model chooses between the events allowed in `deciding`. The `AUTO_REFUND` transition only works when the amount is at most $100. If the model chooses it for a larger amount, the guard rejects the choice and the decision is tried again.
 
+To call a real model, leave the machine unchanged and swap the executors:
+
 ```ts
-import { createScriptedExecutors } from "@statelyai/agent";
+import { openai } from "@ai-sdk/openai";
+import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
 
-const result = await runAgent(refundMachine, {
+const liveResult = await runAgent(refundMachine, {
   input: { request: "I was charged twice for the same order.", amount: 75 },
-  executors: createScriptedExecutors({ decisions: [{ type: "AUTO_REFUND" }] }),
+  executors: createAiSdkExecutors({ models: { fast: openai("gpt-5.4-mini") } }),
 });
 ```
 
-Scripted executors run the machine above end to end with no API key; swap in `createAiSdkExecutors({ models })` for a real model. See [Hosts and executors](docs/hosts.md).
+For a machine with several requests, `createScriptedExecutors` holds ordered answers keyed by request name. See [Evals](docs/evals.md#scripted-executors).
+
+Passing a `defineModels` registry to `setupAgent({ models })` types the machine's model refs and supplies the AI SDK executor by default; explicit `executors` override it. Core does not import the AI SDK. See [Hosts and executors](docs/hosts.md).
 
 ## Architecture
 
@@ -147,15 +159,18 @@ The machine never talks to a model directly, so swapping `createAiSdkExecutors`
 
 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.
 
-The core concepts (machines owning control flow, bounded model decisions, typed requests, host-run executors, storable snapshots, verified replay entries) are in the [documentation overview](docs/index.md).
+The core concepts (machines owning control flow, bounded model decisions, typed requests, host-run executors, and native XState snapshots) are in the [documentation overview](docs/index.md).
 
 ## Examples
 
 <!-- starter examples derived from examples/*/metadata.json and examples/index.ts -->
 
 - [Twenty Questions](examples/twenty-questions) shows a model choosing legal events in a loop.
-- [Go Fish](examples/go-fish) pits a model against a human while the machine enforces hidden-information game rules.
-- [Human in the loop](examples/human-in-the-loop) pauses, stores a snapshot, and resumes after review.
+- [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.
+- [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.
 
@@ -173,7 +188,7 @@ See [all examples](examples/README.md).
 - [Hosts and executors](docs/hosts.md)
 - [Models and providers](docs/models-and-providers.md)
 - [Use in any stack](docs/any-stack.md)
-- [The event log](docs/event-log.md)
+- [Persistence](docs/persistence.md)
 - [Observability](docs/observability.md)
 - [Usage and budgets](docs/usage-and-budgets.md)
 - [Agent patterns](docs/patterns.md)

package/dist/errors-BQRk9eiZ.d.cts

@@ -1,19 +0,0 @@
-//#region src/errors.d.ts
-/**
- * Base class for every error this package throws. Carries a stable, kebab-case
- * `code` so hosts can branch on the failure without `instanceof` (useful across
- * bundle/realm boundaries and after serialization).
- *
- * @example
- * ```ts
- * catch (error) {
- *   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
- * }
- * ```
- */
-declare class AgentError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string, options?: ErrorOptions);
-}
-//#endregion
-export { AgentError as t };

package/dist/errors-C9rxnWbX.d.mts

@@ -1,19 +0,0 @@
-//#region src/errors.d.ts
-/**
- * Base class for every error this package throws. Carries a stable, kebab-case
- * `code` so hosts can branch on the failure without `instanceof` (useful across
- * bundle/realm boundaries and after serialization).
- *
- * @example
- * ```ts
- * catch (error) {
- *   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
- * }
- * ```
- */
-declare class AgentError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string, options?: ErrorOptions);
-}
-//#endregion
-export { AgentError as t };

package/dist/errors-CeSXQx0v.mjs

@@ -1,23 +0,0 @@
-//#region src/errors.ts
-/**
-* Base class for every error this package throws. Carries a stable, kebab-case
-* `code` so hosts can branch on the failure without `instanceof` (useful across
-* bundle/realm boundaries and after serialization).
-*
-* @example
-* ```ts
-* catch (error) {
-*   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
-* }
-* ```
-*/
-var AgentError = class extends Error {
-	code;
-	constructor(code, message, options) {
-		super(message, options);
-		this.name = "AgentError";
-		this.code = code;
-	}
-};
-//#endregion
-export { AgentError as t };

package/dist/errors-DUBBzRLP.cjs

@@ -1,28 +0,0 @@
-//#region src/errors.ts
-/**
-* Base class for every error this package throws. Carries a stable, kebab-case
-* `code` so hosts can branch on the failure without `instanceof` (useful across
-* bundle/realm boundaries and after serialization).
-*
-* @example
-* ```ts
-* catch (error) {
-*   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
-* }
-* ```
-*/
-var AgentError = class extends Error {
-	code;
-	constructor(code, message, options) {
-		super(message, options);
-		this.name = "AgentError";
-		this.code = code;
-	}
-};
-//#endregion
-Object.defineProperty(exports, "AgentError", {
-	enumerable: true,
-	get: function() {
-		return AgentError;
-	}
-});

package/dist/event-log-store-Bz7HDBkE.d.cts

@@ -1,145 +0,0 @@
-import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { EventObject } from "xstate";
-
-//#region src/event-log-store-conformance.d.ts
-/** Produces a fresh, empty store for one assertion. */
-type CreateStore = () => Promise<AgentEventLogStore> | AgentEventLogStore;
-/**
- * Validates a store against the reference's semantics: empty read + zero length
- * for unknown threads; single and multi-entry append; contiguity misuse guard;
- * stale-`expectedIndex` conflict with correct fields; an interleaved concurrent
- * append race (exactly one winner); event-id uniqueness; `read({ from })`
- * incremental correctness; thread isolation; metadata round-trip; deep-copy
- * isolation on append and read; and the full fork contract.
- */
-declare function assertEventLogStoreConformance(create: CreateStore): Promise<void>;
-//#endregion
-//#region src/event-log-store.d.ts
-/** The durable replay-entry envelope version. */
-declare const AGENT_EVENT_SCHEMA_VERSION: 1;
-/** Values that round-trip through JSON without adapters or silent coercion. */
-type JsonValue = null | boolean | number | string | JsonValue[] | {
-  [key: string]: JsonValue;
-};
-interface AgentLogVerification {
-  /** Hash of the logical machine projection after this entry is applied. */
-  stateHash: string;
-  /** Hash of the serializable effects owed at that frontier. */
-  effectsHash: string;
-}
-/**
- * One journaled entry: an EXTERNAL input to the machine — an effect completion
- * (a `done`/`error` event carrying its output inline), a user-sent event, or a
- * timer firing. Never a raised/internal event: deterministic replay re-derives
- * those from the machine's own logic, so journaling them would double-apply.
- * JSON-safe, stored verbatim.
- */
-interface AgentLogEntry {
-  /** Version of this outer envelope, independent of the machine event type. */
-  schemaVersion: typeof AGENT_EVENT_SCHEMA_VERSION;
-  /** Stable identity within the thread. Forked prefixes retain their ids. */
-  id: string;
-  /** 0-based position in the thread's log. */
-  index: number;
-  /** RFC 3339 wall-clock time when the host accepted the entry. Metadata only. */
-  recordedAt: string;
-  /** The authored XState machine id. */
-  machineId: string;
-  /** Explicit version or structural hash of the machine that accepted the event. */
-  machineVersion: string;
-  event: EventObject;
-  /** Optional causal parent entry id, scoped to the same thread. */
-  causationId?: string;
-  /** Optional host-owned correlation id spanning threads/runs. */
-  correlationId?: string;
-  /** Recorded projection hashes used by strict replay verification. */
-  verification?: AgentLogVerification;
-  /** Host-owned, JSON-safe; stored verbatim, never interpreted. */
-  metadata?: Record<string, JsonValue>;
-}
-/** A precise failure when an entry would not survive a JSON round-trip. */
-declare class NonSerializableAgentEventError extends AgentError {
-  readonly path: string;
-  readonly valueType: string;
-  constructor(path: string, valueType: string);
-}
-/**
- * Rejects values JSON would drop or coerce. Unlike `JSON.stringify`, this does
- * not silently erase `undefined`/functions or turn non-finite numbers into
- * `null`; durable entries contain only plain JSON values.
- */
-declare function assertJsonSerializable(value: unknown, path?: string, ancestors?: WeakSet<object>): asserts value is JsonValue;
-/** Validates the complete durable envelope before append/export/replay. */
-declare function assertAgentLogEntry(entry: unknown): asserts entry is AgentLogEntry;
-/**
- * An append-only event log: the authoritative durability artifact of a thread.
- * The journal of external inputs IS the source of truth — deterministic machine
- * replay derives every snapshot from it, a fork is a copied log prefix, and the
- * type-only {@link AgentSnapshotStore} is a mere idle-point compaction cache
- * over what the log already implies.
- *
- * Userland stores (a Postgres table with a `(thread_id, index)` primary key, an
- * append-only object in blob storage, …) implement this one shape so they
- * interoperate; {@link createInMemoryEventLogStore} is the in-memory reference.
- */
-interface AgentEventLogStore {
-  /**
-   * Append `entries` starting at `expectedIndex` (the current length of the
-   * thread's log; 0 for a new thread). Atomic — all entries land or none do.
-   * Rejects with {@link AgentEventLogConflictError} when the thread's length
-   * differs from `expectedIndex`: a concurrent writer appended first. Each
-   * entry's `index` must be contiguous from `expectedIndex` (a plain `Error`
-   * otherwise: that is caller misuse, not a race).
-   */
-  append(input: {
-    threadId: string;
-    expectedIndex: number;
-    entries: AgentLogEntry[];
-  }): Promise<void>;
-  /**
-   * Read a thread's entries in log order. `from` (default 0) skips entries
-   * below that index for incremental catch-up. An unknown thread reads as an
-   * empty array.
-   */
-  read(threadId: string, options?: {
-    from?: number;
-  }): Promise<AgentLogEntry[]>;
-  /** The thread's current log length (0 for an unknown thread) — the next `expectedIndex`. */
-  length(threadId: string): Promise<number>;
-  /**
-   * Copy the prefix `[0, upToIndex)` onto a fresh, empty `newThreadId`.
-   * Without `upToIndex` the full source is copied. The fork then appends
-   * independently. Rejects (plain `Error`) if `newThreadId` already has
-   * entries, the source is unknown, or `upToIndex` is out of range.
-   * Implementations may copy-on-write or physically copy; observable behavior
-   * must match a full copy.
-   */
-  fork(input: {
-    threadId: string;
-    newThreadId: string; /** Exclusive index cutoff. */
-    upToIndex?: number;
-  }): Promise<void>;
-}
-/**
- * Rejection from {@link AgentEventLogStore.append} when the thread's stored
- * length is not the `expectedIndex` the writer held — a concurrent writer
- * appended first. `actualIndex` is the next index the store would accept.
- */
-declare class AgentEventLogConflictError extends AgentError {
-  readonly threadId: string;
-  readonly expectedIndex: number;
-  readonly actualIndex: number;
-  constructor(threadId: string, expectedIndex: number, actualIndex: number);
-}
-/**
- * In-memory reference store, and the baseline the conformance suite runs
- * against. Per-thread entries are held in a contiguous, index-ordered list;
- * append's check-and-push runs synchronously (no `await` between reading the
- * length and writing), so two appends racing on the same `expectedIndex`
- * resolve to exactly one winner. Every stored and returned entry is
- * `structuredClone`d, so a caller can neither mutate stored state through a
- * value it appended nor through a value it read.
- */
-declare function createInMemoryEventLogStore(): AgentEventLogStore;
-//#endregion
-export { AgentLogVerification as a, assertAgentLogEntry as c, assertEventLogStoreConformance as d, AgentLogEntry as i, assertJsonSerializable as l, AgentEventLogConflictError as n, JsonValue as o, AgentEventLogStore as r, NonSerializableAgentEventError as s, AGENT_EVENT_SCHEMA_VERSION as t, createInMemoryEventLogStore as u };