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

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

@@ -1,6 +1,6 @@
-import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-_FXoFBGO.mjs";
+import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-9Bqg5rZB.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, MachineSnapshot } from "xstate";
+import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
 
 //#region src/events.d.ts
 /** The invoke `src` of an {@link AgentRequest}/{@link AgentDecisionRequest} — a plain string, widened so literal `src` values still narrow in editor hints. */
@@ -97,92 +97,6 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
   stopSequences?: string[];
   metadata?: TMetadata;
 }
-/**
- * Inline input for the `agent.plan` builtin actor — a multi-event decision.
- * Where `agent.decide` picks exactly one currently-legal event, `agent.plan`
- * applies an ordered sequence of them: each step re-reads the live snapshot,
- * asks the `decide` executor for one legal event (same validation and
- * `rejected-by-guard` retry loop as a decision), sends it to the machine,
- * and repeats until a `stopOn` event is chosen, `maxSteps` is reached, no
- * legal candidate remains, or an applied event exits the invoking state
- * (which cancels the invoke — the machine simply moves on).
- *
- * Requires a snapshot-aware host: {@link runAgent}, or the step path (where an
- * `agent.plan` invoke re-surfaces as a `kind: 'plan'` request that
- * `resolveAgentRequests` drives one step per call).
- */
-interface AgentPlanInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> extends AgentDecisionInput<TEvent, TMetadata, TModel> {
-  /** Maximum events applied in one plan. Default 8. */
-  maxSteps?: number;
-  /**
-   * Machine events that end the plan once chosen: the event is still
-   * validated and sent, then the loop stops. Usually unnecessary — every
-   * plan step already offers the built-in {@link PLAN_DONE_EVENT_TYPE}
-   * "done" option, which ends the plan without touching the machine.
-   * Declare `stopOn` only for "send this real event AND stop" semantics.
-   */
-  stopOn?: readonly TEvent[];
-}
-/**
- * Reserved event type the `agent.plan` builtin adds to every step's
- * candidates as the explicit "no further action needed" move. Choosing it
- * ends the plan (`stopped: 'done'`); it is never sent to the machine, so
- * machines need no no-op sentinel event of their own.
- */
-declare const PLAN_DONE_EVENT_TYPE: "agent.plan.done";
-/** What an `agent.plan` invoke resolves with (its `onDone` output). */
-interface AgentPlanOutput {
-  /** The events applied, in order (possibly empty). */
-  steps: ChosenEvent[];
-  /** Why the loop ended. */
-  stopped: "done" | "stop-event" | "max-steps" | "no-legal-events";
-}
-/**
- * The in-progress state of a plan, held in the `agent.plan` invoke child's own
- * `createLogic` snapshot `context`. Because a `createLogic` snapshot serializes
- * (and restores) by identity, this lands at
- * `children.<planId>.snapshot.context` in a machine's persisted snapshot for
- * free — so a step-path host that persists after every event resumes a plan
- * mid-flight without a bespoke carrier.
- */
-interface PlanLedgerContext {
-  /** The events applied so far in this plan, in order (the trail). */
-  applied: ChosenEvent[];
-  /** How many more events the plan may apply (`maxSteps - applied.length`). */
-  stepsRemaining: number;
-  /** Set once the plan terminates; `null` while in flight. */
-  stopped: AgentPlanOutput["stopped"] | null;
-}
-/**
- * The two ledger events that drive a {@link PlanLedgerContext} forward:
- * `plan.applied` appends one event to the trail and decrements the budget;
- * `plan.ended` records the stop reason and completes the ledger (its snapshot
- * goes `done` with the {@link AgentPlanOutput}).
- */
-type PlanLedgerEvent = {
-  type: "plan.applied";
-  event: ChosenEvent;
-} | {
-  type: "plan.ended";
-  stopped: AgentPlanOutput["stopped"];
-};
-/**
- * Actor logic for the `agent.plan` builtin: a stateful, transition-based
- * ledger. Its snapshot `context` ({@link PlanLedgerContext}) IS the plan's
- * in-progress state — the applied trail plus remaining budget — advanced one
- * {@link PlanLedgerEvent} at a time. On the step path the invoke child runs this
- * logic directly (so its context persists at `children.<id>.snapshot.context`);
- * runAgent swaps in an async implementation that drives the SAME ledger via the
- * shared {@link initialPlanLedger}/{@link advancePlanLedger} drivers.
- */
-interface PlanLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<AgentPlanInput>> extends LogicActorLogic<PlanLedgerContext, AgentPlanOutput, PlanLedgerEvent, InferOutput<TInputSchema>> {
-  readonly kind: "statelyai.planLogic";
-  readonly maxRetries: number;
-  /** Builds the per-step base {@link AgentDecisionRequest} (id/events filled in per step). */
-  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
-  /** @internal Resolves declared `allowedEvents` (undefined = all currently legal). */
-  allowedEventTypes(input: InferOutput<TInputSchema>): readonly string[] | undefined;
-}
 /**
  * Config for {@link createDecisionLogic}: how to build an
  * {@link AgentDecisionRequest} from typed input. Each field mirrors
@@ -366,7 +280,6 @@ declare const USER_INPUT_ACTOR: "agent.userInput";
 declare const GENERATE_TEXT_ACTOR: "agent.generateText";
 declare const STREAM_TEXT_ACTOR: "agent.streamText";
 declare const DECIDE_ACTOR: "agent.decide";
-declare const PLAN_ACTOR: "agent.plan";
 /** Whether a text request should be resolved with `generateText` (one-shot) or `streamText` (chunked, via `onChunk`). */
 type AgentRequestMode = "generate" | "stream";
 /** A `setupAgent({ models })` model registry, mapping short model refs to provider-specific model values. */
@@ -485,13 +398,12 @@ interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
   metadata?: TMetadata;
 }
-/** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
+/** The four `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
-  [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
 /**
  * Validates a raw model/executor output against `schema`, returning the
@@ -660,7 +572,12 @@ interface AgentRequestExecutorInfo {
  */
 type AiSdkShapedTextResult = {
   text: string | PromiseLike<string>;
-  [key: string]: unknown;
+  output?: unknown;
+  usage?: unknown;
+  reasoning?: unknown;
+  finishReason?: unknown;
+  toolCalls?: unknown;
+  toolResults?: unknown;
 };
 /**
  * A raw Vercel AI SDK `streamText` result shape: exposes a `textStream` async
@@ -674,27 +591,61 @@ type AiSdkShapedTextResult = {
 type AiSdkShapedStreamResult = {
   textStream: AsyncIterable<string>;
   text?: PromiseLike<string>;
-  [key: string]: unknown;
+  output?: unknown;
+  usage?: unknown;
+  reasoning?: unknown;
+  finishReason?: unknown;
+  toolCalls?: unknown;
+  toolResults?: unknown;
 };
+/**
+ * The lowered request as an {@link AgentRequestExecutor} receives it. At
+ * runtime this is exactly the {@link AgentTextRequest} core built (plus the
+ * merged `tools` map); the TYPE is deliberately shaped so the Vercel AI SDK's
+ * own `generateText`/`streamText` are directly assignable as executors
+ * (function parameters are contravariant, so this type must be assignable to
+ * `ai`'s options type):
+ *
+ * - `prompt`/`messages` are mutually exclusive, matching `ai`'s `Prompt`
+ *   union (core always sets exactly one).
+ * - `tools`, `toolChoice`, and `messages` are widened to `any` — their
+ *   portable shapes ({@link AgentTools}, {@link AgentToolChoice},
+ *   {@link AgentMessage}) are structural supersets of `ai`'s branded types
+ *   and would otherwise fail the contravariant check.
+ *
+ * Hand-written executors that want the precise shapes can annotate their
+ * parameter as `AgentTextRequest & { tools: AgentTools }` — that wider
+ * parameter type keeps the executor assignable.
+ */
+type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "prompt" | "messages" | "tools" | "toolChoice"> & {
+  tools: any;
+  toolChoice?: any;
+} & ({
+  prompt: string;
+  messages?: undefined;
+} | {
+  prompt?: undefined;
+  messages: any[];
+});
 /**
  * Host implementation of one text call (`generateText` or `streamText`) —
- * resolves a lowered {@link AgentTextRequest} to an `{ output }` envelope (see
- * {@link AgentRequestExecutorResult}), unwrapped by
- * {@link normalizeGeneratorResult}. The return type is widened to also admit the
- * raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
- * {@link AiSdkShapedStreamResult}) so `ai`'s own `generateText`/`streamText`
- * pass through without a cast; `normalizeGeneratorResult` checks for `{ output }`
- * first, then falls back to those shapes at runtime.
- */
-type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentTextRequest & {
-  tools: AgentTools;
-}, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
+ * resolves a lowered {@link AgentExecutorTextRequest} to an `{ output }`
+ * envelope (see {@link AgentRequestExecutorResult}), unwrapped by
+ * {@link normalizeGeneratorResult}. Both sides are shaped so `ai`'s own
+ * `generateText`/`streamText` pass through without a cast: the request
+ * parameter is assignable to `ai`'s options (see
+ * {@link AgentExecutorTextRequest}), and the return type is widened to also
+ * admit the raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
+ * {@link AiSdkShapedStreamResult}) — `normalizeGeneratorResult` checks for
+ * `{ output }` first, then falls back to those shapes at runtime.
+ */
+type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
 /**
  * The full set of host executors a machine's agent actors are resolved
  * with — passed to `runAgent`, `executeAgentRequest`, and
  * `TextLogic.execute`. Every slot is optional: `generateText` is needed only
  * if the machine has a `mode: 'generate'` text request, `streamText` only for
- * a `mode: 'stream'` request, and `decide` only for a decision/plan — omitting
+ * a `mode: 'stream'` request, and `decide` only for a decision — omitting
  * a slot the machine actually needs is a clear bind-time error (see `runAgent`
  * and `provideExecutors`). Adapter result sets (`AiSdkExecutors`,
  * `OpenAiCompatExecutors`) re-require all three.
@@ -751,4 +702,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionInput as A, resolveDecision as B, createTextLogic as C, parseStructuredEnvelope as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentEventToolNameResolver as H, PLAN_DONE_EVENT_TYPE as I, parseAgentEvent as K, PlanLogic as L, AgentPlanInput as M, AgentPlanOutput as N, AgentDecisionExecutor as O, DecisionAttempt as P, ResolveDecisionOptions as R, buildEnvelopeSchema as S, parseModelRef as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, TextLogic as _, AgentRequestExecutor as a, TextLogicExecutor as b, AgentRequestExecutors as c, AgentUsage as d, AgentUserInput as f, StructuredOutputEnvelope as g, BuiltinAgentActors as h, AgentOutputMode as i, AgentDecisionRequest as j, AgentDecisionExhaustedError as k, AgentRequestMode as l, AiSdkShapedTextResult as m, AgentModelMap as n, AgentRequestExecutorInfo as o, AiSdkShapedStreamResult as p, AgentModelRef as r, AgentRequestExecutorResult as s, AgentCallUsage as t, AgentTextRequest as u, TextLogicConfig as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, renderDecisionAttempts as z };
+export { AgentDecisionExhaustedError as A, AgentRequestOptions as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, ResolveDecisionOptions as F, getAcceptedEvents as H, renderDecisionAttempts as I, resolveDecision as L, AgentDecisionRequest as M, DecisionAttempt as N, parseStructuredEnvelope as O, DecisionLogicConfig as P, AgentEventDescriptor as R, bindRequestExecutor as S, getAgentOutputMode as T, parseAgentEvent as U, AgentRequestSource as V, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventToolNameResolver as z };

package/dist/{text-logic-CorGzucG.d.cts → text-logic-Jkilp1Ie.d.cts}

@@ -1,6 +1,6 @@
-import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-QbEfCVny.cjs";
+import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-rMe7x6NR.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, MachineSnapshot } from "xstate";
+import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
 
 //#region src/events.d.ts
 /** The invoke `src` of an {@link AgentRequest}/{@link AgentDecisionRequest} — a plain string, widened so literal `src` values still narrow in editor hints. */
@@ -97,92 +97,6 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
   stopSequences?: string[];
   metadata?: TMetadata;
 }
-/**
- * Inline input for the `agent.plan` builtin actor — a multi-event decision.
- * Where `agent.decide` picks exactly one currently-legal event, `agent.plan`
- * applies an ordered sequence of them: each step re-reads the live snapshot,
- * asks the `decide` executor for one legal event (same validation and
- * `rejected-by-guard` retry loop as a decision), sends it to the machine,
- * and repeats until a `stopOn` event is chosen, `maxSteps` is reached, no
- * legal candidate remains, or an applied event exits the invoking state
- * (which cancels the invoke — the machine simply moves on).
- *
- * Requires a snapshot-aware host: {@link runAgent}, or the step path (where an
- * `agent.plan` invoke re-surfaces as a `kind: 'plan'` request that
- * `resolveAgentRequests` drives one step per call).
- */
-interface AgentPlanInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> extends AgentDecisionInput<TEvent, TMetadata, TModel> {
-  /** Maximum events applied in one plan. Default 8. */
-  maxSteps?: number;
-  /**
-   * Machine events that end the plan once chosen: the event is still
-   * validated and sent, then the loop stops. Usually unnecessary — every
-   * plan step already offers the built-in {@link PLAN_DONE_EVENT_TYPE}
-   * "done" option, which ends the plan without touching the machine.
-   * Declare `stopOn` only for "send this real event AND stop" semantics.
-   */
-  stopOn?: readonly TEvent[];
-}
-/**
- * Reserved event type the `agent.plan` builtin adds to every step's
- * candidates as the explicit "no further action needed" move. Choosing it
- * ends the plan (`stopped: 'done'`); it is never sent to the machine, so
- * machines need no no-op sentinel event of their own.
- */
-declare const PLAN_DONE_EVENT_TYPE: "agent.plan.done";
-/** What an `agent.plan` invoke resolves with (its `onDone` output). */
-interface AgentPlanOutput {
-  /** The events applied, in order (possibly empty). */
-  steps: ChosenEvent[];
-  /** Why the loop ended. */
-  stopped: "done" | "stop-event" | "max-steps" | "no-legal-events";
-}
-/**
- * The in-progress state of a plan, held in the `agent.plan` invoke child's own
- * `createLogic` snapshot `context`. Because a `createLogic` snapshot serializes
- * (and restores) by identity, this lands at
- * `children.<planId>.snapshot.context` in a machine's persisted snapshot for
- * free — so a step-path host that persists after every event resumes a plan
- * mid-flight without a bespoke carrier.
- */
-interface PlanLedgerContext {
-  /** The events applied so far in this plan, in order (the trail). */
-  applied: ChosenEvent[];
-  /** How many more events the plan may apply (`maxSteps - applied.length`). */
-  stepsRemaining: number;
-  /** Set once the plan terminates; `null` while in flight. */
-  stopped: AgentPlanOutput["stopped"] | null;
-}
-/**
- * The two ledger events that drive a {@link PlanLedgerContext} forward:
- * `plan.applied` appends one event to the trail and decrements the budget;
- * `plan.ended` records the stop reason and completes the ledger (its snapshot
- * goes `done` with the {@link AgentPlanOutput}).
- */
-type PlanLedgerEvent = {
-  type: "plan.applied";
-  event: ChosenEvent;
-} | {
-  type: "plan.ended";
-  stopped: AgentPlanOutput["stopped"];
-};
-/**
- * Actor logic for the `agent.plan` builtin: a stateful, transition-based
- * ledger. Its snapshot `context` ({@link PlanLedgerContext}) IS the plan's
- * in-progress state — the applied trail plus remaining budget — advanced one
- * {@link PlanLedgerEvent} at a time. On the step path the invoke child runs this
- * logic directly (so its context persists at `children.<id>.snapshot.context`);
- * runAgent swaps in an async implementation that drives the SAME ledger via the
- * shared {@link initialPlanLedger}/{@link advancePlanLedger} drivers.
- */
-interface PlanLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<AgentPlanInput>> extends LogicActorLogic<PlanLedgerContext, AgentPlanOutput, PlanLedgerEvent, InferOutput<TInputSchema>> {
-  readonly kind: "statelyai.planLogic";
-  readonly maxRetries: number;
-  /** Builds the per-step base {@link AgentDecisionRequest} (id/events filled in per step). */
-  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
-  /** @internal Resolves declared `allowedEvents` (undefined = all currently legal). */
-  allowedEventTypes(input: InferOutput<TInputSchema>): readonly string[] | undefined;
-}
 /**
  * Config for {@link createDecisionLogic}: how to build an
  * {@link AgentDecisionRequest} from typed input. Each field mirrors
@@ -366,7 +280,6 @@ declare const USER_INPUT_ACTOR: "agent.userInput";
 declare const GENERATE_TEXT_ACTOR: "agent.generateText";
 declare const STREAM_TEXT_ACTOR: "agent.streamText";
 declare const DECIDE_ACTOR: "agent.decide";
-declare const PLAN_ACTOR: "agent.plan";
 /** Whether a text request should be resolved with `generateText` (one-shot) or `streamText` (chunked, via `onChunk`). */
 type AgentRequestMode = "generate" | "stream";
 /** A `setupAgent({ models })` model registry, mapping short model refs to provider-specific model values. */
@@ -485,13 +398,12 @@ interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
   metadata?: TMetadata;
 }
-/** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
+/** The four `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
-  [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
 /**
  * Validates a raw model/executor output against `schema`, returning the
@@ -660,7 +572,12 @@ interface AgentRequestExecutorInfo {
  */
 type AiSdkShapedTextResult = {
   text: string | PromiseLike<string>;
-  [key: string]: unknown;
+  output?: unknown;
+  usage?: unknown;
+  reasoning?: unknown;
+  finishReason?: unknown;
+  toolCalls?: unknown;
+  toolResults?: unknown;
 };
 /**
  * A raw Vercel AI SDK `streamText` result shape: exposes a `textStream` async
@@ -674,27 +591,61 @@ type AiSdkShapedTextResult = {
 type AiSdkShapedStreamResult = {
   textStream: AsyncIterable<string>;
   text?: PromiseLike<string>;
-  [key: string]: unknown;
+  output?: unknown;
+  usage?: unknown;
+  reasoning?: unknown;
+  finishReason?: unknown;
+  toolCalls?: unknown;
+  toolResults?: unknown;
 };
+/**
+ * The lowered request as an {@link AgentRequestExecutor} receives it. At
+ * runtime this is exactly the {@link AgentTextRequest} core built (plus the
+ * merged `tools` map); the TYPE is deliberately shaped so the Vercel AI SDK's
+ * own `generateText`/`streamText` are directly assignable as executors
+ * (function parameters are contravariant, so this type must be assignable to
+ * `ai`'s options type):
+ *
+ * - `prompt`/`messages` are mutually exclusive, matching `ai`'s `Prompt`
+ *   union (core always sets exactly one).
+ * - `tools`, `toolChoice`, and `messages` are widened to `any` — their
+ *   portable shapes ({@link AgentTools}, {@link AgentToolChoice},
+ *   {@link AgentMessage}) are structural supersets of `ai`'s branded types
+ *   and would otherwise fail the contravariant check.
+ *
+ * Hand-written executors that want the precise shapes can annotate their
+ * parameter as `AgentTextRequest & { tools: AgentTools }` — that wider
+ * parameter type keeps the executor assignable.
+ */
+type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "prompt" | "messages" | "tools" | "toolChoice"> & {
+  tools: any;
+  toolChoice?: any;
+} & ({
+  prompt: string;
+  messages?: undefined;
+} | {
+  prompt?: undefined;
+  messages: any[];
+});
 /**
  * Host implementation of one text call (`generateText` or `streamText`) —
- * resolves a lowered {@link AgentTextRequest} to an `{ output }` envelope (see
- * {@link AgentRequestExecutorResult}), unwrapped by
- * {@link normalizeGeneratorResult}. The return type is widened to also admit the
- * raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
- * {@link AiSdkShapedStreamResult}) so `ai`'s own `generateText`/`streamText`
- * pass through without a cast; `normalizeGeneratorResult` checks for `{ output }`
- * first, then falls back to those shapes at runtime.
- */
-type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentTextRequest & {
-  tools: AgentTools;
-}, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
+ * resolves a lowered {@link AgentExecutorTextRequest} to an `{ output }`
+ * envelope (see {@link AgentRequestExecutorResult}), unwrapped by
+ * {@link normalizeGeneratorResult}. Both sides are shaped so `ai`'s own
+ * `generateText`/`streamText` pass through without a cast: the request
+ * parameter is assignable to `ai`'s options (see
+ * {@link AgentExecutorTextRequest}), and the return type is widened to also
+ * admit the raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
+ * {@link AiSdkShapedStreamResult}) — `normalizeGeneratorResult` checks for
+ * `{ output }` first, then falls back to those shapes at runtime.
+ */
+type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
 /**
  * The full set of host executors a machine's agent actors are resolved
  * with — passed to `runAgent`, `executeAgentRequest`, and
  * `TextLogic.execute`. Every slot is optional: `generateText` is needed only
  * if the machine has a `mode: 'generate'` text request, `streamText` only for
- * a `mode: 'stream'` request, and `decide` only for a decision/plan — omitting
+ * a `mode: 'stream'` request, and `decide` only for a decision — omitting
  * a slot the machine actually needs is a clear bind-time error (see `runAgent`
  * and `provideExecutors`). Adapter result sets (`AiSdkExecutors`,
  * `OpenAiCompatExecutors`) re-require all three.
@@ -751,4 +702,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionInput as A, resolveDecision as B, createTextLogic as C, parseStructuredEnvelope as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentEventToolNameResolver as H, PLAN_DONE_EVENT_TYPE as I, parseAgentEvent as K, PlanLogic as L, AgentPlanInput as M, AgentPlanOutput as N, AgentDecisionExecutor as O, DecisionAttempt as P, ResolveDecisionOptions as R, buildEnvelopeSchema as S, parseModelRef as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, TextLogic as _, AgentRequestExecutor as a, TextLogicExecutor as b, AgentRequestExecutors as c, AgentUsage as d, AgentUserInput as f, StructuredOutputEnvelope as g, BuiltinAgentActors as h, AgentOutputMode as i, AgentDecisionRequest as j, AgentDecisionExhaustedError as k, AgentRequestMode as l, AiSdkShapedTextResult as m, AgentModelMap as n, AgentRequestExecutorInfo as o, AiSdkShapedStreamResult as p, AgentModelRef as r, AgentRequestExecutorResult as s, AgentCallUsage as t, AgentTextRequest as u, TextLogicConfig as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, renderDecisionAttempts as z };
+export { AgentDecisionExhaustedError as A, AgentRequestOptions as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, ResolveDecisionOptions as F, getAcceptedEvents as H, renderDecisionAttempts as I, resolveDecision as L, AgentDecisionRequest as M, DecisionAttempt as N, parseStructuredEnvelope as O, DecisionLogicConfig as P, AgentEventDescriptor as R, bindRequestExecutor as S, getAgentOutputMode as T, parseAgentEvent as U, AgentRequestSource as V, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventToolNameResolver as z };

package/dist/{types-QbEfCVny.d.cts → types-9Bqg5rZB.d.mts}

@@ -201,8 +201,8 @@ type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${i
 /** 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
+ * Candidate event types for a decision (declared on the `agent.decide`
+ * builtin's `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

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

@@ -201,8 +201,8 @@ type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${i
 /** 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
+ * Candidate event types for a decision (declared on the `agent.decide`
+ * builtin's `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.14",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -99,7 +99,7 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0",
-    "@statelyai/sdk": "^0.15.0",
+    "@statelyai/sdk": "^0.16.2",
     "@types/express": "^5.0.6",
     "@types/node": "^20.16.10",
     "@types/react": "^19.2.17",
@@ -117,6 +117,7 @@
     "react": "^19.2.7",
     "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
+    "twoslash": "^0.3.9",
     "typescript": "^5.6.2",
     "valibot": "^1.4.2",
     "vitest": "^3.2.6",
@@ -141,7 +142,9 @@
   },
   "scripts": {
     "build": "tsdown",
+    "demo": "pnpm --filter @statelyai/agent-demo dev",
     "proto:prefabs": "tsx .scratch/prefabs/demo.ts",
+    "docs:check": "tsx scripts/check-docs-snippets.ts",
     "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
     "typecheck:src": "tsc --noEmit",
     "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",

package/readme.md

@@ -4,15 +4,17 @@
 
 Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere. The machine owns control flow; the model only ever picks a legal event. Testing, inspection, and visualization fall out for free.
 
-Stately Agent adds model requests and decisions to XState. The state machine defines what the agent can do. Your application chooses the model, runs the requests, and stores the state.
+Stately Agent adds model requests and decisions to XState:
 
-Any agent workflow or loop can be modeled as a state machine. Model calls and tools run as effects inside it. The model proposes an event. The machine decides whether it is allowed and what happens next.
+- The machine defines what the agent can do.
+- Your application chooses the model, runs the requests, and stores the state.
+- The model proposes an event; the machine decides whether it is allowed and what happens next.
 
 Stately Agent 2 is in alpha. APIs may change before the stable release.
 
 [Documentation](https://stately.ai/docs/agents) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
 
-## Three ways to start
+## Three starting points
 
 - **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
 - **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a loop](docs/from-a-loop.md).
@@ -26,7 +28,11 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 pnpm add @statelyai/agent@alpha xstate@alpha zod ai@^6 @ai-sdk/openai@^3
 ```
 
-Node 22.18 or newer is required. The package is ESM-first (CommonJS builds are published too, so `require()` works) and requires XState v6 alpha.25 or newer. Provider packages must match your `ai` major: `@ai-sdk/openai@^3` pairs with `ai@^6` (a bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer).
+Requirements:
+
+- Node 22.18 or newer, and XState v6 alpha.25 or newer.
+- The package is ESM-first. CommonJS builds are published too, so `require()` works.
+- Provider packages must match your `ai` major: `@ai-sdk/openai@^3` pairs with `ai@^6`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer.
 
 ## Quick start
 
@@ -114,7 +120,7 @@ When the machine reaches `refunded`, the result is:
 
 The model chooses between the events allowed in `deciding`. The `AUTO_REFUND` transition only works when the amount is at most $100. If the model chooses it for a larger amount, the guard rejects the choice and the decision is tried again.
 
-**Run it with no API key.** `createScriptedExecutors` plays back canned answers through the same executor contract, so the machine above runs end to end before a model is involved:
+`createScriptedExecutors` plays back canned answers through the same executor contract, so the machine above runs end to end before a model is involved. **No API key needed:**
 
 ```ts
 import { createScriptedExecutors } from "@statelyai/agent";
@@ -127,11 +133,21 @@ const result = await runAgent(refundMachine, {
 
 Swap in `createAiSdkExecutors({ models })` when you want a real model. The scripted set is what your tests keep using.
 
-## The state machine
+## Architecture
+
+```mermaid
+flowchart LR
+  M["Agent machine<br/>states · guards · requests"] -->|request| R["runAgent"]
+  R -->|executor call| E["Host executors<br/>generateText · streamText · decide"]
+  E -->|API call| L["Model"]
+  L -->|result| E
+  E -->|result| R
+  R -->|event or output| M
+```
 
-<!-- Add the state machine illustration here. -->
+The machine never talks to a model directly, so swapping `createAiSdkExecutors` for `createScriptedExecutors` (or your own functions) changes nothing about the agent.
 
-The example has one model decision and two final outcomes. Real machines can add approval states, retries, parallel work, child agents, and long-running waits without changing how the control flow is represented.
+The example above has one model decision and two final outcomes. Real machines add approval states, retries, parallel work, child agents, and long-running waits without changing how control flow is represented.
 
 ## Core concepts