@statelyai/agent 1.1.6 → 2.0.0-alpha.5

package/dist/types-BHjeDdch.d.cts

@@ -0,0 +1,208 @@
+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
+ * `StandardSchemaV1` — Zod, Valibot, ArkType, and hand-written validators all
+ * implement it, so the library never depends on a specific validation
+ * library. JSON workflow configs use a caller-provided {@link SchemaCompiler}.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => any;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    };
+    readonly jsonSchema?: {
+      readonly input?: (...args: any[]) => unknown;
+      readonly output?: (...args: any[]) => unknown;
+    };
+  };
+}
+/** The validated output type of a {@link StandardSchemaV1}. */
+type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
+type EventPayload<T> = T extends Record<string, never> ? unknown : T;
+/**
+ * The discriminated event union derived from a machine's event schema map
+ * (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
+ * question: string }`). Used internally by {@link createAgentSchemas} and
+ * `setupAgent` to type a machine's `TEvent`.
+ */
+type EventUnion<T extends Record<string, StandardSchemaV1>> = { [K in keyof T & string]: {
+  type: K;
+} & EventPayload<InferOutput<T[K]>> }[keyof T & string];
+/** Raw binary or string content for an {@link ImagePart}/{@link FilePart}. */
+type DataContent = string | Uint8Array | ArrayBuffer;
+/** Provider-specific passthrough options, keyed by provider name (e.g. `{ anthropic: { cacheControl: ... } }`). */
+type ProviderOptions = Record<string, Record<string, unknown>>;
+/** A plain-text segment of a multi-part {@link AgentMessage} content array. */
+interface TextPart {
+  type: "text";
+  text: string;
+  providerOptions?: ProviderOptions;
+}
+/**
+ * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
+ * JSON-serializable. Machines that persist snapshots/event logs should use
+ * URL strings or base64-encoded strings in `image` instead.
+ */
+interface ImagePart {
+  type: "image";
+  image: DataContent | URL;
+  mediaType?: string;
+  providerOptions?: ProviderOptions;
+}
+/**
+ * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
+ * JSON-serializable. Machines that persist snapshots/event logs should use
+ * URL strings or base64-encoded strings in `data` instead.
+ */
+interface FilePart {
+  type: "file";
+  data: DataContent | URL;
+  mediaType: string;
+  filename?: string;
+  providerOptions?: ProviderOptions;
+}
+/** A model-issued tool call, as an {@link AssistantMessage} content part. */
+interface ToolCallPart {
+  type: "tool-call";
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  providerOptions?: ProviderOptions;
+}
+/** The result payload of a {@link ToolResultPart}, discriminated by shape (plain text/JSON, or an error variant of either). */
+type ToolResultOutput = {
+  type: "text";
+  value: string;
+} | {
+  type: "json";
+  value: unknown;
+} | {
+  type: "error-text";
+  value: string;
+} | {
+  type: "error-json";
+  value: unknown;
+} | {
+  type: "content";
+  value: Array<TextPart | ImagePart>;
+};
+/** A tool's result, as a {@link ToolMessage} content part. */
+interface ToolResultPart {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  output: ToolResultOutput;
+  providerOptions?: ProviderOptions;
+}
+/** A system-role {@link AgentMessage}. Create with {@link systemMessage}. */
+type SystemMessage = {
+  role: "system";
+  content: string;
+  providerOptions?: ProviderOptions;
+};
+/** A user-role {@link AgentMessage}, optionally multimodal. Create with {@link userMessage}. */
+type UserMessage = {
+  role: "user";
+  content: string | Array<TextPart | ImagePart | FilePart>;
+  providerOptions?: ProviderOptions;
+};
+/** An assistant-role {@link AgentMessage}, which may carry tool calls/results inline. Create with {@link assistantMessage}. */
+type AssistantMessage = {
+  role: "assistant";
+  content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>;
+  providerOptions?: ProviderOptions;
+};
+/** A tool-role {@link AgentMessage} carrying one or more tool results. Create with {@link toolMessage}. */
+type ToolMessage = {
+  role: "tool";
+  content: Array<ToolResultPart>;
+  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}.
+ */
+type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+/**
+ * A schema value on an {@link AgentToolDescriptor}. Core reads it as a
+ * {@link StandardSchemaV1} (via `getJsonSchema`/`isStandardSchema`) when it can,
+ * but the type is deliberately widened with `object` so an SDK-native tool —
+ * whose `inputSchema` is the SDK's own union type (a Zod schema, the SDK's
+ * `Schema`, a lazy thunk, …) — assigns structurally with no cast.
+ */
+type AgentToolSchema = StandardSchemaV1 | object;
+/**
+ * A tool exposed to a text request, described for both the model and
+ * (optionally) host execution. This is a **minimal structural contract**: any
+ * object matching it — an AI SDK `tool({...})`, an MCP-style descriptor, or a
+ * hand-written `{ description, inputSchema, execute }` — is a valid entry, and
+ * extra properties (`providerOptions`, `toModelOutput`, …) pass through
+ * untouched via the index signature. `execute` is typed permissively so a
+ * native tool's `(input, options)` executor is structurally assignable; the
+ * SDK you built the tool with owns its precise input typing.
+ */
+interface AgentToolDescriptor {
+  description?: string;
+  inputSchema?: AgentToolSchema;
+  outputSchema?: AgentToolSchema;
+  execute?: (...args: any[]) => unknown;
+  [key: string]: unknown;
+}
+/** A bare tool implementation (no description/schema) — shorthand for {@link AgentToolDescriptor.execute}. */
+type AgentToolExecute = (input?: unknown) => unknown | Promise<unknown>;
+/** A tool entry in {@link AgentTools}: either a full descriptor or a bare execute function. */
+type AgentTool = AgentToolDescriptor | AgentToolExecute;
+/** The `tools` map passed on an {@link AgentTextRequest}, keyed by tool name. */
+type AgentTools = Record<string, AgentTool | undefined>;
+/** How a text request's model should select among its `tools`; `{ type: 'tool', name }` forces one specific tool. */
+type AgentToolChoice = "auto" | "none" | "required" | {
+  type: "tool";
+  name: string;
+};
+/** The event chosen and raised by a decision. */
+type ChosenEvent = {
+  type: string;
+  [key: string]: unknown;
+};
+type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${infer Rest}` ? `${Head}.*` | `${Head}.${EventWildcardsOf<Rest>}` : never;
+/** One `allowedEvents` entry: an exact declared event type, `'*'` (every event), or a `'prefix.*'` wildcard derived from the declared dotted event types. */
+type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventWildcardsOf<TEvent>;
+/**
+ * Candidate event types for a decision or plan (declared on the
+ * `agent.decide`/`agent.plan` builtins' `allowedEvents` input). A single
+ * entry or an array; entries are exact event types or wildcard patterns
+ * (`'*'` for every event, `'todo.*'` for a dotted namespace). The effective
+ * candidate set offered to the model is this declaration **intersected with
+ * the snapshot's currently-legal events** (via `getAcceptedEvents`) —
+ * omitting `allowedEvents` means "all currently-legal events." A resolver
+ * function can therefore only ever narrow, never widen, the real surface.
+ * Wildcards expand against the live snapshot, so they need a snapshot-aware
+ * host (`runAgent` or the step path).
+ */
+type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
+  input: TInput;
+}) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
+//#endregion
+export { ToolCallPart as C, UserMessage as D, ToolResultPart as E, TextPart as S, ToolResultOutput as T, ImagePart as _, AgentToolDescriptor as a, StandardSchemaV1 as b, AgentTools as c, AssistantMessage as d, ChosenEvent as f, FilePart as g, EventUnion as h, AgentToolChoice as i, AllowedEventPattern as l, EventPayload as m, AgentSnapshotStore as n, AgentToolExecute as o, DataContent as p, AgentTool as r, AgentToolSchema as s, AgentMessage as t, AllowedEvents as u, InferOutput as v, ToolMessage as w, SystemMessage as x, ProviderOptions as y };

package/dist/types-Cq1YlAQ6.d.mts

@@ -0,0 +1,208 @@
+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
+ * `StandardSchemaV1` — Zod, Valibot, ArkType, and hand-written validators all
+ * implement it, so the library never depends on a specific validation
+ * library. JSON workflow configs use a caller-provided {@link SchemaCompiler}.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => any;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    };
+    readonly jsonSchema?: {
+      readonly input?: (...args: any[]) => unknown;
+      readonly output?: (...args: any[]) => unknown;
+    };
+  };
+}
+/** The validated output type of a {@link StandardSchemaV1}. */
+type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
+type EventPayload<T> = T extends Record<string, never> ? unknown : T;
+/**
+ * The discriminated event union derived from a machine's event schema map
+ * (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
+ * question: string }`). Used internally by {@link createAgentSchemas} and
+ * `setupAgent` to type a machine's `TEvent`.
+ */
+type EventUnion<T extends Record<string, StandardSchemaV1>> = { [K in keyof T & string]: {
+  type: K;
+} & EventPayload<InferOutput<T[K]>> }[keyof T & string];
+/** Raw binary or string content for an {@link ImagePart}/{@link FilePart}. */
+type DataContent = string | Uint8Array | ArrayBuffer;
+/** Provider-specific passthrough options, keyed by provider name (e.g. `{ anthropic: { cacheControl: ... } }`). */
+type ProviderOptions = Record<string, Record<string, unknown>>;
+/** A plain-text segment of a multi-part {@link AgentMessage} content array. */
+interface TextPart {
+  type: "text";
+  text: string;
+  providerOptions?: ProviderOptions;
+}
+/**
+ * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
+ * JSON-serializable. Machines that persist snapshots/event logs should use
+ * URL strings or base64-encoded strings in `image` instead.
+ */
+interface ImagePart {
+  type: "image";
+  image: DataContent | URL;
+  mediaType?: string;
+  providerOptions?: ProviderOptions;
+}
+/**
+ * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
+ * JSON-serializable. Machines that persist snapshots/event logs should use
+ * URL strings or base64-encoded strings in `data` instead.
+ */
+interface FilePart {
+  type: "file";
+  data: DataContent | URL;
+  mediaType: string;
+  filename?: string;
+  providerOptions?: ProviderOptions;
+}
+/** A model-issued tool call, as an {@link AssistantMessage} content part. */
+interface ToolCallPart {
+  type: "tool-call";
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  providerOptions?: ProviderOptions;
+}
+/** The result payload of a {@link ToolResultPart}, discriminated by shape (plain text/JSON, or an error variant of either). */
+type ToolResultOutput = {
+  type: "text";
+  value: string;
+} | {
+  type: "json";
+  value: unknown;
+} | {
+  type: "error-text";
+  value: string;
+} | {
+  type: "error-json";
+  value: unknown;
+} | {
+  type: "content";
+  value: Array<TextPart | ImagePart>;
+};
+/** A tool's result, as a {@link ToolMessage} content part. */
+interface ToolResultPart {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  output: ToolResultOutput;
+  providerOptions?: ProviderOptions;
+}
+/** A system-role {@link AgentMessage}. Create with {@link systemMessage}. */
+type SystemMessage = {
+  role: "system";
+  content: string;
+  providerOptions?: ProviderOptions;
+};
+/** A user-role {@link AgentMessage}, optionally multimodal. Create with {@link userMessage}. */
+type UserMessage = {
+  role: "user";
+  content: string | Array<TextPart | ImagePart | FilePart>;
+  providerOptions?: ProviderOptions;
+};
+/** An assistant-role {@link AgentMessage}, which may carry tool calls/results inline. Create with {@link assistantMessage}. */
+type AssistantMessage = {
+  role: "assistant";
+  content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>;
+  providerOptions?: ProviderOptions;
+};
+/** A tool-role {@link AgentMessage} carrying one or more tool results. Create with {@link toolMessage}. */
+type ToolMessage = {
+  role: "tool";
+  content: Array<ToolResultPart>;
+  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}.
+ */
+type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+/**
+ * A schema value on an {@link AgentToolDescriptor}. Core reads it as a
+ * {@link StandardSchemaV1} (via `getJsonSchema`/`isStandardSchema`) when it can,
+ * but the type is deliberately widened with `object` so an SDK-native tool —
+ * whose `inputSchema` is the SDK's own union type (a Zod schema, the SDK's
+ * `Schema`, a lazy thunk, …) — assigns structurally with no cast.
+ */
+type AgentToolSchema = StandardSchemaV1 | object;
+/**
+ * A tool exposed to a text request, described for both the model and
+ * (optionally) host execution. This is a **minimal structural contract**: any
+ * object matching it — an AI SDK `tool({...})`, an MCP-style descriptor, or a
+ * hand-written `{ description, inputSchema, execute }` — is a valid entry, and
+ * extra properties (`providerOptions`, `toModelOutput`, …) pass through
+ * untouched via the index signature. `execute` is typed permissively so a
+ * native tool's `(input, options)` executor is structurally assignable; the
+ * SDK you built the tool with owns its precise input typing.
+ */
+interface AgentToolDescriptor {
+  description?: string;
+  inputSchema?: AgentToolSchema;
+  outputSchema?: AgentToolSchema;
+  execute?: (...args: any[]) => unknown;
+  [key: string]: unknown;
+}
+/** A bare tool implementation (no description/schema) — shorthand for {@link AgentToolDescriptor.execute}. */
+type AgentToolExecute = (input?: unknown) => unknown | Promise<unknown>;
+/** A tool entry in {@link AgentTools}: either a full descriptor or a bare execute function. */
+type AgentTool = AgentToolDescriptor | AgentToolExecute;
+/** The `tools` map passed on an {@link AgentTextRequest}, keyed by tool name. */
+type AgentTools = Record<string, AgentTool | undefined>;
+/** How a text request's model should select among its `tools`; `{ type: 'tool', name }` forces one specific tool. */
+type AgentToolChoice = "auto" | "none" | "required" | {
+  type: "tool";
+  name: string;
+};
+/** The event chosen and raised by a decision. */
+type ChosenEvent = {
+  type: string;
+  [key: string]: unknown;
+};
+type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${infer Rest}` ? `${Head}.*` | `${Head}.${EventWildcardsOf<Rest>}` : never;
+/** One `allowedEvents` entry: an exact declared event type, `'*'` (every event), or a `'prefix.*'` wildcard derived from the declared dotted event types. */
+type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventWildcardsOf<TEvent>;
+/**
+ * Candidate event types for a decision or plan (declared on the
+ * `agent.decide`/`agent.plan` builtins' `allowedEvents` input). A single
+ * entry or an array; entries are exact event types or wildcard patterns
+ * (`'*'` for every event, `'todo.*'` for a dotted namespace). The effective
+ * candidate set offered to the model is this declaration **intersected with
+ * the snapshot's currently-legal events** (via `getAcceptedEvents`) —
+ * omitting `allowedEvents` means "all currently-legal events." A resolver
+ * function can therefore only ever narrow, never widen, the real surface.
+ * Wildcards expand against the live snapshot, so they need a snapshot-aware
+ * host (`runAgent` or the step path).
+ */
+type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
+  input: TInput;
+}) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
+//#endregion
+export { ToolCallPart as C, UserMessage as D, ToolResultPart as E, TextPart as S, ToolResultOutput as T, ImagePart as _, AgentToolDescriptor as a, StandardSchemaV1 as b, AgentTools as c, AssistantMessage as d, ChosenEvent as f, FilePart as g, EventUnion as h, AgentToolChoice as i, AllowedEventPattern as l, EventPayload as m, AgentSnapshotStore as n, AgentToolExecute as o, DataContent as p, AgentTool as r, AgentToolSchema as s, AgentMessage as t, AllowedEvents as u, InferOutput as v, ToolMessage as w, SystemMessage as x, ProviderOptions as y };

package/dist/utils-CWUCa3pF.d.mts

@@ -0,0 +1,108 @@
+import { C as ToolCallPart, D as UserMessage, E as ToolResultPart, S as TextPart, _ as ImagePart, b as StandardSchemaV1, d as AssistantMessage, g as FilePart, t as AgentMessage, w as ToolMessage, x as SystemMessage } from "./types-Cq1YlAQ6.mjs";
+import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
+
+//#region src/utils.d.ts
+/**
+ * Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
+ * shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
+ * JSON-serializability: functions, `undefined`, and other non-JSON values are
+ * dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
+ * plain-JSON deep clone, not a live snapshot.
+ */
+declare function persistSnapshot<TSnapshot>(snapshot: TSnapshot): TSnapshot;
+/**
+ * A stable, dependency-free structural fingerprint of a machine — a short hex
+ * `djb2` hash over its **structural** config only: state ids/nesting, transition
+ * event types and targets, invoke `src`s, `initial`, and any other serializable
+ * config fields. Function values (context/output builders, prompts, inline
+ * guards/actions) are excluded entirely, so two machines that differ only in
+ * 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
+ * detect a structurally-edited machine on resume. It is a change detector, not
+ * a cryptographic digest — collisions are possible but unlikely for real
+ * configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+ */
+declare function getMachineStructuralHash(machine: AnyStateMachine): string;
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
+/** Builds a {@link SystemMessage}. */
+declare function systemMessage(content: string): SystemMessage;
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
+type MetaOfSnapshot<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
+/**
+ * Returns the merged `meta` of a snapshot's active state(s) — the typed
+ * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+ *
+ * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+ * state, but parallel/nested machines can have several. This shallow-merges
+ * every active state's meta into one object (later/deeper entries win) and
+ * returns `{}` when no active state declares meta.
+ *
+ * The return type is recovered from the snapshot's own `getMeta()` type, so a
+ * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+ * output type. Pass an explicit `TMeta` to override when the snapshot is
+ * untyped (e.g. `AnyMachineSnapshot`).
+ *
+ * @example HITL: read the current state's interaction protocol off an idle
+ * snapshot to render for a human.
+ * ```ts
+ * const { interaction } = getStateMeta(result.snapshot);
+ * ```
+ */
+declare function getStateMeta<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
+/**
+ * Reads the run-owned message log off a snapshot settled by a `runAgent` call
+ * that used `getRequests` (or `options.messages`) — the typed replacement for
+ * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+ * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+ * so it survives a JSON persist/resume round-trip; this accessor works on the
+ * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+ * when no log was stamped (e.g. a default invoke-driven run).
+ *
+ * The write path is `runAgent(..., { messages })`: an explicit seed that
+ * overrides the resume snapshot's stamped log (fold in a user reply on
+ * resume, or start a run with prior history).
+ */
+declare function getAgentMessages(snapshot: unknown): AgentMessage[];
+/**
+ * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+ * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+ * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+ * can't read directly — see the `ai-sdk` tool pass-through and `openai-compat`
+ * tool serialization.
+ */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+ * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+ * `z.toJSONSchema`), awaiting it when the producer is async. Returns
+ * `undefined` when the schema doesn't expose the extension. Use this to build
+ * a provider request's `response_format`/tool `parameters` from a schema.
+ */
+declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
+/**
+ * Synchronous variant of {@link getJsonSchema}, for call sites that can't
+ * await (building tool/event descriptors inline). An async JSON Schema
+ * producer is treated as absent (returns `undefined`) — in practice Zod's
+ * `z.toJSONSchema` resolves synchronously.
+ */
+declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
+/**
+ * Validates `value` against a {@link StandardSchemaV1}, synchronously.
+ * Throws if the schema's `validate` returns a `Promise` (async validation is
+ * not supported anywhere in this library) or if validation reports issues —
+ * in which case the thrown `Error.message` joins every issue message with
+ * `', '`.
+ */
+declare function validateSchemaSync<T>(schema: StandardSchemaV1<T>, value: unknown): T;
+//#endregion
+export { getMachineStructuralHash as a, persistSnapshot as c, userMessage as d, validateSchemaSync as f, getJsonSchemaSync as i, systemMessage as l, getAgentMessages as n, getStateMeta as o, getJsonSchema as r, isStandardSchema as s, assistantMessage as t, toolMessage as u };

package/dist/utils-lK1wnL2i.d.cts

@@ -0,0 +1,108 @@
+import { C as ToolCallPart, D as UserMessage, E as ToolResultPart, S as TextPart, _ as ImagePart, b as StandardSchemaV1, d as AssistantMessage, g as FilePart, t as AgentMessage, w as ToolMessage, x as SystemMessage } from "./types-BHjeDdch.cjs";
+import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
+
+//#region src/utils.d.ts
+/**
+ * Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
+ * shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
+ * JSON-serializability: functions, `undefined`, and other non-JSON values are
+ * dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
+ * plain-JSON deep clone, not a live snapshot.
+ */
+declare function persistSnapshot<TSnapshot>(snapshot: TSnapshot): TSnapshot;
+/**
+ * A stable, dependency-free structural fingerprint of a machine — a short hex
+ * `djb2` hash over its **structural** config only: state ids/nesting, transition
+ * event types and targets, invoke `src`s, `initial`, and any other serializable
+ * config fields. Function values (context/output builders, prompts, inline
+ * guards/actions) are excluded entirely, so two machines that differ only in
+ * 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
+ * detect a structurally-edited machine on resume. It is a change detector, not
+ * a cryptographic digest — collisions are possible but unlikely for real
+ * configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+ */
+declare function getMachineStructuralHash(machine: AnyStateMachine): string;
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
+/** Builds a {@link SystemMessage}. */
+declare function systemMessage(content: string): SystemMessage;
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
+type MetaOfSnapshot<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
+/**
+ * Returns the merged `meta` of a snapshot's active state(s) — the typed
+ * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+ *
+ * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+ * state, but parallel/nested machines can have several. This shallow-merges
+ * every active state's meta into one object (later/deeper entries win) and
+ * returns `{}` when no active state declares meta.
+ *
+ * The return type is recovered from the snapshot's own `getMeta()` type, so a
+ * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+ * output type. Pass an explicit `TMeta` to override when the snapshot is
+ * untyped (e.g. `AnyMachineSnapshot`).
+ *
+ * @example HITL: read the current state's interaction protocol off an idle
+ * snapshot to render for a human.
+ * ```ts
+ * const { interaction } = getStateMeta(result.snapshot);
+ * ```
+ */
+declare function getStateMeta<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
+/**
+ * Reads the run-owned message log off a snapshot settled by a `runAgent` call
+ * that used `getRequests` (or `options.messages`) — the typed replacement for
+ * the `(snapshot as { messages?: AgentMessage[] }).messages` cast. runAgent
+ * stamps the log as a plain enumerable `messages` property (like `agentMeta`),
+ * so it survives a JSON persist/resume round-trip; this accessor works on the
+ * live settled snapshot and on a JSON-parsed persisted one alike. Returns `[]`
+ * when no log was stamped (e.g. a default invoke-driven run).
+ *
+ * The write path is `runAgent(..., { messages })`: an explicit seed that
+ * overrides the resume snapshot's stamped log (fold in a user reply on
+ * resume, or start a run with prior history).
+ */
+declare function getAgentMessages(snapshot: unknown): AgentMessage[];
+/**
+ * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+ * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+ * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+ * can't read directly — see the `ai-sdk` tool pass-through and `openai-compat`
+ * tool serialization.
+ */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+ * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+ * `z.toJSONSchema`), awaiting it when the producer is async. Returns
+ * `undefined` when the schema doesn't expose the extension. Use this to build
+ * a provider request's `response_format`/tool `parameters` from a schema.
+ */
+declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
+/**
+ * Synchronous variant of {@link getJsonSchema}, for call sites that can't
+ * await (building tool/event descriptors inline). An async JSON Schema
+ * producer is treated as absent (returns `undefined`) — in practice Zod's
+ * `z.toJSONSchema` resolves synchronously.
+ */
+declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
+/**
+ * Validates `value` against a {@link StandardSchemaV1}, synchronously.
+ * Throws if the schema's `validate` returns a `Promise` (async validation is
+ * not supported anywhere in this library) or if validation reports issues —
+ * in which case the thrown `Error.message` joins every issue message with
+ * `', '`.
+ */
+declare function validateSchemaSync<T>(schema: StandardSchemaV1<T>, value: unknown): T;
+//#endregion
+export { getMachineStructuralHash as a, persistSnapshot as c, userMessage as d, validateSchemaSync as f, getJsonSchemaSync as i, systemMessage as l, getAgentMessages as n, getStateMeta as o, getJsonSchema as r, isStandardSchema as s, assistantMessage as t, toolMessage as u };

package/dist/zod.cjs

@@ -0,0 +1,31 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/zod/index.ts
+/**
+* A zod schema for an `AgentMessage[]` context/input field — the typed,
+* dependency-light replacement for the hand-rolled
+* `z.custom<AgentMessage[]>((value) => Array.isArray(value))` recipe repeated
+* across machines that carry a message transcript in context.
+*
+* `AgentMessage` is a structural union (see `src/types.ts`), not something to
+* re-declare as a zod object, so this stays a `z.custom` under the hood while
+* exposing the precise `z.ZodType<AgentMessage[]>` type. Validation checks that
+* the value is an array; element shape is trusted (the library's own message
+* builders and adapters produce well-formed `AgentMessage`s).
+*
+* `zod` is an optional peer of `@statelyai/agent` — this subpath is the only
+* place it's imported, mirroring how `./ai-sdk` gates on `ai`.
+*
+* @example
+* ```ts
+* import { z } from 'zod';
+* import { zodAgentMessages } from '@statelyai/agent/zod';
+*
+* const context = z.object({ messages: zodAgentMessages() });
+* ```
+*/
+function zodAgentMessages() {
+	return zod.z.custom((value) => Array.isArray(value));
+}
+//#endregion
+exports.zodAgentMessages = zodAgentMessages;