@statelyai/agent 2.0.0-alpha.13 → 2.0.0-alpha.15

package/dist/{text-logic-TkKPw8Aq.d.mts → text-logic-C7anC7qX.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 { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-CTBhMnFu.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. */
@@ -16,9 +16,11 @@ interface AgentEventDescriptor {
   toolName: string;
   inputSchema?: StandardSchemaV1;
 }
-/** Registered event payload schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
+/** Registered schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
 interface AgentSchemas {
   events?: Record<string, StandardSchemaV1>;
+  /** Machine input schema; `runAgent` validates `options.input` against it. */
+  input?: StandardSchemaV1;
 }
 /** Shared options threaded through step discovery ({@link getAgentRequests}/{@link getAcceptedEvents}) — snapshot for event legality, event schemas for payload validation/tool schemas, and registered actor source logics. */
 interface AgentRequestOptions {
@@ -97,92 +99,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 +282,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 +400,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
@@ -733,7 +647,7 @@ type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequ
  * 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.
@@ -790,4 +704,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExhaustedError as A, renderDecisionAttempts as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, DecisionAttempt as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogicConfig as I, getAcceptedEvents as K, PLAN_DONE_EVENT_TYPE as L, AgentDecisionRequest as M, AgentPlanInput as N, parseStructuredEnvelope as O, AgentPlanOutput as P, PlanLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, ResolveDecisionOptions 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-BDxwQNsD.d.cts → text-logic-DZW7XWy9.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 { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-DFD28AWe.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. */
@@ -16,9 +16,11 @@ interface AgentEventDescriptor {
   toolName: string;
   inputSchema?: StandardSchemaV1;
 }
-/** Registered event payload schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
+/** Registered schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
 interface AgentSchemas {
   events?: Record<string, StandardSchemaV1>;
+  /** Machine input schema; `runAgent` validates `options.input` against it. */
+  input?: StandardSchemaV1;
 }
 /** Shared options threaded through step discovery ({@link getAgentRequests}/{@link getAcceptedEvents}) — snapshot for event legality, event schemas for payload validation/tool schemas, and registered actor source logics. */
 interface AgentRequestOptions {
@@ -97,92 +99,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 +282,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 +400,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
@@ -733,7 +647,7 @@ type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequ
  * 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.
@@ -790,4 +704,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExhaustedError as A, renderDecisionAttempts as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, DecisionAttempt as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogicConfig as I, getAcceptedEvents as K, PLAN_DONE_EVENT_TYPE as L, AgentDecisionRequest as M, AgentPlanInput as N, parseStructuredEnvelope as O, AgentPlanOutput as P, PlanLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, ResolveDecisionOptions 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-CTBhMnFu.d.mts}

@@ -36,6 +36,33 @@ interface StandardSchemaV1<Input = unknown, Output = Input> {
 }
 /** The validated output type of a {@link StandardSchemaV1}. */
 type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/**
+ * The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
+ * passes in, before defaults are filled and transforms applied. Standard Schema
+ * carries both sides (`~standard.types.input` / `.output`), so a schema
+ * declaring a defaulted field makes that field optional here and required in
+ * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * accepts as machine `input` and what the `context` factory then sees.
+ */
+type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
+/**
+ * Phantom brand carrying a machine's declared input schema on the machine type.
+ *
+ * XState resolves `schemas.input` to a single type and uses it for both
+ * `createActor`'s `input` option and the `context: ({ input })` factory, so the
+ * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
+ * `createMachine` brands the machine's input type with the schema itself, which
+ * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * `context` factory keeps the strict validated side.
+ *
+ * The key is a `~`-prefixed phantom property (the same convention Standard
+ * Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
+ * have to be exported as a runtime value for declaration emit to name it in
+ * every machine type it touches.
+ */
+type WithAgentInputSchema<TInputSchema> = {
+  readonly "~agent.inputSchema"?: TInputSchema;
+};
 /** 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;
 /**
@@ -201,8 +228,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
@@ -216,4 +243,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };
+export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };

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

@@ -36,6 +36,33 @@ interface StandardSchemaV1<Input = unknown, Output = Input> {
 }
 /** The validated output type of a {@link StandardSchemaV1}. */
 type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/**
+ * The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
+ * passes in, before defaults are filled and transforms applied. Standard Schema
+ * carries both sides (`~standard.types.input` / `.output`), so a schema
+ * declaring a defaulted field makes that field optional here and required in
+ * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * accepts as machine `input` and what the `context` factory then sees.
+ */
+type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
+/**
+ * Phantom brand carrying a machine's declared input schema on the machine type.
+ *
+ * XState resolves `schemas.input` to a single type and uses it for both
+ * `createActor`'s `input` option and the `context: ({ input })` factory, so the
+ * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
+ * `createMachine` brands the machine's input type with the schema itself, which
+ * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * `context` factory keeps the strict validated side.
+ *
+ * The key is a `~`-prefixed phantom property (the same convention Standard
+ * Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
+ * have to be exported as a runtime value for declaration emit to name it in
+ * every machine type it touches.
+ */
+type WithAgentInputSchema<TInputSchema> = {
+  readonly "~agent.inputSchema"?: TInputSchema;
+};
 /** 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;
 /**
@@ -201,8 +228,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
@@ -216,4 +243,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };
+export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.13",
+  "version": "2.0.0-alpha.15",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "type": "module",
   "main": "dist/index.cjs",