@statelyai/agent 2.0.0-alpha.10 → 2.0.0-alpha.12

package/dist/{text-logic-CZjyACzQ.d.cts → text-logic-DjR5PUVz.d.mts}

@@ -1,23 +1,15 @@
-import { C as StandardSchemaV1, b as InferOutput, f as AllowedEvents, m as ChosenEvent, o as AgentToolChoice, r as AgentMessage, u as AgentTools } from "./types-C9QiMjre.cjs";
+import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-_FXoFBGO.mjs";
+import { t as AgentError } from "./errors-C9rxnWbX.mjs";
 import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, MachineSnapshot } from "xstate";
 
 //#region src/events.d.ts
 /** The invoke `src` of an {@link AgentRequest}/{@link AgentDecisionRequest} — a plain string, widened so literal `src` values still narrow in editor hints. */
 type AgentRequestSource = string & {};
-/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. */
-declare const EVENT_TOOL_PREFIX: "send_event_";
 /** Customizes the tool name generated for a candidate event; see {@link AgentRequestOptions.eventToolName}. */
 type AgentEventToolNameResolver = (args: {
   eventType: string;
   defaultToolName: string;
 }) => string;
-/**
- * True when an event type matches an `allowedEvents` entry: an exact type,
- * `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
- * segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
- * `'todo'` itself — mirroring xstate's partial wildcard events).
- */
-declare function matchesEventPattern(eventType: string, pattern: string): boolean;
 /** One candidate event a decision (or {@link getAcceptedEvents} caller) may choose: its type, the synthetic tool name a model can call to pick it, and its payload schema if one is registered. */
 interface AgentEventDescriptor {
   type: string;
@@ -33,21 +25,10 @@ interface AgentRequestOptions {
   snapshot?: AnyMachineSnapshot;
   events?: Record<string, StandardSchemaV1>;
   schemas?: AgentSchemas;
-  actorSources?: Record<string, unknown>;
+  actors?: Record<string, unknown>;
   /** Customize machine-event tool names. Defaults to send_event_<TYPE>. */
   eventToolName?: AgentEventToolNameResolver;
 }
-/**
- * Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
- * a model can be offered (via `resolveDecision`/an adapter's tool-per-event
- * mapping). **Filters by event TYPE only** — it does not evaluate guards, so
- * a type-legal-but-guard-rejected event can still appear here. Guard
- * legality is checked separately, at decision-resolution time, via
- * `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
- * {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
- * declared `allowedEvents` set — entries may be exact types or wildcard
- * patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
- */
 /** Recovers a machine's event union from its snapshot type, so {@link parseAgentEvent} returns the machine-typed event without a downstream cast. @internal */
 type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer TEvent, any, any, any, any, any, any> ? TEvent : EventObject;
 /**
@@ -74,6 +55,22 @@ type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer
 declare function parseAgentEvent<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, event: {
   type: string;
 } & Record<string, unknown>, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName">): EventFromSnapshot<TSnapshot>;
+/**
+ * Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
+ * a model can be offered (via `resolveDecision`/an adapter's tool-per-event
+ * mapping). **Filters by event TYPE only** — it does not evaluate guards, so
+ * a type-legal-but-guard-rejected event can still appear here. Guard
+ * legality is checked separately, at decision-resolution time, via
+ * `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
+ * {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
+ * declared `allowedEvents` set — entries may be exact types or wildcard
+ * patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
+ *
+ * XState-internal (`xstate.*`) and library-reserved
+ * ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
+ * any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
+ * never offers it to a model.
+ */
 declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName"> & {
   eventTypes?: readonly string[];
 }): AgentEventDescriptor[];
@@ -211,21 +208,6 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
-/**
- * Actor logic for a decision: an async effect that resolves to exactly one
- * currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
- * 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 `actorSources:` to reuse/export/
- * test it standalone; for a state-local, zero-config decision, use the
- * `agent.decide` builtin invoke instead.
- */
-interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends AsyncActorLogic<ChosenEvent, InferOutput<TInputSchema>> {
-  readonly kind: "statelyai.decisionLogic";
-  readonly maxRetries: number;
-  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
-  withExecutor(execute: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
-}
 /**
  * A decision request: resolves to exactly one currently-legal event. See
  * `resolveDecision`.
@@ -260,6 +242,15 @@ interface AgentDecisionRequest {
    * `info.signal`). Runtime-only — never serialized into a provider request.
    */
   signal?: AbortSignal;
+  /**
+   * The `runAgent` run this decision belongs to (`run_<n>`, matching trace
+   * events), injected by runAgent 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
+   * on the request: `id` is the durable invoke id and `attempts.length` is
+   * the current attempt index.
+   */
+  runId?: string;
 }
 /**
  * A single failed decision attempt, recorded by {@link resolveDecision} and
@@ -282,8 +273,8 @@ interface DecisionAttempt {
  * diagnostics; a machine typically routes this via the decision invoke's
  * `onError`.
  */
-declare class DecisionExhaustedError extends Error {
-  attempts: DecisionAttempt[];
+declare class AgentDecisionExhaustedError extends AgentError {
+  readonly attempts: DecisionAttempt[];
   constructor(attempts: DecisionAttempt[]);
 }
 /**
@@ -309,12 +300,15 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * adapter business; core only validates and retries the returned choice (see
  * {@link resolveDecision}). The optional `reason` is carried through to
  * `onResult`/event-sourcing but never affects validation. Like text
- * executors' `{ output, ...extras }` envelope, any extra keys (usage, finish
- * reason, …) flow untouched to `onResult`'s `raw`.
+ * executors' `{ output, ...extras }` envelope, 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
+ * aggregated {@link AgentUsage}.
  */
 type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
   event: ChosenEvent;
-  reason?: string;
+  reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
+  usage?: AgentCallUsage;
   [key: string]: unknown;
 }>;
 /**
@@ -356,7 +350,7 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  * the next attempt via `request.attempts`, so an adapter can render "your
  * last choice failed because X — try again" into the next model call; core
  * never rewrites the request itself. Exhausting all attempts throws
- * {@link DecisionExhaustedError} with the full attempts list.
+ * {@link AgentDecisionExhaustedError} with the full attempts list.
  *
  * @example
  * ```ts
@@ -452,6 +446,34 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
+/**
+ * Aggregated model-call usage for ONE `runAgent` call — the run-level total
+ * attached to every settled {@link RunAgentResult} (and therefore to
+ * `generateResult`'s `{ output, snapshot, events, usage }`).
+ *
+ * - `modelCalls` counts every model/decision call this run made (each decision
+ *   retry counts separately) — the same seam `maxModelCalls` budgets. Always a
+ *   number, even when no executor reported tokens.
+ * - Token fields are OPTIONAL and are PARTIAL SUMS: each one sums only the
+ *   calls that reported it, and stays `undefined` when NO call reported it.
+ *   Executors that report nothing (custom hosts, test mocks) simply do not
+ *   contribute — a run mixing reporting and non-reporting calls yields a sum
+ *   over the reporting subset, not `undefined`.
+ * - Aggregation is per-run: a resumed run counts only ITS OWN calls, never the
+ *   history behind `snapshot`/`events`. Add prior runs' totals yourself if you
+ *   want a conversation-wide figure.
+ */
+interface AgentUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+  /** Model/decision calls made by this run (decision retries count separately). */
+  modelCalls: number;
+}
+/** One model call's reported usage — {@link AgentUsage} without the run-level `modelCalls` count. What an executor puts on its result's `usage` field. */
+type AgentCallUsage = Omit<AgentUsage, "modelCalls">;
 /**
  * Inline input for the `agent.userInput` builtin actor — a human-input request
  * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
@@ -488,13 +510,19 @@ type ResolveTextLogicValue<TValue, TInput> = TValue | ((args: {
  * that validate it. Each request-shaping field (`model`, `system`, `prompt`,
  * …) is either a static value or a `({ input }) => value` resolver.
  */
-interface TextLogicConfig<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string> {
+interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string> {
   mode?: AgentRequestMode;
   /** Stamped onto every lowered request as {@link AgentTextRequest.name}. `setupAgent({ requests })` sets this to the request's key. */
   name?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
-  schemas: {
-    input: TInputSchema;
-    output: TOutputSchema;
+  /**
+   * The request's input/output schemas. Both are optional:
+   * - `output` defaults to a string schema (a plain text request).
+   * - `input` defaults to a schema that accepts (and types) `undefined`, so
+   *   the request takes no `input` at the invoke site.
+   */
+  schemas?: {
+    input?: TInputSchema;
+    output?: TOutputSchema;
   };
   model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
   system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
@@ -526,7 +554,7 @@ type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema exte
 /**
  * Actor logic for a text request: an async effect that resolves typed input
  * to typed, schema-validated output via a model call. Built by
- * {@link createTextLogic}; register under `actorSources:` and invoke by name, or
+ * {@link createTextLogic}; register under `actors:` and invoke by name, or
  * bind an executor later with `withExecutor`. The `agent.generateText`/
  * `agent.streamText` builtins and `setupAgent({ requests })` entries are
  * both `TextLogic` under the hood.
@@ -542,14 +570,10 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
   execute(input: InferOutput<TInputSchema>, executors: AgentRequestExecutors): Promise<InferOutput<TOutputSchema>>;
   withExecutor(execute: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 }
-/** Extracts a {@link TextLogic}'s validated input type. */
-type TextLogicInput<TLogic extends TextLogic> = TLogic extends TextLogic<infer TInputSchema, StandardSchemaV1, infer _TMetadata> ? InferOutput<TInputSchema> : never;
-/** Extracts a {@link TextLogic}'s validated output type. */
-type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<StandardSchemaV1, infer TOutputSchema, infer _TMetadata> ? InferOutput<TOutputSchema> : never;
 /**
  * Creates reusable, standalone {@link TextLogic}: an actor that, when run,
  * resolves typed input to typed output via a model call. Register the
- * result under `actorSources:` and invoke it by name (equivalent to what
+ * 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`/
@@ -566,7 +590,7 @@ type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<Standa
  * });
  * ```
  */
-declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function createTextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * Binds a child machine's {@link TextLogic} to a raw
  * {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
@@ -578,7 +602,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * @example
  * ```ts
  * childMachine.provide({
- *   actorSources: {
+ *   actors: {
  *     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
  *   },
  * });
@@ -588,12 +612,18 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
- * Passthrough fields (usage, toolCalls, finishReason, raw, …) are allowed
- * alongside `output` and preserved on the raw result. {@link normalizeGeneratorResult}
+ * Passthrough fields (toolCalls, finishReason, raw, …) are allowed alongside
+ * `output` and preserved on the raw result. {@link normalizeGeneratorResult}
  * unwraps `output`; a non-envelope return 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
+ * {@link AgentUsage}. Optional — an executor that reports nothing still counts
+ * toward `modelCalls`.
  */
 type AgentRequestExecutorResult<TOutput = unknown> = {
-  output: TOutput;
+  output: TOutput; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
+  usage?: AgentCallUsage;
   [key: string]: unknown;
 };
 /**
@@ -604,6 +634,20 @@ type AgentRequestExecutorResult<TOutput = unknown> = {
 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` /
+   * direct `TextLogic.execute`). Lets executor middleware (caching, rate
+   * limits, span parenting) correlate calls without side channels.
+   */
+  runId?: string;
+  /**
+   * The durable invoke id of the request making this call (e.g.
+   * `'0.(machine).asking'`) — stable across resume/replay, and it encodes the
+   * invoking state, so per-state middleware can key on it. Undefined when the
+   * call has no invoking actor.
+   */
+  requestId?: string;
 }
 /**
  * A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
@@ -648,13 +692,15 @@ type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequ
 /**
  * The full set of host executors a machine's agent actors are resolved
  * with — passed to `runAgent`, `executeAgentRequest`, and
- * `TextLogic.execute`. `generateText` is required; `streamText` is only
- * needed if the machine has a `mode: 'stream'` text request, and `decide`
- * only if it uses a decision — omitting either is a bind-time error when the
- * machine actually needs it (see `runAgent`).
+ * `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/plan — omitting
+ * a slot the machine actually needs is a clear bind-time error (see `runAgent`
+ * and `provideExecutors`). Adapter result sets (`AiSdkExecutors`,
+ * `OpenAiCompatExecutors`) re-require all three.
  */
 interface AgentRequestExecutors<TGenerateResult extends AgentRequestExecutorResult = AgentRequestExecutorResult, TStreamResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> {
-  generateText: AgentRequestExecutor<TGenerateResult>;
+  generateText?: AgentRequestExecutor<TGenerateResult>;
   streamText?: AgentRequestExecutor<TStreamResult>;
   decide?: AgentDecisionExecutor;
 }
@@ -670,8 +716,6 @@ type AgentOutputMode = "structured" | "text";
  * as `'text'`.
  */
 declare function getAgentOutputMode(schema?: StandardSchemaV1): AgentOutputMode;
-/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
-declare function isStructuredOutputSchema(schema?: StandardSchemaV1): boolean;
 /** The unwrapped shape a {@link buildEnvelopeSchema} validate returns: the inner
  * `result` value plus, when opted in and present, the model's `reasoning`. */
 interface StructuredOutputEnvelope {
@@ -707,4 +751,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };
+export { AgentDecisionInput as A, resolveDecision as B, createTextLogic as C, parseStructuredEnvelope as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentEventToolNameResolver as H, PLAN_DONE_EVENT_TYPE as I, parseAgentEvent as K, PlanLogic as L, AgentPlanInput as M, AgentPlanOutput as N, AgentDecisionExecutor as O, DecisionAttempt as P, ResolveDecisionOptions as R, buildEnvelopeSchema as S, parseModelRef as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, TextLogic as _, AgentRequestExecutor as a, TextLogicExecutor as b, AgentRequestExecutors as c, AgentUsage as d, AgentUserInput as f, StructuredOutputEnvelope as g, BuiltinAgentActors as h, AgentOutputMode as i, AgentDecisionRequest as j, AgentDecisionExhaustedError as k, AgentRequestMode as l, AiSdkShapedTextResult as m, AgentModelMap as n, AgentRequestExecutorInfo as o, AiSdkShapedStreamResult as p, AgentModelRef as r, AgentRequestExecutorResult as s, AgentCallUsage as t, AgentTextRequest as u, TextLogicConfig as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, renderDecisionAttempts as z };

package/dist/{types-C9QiMjre.d.cts → types-QbEfCVny.d.cts}

@@ -216,4 +216,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as A, StandardSchemaV1 as C, ToolMessage as D, ToolCallPart as E, ToolResultOutput as O, ProviderOptions as S, TextPart as T, EventUnion as _, AgentTool as a, InferOutput as b, AgentToolExecute as c, AllowedEventPattern as d, AllowedEvents as f, EventPayload as g, DataContent as h, AgentSnapshotStore as i, ToolResultPart as k, AgentToolSchema as l, ChosenEvent as m, AgentEventSchemaInputMap as n, AgentToolChoice as o, AssistantMessage as p, AgentMessage as r, AgentToolDescriptor as s, AgentEventSchemaInput as t, AgentTools as u, FilePart as v, SystemMessage as w, NormalizedEventSchemas as x, ImagePart as y };
+export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };

package/dist/{types-qm00QF91.d.mts → types-_FXoFBGO.d.mts}

@@ -216,4 +216,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as A, StandardSchemaV1 as C, ToolMessage as D, ToolCallPart as E, ToolResultOutput as O, ProviderOptions as S, TextPart as T, EventUnion as _, AgentTool as a, InferOutput as b, AgentToolExecute as c, AllowedEventPattern as d, AllowedEvents as f, EventPayload as g, DataContent as h, AgentSnapshotStore as i, ToolResultPart as k, AgentToolSchema as l, ChosenEvent as m, AgentEventSchemaInputMap as n, AgentToolChoice as o, AssistantMessage as p, AgentMessage as r, AgentToolDescriptor as s, AgentEventSchemaInput as t, AgentTools as u, FilePart as v, SystemMessage as w, NormalizedEventSchemas as x, ImagePart as y };
+export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.10",
-  "description": "State-machine authoring layer for AI agents",
+  "version": "2.0.0-alpha.12",
+  "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
-  "bin": {
-    "statelyai-agent": "dist/cli.mjs"
-  },
   "exports": {
     ".": {
       "import": {
@@ -30,31 +27,42 @@
         "default": "./dist/ai-sdk.cjs"
       }
     },
-    "./openai-compat": {
+    "./machines": {
+      "import": {
+        "types": "./dist/machines.d.mts",
+        "default": "./dist/machines.mjs"
+      },
+      "require": {
+        "types": "./dist/machines.d.cts",
+        "default": "./dist/machines.cjs"
+      }
+    },
+    "./otel": {
       "import": {
-        "types": "./dist/openai-compat.d.mts",
-        "default": "./dist/openai-compat.mjs"
+        "types": "./dist/otel.d.mts",
+        "default": "./dist/otel.mjs"
       },
       "require": {
-        "types": "./dist/openai-compat.d.cts",
-        "default": "./dist/openai-compat.cjs"
+        "types": "./dist/otel.d.cts",
+        "default": "./dist/otel.cjs"
       }
     },
-    "./zod": {
+    "./sqlite": {
       "import": {
-        "types": "./dist/zod.d.mts",
-        "default": "./dist/zod.mjs"
+        "types": "./dist/sqlite.d.mts",
+        "default": "./dist/sqlite.mjs"
       },
       "require": {
-        "types": "./dist/zod.d.cts",
-        "default": "./dist/zod.cjs"
+        "types": "./dist/sqlite.d.cts",
+        "default": "./dist/sqlite.cjs"
       }
     },
     "./agent-workflow.json": "./schemas/agent-workflow.json"
   },
   "files": [
     "dist",
-    "schemas"
+    "schemas",
+    "skills"
   ],
   "keywords": [
     "ai",
@@ -80,54 +88,74 @@
     "@anthropic-ai/sdk": "^0.109.1",
     "@changesets/changelog-github": "^0.5.0",
     "@changesets/cli": "^2.27.9",
-    "@cloudflare/workers-types": "^4.20260702.1",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@flue/runtime": "2.0.0",
     "@inquirer/prompts": "^8.5.2",
-    "@statelyai/inspect": "^0.7.2",
+    "@langchain/core": "^1.2.4",
+    "@langchain/openai": "^1.5.5",
+    "@mastra/core": "^1.54.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
+    "@statelyai/sdk": "^0.15.0",
+    "@types/express": "^5.0.6",
     "@types/node": "^20.16.10",
-    "agents": "0.11.5",
+    "@types/react": "^19.2.17",
     "ai": "^6.0.67",
     "ajv": "^8.20.0",
+    "braintrust": "^3.25.0",
     "dotenv": "^16.4.5",
+    "express": "^5.2.1",
+    "hono": "^4.12.30",
     "knip": "6.24.0",
+    "langchain": "^1.5.4",
     "openai": "^6.45.0",
     "oxfmt": "0.57.0",
     "oxlint": "1.72.0",
+    "react": "^19.2.7",
     "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
     "typescript": "^5.6.2",
-    "vitest": "^2.1.2",
-    "xstate": "6.0.0-alpha.21",
+    "valibot": "^1.4.2",
+    "vitest": "^3.2.6",
+    "xstate": "6.0.0-alpha.25",
     "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
+    "@opentelemetry/api": "^1",
     "ai": "^6.0.67",
-    "xstate": ">=6.0.0-alpha.16 <6.0.0",
-    "zod": "^3.25.0 || ^4.0.0"
+    "xstate": ">=6.0.0-alpha.25 <6.0.0"
   },
   "peerDependenciesMeta": {
-    "ai": {
+    "@opentelemetry/api": {
       "optional": true
     },
-    "zod": {
+    "ai": {
       "optional": true
     }
   },
   "scripts": {
     "build": "tsdown",
     "proto:prefabs": "tsx .scratch/prefabs/demo.ts",
-    "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples",
+    "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
     "typecheck:src": "tsc --noEmit",
     "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
+    "typecheck:example-packages": "tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-start-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit",
+    "test:cloudflare": "pnpm --filter @statelyai/example-cloudflare-agent-host test && pnpm --filter @statelyai/example-cloudflare-workers-ai-host test",
     "lint": "oxlint",
     "format": "oxfmt src examples",
     "format:check": "oxfmt --check src examples",
     "knip": "knip",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run knip",
+    "check:dts": "tsc -p fixtures/dts-consumer/tsconfig.json",
     "test": "vitest",
-    "test:ci": "vitest --run",
+    "test:live": "LIVE_TESTS=1 vitest --run",
+    "test:ci": "vitest --run && pnpm run test:cloudflare",
     "changeset": "changeset",
     "release": "changeset publish",
     "version": "changeset version"

package/readme.md

@@ -1,8 +1,8 @@
 # Stately Agent
 
-**The logic layer for AI agents.**
+**Make invalid agent actions impossible.**
 
-Build agents as state machines, with explicit control flow you can inspect, test, visualize, and run anywhere.
+Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere. The machine owns control flow; the model only ever picks a legal event. Testing, inspection, and visualization fall out for free.
 
 Stately Agent adds model requests and decisions to XState. The state machine defines what the agent can do. Your application chooses the model, runs the requests, and stores the state.
 
@@ -12,15 +12,21 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 
 [Documentation](https://stately.ai/docs/agents) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
 
+## Three ways to start
+
+- **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).
+- **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 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).
+
 ## Install
 
 <!-- install command matching the package prerelease channel and package.json peers -->
 
 ```sh
-pnpm add @statelyai/agent@alpha xstate@alpha zod ai @ai-sdk/openai
+pnpm add @statelyai/agent@alpha xstate@alpha zod ai@^6 @ai-sdk/openai@^3
 ```
 
-Node 22.18 or newer is required.
+Node 22.18 or newer is required. The package is ESM-first (CommonJS builds are published too, so `require()` works) and requires XState v6 alpha.25 or newer. Provider packages must match your `ai` major: `@ai-sdk/openai@^3` pairs with `ai@^6` (a bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer).
 
 ## Quick start
 
@@ -30,15 +36,15 @@ This agent reviews refund requests. The model may propose an automatic refund, b
 
 ```ts
 import { openai } from "@ai-sdk/openai";
-import { defineModels, runAgent } from "@statelyai/agent/ai-sdk";
-import { setupAgent } from "@statelyai/agent";
+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 agent = setupAgent({
+const agentSetup = setupAgent({
   models,
   context: z.object({
     request: z.string(),
@@ -57,7 +63,7 @@ const agent = setupAgent({
   },
 });
 
-const refundMachine = agent.createMachine({
+const refundMachine = agentSetup.createMachine({
   context: ({ input }) => input,
   initial: "deciding",
   states: {
@@ -92,6 +98,7 @@ const result = await runAgent(refundMachine, {
     request: "I was charged twice for the same order.",
     amount: 75,
   },
+  executors: createAiSdkExecutors({ models }),
 });
 
 if (result.status === "done") {
@@ -107,6 +114,19 @@ 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.
 
+**Run it with no API key.** `createScriptedExecutors` plays back canned answers through the same executor contract, so the machine above runs end to end before a model is involved:
+
+```ts
+import { createScriptedExecutors } from "@statelyai/agent";
+
+const result = await runAgent(refundMachine, {
+  input: { request: "I was charged twice for the same order.", amount: 75 },
+  executors: createScriptedExecutors({ decisions: [{ type: "AUTO_REFUND" }] }),
+});
+```
+
+Swap in `createAiSdkExecutors({ models })` when you want a real model. The scripted set is what your tests keep using.
+
 ## The state machine
 
 <!-- Add the state machine illustration here. -->
@@ -122,6 +142,7 @@ The example has one model decision and two final outcomes. Real machines can add
 - **Requests are typed.** Inputs, outputs, context, and events use Standard Schema. Zod works out of the box.
 - **Your code runs the model.** `runAgent` accepts executor functions. The example uses the Vercel AI SDK adapter, but the machine does not depend on a provider.
 - **Snapshots can be stored.** An agent can stop for human input, save its XState snapshot, and resume later in another process.
+- **Runs export verified replay entries.** Every `runAgent` result carries a JSON-safe `AgentLogEntry[]` with event identity, timestamp, machine version, and state/effect hashes; pass it to `replay` or `verifyReplay` without repeating model or tool calls.
 - **Machines can be checked without model calls.** Lint their structure, simulate scripted decisions, and explore paths without an API key.
 - **Agents are XState machines.** Guards, actors, parallel states, inspection, testing, and visualization work as usual.
 
@@ -144,4 +165,14 @@ See [all examples](examples/README.md).
 - [Decisions](docs/decisions.md)
 - [Human in the loop](docs/human-in-the-loop.md)
 - [Testing and verification](docs/verify.md)
-- [Running on different hosts](docs/hosts.md)
+- [Evals](docs/evals.md)
+- [Generating machines with an LLM](docs/generate-machines.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)
+- [Observability](docs/observability.md)
+- [Usage and budgets](docs/usage-and-budgets.md)
+- [Agent patterns](docs/patterns.md)
+- [Migrating from a loop](docs/from-a-loop.md)
+- [LangGraph vs agent machines](docs/langgraph-comparison.md)