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

package/dist/{run-agent-C3mFDGTf.d.mts → run-agent-BWzo4FLv.d.mts}

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-_FXoFBGO.mjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-CTBhMnFu.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { G as AgentRequestSource, H as AgentEventDescriptor, M as AgentDecisionRequest, N as AgentPlanInput, W as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-TkKPw8Aq.mjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-CriMgX1D.mjs";
+import { B as AgentRequestOptions, M as AgentDecisionRequest, R as AgentEventDescriptor, V as AgentRequestSource, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-C7anC7qX.mjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-BkUNtyOF.mjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
 //#region src/internal/registry.d.ts
@@ -9,94 +9,6 @@ type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actors"> & {
   models?: object;
 };
 //#endregion
-//#region src/steps.d.ts
-/**
- * A pending text request surfaced by step discovery ({@link getAgentRequests}
- * / {@link AgentStep.requests}): the machine has spawned a
- * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
- * {@link executeAgentRequest} (or by hand, then feed the output into
- * {@link resolveAgentStep} via `xstate.done.actor` + `actorId`).
- */
-interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
-  kind: "text";
-  id: string;
-  src: AgentRequestSource;
-  mode?: AgentRequestMode;
-  input: TInput;
-  tools: AgentTools;
-  events: AgentEventDescriptor[];
-}
-/**
- * A pending **plan** request re-surfaced by step discovery: the machine
- * invoked `agent.plan`, which applies an ordered sequence of legal events
- * (each one a decision) rather than a single one. Unlike text/decision
- * requests — surfaced once and resolved once — a plan request **re-surfaces on
- * every step** while the plan is in flight, its `events`/`applied`/
- * `stepsRemaining` updated each time, until it terminates.
- *
- * All fields are plain serializable data. Resolve ONE decision per step from
- * `events` (via {@link resolveDecision}, wiring `canTake` to
- * `snapshot.can` exactly like a single decision) then apply it: a real machine
- * event advances the plan (the next step re-surfaces this request); the
- * reserved `agent.plan.done` move, a `stopOn` event, an exhausted budget, or no
- * legal events completes it (its invoke resolves with `{ steps, stopped }`).
- * {@link resolveAgentRequests} does all of this natively — one decision (or one
- * completion) per call.
- *
- * The in-progress plan state (`applied` trail + remaining budget) lives in the
- * plan invoke child's own `createLogic` snapshot `context`
- * (`children.<id>.snapshot.context`), so it survives a full JSON
- * `getPersistedSnapshot` → restore round-trip: a host that persists the step
- * after every event and reloads resumes the plan identically.
- */
-interface AgentPlanRequest {
-  kind: "plan";
-  /** Durable invoke id of the `agent.plan` invoke. */
-  id: string;
-  /** Invoke src (`'agent.plan'` or a registered plan-logic source name). */
-  src: AgentRequestSource;
-  /** The resolved plan input (`model`/`system`/`prompt`/`allowedEvents`/`stopOn`/`maxSteps`/…). */
-  input: AgentPlanInput;
-  /**
-   * The legal candidates for the NEXT plan step: the currently
-   * snapshot-legal machine events (∩ declared `allowedEvents`) plus the
-   * reserved `agent.plan.done` move.
-   */
-  events: AgentEventDescriptor[];
-  /** 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;
-}
-/** `AgentStep.requests` element: a text, decision, or plan request. */
-type AgentStepRequest = AgentRequest | AgentDecisionRequest | AgentPlanRequest;
-/**
- * Resolves one **text** request against a host's {@link AgentRequestExecutors}
- * — merges the request's tools, dispatches to `generateText`/`streamText` per
- * `mode`, and validates the result against the request's `outputSchema` if
- * present. Accepts either a `kind: 'text'` `AgentEffect` (the thin-loop shape
- * from `getAgentEffects`) or a legacy {@link AgentRequest} envelope.
- * **Text-only**: passing a `kind: 'decision'` request throws, directing the
- * caller to `resolveDecision(request, executors.decide, ...)` instead. By default
- * returns the normalized output; pass `{ verbose: true }` to also get the
- * raw executor result (tool calls, usage, finish reason — needed for
- * observability and event-sourced replay).
- */
-/** A `kind: 'text'` `AgentEffect` (structural, to avoid an import cycle with effects.ts). */
-interface TextEffectLike {
-  kind: "text";
-  requestId: string;
-  request: AgentTextRequest;
-  mode?: AgentRequestMode;
-}
-declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
-declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>, options: {
-  verbose: true;
-}): Promise<{
-  output: unknown;
-  raw: unknown;
-}>;
-//#endregion
 //#region src/effects.d.ts
 /**
  * One thing a host does at the frontier. Effect kinds mirror what a machine
@@ -109,8 +21,6 @@ declare function executeAgentRequest(request: AgentRequest | TextEffectLike, exe
  * - `decision` — an `agent.decide`/`DecisionLogic` invoke. Resolve with
  *   `resolveDecision` and journal the CHOSEN machine event directly (a decision
  *   has no output value of its own; the chosen event advances the machine).
- * - `plan` — an `agent.plan` invoke (multi-event). Drive it a step at a time
- *   (see `resolveAgentRequests`), journaling each applied event.
  * - `task` — any other invoke/spawn: a plain host-run task keyed by `src` +
  *   `input`. Run it, then journal `toDoneEvent`/`toErrorEvent`.
  * - `delay` — an `after(...)` timer. Schedule it; when it fires, journal
@@ -130,10 +40,6 @@ type AgentEffect = {
   kind: "decision";
   requestId: string;
   request: AgentDecisionRequest;
-} | {
-  kind: "plan";
-  requestId: string;
-  request: AgentPlanRequest;
 } | {
   kind: "task";
   requestId: string;
@@ -195,7 +101,7 @@ interface AgentUsageEvent extends EventObject {
   /** The settled call's token usage, as reported by the executor. */
   usage: AgentCallUsage;
   /** Which kind of request reported it. */
-  kind?: "text" | "decision" | "plan";
+  kind?: "text" | "decision";
   /** The reporting request's durable invoke id. */
   id?: string;
   /** The reporting request's invoke `src`. */
@@ -261,8 +167,8 @@ interface GetAgentEffectsOptions extends Partial<AgentExecutionOptions> {
  * Ordering is load-bearing: a single transition's actions are emitted in
  * document order (a custom entry action, a spawn, and a `sendTo` in that order
  * yield `execute`, then `task`/agent effect, then `execute` — never a
- * reordered set). Effects visible only on the snapshot (an `agent.plan` that
- * re-surfaces every step, and children spawned by an EARLIER transition that
+ * reordered set). Effects visible only on the snapshot (children spawned by
+ * an EARLIER transition that
  * have not completed yet — the fan-out / crash-resume case) are appended after
  * the action-derived effects, deduped by site id.
  *
@@ -370,6 +276,52 @@ declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachin
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 declare function diffEventLogs<TMachine extends AnyStateMachine>(machine: TMachine, parentEntries: readonly AgentLogEntry[], forkEntries: readonly AgentLogEntry[], options?: ReplayOptions): AgentEventLogDiff<TMachine>;
 //#endregion
+//#region src/steps.d.ts
+/**
+ * A pending text request surfaced by step discovery ({@link getAgentRequests}
+ * / {@link AgentStep.requests}): the machine has spawned a
+ * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
+ * {@link executeAgentRequest} (or by hand, then feed the output into
+ * {@link resolveAgentStep} via `xstate.done.actor` + `actorId`).
+ */
+interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
+  kind: "text";
+  id: string;
+  src: AgentRequestSource;
+  mode?: AgentRequestMode;
+  input: TInput;
+  tools: AgentTools;
+  events: AgentEventDescriptor[];
+}
+/** `AgentStep.requests` element: a text or decision request. */
+type AgentStepRequest = AgentRequest | AgentDecisionRequest;
+/**
+ * Resolves one **text** request against a host's {@link AgentRequestExecutors}
+ * — merges the request's tools, dispatches to `generateText`/`streamText` per
+ * `mode`, and validates the result against the request's `outputSchema` if
+ * present. Accepts either a `kind: 'text'` `AgentEffect` (the thin-loop shape
+ * from `getAgentEffects`) or a legacy {@link AgentRequest} envelope.
+ * **Text-only**: passing a `kind: 'decision'` request throws, directing the
+ * caller to `resolveDecision(request, executors.decide, ...)` instead. By default
+ * returns the normalized output; pass `{ verbose: true }` to also get the
+ * raw executor result (tool calls, usage, finish reason — needed for
+ * observability and event-sourced replay).
+ */
+/** A `kind: 'text'` `AgentEffect` (structural, to avoid an import cycle with effects.ts). */
+interface TextEffectLike {
+  kind: "text";
+  requestId: string;
+  request: AgentTextRequest;
+  mode?: AgentRequestMode;
+}
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+//#endregion
 //#region src/internal/state-request-pass.d.ts
 /**
  * One model request read off the machine's CURRENT snapshot by a
@@ -672,8 +624,15 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * kind, so e.g. a stream-only machine may pass `{ streamText }` alone.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /** Machine input, passed straight to `createActor(machine, { input })`. Omit when resuming via `snapshot`. */
-  input?: InputFrom<TMachine>;
+  /**
+   * Machine input. Validated against the machine's declared input schema —
+   * defaults filled, transforms applied — before it reaches
+   * `createActor(machine, { input })` and the replayable event log; invalid
+   * input throws an {@link AgentError} with code `invalid-machine-input`.
+   * Typed as {@link AgentInputFrom}, so fields the schema defaults are optional
+   * here. Omit when resuming via `snapshot`.
+   */
+  input?: AgentInputFrom<TMachine>;
   /** A previously-settled run's `result.snapshot`, to resume from instead of starting fresh. Pair with `event` to deliver the event that unblocks the resumed idle state. */
   snapshot?: Snapshot<unknown>;
   /** An event to send immediately after starting/resuming the actor (e.g. the human's answer to an idle-state prompt). */
@@ -749,7 +708,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * runAgent uses to settle idle. Resolution order: this option (host override)
    * → the machine-carried predicate declared via `setupAgent({ isSuspended })`
    * → the timing heuristic (when neither is present). When the resolved
-   * predicate returns true and nothing is in flight (no live requests/plans/
+   * predicate returns true and nothing is in flight (no live requests/
    * invokes; the `agent.userInput` placeholder exemption still applies), runAgent
    * settles idle immediately, without the `setTimeout` heuristic. It does NOT
    * force-settle while agent work is in flight, and whole-machine idle semantics
@@ -902,12 +861,13 @@ type RunAgentOutcome<TMachine extends AnyStateMachine> = {
   snapshot: SnapshotFrom<TMachine>; /** Present when the machine is waiting on unhandled `agent.userInput` invokes: one entry per pending invoke. */
   pendingUserInputs?: PendingUserInput[];
   /**
-   * Present alongside `pendingUserInputs`: the JSON-serializable persisted
-   * snapshot (in-flight children included). Persist THIS one and resume
-   * with `runAgent(machine, { snapshot: persistedSnapshot, userInput })` —
-   * the live `snapshot` above cannot round-trip active children.
+   * The JSON-serializable persisted snapshot (in-flight children included,
+   * WITH their own state). Persist THIS one and resume with
+   * `runAgent(machine, { snapshot: persistedSnapshot, ... })` — the live
+   * `snapshot` above cannot round-trip active children, so resuming from
+   * it restarts every invoked child from scratch.
    */
-  persistedSnapshot?: Snapshot<unknown>;
+  persistedSnapshot: Snapshot<unknown>;
 } | {
   status: "error";
   cause: RunAgentErrorCause;
@@ -948,6 +908,20 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
  * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
  */
 type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
+/**
+ * The machine input a run accepts, which is the schema's *pre*-validation side.
+ *
+ * XState's `schemas` are types only — it never validates, and it resolves
+ * `schemas.input` to one type shared by `createActor`'s `input` option and the
+ * `context: ({ input })` factory. A schema field declared with a default
+ * therefore reads as required at the call site even though the caller is meant
+ * to omit it. `setupAgent` brands the machine's input type with its own schema
+ * ({@link WithAgentInputSchema}), so this recovers the looser caller-facing
+ * side while the factory keeps seeing the validated one. Machines with no
+ * declared input schema — and machines reached through `.provide(...)`, which
+ * drops the brand — fall back to xstate's `InputFrom`.
+ */
+type AgentInputFrom<TMachine extends AnyStateMachine> = InputFrom<TMachine> extends WithAgentInputSchema<infer TInputSchema> ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
 /**
  * Runs an agent machine to completion or idle: a `createActor` host that
  * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
@@ -1108,4 +1082,4 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  */
 declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
 //#endregion
-export { AgentReplayDivergenceError as A, getCallUsage as B, AgentStateRequest as C, AgentEffectDiff as D, AgentEffect as E, ReplayOptions as F, AgentRequest as G, replay as H, ReplayResult as I, AgentStepRequest as K, createReplayEntry as L, AgentUsageEvent as M, CreateReplayEntryOptions as N, AgentEventLogDiff as O, GetAgentEffectsOptions as P, diffEventLogs as R, traceTransitions as S, AGENT_USAGE_EVENT_TYPE as T, verifyReplay as U, initEntry as V, AgentPlanRequest as W, createAgentActor as _, AgentMessageInfo as a, runAgent as b, AgentTraceEvent as c, InspectedActorRef as d, JsonSerializableTraceEvent as f, RunAgentResult as g, RunAgentOptions as h, AgentIllegalResumeEventError as i, AgentReplayMachineMismatchError as j, AgentLogPatchOperation as k, AgentUserInputExecutor as l, RunAgentErrorCause as m, AgentActorSession as n, AgentRunMeta as o, PendingUserInput as p, executeAgentRequest as q, AgentIdleError as r, AgentSnapshotVersionMismatchError as s, AGENT_TRACE_SCHEMA_VERSION as t, GenerateResult as u, generateResult as v, AGENT_INIT_EVENT_TYPE as w, serializeTraceEvent as x, inspectTransitions as y, getAgentEffects as z };
+export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, initEntry as G, diffEventLogs as H, AgentUsageEvent as I, replay as K, CreateReplayEntryOptions as L, AgentEventLogDiff as M, AgentLogPatchOperation as N, AGENT_INIT_EVENT_TYPE as O, AgentReplayDivergenceError as P, GetAgentEffectsOptions as R, serializeTraceEvent as S, AgentRequest as T, getAgentEffects as U, createReplayEntry as V, getCallUsage as W, RunAgentResult as _, AgentInputFrom as a, inspectTransitions as b, AgentSnapshotVersionMismatchError as c, GenerateResult as d, InspectedActorRef as f, RunAgentOptions as g, RunAgentErrorCause as h, AgentIllegalResumeEventError as i, AgentEffectDiff as j, AGENT_USAGE_EVENT_TYPE as k, AgentTraceEvent as l, PendingUserInput as m, AgentActorSession as n, AgentMessageInfo as o, JsonSerializableTraceEvent as p, verifyReplay as q, AgentIdleError as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentUserInputExecutor as u, createAgentActor as v, AgentStateRequest as w, runAgent as x, generateResult as y, ReplayOptions as z };

package/dist/{run-agent-DnvtcnTZ.d.cts → run-agent-B_n4Qxye.d.cts}

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-QbEfCVny.cjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-DFD28AWe.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { G as AgentRequestSource, H as AgentEventDescriptor, M as AgentDecisionRequest, N as AgentPlanInput, W as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-BDxwQNsD.cjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-Ruq18mGp.cjs";
+import { B as AgentRequestOptions, M as AgentDecisionRequest, R as AgentEventDescriptor, V as AgentRequestSource, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-DZW7XWy9.cjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-CVd2eyRy.cjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
 //#region src/internal/registry.d.ts
@@ -9,94 +9,6 @@ type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actors"> & {
   models?: object;
 };
 //#endregion
-//#region src/steps.d.ts
-/**
- * A pending text request surfaced by step discovery ({@link getAgentRequests}
- * / {@link AgentStep.requests}): the machine has spawned a
- * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
- * {@link executeAgentRequest} (or by hand, then feed the output into
- * {@link resolveAgentStep} via `xstate.done.actor` + `actorId`).
- */
-interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
-  kind: "text";
-  id: string;
-  src: AgentRequestSource;
-  mode?: AgentRequestMode;
-  input: TInput;
-  tools: AgentTools;
-  events: AgentEventDescriptor[];
-}
-/**
- * A pending **plan** request re-surfaced by step discovery: the machine
- * invoked `agent.plan`, which applies an ordered sequence of legal events
- * (each one a decision) rather than a single one. Unlike text/decision
- * requests — surfaced once and resolved once — a plan request **re-surfaces on
- * every step** while the plan is in flight, its `events`/`applied`/
- * `stepsRemaining` updated each time, until it terminates.
- *
- * All fields are plain serializable data. Resolve ONE decision per step from
- * `events` (via {@link resolveDecision}, wiring `canTake` to
- * `snapshot.can` exactly like a single decision) then apply it: a real machine
- * event advances the plan (the next step re-surfaces this request); the
- * reserved `agent.plan.done` move, a `stopOn` event, an exhausted budget, or no
- * legal events completes it (its invoke resolves with `{ steps, stopped }`).
- * {@link resolveAgentRequests} does all of this natively — one decision (or one
- * completion) per call.
- *
- * The in-progress plan state (`applied` trail + remaining budget) lives in the
- * plan invoke child's own `createLogic` snapshot `context`
- * (`children.<id>.snapshot.context`), so it survives a full JSON
- * `getPersistedSnapshot` → restore round-trip: a host that persists the step
- * after every event and reloads resumes the plan identically.
- */
-interface AgentPlanRequest {
-  kind: "plan";
-  /** Durable invoke id of the `agent.plan` invoke. */
-  id: string;
-  /** Invoke src (`'agent.plan'` or a registered plan-logic source name). */
-  src: AgentRequestSource;
-  /** The resolved plan input (`model`/`system`/`prompt`/`allowedEvents`/`stopOn`/`maxSteps`/…). */
-  input: AgentPlanInput;
-  /**
-   * The legal candidates for the NEXT plan step: the currently
-   * snapshot-legal machine events (∩ declared `allowedEvents`) plus the
-   * reserved `agent.plan.done` move.
-   */
-  events: AgentEventDescriptor[];
-  /** 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;
-}
-/** `AgentStep.requests` element: a text, decision, or plan request. */
-type AgentStepRequest = AgentRequest | AgentDecisionRequest | AgentPlanRequest;
-/**
- * Resolves one **text** request against a host's {@link AgentRequestExecutors}
- * — merges the request's tools, dispatches to `generateText`/`streamText` per
- * `mode`, and validates the result against the request's `outputSchema` if
- * present. Accepts either a `kind: 'text'` `AgentEffect` (the thin-loop shape
- * from `getAgentEffects`) or a legacy {@link AgentRequest} envelope.
- * **Text-only**: passing a `kind: 'decision'` request throws, directing the
- * caller to `resolveDecision(request, executors.decide, ...)` instead. By default
- * returns the normalized output; pass `{ verbose: true }` to also get the
- * raw executor result (tool calls, usage, finish reason — needed for
- * observability and event-sourced replay).
- */
-/** A `kind: 'text'` `AgentEffect` (structural, to avoid an import cycle with effects.ts). */
-interface TextEffectLike {
-  kind: "text";
-  requestId: string;
-  request: AgentTextRequest;
-  mode?: AgentRequestMode;
-}
-declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
-declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>, options: {
-  verbose: true;
-}): Promise<{
-  output: unknown;
-  raw: unknown;
-}>;
-//#endregion
 //#region src/effects.d.ts
 /**
  * One thing a host does at the frontier. Effect kinds mirror what a machine
@@ -109,8 +21,6 @@ declare function executeAgentRequest(request: AgentRequest | TextEffectLike, exe
  * - `decision` — an `agent.decide`/`DecisionLogic` invoke. Resolve with
  *   `resolveDecision` and journal the CHOSEN machine event directly (a decision
  *   has no output value of its own; the chosen event advances the machine).
- * - `plan` — an `agent.plan` invoke (multi-event). Drive it a step at a time
- *   (see `resolveAgentRequests`), journaling each applied event.
  * - `task` — any other invoke/spawn: a plain host-run task keyed by `src` +
  *   `input`. Run it, then journal `toDoneEvent`/`toErrorEvent`.
  * - `delay` — an `after(...)` timer. Schedule it; when it fires, journal
@@ -130,10 +40,6 @@ type AgentEffect = {
   kind: "decision";
   requestId: string;
   request: AgentDecisionRequest;
-} | {
-  kind: "plan";
-  requestId: string;
-  request: AgentPlanRequest;
 } | {
   kind: "task";
   requestId: string;
@@ -195,7 +101,7 @@ interface AgentUsageEvent extends EventObject {
   /** The settled call's token usage, as reported by the executor. */
   usage: AgentCallUsage;
   /** Which kind of request reported it. */
-  kind?: "text" | "decision" | "plan";
+  kind?: "text" | "decision";
   /** The reporting request's durable invoke id. */
   id?: string;
   /** The reporting request's invoke `src`. */
@@ -261,8 +167,8 @@ interface GetAgentEffectsOptions extends Partial<AgentExecutionOptions> {
  * Ordering is load-bearing: a single transition's actions are emitted in
  * document order (a custom entry action, a spawn, and a `sendTo` in that order
  * yield `execute`, then `task`/agent effect, then `execute` — never a
- * reordered set). Effects visible only on the snapshot (an `agent.plan` that
- * re-surfaces every step, and children spawned by an EARLIER transition that
+ * reordered set). Effects visible only on the snapshot (children spawned by
+ * an EARLIER transition that
  * have not completed yet — the fan-out / crash-resume case) are appended after
  * the action-derived effects, deduped by site id.
  *
@@ -370,6 +276,52 @@ declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachin
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 declare function diffEventLogs<TMachine extends AnyStateMachine>(machine: TMachine, parentEntries: readonly AgentLogEntry[], forkEntries: readonly AgentLogEntry[], options?: ReplayOptions): AgentEventLogDiff<TMachine>;
 //#endregion
+//#region src/steps.d.ts
+/**
+ * A pending text request surfaced by step discovery ({@link getAgentRequests}
+ * / {@link AgentStep.requests}): the machine has spawned a
+ * `TextLogic`-backed invoke and is waiting on its result. Resolve it with
+ * {@link executeAgentRequest} (or by hand, then feed the output into
+ * {@link resolveAgentStep} via `xstate.done.actor` + `actorId`).
+ */
+interface AgentRequest<TInput extends AgentTextRequest = AgentTextRequest> {
+  kind: "text";
+  id: string;
+  src: AgentRequestSource;
+  mode?: AgentRequestMode;
+  input: TInput;
+  tools: AgentTools;
+  events: AgentEventDescriptor[];
+}
+/** `AgentStep.requests` element: a text or decision request. */
+type AgentStepRequest = AgentRequest | AgentDecisionRequest;
+/**
+ * Resolves one **text** request against a host's {@link AgentRequestExecutors}
+ * — merges the request's tools, dispatches to `generateText`/`streamText` per
+ * `mode`, and validates the result against the request's `outputSchema` if
+ * present. Accepts either a `kind: 'text'` `AgentEffect` (the thin-loop shape
+ * from `getAgentEffects`) or a legacy {@link AgentRequest} envelope.
+ * **Text-only**: passing a `kind: 'decision'` request throws, directing the
+ * caller to `resolveDecision(request, executors.decide, ...)` instead. By default
+ * returns the normalized output; pass `{ verbose: true }` to also get the
+ * raw executor result (tool calls, usage, finish reason — needed for
+ * observability and event-sourced replay).
+ */
+/** A `kind: 'text'` `AgentEffect` (structural, to avoid an import cycle with effects.ts). */
+interface TextEffectLike {
+  kind: "text";
+  requestId: string;
+  request: AgentTextRequest;
+  mode?: AgentRequestMode;
+}
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+//#endregion
 //#region src/internal/state-request-pass.d.ts
 /**
  * One model request read off the machine's CURRENT snapshot by a
@@ -672,8 +624,15 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * kind, so e.g. a stream-only machine may pass `{ streamText }` alone.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /** Machine input, passed straight to `createActor(machine, { input })`. Omit when resuming via `snapshot`. */
-  input?: InputFrom<TMachine>;
+  /**
+   * Machine input. Validated against the machine's declared input schema —
+   * defaults filled, transforms applied — before it reaches
+   * `createActor(machine, { input })` and the replayable event log; invalid
+   * input throws an {@link AgentError} with code `invalid-machine-input`.
+   * Typed as {@link AgentInputFrom}, so fields the schema defaults are optional
+   * here. Omit when resuming via `snapshot`.
+   */
+  input?: AgentInputFrom<TMachine>;
   /** A previously-settled run's `result.snapshot`, to resume from instead of starting fresh. Pair with `event` to deliver the event that unblocks the resumed idle state. */
   snapshot?: Snapshot<unknown>;
   /** An event to send immediately after starting/resuming the actor (e.g. the human's answer to an idle-state prompt). */
@@ -749,7 +708,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * runAgent uses to settle idle. Resolution order: this option (host override)
    * → the machine-carried predicate declared via `setupAgent({ isSuspended })`
    * → the timing heuristic (when neither is present). When the resolved
-   * predicate returns true and nothing is in flight (no live requests/plans/
+   * predicate returns true and nothing is in flight (no live requests/
    * invokes; the `agent.userInput` placeholder exemption still applies), runAgent
    * settles idle immediately, without the `setTimeout` heuristic. It does NOT
    * force-settle while agent work is in flight, and whole-machine idle semantics
@@ -902,12 +861,13 @@ type RunAgentOutcome<TMachine extends AnyStateMachine> = {
   snapshot: SnapshotFrom<TMachine>; /** Present when the machine is waiting on unhandled `agent.userInput` invokes: one entry per pending invoke. */
   pendingUserInputs?: PendingUserInput[];
   /**
-   * Present alongside `pendingUserInputs`: the JSON-serializable persisted
-   * snapshot (in-flight children included). Persist THIS one and resume
-   * with `runAgent(machine, { snapshot: persistedSnapshot, userInput })` —
-   * the live `snapshot` above cannot round-trip active children.
+   * The JSON-serializable persisted snapshot (in-flight children included,
+   * WITH their own state). Persist THIS one and resume with
+   * `runAgent(machine, { snapshot: persistedSnapshot, ... })` — the live
+   * `snapshot` above cannot round-trip active children, so resuming from
+   * it restarts every invoked child from scratch.
    */
-  persistedSnapshot?: Snapshot<unknown>;
+  persistedSnapshot: Snapshot<unknown>;
 } | {
   status: "error";
   cause: RunAgentErrorCause;
@@ -948,6 +908,20 @@ type RunAgentResult<TMachine extends AnyStateMachine> = RunAgentOutcome<TMachine
  * - `'stopped'` — the actor was stopped externally (`status === 'stopped'`).
  */
 type RunAgentErrorCause = "aborted" | "max-model-calls" | "decision-exhausted" | "machine" | "stopped";
+/**
+ * The machine input a run accepts, which is the schema's *pre*-validation side.
+ *
+ * XState's `schemas` are types only — it never validates, and it resolves
+ * `schemas.input` to one type shared by `createActor`'s `input` option and the
+ * `context: ({ input })` factory. A schema field declared with a default
+ * therefore reads as required at the call site even though the caller is meant
+ * to omit it. `setupAgent` brands the machine's input type with its own schema
+ * ({@link WithAgentInputSchema}), so this recovers the looser caller-facing
+ * side while the factory keeps seeing the validated one. Machines with no
+ * declared input schema — and machines reached through `.provide(...)`, which
+ * drops the brand — fall back to xstate's `InputFrom`.
+ */
+type AgentInputFrom<TMachine extends AnyStateMachine> = InputFrom<TMachine> extends WithAgentInputSchema<infer TInputSchema> ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
 /**
  * Runs an agent machine to completion or idle: a `createActor` host that
  * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/
@@ -1108,4 +1082,4 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  */
 declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMachine>(onTrace: (event: AgentTraceEvent<TMachine>) => void): (inspectionEvent: InspectionEvent) => void;
 //#endregion
-export { AgentReplayDivergenceError as A, getCallUsage as B, AgentStateRequest as C, AgentEffectDiff as D, AgentEffect as E, ReplayOptions as F, AgentRequest as G, replay as H, ReplayResult as I, AgentStepRequest as K, createReplayEntry as L, AgentUsageEvent as M, CreateReplayEntryOptions as N, AgentEventLogDiff as O, GetAgentEffectsOptions as P, diffEventLogs as R, traceTransitions as S, AGENT_USAGE_EVENT_TYPE as T, verifyReplay as U, initEntry as V, AgentPlanRequest as W, createAgentActor as _, AgentMessageInfo as a, runAgent as b, AgentTraceEvent as c, InspectedActorRef as d, JsonSerializableTraceEvent as f, RunAgentResult as g, RunAgentOptions as h, AgentIllegalResumeEventError as i, AgentReplayMachineMismatchError as j, AgentLogPatchOperation as k, AgentUserInputExecutor as l, RunAgentErrorCause as m, AgentActorSession as n, AgentRunMeta as o, PendingUserInput as p, executeAgentRequest as q, AgentIdleError as r, AgentSnapshotVersionMismatchError as s, AGENT_TRACE_SCHEMA_VERSION as t, GenerateResult as u, generateResult as v, AGENT_INIT_EVENT_TYPE as w, serializeTraceEvent as x, inspectTransitions as y, getAgentEffects as z };
+export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, initEntry as G, diffEventLogs as H, AgentUsageEvent as I, replay as K, CreateReplayEntryOptions as L, AgentEventLogDiff as M, AgentLogPatchOperation as N, AGENT_INIT_EVENT_TYPE as O, AgentReplayDivergenceError as P, GetAgentEffectsOptions as R, serializeTraceEvent as S, AgentRequest as T, getAgentEffects as U, createReplayEntry as V, getCallUsage as W, RunAgentResult as _, AgentInputFrom as a, inspectTransitions as b, AgentSnapshotVersionMismatchError as c, GenerateResult as d, InspectedActorRef as f, RunAgentOptions as g, RunAgentErrorCause as h, AgentIllegalResumeEventError as i, AgentEffectDiff as j, AGENT_USAGE_EVENT_TYPE as k, AgentTraceEvent as l, PendingUserInput as m, AgentActorSession as n, AgentMessageInfo as o, JsonSerializableTraceEvent as p, verifyReplay as q, AgentIdleError as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentUserInputExecutor as u, createAgentActor as v, AgentStateRequest as w, runAgent as x, generateResult as y, ReplayOptions as z };