@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.29

package/dist/{text-logic-IjfYy9DP.d.cts → text-logic-9fv1i9aK.d.cts}

@@ -1,6 +1,5 @@
-import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-hR5f5YXa.cjs";
+import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
 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
@@ -152,6 +151,14 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
   /** Framework-native messages, passed through without conversion. */
   messages?: any[];
   allowedEvents?: AllowedEvents<TEvent>;
+  /**
+   * Concrete payloads per event type, without `type`. When given, the
+   * decision is a closed choice: the request carries one
+   * {@link AgentDecisionOption} per payload whose event the snapshot accepts,
+   * and the decider picks one instead of writing a payload. Event types in
+   * `allowedEvents` with no entry here are offered as `{ type }`.
+   */
+  payloads?: Partial<Record<TEvent, Record<string, unknown>[]>>;
   maxRetries?: number;
   temperature?: number;
   maxOutputTokens?: number;
@@ -251,6 +258,21 @@ interface AgentDecisionRequest {
   messages?: any[];
   /** Candidate events: declared `allowedEvents` ∩ snapshot-legal events. */
   events: AgentEventDescriptor[];
+  /**
+   * Concrete choices, present when the host enumerated payloads
+   * (`payloads` on the decide input, or `decideNext`). A snapshot-aware host
+   * keeps only options the snapshot accepts. An executor that sees options
+   * should choose one of them; a chosen event matching no option is
+   * rejected and retried like a guard rejection.
+   */
+  options?: AgentDecisionOption[];
+  /**
+   * Candidate events the snapshot rejected when the options were built:
+   * enumerated like `options`, but `snapshot.can(event)` was false. Never
+   * offered; executors ignore it. Set by `decideNext` and by the runtime's
+   * closed choices, so a `request.start` trace shows what the guards blocked.
+   */
+  withheld?: ChosenEvent[];
   /**
    * Prior failed attempts for THIS decision. Empty on the first attempt.
    * Adapters render these into the provider request so retries converge.
@@ -264,6 +286,11 @@ interface AgentDecisionRequest {
   seed?: number;
   stopSequences?: string[];
   metadata?: Record<string, unknown>;
+  /**
+   * Per-invoke retry budget lowered from `agent.decide` inline input. Hosts
+   * prefer it over the logic's configured `maxRetries` when set.
+   */
+  maxRetries?: number;
   /**
    * The run this decision belongs to (`run_<n>`, matching trace
    * events), injected by the runtime like `signal` (symmetric with the text
@@ -310,6 +337,12 @@ declare function createDecisionRequest(options: CreateDecisionRequestOptions): A
 type AgentExecutorDecisionRequest = AgentDecisionRequest & {
   name: string;
 };
+/** One concrete event a decider may choose, with an optional description for the model. */
+interface AgentDecisionOption {
+  event: ChosenEvent;
+  /** What choosing this does, in words; lookahead text when the host computed it. */
+  description?: string;
+}
 /**
  * A single failed decision attempt, recorded by {@link resolveDecision} and
  * fed back to the executor on the next attempt via
@@ -317,7 +350,7 @@ type AgentExecutorDecisionRequest = AgentDecisionRequest & {
  * choice: `'unknown-event'` (not among the candidate `events`),
  * `'invalid-payload'` (failed the event's schema), or `'rejected-by-guard'`
  * (failed the `canTake` check — type/payload were legal, but the machine's
- * guard rejected it at apply time).
+ * guard rejected it at apply time — or matched none of `request.options`).
  */
 interface DecisionAttempt {
   event?: ChosenEvent;
@@ -349,7 +382,7 @@ declare class AgentDecisionExhaustedError extends AgentError {
  * const messages = [...baseMessages, ...renderDecisionAttempts(request)];
  * ```
  */
-declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "events" | "attempts">): AgentMessage[];
+declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "events" | "attempts" | "options">): AgentMessage[];
 /**
  * Host implementation of "make the model choose one of `request.events`."
  * Third executor slot on {@link AgentRequestExecutors}, symmetric with
@@ -368,7 +401,8 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  */
 type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
   event: ChosenEvent;
-  reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
+  reason?: string;
+  /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
   usage?: AgentCallUsage;
   [key: string]: unknown;
 }>;
@@ -407,6 +441,8 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  * event's schema), or `'rejected-by-guard'` (passes both checks but
  * `options.canTake` returns `false` — a type/payload-legal event the
  * machine's guard rejects right now; omit `canTake` to skip this check).
+ * When the request carries `options`, a choice matching none of them (type and
+ * payload, deep-equal) also fails as `'rejected-by-guard'`.
  * Every prior failed attempt for this call is fed back to the executor on
  * the next attempt via `request.attempts`, so an adapter can render "your
  * last choice failed because X — try again" into the next model call; core
@@ -737,9 +773,12 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
  * toward `modelCalls`.
  */
 type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
-  result: TOutput; /** The provider's response messages for this call (the assistant turn, tool calls and results). */
-  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. */
+  result: TOutput;
+  /** The provider's response messages for this call (the assistant turn, tool calls and results). */
+  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;
 };
@@ -789,7 +828,8 @@ interface AgentRequestExecutorInfo {
  * `tools` merged in. Exactly one of `prompt`/`messages` is set.
  */
 type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "name" | "tools"> & {
-  /** Semantic request identity; always resolved before an executor is called. */name: string;
+  /** Semantic request identity; always resolved before an executor is called. */
+  name: string;
   tools: AgentTools;
 };
 /**
@@ -861,4 +901,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
 //#endregion
-export { AgentDecisionExhaustedError as A, createDecisionRequest as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, DecisionAttempt as F, AgentRequestOptions as G, resolveDecision as H, DecisionLogic as I, EventFromSnapshot as J, AgentRequestSource as K, DecisionLogicConfig as L, AgentDecisionRequest as M, AgentExecutorDecisionRequest as N, providerOutputSchema as O, CreateDecisionRequestOptions as P, AgentTruncatedError as Q, ResolveDecisionOptions as R, createTextLogic as S, getCallUsage as T, AgentEventDescriptor as U, renderDecisionAttempts as V, AgentInvalidEventPayloadError as W, parseAgentEvent as X, getAcceptedEvents as Y, AgentError as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentSchemas as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, createDecisionLogic as z };
+export { AgentTruncatedError as $, AgentDecisionExhaustedError as A, createDecisionLogic as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, CreateDecisionRequestOptions as F, AgentInvalidEventPayloadError as G, renderDecisionAttempts as H, DecisionAttempt as I, AgentSchemas as J, AgentRequestOptions as K, DecisionLogic as L, AgentDecisionOption as M, AgentDecisionRequest as N, providerOutputSchema as O, AgentExecutorDecisionRequest as P, AgentError as Q, DecisionLogicConfig as R, createTextLogic as S, getCallUsage as T, resolveDecision as U, createDecisionRequest as V, AgentEventDescriptor as W, getAcceptedEvents as X, EventFromSnapshot as Y, parseAgentEvent as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestSource as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, ResolveDecisionOptions as z };

package/dist/{text-logic-D-czVPYp.d.mts → text-logic-BDbGjYMh.d.mts}

@@ -1,6 +1,5 @@
-import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
+import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.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
@@ -152,6 +151,14 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
   /** Framework-native messages, passed through without conversion. */
   messages?: any[];
   allowedEvents?: AllowedEvents<TEvent>;
+  /**
+   * Concrete payloads per event type, without `type`. When given, the
+   * decision is a closed choice: the request carries one
+   * {@link AgentDecisionOption} per payload whose event the snapshot accepts,
+   * and the decider picks one instead of writing a payload. Event types in
+   * `allowedEvents` with no entry here are offered as `{ type }`.
+   */
+  payloads?: Partial<Record<TEvent, Record<string, unknown>[]>>;
   maxRetries?: number;
   temperature?: number;
   maxOutputTokens?: number;
@@ -251,6 +258,21 @@ interface AgentDecisionRequest {
   messages?: any[];
   /** Candidate events: declared `allowedEvents` ∩ snapshot-legal events. */
   events: AgentEventDescriptor[];
+  /**
+   * Concrete choices, present when the host enumerated payloads
+   * (`payloads` on the decide input, or `decideNext`). A snapshot-aware host
+   * keeps only options the snapshot accepts. An executor that sees options
+   * should choose one of them; a chosen event matching no option is
+   * rejected and retried like a guard rejection.
+   */
+  options?: AgentDecisionOption[];
+  /**
+   * Candidate events the snapshot rejected when the options were built:
+   * enumerated like `options`, but `snapshot.can(event)` was false. Never
+   * offered; executors ignore it. Set by `decideNext` and by the runtime's
+   * closed choices, so a `request.start` trace shows what the guards blocked.
+   */
+  withheld?: ChosenEvent[];
   /**
    * Prior failed attempts for THIS decision. Empty on the first attempt.
    * Adapters render these into the provider request so retries converge.
@@ -264,6 +286,11 @@ interface AgentDecisionRequest {
   seed?: number;
   stopSequences?: string[];
   metadata?: Record<string, unknown>;
+  /**
+   * Per-invoke retry budget lowered from `agent.decide` inline input. Hosts
+   * prefer it over the logic's configured `maxRetries` when set.
+   */
+  maxRetries?: number;
   /**
    * The run this decision belongs to (`run_<n>`, matching trace
    * events), injected by the runtime like `signal` (symmetric with the text
@@ -310,6 +337,12 @@ declare function createDecisionRequest(options: CreateDecisionRequestOptions): A
 type AgentExecutorDecisionRequest = AgentDecisionRequest & {
   name: string;
 };
+/** One concrete event a decider may choose, with an optional description for the model. */
+interface AgentDecisionOption {
+  event: ChosenEvent;
+  /** What choosing this does, in words; lookahead text when the host computed it. */
+  description?: string;
+}
 /**
  * A single failed decision attempt, recorded by {@link resolveDecision} and
  * fed back to the executor on the next attempt via
@@ -317,7 +350,7 @@ type AgentExecutorDecisionRequest = AgentDecisionRequest & {
  * choice: `'unknown-event'` (not among the candidate `events`),
  * `'invalid-payload'` (failed the event's schema), or `'rejected-by-guard'`
  * (failed the `canTake` check — type/payload were legal, but the machine's
- * guard rejected it at apply time).
+ * guard rejected it at apply time — or matched none of `request.options`).
  */
 interface DecisionAttempt {
   event?: ChosenEvent;
@@ -349,7 +382,7 @@ declare class AgentDecisionExhaustedError extends AgentError {
  * const messages = [...baseMessages, ...renderDecisionAttempts(request)];
  * ```
  */
-declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "events" | "attempts">): AgentMessage[];
+declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "events" | "attempts" | "options">): AgentMessage[];
 /**
  * Host implementation of "make the model choose one of `request.events`."
  * Third executor slot on {@link AgentRequestExecutors}, symmetric with
@@ -368,7 +401,8 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  */
 type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
   event: ChosenEvent;
-  reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
+  reason?: string;
+  /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
   usage?: AgentCallUsage;
   [key: string]: unknown;
 }>;
@@ -407,6 +441,8 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  * event's schema), or `'rejected-by-guard'` (passes both checks but
  * `options.canTake` returns `false` — a type/payload-legal event the
  * machine's guard rejects right now; omit `canTake` to skip this check).
+ * When the request carries `options`, a choice matching none of them (type and
+ * payload, deep-equal) also fails as `'rejected-by-guard'`.
  * Every prior failed attempt for this call is fed back to the executor on
  * the next attempt via `request.attempts`, so an adapter can render "your
  * last choice failed because X — try again" into the next model call; core
@@ -737,9 +773,12 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
  * toward `modelCalls`.
  */
 type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
-  result: TOutput; /** The provider's response messages for this call (the assistant turn, tool calls and results). */
-  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. */
+  result: TOutput;
+  /** The provider's response messages for this call (the assistant turn, tool calls and results). */
+  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;
 };
@@ -789,7 +828,8 @@ interface AgentRequestExecutorInfo {
  * `tools` merged in. Exactly one of `prompt`/`messages` is set.
  */
 type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "name" | "tools"> & {
-  /** Semantic request identity; always resolved before an executor is called. */name: string;
+  /** Semantic request identity; always resolved before an executor is called. */
+  name: string;
   tools: AgentTools;
 };
 /**
@@ -861,4 +901,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
 //#endregion
-export { AgentDecisionExhaustedError as A, createDecisionRequest as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, DecisionAttempt as F, AgentRequestOptions as G, resolveDecision as H, DecisionLogic as I, EventFromSnapshot as J, AgentRequestSource as K, DecisionLogicConfig as L, AgentDecisionRequest as M, AgentExecutorDecisionRequest as N, providerOutputSchema as O, CreateDecisionRequestOptions as P, AgentTruncatedError as Q, ResolveDecisionOptions as R, createTextLogic as S, getCallUsage as T, AgentEventDescriptor as U, renderDecisionAttempts as V, AgentInvalidEventPayloadError as W, parseAgentEvent as X, getAcceptedEvents as Y, AgentError as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentSchemas as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, createDecisionLogic as z };
+export { AgentTruncatedError as $, AgentDecisionExhaustedError as A, createDecisionLogic as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, CreateDecisionRequestOptions as F, AgentInvalidEventPayloadError as G, renderDecisionAttempts as H, DecisionAttempt as I, AgentSchemas as J, AgentRequestOptions as K, DecisionLogic as L, AgentDecisionOption as M, AgentDecisionRequest as N, providerOutputSchema as O, AgentExecutorDecisionRequest as P, AgentError as Q, DecisionLogicConfig as R, createTextLogic as S, getCallUsage as T, resolveDecision as U, createDecisionRequest as V, AgentEventDescriptor as W, getAcceptedEvents as X, EventFromSnapshot as Y, parseAgentEvent as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestSource as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, ResolveDecisionOptions as z };

package/dist/{types-BgNbNKnJ.d.mts → types-Dp5_Ru4R.d.cts}

@@ -61,7 +61,7 @@ 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<{}> };
+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';
@@ -71,7 +71,7 @@ type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof
  */
 type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
   type: K;
-} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown) }[keyof T & string];
+} & (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: ... } }`). */

package/dist/{types-hR5f5YXa.d.cts → types-Dp5_Ru4R.d.mts}

@@ -61,7 +61,7 @@ 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<{}> };
+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';
@@ -71,7 +71,7 @@ type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof
  */
 type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
   type: K;
-} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown) }[keyof T & string];
+} & (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: ... } }`). */

package/dist/usage-D8UphgEA.d.mts

@@ -0,0 +1,17 @@
+import { t as AgentCallUsage } from "./text-logic-BDbGjYMh.mjs";
+import { EventObject } from "xstate";
+//#region src/usage.d.ts
+/** Reserved event delivered after a model call reports token usage. */
+declare const AGENT_USAGE_EVENT_TYPE: "@agent.usage";
+/** Machine-owned usage signal. Handle it with an ordinary XState transition. */
+interface AgentUsageEvent extends EventObject {
+  type: typeof AGENT_USAGE_EVENT_TYPE;
+  usage: AgentCallUsage;
+  kind?: "text" | "decision";
+  id?: string;
+  src?: string;
+  model?: string;
+  name?: string;
+}
+//#endregion
+export { AgentUsageEvent as n, AGENT_USAGE_EVENT_TYPE as t };

package/dist/usage-R1NTmLxY.d.cts

@@ -0,0 +1,17 @@
+import { t as AgentCallUsage } from "./text-logic-9fv1i9aK.cjs";
+import { EventObject } from "xstate";
+//#region src/usage.d.ts
+/** Reserved event delivered after a model call reports token usage. */
+declare const AGENT_USAGE_EVENT_TYPE: "@agent.usage";
+/** Machine-owned usage signal. Handle it with an ordinary XState transition. */
+interface AgentUsageEvent extends EventObject {
+  type: typeof AGENT_USAGE_EVENT_TYPE;
+  usage: AgentCallUsage;
+  kind?: "text" | "decision";
+  id?: string;
+  src?: string;
+  model?: string;
+  name?: string;
+}
+//#endregion
+export { AgentUsageEvent as n, AGENT_USAGE_EVENT_TYPE as t };

package/dist/{utils-_q7F-AZu.d.mts → utils-BnXdWih3.d.mts}

@@ -1,6 +1,5 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-BgNbNKnJ.mjs";
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.mjs";
 import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
-
 //#region src/utils.d.ts
 /** Returns the human-readable text carried by a message, ignoring non-text parts. */
 declare function getMessageText(message: AgentMessage): string;

package/dist/{utils-o4YRdHJX.d.cts → utils-ebVpCYoF.d.cts}

@@ -1,6 +1,5 @@
-import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-hR5f5YXa.cjs";
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.cjs";
 import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
-
 //#region src/utils.d.ts
 /** Returns the human-readable text carried by a message, ignoring non-text parts. */
 declare function getMessageText(message: AgentMessage): string;

package/dist/validate.cjs

@@ -16,11 +16,14 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
 //#endregion
+const require_event_log = require("./event-log-Dtb16p1p.cjs");
+const require_setup_agent = require("./setup-agent-DTF3NQg3.cjs");
+const require_verify = require("./verify-Cqghu4gz.cjs");
 let ajv_dist_2020_js = require("ajv/dist/2020.js");
 ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
 //#region schemas/agent-workflow.json
@@ -383,13 +386,10 @@ var agent_workflow_default = {
 	}
 };
 //#endregion
-//#region src/validate/index.ts
+//#region src/validate/validate-config.ts
 /**
-* Schema validation for agent workflow configs.
-*
-* Lives behind the `@statelyai/agent/validate` subpath so the core package
-* stays dependency-free. This module imports `ajv`, which is declared as an
-* optional peer dependency.
+* Schema validation for agent workflow configs. Imports `ajv`, an optional
+* peer dependency of the package.
 */
 let compiledWorkflowValidator;
 function getWorkflowValidator() {
@@ -424,5 +424,236 @@ function validateAgentConfig(config) {
 	};
 }
 //#endregion
-exports.__toESM = __toESM;
+//#region src/validate/verify-config.ts
+const BUILTIN_SRCS = [
+	require_event_log.DECIDE_ACTOR,
+	require_event_log.GENERATE_TEXT_ACTOR,
+	require_event_log.STREAM_TEXT_ACTOR
+];
+const MAX_DETAIL_LINES = 10;
+/**
+* Runs every pre-run gate on a model-authored workflow config and stops at
+* the first failure. Never throws on a bad config: each failure becomes a gate
+* record whose `detail` is a repair prompt.
+*
+* - `validate`: the config's shape, against the shipped JSON Schema.
+* - `vocabulary`: names the config references, against `allow`.
+* - `lower`: `setupAgent.fromConfig` (unresolved guards/actions, bad targets).
+* - `lint`: `lintAgentMachine` (errors fail; warnings fail with `lint.warnings`).
+* - `explore`: `explorePaths` from each `explore.inputs` entry; every terminal
+*   must be one of `explore.terminals`, no cap (`maxPaths`, `maxNodes`) may cut
+*   it short, every event's payloads must be tried (`unexpandedEvents`), and
+*   every reached text request or invoke needs an `explore.outputs` entry.
+*
+* @example
+* ```ts
+* const result = await verifyAgentConfig(candidate, { compileSchema, allow: { events: ["APPROVE", "DENY"] } });
+* const failed = result.gates.find((gate) => !gate.ok);
+* if (failed) feedback.push(`gate '${failed.name}' failed: ${failed.detail}`);
+* ```
+*/
+async function verifyAgentConfig(config, options) {
+	const gates = [];
+	const record = (name, problems, notes = []) => {
+		const lines = problems.length ? problems : notes;
+		gates.push({
+			name,
+			ok: problems.length === 0,
+			...lines.length ? { detail: formatDetail(lines) } : {}
+		});
+		return problems.length === 0;
+	};
+	const fail = (extra = {}) => ({
+		ok: false,
+		gates,
+		...extra
+	});
+	if (!record("validate", validateAgentConfig(config).errors.map((error) => `${error.path} ${error.message}`))) return fail();
+	const typed = config;
+	if (options.allow && !record("vocabulary", checkVocabulary(typed, options.allow))) return fail({ config: typed });
+	let machine;
+	try {
+		machine = require_setup_agent.setupAgentFromConfig(typed, {
+			compileSchema: options.compileSchema,
+			...options.guards ? { guards: options.guards } : {},
+			...options.actions ? { actions: options.actions } : {}
+		}).machine;
+		if (options.actors) machine = machine.provide({ actors: options.actors });
+	} catch (error) {
+		record("lower", [errorMessage(error)]);
+		return fail({ config: typed });
+	}
+	record("lower", []);
+	const diagnostics = require_verify.lintAgentMachine(machine).map((d) => ({
+		failing: d.severity === "error" || options.lint?.warnings === true,
+		line: `${d.severity} ${d.code} at '${d.path}': ${d.message}`
+	}));
+	if (!record("lint", diagnostics.filter((d) => d.failing).map((d) => d.line), diagnostics.map((d) => d.line))) return fail({
+		config: typed,
+		machine
+	});
+	if (options.explore && !record("explore", await checkExplore(machine, options.explore))) return fail({
+		config: typed,
+		machine
+	});
+	return {
+		ok: true,
+		gates,
+		config: typed,
+		machine
+	};
+}
+/** A config's `T | T[]` field as a list of objects. */
+const nodes = (value) => (value === void 0 ? [] : Array.isArray(value) ? value : [value]).filter((node) => !!node && typeof node === "object");
+const hasTemplate = (value) => typeof value === "string" && value.includes("{{");
+const list = (names) => names.length ? names.join(", ") : "(none)";
+/** Every state in the config, depth-first, with its dotted path. */
+function walkStates(states, prefix = "") {
+	if (!states || typeof states !== "object") return [];
+	return Object.entries(states).flatMap(([key, state]) => {
+		const path = prefix ? `${prefix}.${key}` : key;
+		return [{
+			path,
+			state
+		}, ...walkStates(state?.states, path)];
+	});
+}
+/** Every transition on a state: `on`, `after`, `always`, `choice`, `onDone`, and invoke done/error. */
+function transitionsOf(state) {
+	return [
+		...Object.values(state.on ?? {}).flatMap(nodes),
+		...Object.values(state.after ?? {}).flatMap(nodes),
+		...nodes(state.always),
+		...nodes(state.choice),
+		...nodes(state.onDone),
+		...nodes(state.invoke).flatMap((invoke) => [...nodes(invoke.onDone), ...nodes(invoke.onError)])
+	];
+}
+/**
+* Paths of raw xstate expression slots (`{ "@expr": ... }`, `{ "@code": ... }`).
+* xstate evaluates such an object whole, ignoring its literal siblings, so a
+* slot would hide the model ref or `allowedEvents` the checks below read.
+*/
+function rawExpressionPaths(value, path) {
+	if (Array.isArray(value)) return value.flatMap((item, index) => rawExpressionPaths(item, `${path}[${index}]`));
+	if (!value || typeof value !== "object") return [];
+	const node = value;
+	if (typeof node["@expr"] === "string" || typeof node["@code"] === "string") return [path];
+	return Object.entries(node).flatMap(([key, item]) => rawExpressionPaths(item, path ? `${path}.${key}` : key));
+}
+function checkVocabulary(config, allow) {
+	const problems = rawExpressionPaths(config, "").map((path) => `${path || "(root)"} uses a raw '@expr' slot, which the vocabulary cannot check; write {{ }} templates instead`);
+	const checkModel = (where, model) => {
+		if (!allow.models) return;
+		if (typeof model !== "string" || hasTemplate(model)) problems.push(`${where} needs a literal string model ref; allowed: ${list(allow.models)}`);
+		else if (!allow.models.includes(model)) problems.push(`${where} uses model '${model}'; allowed: ${list(allow.models)}`);
+	};
+	for (const [kind, declared, allowed] of [[
+		"request",
+		config.requests,
+		allow.requests
+	], [
+		"actor",
+		config.actors,
+		allow.actors
+	]]) {
+		if (!allowed) continue;
+		for (const key of Object.keys(declared ?? {})) if (!allowed.includes(key)) problems.push(`${kind} '${key}' is not in the vocabulary; allowed: ${list(allowed)}`);
+	}
+	for (const [key, request] of Object.entries(config.requests ?? {})) checkModel(`request '${key}'`, request.model);
+	const srcs = allow.actors ? [
+		...BUILTIN_SRCS,
+		...allow.actors,
+		...allow.requests ?? Object.keys(config.requests ?? {})
+	] : void 0;
+	for (const { path, state } of walkStates(config.states)) {
+		for (const invoke of nodes(state.invoke)) {
+			const src = String(invoke.src);
+			if (srcs && !srcs.includes(src)) {
+				problems.push(`state '${path}' invokes unknown src '${src}'; allowed: ${list(srcs)}`);
+				continue;
+			}
+			if (!BUILTIN_SRCS.includes(src)) continue;
+			const input = invoke.input;
+			if ((allow.models || src === "agent.decide" && allow.events) && !isPlainObject(input)) {
+				problems.push(`state '${path}': '${src}' input must be a literal object`);
+				continue;
+			}
+			checkModel(`state '${path}': '${src}'`, input?.model);
+			if (src !== "agent.decide" || !allow.events) continue;
+			const allowedEvents = input.allowedEvents;
+			if (!Array.isArray(allowedEvents) || allowedEvents.length === 0) {
+				problems.push(`state '${path}': agent.decide needs a literal, non-empty allowedEvents list; allowed: ${list(allow.events)}`);
+				continue;
+			}
+			for (const type of allowedEvents) if (typeof type !== "string" || !allow.events.includes(type)) problems.push(`state '${path}': agent.decide allowedEvents entry '${String(type)}' is not allowed; allowed: ${list(allow.events)}`);
+		}
+		const actionsAt = [["entry", state.entry], ["exit", state.exit]];
+		for (const transition of transitionsOf(state)) {
+			const guard = transition.guard;
+			if (allow.guards && typeof guard === "string" && !hasTemplate(guard) && !allow.guards.includes(guard)) problems.push(`state '${path}' uses unknown named guard '${guard}'; allowed: ${list(allow.guards)}`);
+			actionsAt.push(["a transition", transition.actions]);
+		}
+		if (!allow.actions) continue;
+		for (const [where, actions] of actionsAt) for (const action of nodes(actions)) if (typeof action.type === "string" && !allow.actions.includes(action.type)) problems.push(`state '${path}' ${where} uses unknown named action '${action.type}'; allowed: ${list(allow.actions)}`);
+	}
+	return problems;
+}
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+async function checkExplore(machine, options) {
+	const { inputs, terminals = ["done"], ...rest } = options;
+	if (inputs.length === 0) return ["explore.inputs is empty, so no path was explored; give at least one input"];
+	const allowed = terminals;
+	const maxDepth = options.maxDepth ?? 8;
+	const problems = /* @__PURE__ */ new Set();
+	for (const [index, input] of inputs.entries()) {
+		const at = inputs.length > 1 ? `input ${index}: ` : "";
+		let report;
+		try {
+			report = await require_verify.explorePaths(machine, {
+				...rest,
+				input
+			});
+		} catch (error) {
+			problems.add(`${at}exploration threw: ${errorMessage(error)}`);
+			continue;
+		}
+		for (const terminal of report.terminals) {
+			if (allowed.includes(terminal.status)) continue;
+			const trail = `path [${terminal.path.map((event) => event.type).join(", ")}]`;
+			const state = JSON.stringify(terminal.state);
+			switch (terminal.status) {
+				case "max-depth":
+					problems.add(`${at}${trail} hit maxDepth ${maxDepth} in state ${state} without ending; the workflow may loop`);
+					break;
+				case "needs-output":
+					problems.add(`${at}${trail} reached '${terminal.missingSrc}' in state ${state}, which has no output to explore with; add an explore.outputs entry for it`);
+					break;
+				case "error":
+					problems.add(`${at}${trail} errored in state ${state} with no onError: ${errorMessage(terminal.error)}`);
+					break;
+				default: problems.add(`${at}${trail} ends '${terminal.status}' in state ${state}; every path must end ${allowed.map((t) => `'${t}'`).join(" or ")}`);
+			}
+		}
+		if (report.hitPathCap) problems.add(`${at}a cap (maxPaths ${options.maxPaths ?? 200} or maxNodes ${options.maxNodes ?? 1e5}) cut exploration short; the workflow branches too much to verify`);
+		if (report.unexpandedEvents.length > 0) problems.add(`${at}explore did not try every payload of: ${report.unexpandedEvents.join(", ")}; add explore.payloads entries for them`);
+	}
+	return [...problems];
+}
+function formatDetail(lines) {
+	const shown = lines.slice(0, MAX_DETAIL_LINES);
+	const hidden = lines.length - shown.length;
+	return [...shown, ...hidden > 0 ? [`(${hidden} more)`] : []].join("\n");
+}
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}
+//#endregion
 exports.validateAgentConfig = validateAgentConfig;
+exports.verifyAgentConfig = verifyAgentConfig;