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

package/dist/{text-logic-DhfFWzu9.d.mts → text-logic-DJBK3LbG.d.mts}

@@ -1,8 +1,71 @@
-import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
-import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
+import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-DWA6X9R-.mjs";
+import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
 
+//#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);
+}
+/**
+ * A model call ran out of output tokens before it produced anything usable.
+ * Core never throws this: it is the adapter's signal that a `'length'` finish
+ * reason left nothing to return — a structured request whose envelope never
+ * closed, say. A text request that WAS cut off still returns its text, with
+ * `finishReason: 'length'`.
+ *
+ * The code is `'truncated'`, so an invoke's `onError` can branch on it without
+ * `instanceof`:
+ *
+ * @example
+ * ```ts
+ * onError: [
+ *   { guard: ({ event }) => event.error.code === 'truncated', target: 'retryShorter' },
+ *   { target: 'failed' },
+ * ]
+ * ```
+ */
+declare class AgentTruncatedError extends AgentError {
+  /** The request that was cut off — `AgentTextRequest.name`. */
+  readonly requestName: string;
+  /** The durable invoke id of the request, when the host knows it. */
+  readonly requestId?: string;
+  /** Whatever the model did produce before it hit the limit, if anything. */
+  readonly partialOutput?: unknown;
+  constructor(message: string, options: {
+    requestName: string;
+    requestId?: string;
+    partialOutput?: unknown;
+    cause?: unknown;
+  });
+}
+//#endregion
 //#region src/events.d.ts
+/**
+ * Thrown by {@link parseAgentEvent} (and {@link eventFromInteraction}) when a
+ * wire payload is not a usable event: it is not an object with a string
+ * `type`, it names a reserved `@agent.*` type, or its fields fail the schema
+ * the machine registered for that type. A host turns it into a 400.
+ *
+ * Not handling an event is NOT this error — a state machine ignores events it
+ * has no transition for, so an event the current state does not handle parses
+ * fine and settles the run with `result.ignored` set.
+ */
+declare class AgentInvalidEventPayloadError extends AgentError {
+  readonly eventType: string;
+  constructor(eventType: string, detail: string);
+}
 /** 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 & {};
 /** Customizes the tool name generated for a candidate event; see {@link AgentRequestOptions.eventToolName}. */
@@ -33,30 +96,32 @@ interface AgentRequestOptions {
 }
 /** 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;
+/** The machine event union {@link parseAgentEvent} returns, from a machine or from a snapshot of one. @internal */
+type ParsedAgentEvent<TSource> = TSource extends AnyStateMachine ? EventFromLogic<TSource> : EventFromSnapshot<TSource>;
 /**
- * Runtime-validates a dynamically-built `{ type, ...payload }` event against a
- * snapshot's currently-accepted events (via {@link getAcceptedEvents}) and,
- * when one is registered, the event type's payload schema — returning the
- * event typed as the machine's event union (recovered from the snapshot type)
- * so it can be sent to `runAgent({ event })` / `actor.send(...)` without an
- * `as never` cast. For generic, meta-driven hosts that assemble events from
- * user input or a wire message.
+ * 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
+ * itself, or any snapshot of it.
+ *
+ * It checks exactly what a schema can check: the payload is an object with a
+ * string `type`, that type is not one of the library-reserved `@agent.*` types,
+ * and — when the machine registered a schema for it — the fields satisfy that
+ * schema (defaults filled, transforms applied). Anything else throws
+ * {@link AgentInvalidEventPayloadError}, which a host answers with a 400.
  *
- * Throws a descriptive error when `event.type` is not currently accepted
- * (listing the accepted types) or when its payload fails the registered schema.
- * Pass event payload schemas via `options.events`/`options.schemas` (the same
- * shape {@link getAcceptedEvents} takes) — the accepted TYPES always come from
- * the live snapshot; the schemas only add payload validation.
+ * It deliberately does NOT check whether the current state handles the event.
+ * State machines ignore events they have no transition for; that is normal
+ * behavior, not a validation failure. Send the parsed event and read
+ * `result.ignored` if the host wants to tell the client nothing happened.
  *
  * @example
  * ```ts
- * const event = parseAgentEvent(result.snapshot, rawEvent, { events: schemas.events });
- * result = await runAgent(machine, { snapshot: result.snapshot, event, executors });
+ * const event = parseAgentEvent(machine, await request.json());
+ * const result = await runAgent(machine, { store, threadId, event, executors });
  * ```
  */
-declare function parseAgentEvent<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, event: {
-  type: string;
-} & Record<string, unknown>, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName">): EventFromSnapshot<TSnapshot>;
+declare function parseAgentEvent<TSource extends AnyStateMachine | AnyMachineSnapshot>(source: TSource, payload: unknown, options?: Pick<AgentRequestOptions, "events" | "schemas">): ParsedAgentEvent<TSource>;
 /**
  * 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
@@ -85,10 +150,13 @@ declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<
  * See {@link AgentDecisionRequest} for the request shape this lowers to.
  */
 interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> {
+  /** Semantic request identity. Defaults to the invoke occurrence id. */
+  name?: string;
   model: TModel;
   system?: string;
   prompt?: string;
-  messages?: AgentMessage[];
+  /** Framework-native messages, passed through without conversion. */
+  messages?: any[];
   allowedEvents?: AllowedEvents<TEvent>;
   maxRetries?: number;
   temperature?: number;
@@ -107,13 +175,16 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
  * {@link AllowedEvents}) and `maxRetries` for {@link resolveDecision}.
  */
 interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TEvent extends string = string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TModel extends string = string> {
+  /** Semantic request identity. Defaults to the invoke occurrence id. */
+  name?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
   schemas?: {
     input: TInputSchema;
   };
   model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
   system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
   prompt?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
-  messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
+  /** Framework-native messages, passed through without conversion. */
+  messages?: ResolveTextLogicValue<any[] | undefined, InferOutput<TInputSchema>>;
   allowedEvents?: AllowedEvents<TEvent, InferOutput<TInputSchema>>;
   maxRetries?: number;
   temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -175,10 +246,15 @@ interface AgentDecisionRequest {
   kind: "decision";
   /** Durable invoke id. */
   id: string;
+  /** Semantic request identity; defaults to {@link id}. */
+  name?: string;
+  /** The schema-validated invoke input that produced this request. */
+  input?: unknown;
   model: string;
   system?: string;
   prompt?: string;
-  messages?: AgentMessage[];
+  /** Framework-native messages, passed through without conversion. */
+  messages?: any[];
   /** Candidate events: declared `allowedEvents` ∩ snapshot-legal events. */
   events: AgentEventDescriptor[];
   /**
@@ -194,13 +270,6 @@ interface AgentDecisionRequest {
   seed?: number;
   stopSequences?: string[];
   metadata?: Record<string, unknown>;
-  /**
-   * Abort signal for the underlying model call, threaded through by
-   * {@link resolveDecision} from its `options.signal` so a `decide` executor
-   * can cancel the in-flight request (symmetric with the text executors'
-   * `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
@@ -211,6 +280,42 @@ interface AgentDecisionRequest {
    */
   runId?: string;
 }
+/**
+ * Options for {@link createDecisionRequest}. Everything except `model` and
+ * `events` is optional; `events` also accepts bare event types.
+ */
+interface CreateDecisionRequestOptions extends Omit<AgentDecisionRequest, "kind" | "id" | "events" | "attempts"> {
+  /** Durable invoke id. Defaults to `name`, then `'decision'`. */
+  id?: string;
+  /** Candidate events: descriptors (from `getAcceptedEvents`) or bare types. */
+  events: readonly (string | AgentEventDescriptor)[];
+  /** Prior failed attempts. Defaults to `[]` (a first attempt). */
+  attempts?: DecisionAttempt[];
+}
+/**
+ * Builds an {@link AgentDecisionRequest} for {@link resolveDecision}, filling
+ * in the fields a hand-written literal has to restate every time: `kind`, an
+ * `id`, an empty `attempts` list, and each candidate event's `toolName`.
+ *
+ * @example
+ * ```ts
+ * const chosen = await resolveDecision(
+ *   createDecisionRequest({
+ *     name: 'judge',
+ *     model: 'reviewer',
+ *     prompt: `Judge this draft.\n\n${snapshot.context.draft}`,
+ *     events: getAcceptedEvents(snapshot),
+ *   }),
+ *   { decide },
+ *   { canTake: (event) => snapshot.can(event) },
+ * );
+ * ```
+ */
+declare function createDecisionRequest(options: CreateDecisionRequestOptions): AgentDecisionRequest;
+/** Decision request after core has resolved its semantic identity. */
+type AgentExecutorDecisionRequest = AgentDecisionRequest & {
+  name: string;
+};
 /**
  * A single failed decision attempt, recorded by {@link resolveDecision} and
  * fed back to the executor on the next attempt via
@@ -267,7 +372,7 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * report this attempt's tokens there and `runAgent` folds them into the run's
  * aggregated {@link AgentUsage}.
  */
-type AgentDecisionExecutor = (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
+type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
   event: ChosenEvent;
   reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
   usage?: AgentCallUsage;
@@ -337,7 +442,7 @@ type AgentModelMap = Record<string, unknown>;
  * autocomplete. Refs are opaque routing keys — the host/executor (or the AI SDK
  * adapter's models map / `resolveModel`) resolves them to a real model.
  */
-type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : keyof TModels & string;
 /**
  * Splits a portable `"provider/model-id"` model ref (the convention JSON
  * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
@@ -361,7 +466,7 @@ declare function parseModelRef(modelRef: string): {
  * `createAiSdkExecutors`) map this shape onto their provider's call
  * settings.
  */
-interface AgentTextRequest<TMetadata = Record<string, unknown>> {
+interface AgentTextRequest<TMetadata = Record<string, unknown>, TMessage = any> {
   /**
    * The registered name of the request that produced this call — the
    * `setupAgent({ requests })` key (also set by `setupAgent.fromConfig`), or
@@ -371,10 +476,12 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    * the caller sets it on the inline input.
    */
   name?: string;
+  /** The schema-validated invoke input that produced this request. */
+  input?: unknown;
   model: string;
   system?: string;
   prompt?: string;
-  messages?: AgentMessage[];
+  messages?: TMessage[];
   /** Host/model tools that are always available to this text call. */
   tools?: AgentTools;
   toolChoice?: AgentToolChoice;
@@ -424,7 +531,7 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
 /**
  * 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 }`).
+ * `runAgent`'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
@@ -449,6 +556,29 @@ interface AgentUsage {
 }
 /** 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">;
+/**
+ * Why a model call stopped, normalized across providers:
+ *
+ * - `'stop'` — the model finished on its own.
+ * - `'length'` — the output token limit cut it off.
+ * - `'tool-calls'` — it stopped to call tools.
+ * - `'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
+ * `request.end` trace event. A provider's own string stays on the result's
+ * `raw`.
+ */
+type AgentFinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "other";
+/**
+ * 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.
+ * A provider's `'error'` normalizes to `'other'`; anything else the union does
+ * not name (an un-normalized provider string, a missing field) returns
+ * `undefined`.
+ */
+declare function getCallFinishReason(raw: unknown): AgentFinishReason | undefined;
 /**
  * Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
  * result's `usage` field, keeping only finite numbers — the same normalization
@@ -522,7 +652,8 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
   model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
   system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
   prompt?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
-  messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
+  /** Framework-native messages, passed through without conversion. */
+  messages?: ResolveTextLogicValue<any[] | undefined, InferOutput<TInputSchema>>;
   tools?: ResolveTextLogicValue<AgentTools | undefined, InferOutput<TInputSchema>>;
   toolChoice?: ResolveTextLogicValue<AgentToolChoice | undefined, InferOutput<TInputSchema>>;
   /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.includeReasoning}). */
@@ -618,9 +749,11 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
  * {@link AgentUsage}. Optional — an executor that reports nothing still counts
  * toward `modelCalls`.
  */
-type AgentRequestExecutorResult<TOutput = unknown> = {
-  output: TOutput; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
-  usage?: AgentCallUsage;
+type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
+  output: TOutput; /** Framework-native response messages, preserved without normalization. */
+  messages?: TMessage[]; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
+  usage?: AgentCallUsage; /** Why this call stopped, normalized (see {@link AgentFinishReason}). Surfaced on the `request.end` trace event. */
+  finishReason?: AgentFinishReason;
   [key: string]: unknown;
 };
 /**
@@ -645,6 +778,24 @@ interface AgentRequestExecutorInfo {
    * call has no invoking actor.
    */
   requestId?: string;
+  /**
+   * A per-call idempotency key, `${executionId}:${requestId}#${n}` — the event
+   * log's lineage id plus the occurrence of this call at this invoke site.
+   * IDENTICAL across a crash re-execution: a run resumed from a log whose last
+   * call was still in flight re-issues that call under the same key, so an
+   * executor-level cache (or a provider's own idempotency header) can return
+   * the first attempt's result instead of paying for it twice. A decision
+   * retry appends its attempt ordinal (`${executionId}:${requestId}#${n}.${a}`,
+   * `a` being the number of prior failed attempts), so a retry never collides
+   * with the rejected attempt it is replacing.
+   *
+   * It identifies the CALL SITE, not the request: a fork inherits its parent's
+   * 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`.
+   */
+  callKey?: string;
 }
 /**
  * A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
@@ -694,15 +845,15 @@ type AiSdkShapedStreamResult = {
  * - `prompt`/`messages` are mutually exclusive, matching `ai`'s `Prompt`
  *   union (core always sets exactly one).
  * - `tools`, `toolChoice`, and `messages` are widened to `any` — their
- *   portable shapes ({@link AgentTools}, {@link AgentToolChoice},
- *   {@link AgentMessage}) are structural supersets of `ai`'s branded types
- *   and would otherwise fail the contravariant check.
+ *   framework-native shapes may be branded and would otherwise fail the
+ *   contravariant check.
  *
  * Hand-written executors that want the precise shapes can annotate their
  * parameter as `AgentTextRequest & { tools: AgentTools }` — that wider
  * parameter type keeps the executor assignable.
  */
-type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "prompt" | "messages" | "tools" | "toolChoice"> & {
+type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "name" | "prompt" | "messages" | "tools" | "toolChoice"> & {
+  /** Semantic request identity; always resolved before an executor is called. */name: string;
   tools: any;
   toolChoice?: any;
 } & ({
@@ -787,4 +938,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExecutor as A, resolveDecision as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogic as F, AgentSchemas as G, AgentEventToolNameResolver as H, DecisionLogicConfig as I, getAcceptedEvents as K, ResolveDecisionOptions as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, createDecisionLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, renderDecisionAttempts as z };
+export { getAcceptedEvents as $, parseOutput as A, DecisionLogicConfig as B, bindRequestExecutor as C, getCallFinishReason as D, getAgentOutputMode as E, AgentDecisionRequest as F, resolveDecision as G, createDecisionLogic as H, AgentExecutorDecisionRequest as I, AgentInvalidEventPayloadError as J, AgentEventDescriptor as K, CreateDecisionRequestOptions as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, getCallUsage as O, AgentDecisionInput as P, EventFromSnapshot as Q, DecisionAttempt as R, TextLogicExecutor as S, createTextLogic as T, createDecisionRequest as U, ResolveDecisionOptions as V, renderDecisionAttempts as W, AgentRequestSource as X, AgentRequestOptions as Y, AgentSchemas as Z, BuiltinAgentActors as _, AgentModelRef as a, TextLogicConfig as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, parseAgentEvent as et, AgentTextRequest as f, AiSdkShapedTextResult as g, AiSdkShapedStreamResult as h, AgentModelMap as i, parseStructuredEnvelope as j, parseModelRef as k, AgentRequestExecutorResult as l, AgentUserInput as m, AgentExecutorTextRequest as n, AgentTruncatedError as nt, AgentOutputMode as o, AgentUsage as p, AgentEventToolNameResolver as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentError as tt, AgentRequestExecutors as u, StructuredOutputEnvelope as v, buildEnvelopeSchema as w, TextLogicExecuteArgs as x, TextLogic as y, DecisionLogic as z };

package/dist/{types-DSdj2tGs.d.cts → types-CjHk5OdH.d.cts}

@@ -1,17 +1,4 @@
-import { Snapshot } from "xstate";
-
 //#region src/types.d.ts
-/**
- * A minimal, type-only contract for a snapshot store: persist a `runAgent`
- * idle/settled snapshot under an id and load it back. It exists purely so
- * userland stores (a file, a SQLite table, a KV row, …) share one shape and
- * interoperate — there is **zero runtime** behind it; the library ships no
- * implementation. See `examples/file-snapshot-store` for a `node:fs` store.
- */
-interface AgentSnapshotStore {
-  load(id: string): Promise<Snapshot<unknown> | undefined>;
-  save(id: string, snapshot: Snapshot<unknown>): Promise<void>;
-}
 /**
  * The [Standard Schema](https://standardschema.dev) interface. Every schema
  * this library accepts (context, events, input/output, tool schemas, …) is a
@@ -176,11 +163,9 @@ type ToolMessage = {
   providerOptions?: ProviderOptions;
 };
 /**
- * A single conversation turn, in this library's portable message model
- * (structurally compatible with the AI SDK's `ModelMessage`). Stored as
- * plain context state — see {@link appendMessages} — and passed to text/
- * decision requests via `messages`. Validate a context field with
- * {@link messagesSchema}.
+ * Optional framework-neutral message helpers. Requests also accept native
+ * framework message values directly; core never converts between formats.
+ * Store messages as plain context state — see {@link appendMessages}.
  */
 type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
 /**
@@ -249,4 +234,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput 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, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };
+export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolDescriptor as a, ToolCallPart as b, AllowedEvents as c, EventUnion as d, FilePart as f, NormalizedEventSchemas as g, InferOutput as h, AgentToolChoice as i, AssistantMessage as l, InferInput as m, AgentMessage as n, AgentToolExecute as o, ImagePart as p, AgentTool as r, AgentTools as s, AgentEventSchemaInputMap as t, ChosenEvent as u, SystemMessage as v, WithAgentInputSchema as w, ToolMessage as x, TextPart as y };

package/dist/{types-CvWRGFxP.d.mts → types-DWA6X9R-.d.mts}

@@ -1,17 +1,4 @@
-import { Snapshot } from "xstate";
-
 //#region src/types.d.ts
-/**
- * A minimal, type-only contract for a snapshot store: persist a `runAgent`
- * idle/settled snapshot under an id and load it back. It exists purely so
- * userland stores (a file, a SQLite table, a KV row, …) share one shape and
- * interoperate — there is **zero runtime** behind it; the library ships no
- * implementation. See `examples/file-snapshot-store` for a `node:fs` store.
- */
-interface AgentSnapshotStore {
-  load(id: string): Promise<Snapshot<unknown> | undefined>;
-  save(id: string, snapshot: Snapshot<unknown>): Promise<void>;
-}
 /**
  * The [Standard Schema](https://standardschema.dev) interface. Every schema
  * this library accepts (context, events, input/output, tool schemas, …) is a
@@ -176,11 +163,9 @@ type ToolMessage = {
   providerOptions?: ProviderOptions;
 };
 /**
- * A single conversation turn, in this library's portable message model
- * (structurally compatible with the AI SDK's `ModelMessage`). Stored as
- * plain context state — see {@link appendMessages} — and passed to text/
- * decision requests via `messages`. Validate a context field with
- * {@link messagesSchema}.
+ * Optional framework-neutral message helpers. Requests also accept native
+ * framework message values directly; core never converts between formats.
+ * Store messages as plain context state — see {@link appendMessages}.
  */
 type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
 /**
@@ -249,4 +234,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput 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, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };
+export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolDescriptor as a, ToolCallPart as b, AllowedEvents as c, EventUnion as d, FilePart as f, NormalizedEventSchemas as g, InferOutput as h, AgentToolChoice as i, AssistantMessage as l, InferInput as m, AgentMessage as n, AgentToolExecute as o, ImagePart as p, AgentTool as r, AgentTools as s, AgentEventSchemaInputMap as t, ChosenEvent as u, SystemMessage as v, WithAgentInputSchema as w, ToolMessage as x, TextPart as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.22",
+  "version": "2.0.0-alpha.23",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -58,6 +58,16 @@
         "default": "./dist/machines.cjs"
       }
     },
+    "./openai": {
+      "import": {
+        "types": "./dist/openai.d.mts",
+        "default": "./dist/openai.mjs"
+      },
+      "require": {
+        "types": "./dist/openai.d.cts",
+        "default": "./dist/openai.cjs"
+      }
+    },
     "./otel": {
       "import": {
         "types": "./dist/otel.d.mts",
@@ -78,16 +88,6 @@
         "default": "./dist/validate.cjs"
       }
     },
-    "./sqlite": {
-      "import": {
-        "types": "./dist/sqlite.d.mts",
-        "default": "./dist/sqlite.mjs"
-      },
-      "require": {
-        "types": "./dist/sqlite.d.cts",
-        "default": "./dist/sqlite.cjs"
-      }
-    },
     "./agent-workflow.json": "./schemas/agent-workflow.json"
   },
   "publishConfig": {
@@ -100,31 +100,23 @@
     "@changesets/cli": "^2.31.1",
     "@earendil-works/pi-ai": "0.83.0",
     "@flue/runtime": "2.0.3",
-    "@inquirer/prompts": "^8.6.0",
     "@langchain/core": "^1.2.9",
     "@langchain/openai": "^1.5.10",
     "@mastra/core": "^1.61.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.22.1",
-    "@types/express": "^5.0.6",
     "@types/node": "^20.19.43",
     "@types/react": "^19.2.18",
     "ai": "^7.0.0",
     "ajv": "^8.20.0",
     "braintrust": "^3.28.0",
     "dotenv": "^16.6.1",
-    "express": "^5.2.1",
-    "hono": "^4.13.3",
     "knip": "6.24.0",
     "langchain": "^1.5.10",
     "openai": "^7.5.0",
     "oxfmt": "0.57.0",
     "oxlint": "1.72.0",
-    "react": "^19.2.8",
     "tsdown": "^0.21.10",
     "tsx": "^4.23.12",
     "twoslash": "^0.3.9",
@@ -138,6 +130,7 @@
     "@opentelemetry/api": "^1",
     "ai": "^7.0.0",
     "ajv": "^8.20.0",
+    "openai": ">=5.0.0 <8",
     "xstate": ">=6.0.0-alpha.46 <6.0.0"
   },
   "peerDependenciesMeta": {
@@ -149,6 +142,9 @@
     },
     "ajv": {
       "optional": true
+    },
+    "openai": {
+      "optional": true
     }
   },
   "engines": {
@@ -162,7 +158,7 @@
     "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": "pnpm run build && 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",
+    "typecheck:example-packages": "pnpm run build && tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit && tsc -p demo --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",
@@ -172,7 +168,7 @@
     "check:dts": "tsc -p fixtures/dts-consumer/tsconfig.json",
     "test": "vitest",
     "test:live": "LIVE_TESTS=1 vitest --run",
-    "test:ci": "vitest --run && pnpm run test:cloudflare",
+    "test:ci": "vitest --run && pnpm run test:cloudflare && pnpm run build && pnpm --filter @statelyai/agent-demo test",
     "changeset": "changeset",
     "release": "changeset publish",
     "version": "changeset version"