@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/types-C9QiMjre.d.cts

@@ -0,0 +1,219 @@
+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;
+/**
+ * One entry in an event schema map: a Standard Schema for the event's
+ * payload, or the `{}` shorthand for a payload-less event
+ * (`events: { CONFIRM: {} }` ≡ `events: { CONFIRM: z.object({}) }`).
+ */
+type AgentEventSchemaInput = StandardSchemaV1 | Record<string, never>;
+/** An event schema map as authored: payload schemas and/or `{}` payload-less shorthands, keyed by event type. */
+type AgentEventSchemaInputMap = Record<string, AgentEventSchemaInput>;
+/** Resolves an authored event schema map's `{}` shorthands to real (empty-payload) schemas — the type-level counterpart of the runtime normalization in `createAgentSchemas`. */
+type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof T]: T[K] extends StandardSchemaV1 ? T[K] : StandardSchemaV1<{}> };
+/**
+ * The discriminated event union derived from a machine's event schema map
+ * (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
+ * question: string }`; a `{}` shorthand entry yields its bare `{ type: K }`).
+ * Used internally by {@link createAgentSchemas} and `setupAgent` to type a
+ * machine's `TEvent`.
+ */
+type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
+  type: K;
+} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown) }[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 { 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 };

package/dist/types-qm00QF91.d.mts

@@ -0,0 +1,219 @@
+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;
+/**
+ * One entry in an event schema map: a Standard Schema for the event's
+ * payload, or the `{}` shorthand for a payload-less event
+ * (`events: { CONFIRM: {} }` ≡ `events: { CONFIRM: z.object({}) }`).
+ */
+type AgentEventSchemaInput = StandardSchemaV1 | Record<string, never>;
+/** An event schema map as authored: payload schemas and/or `{}` payload-less shorthands, keyed by event type. */
+type AgentEventSchemaInputMap = Record<string, AgentEventSchemaInput>;
+/** Resolves an authored event schema map's `{}` shorthands to real (empty-payload) schemas — the type-level counterpart of the runtime normalization in `createAgentSchemas`. */
+type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof T]: T[K] extends StandardSchemaV1 ? T[K] : StandardSchemaV1<{}> };
+/**
+ * The discriminated event union derived from a machine's event schema map
+ * (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
+ * question: string }`; a `{}` shorthand entry yields its bare `{ type: K }`).
+ * Used internally by {@link createAgentSchemas} and `setupAgent` to type a
+ * machine's `TEvent`.
+ */
+type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
+  type: K;
+} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown) }[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 { 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 };

package/dist/utils-BYqT_Dyv.d.cts

@@ -0,0 +1,108 @@
+import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, T as TextPart, k as ToolResultPart, p as AssistantMessage, r as AgentMessage, v as FilePart, w as SystemMessage, y as ImagePart } from "./types-C9QiMjre.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/utils-Do5wIJrh.d.mts

@@ -0,0 +1,108 @@
+import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, T as TextPart, k as ToolResultPart, p as AssistantMessage, r as AgentMessage, v as FilePart, w as SystemMessage, y as ImagePart } from "./types-qm00QF91.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 };