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

package/dist/machines.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_setup_agent = require("./setup-agent-CpK0ZRWV.cjs");
+const require_setup_agent = require("./setup-agent-BLU77gqr.cjs");
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";

package/dist/machines.d.cts

@@ -1,4 +1,4 @@
-import { _ as StandardSchemaV1, c as AgentTools } from "./types-rMe7x6NR.cjs";
+import { c as AgentTools, v as StandardSchemaV1 } from "./types-pJ5Hn8fv.cjs";
 import { AnyStateMachine } from "xstate";
 
 //#region src/machines/tool-loop.d.ts

package/dist/machines.d.mts

@@ -1,4 +1,4 @@
-import { _ as StandardSchemaV1, c as AgentTools } from "./types-9Bqg5rZB.mjs";
+import { c as AgentTools, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
 import { AnyStateMachine } from "xstate";
 
 //#region src/machines/tool-loop.d.ts

package/dist/machines.mjs

@@ -1,4 +1,4 @@
-import { n as setupAgent } from "./setup-agent-DeHRW-qX.mjs";
+import { n as setupAgent } from "./setup-agent-SbiiSbAU.mjs";
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";

package/dist/otel.d.cts

@@ -1,4 +1,4 @@
-import { c as AgentTraceEvent } from "./run-agent-BlqKwHIF.cjs";
+import { l as AgentTraceEvent } from "./run-agent-BxjGaVpL.cjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts

package/dist/otel.d.mts

@@ -1,4 +1,4 @@
-import { c as AgentTraceEvent } from "./run-agent-2MnlQTkB.mjs";
+import { l as AgentTraceEvent } from "./run-agent-COHoCgQd.mjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts

package/dist/{run-agent-BlqKwHIF.d.cts → run-agent-BxjGaVpL.d.cts}

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-rMe7x6NR.cjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-pJ5Hn8fv.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.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-Jkilp1Ie.cjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-CVd2eyRy.cjs";
+import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-BFX5q7fM.cjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-CQJq8_v4.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
@@ -111,24 +111,6 @@ interface AgentUsageEvent extends EventObject {
   /** The reporting text request's registered `name`, when it declared one. */
   name?: string;
 }
-/**
- * Reads a settled call's token usage off a RAW executor result — the same
- * normalization `runAgent` applies before it delivers
- * {@link AGENT_USAGE_EVENT_TYPE}. Returns `undefined` when the executor
- * reported none.
- *
- * The seam for the step-loop path, where the host holds the raw result itself:
- *
- * ```ts
- * const { output, raw } = await executeAgentRequest(effect, executors, { verbose: true });
- * const usage = getCallUsage(raw);
- * if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
- * append(effect.toDoneEvent(output));
- * ```
- *
- * See "Token usage on this path" in docs/steps.md for the full loop.
- */
-declare function getCallUsage(raw: unknown): AgentCallUsage | undefined;
 /** Options controlling the durable envelope created by {@link createReplayEntry}. */
 interface CreateReplayEntryOptions {
   /** Explicit machine version; defaults to the machine's structural hash. */
@@ -257,19 +239,6 @@ interface AgentEventLogDiff<TMachine extends AnyStateMachine> {
   stateChanges: AgentLogPatchOperation[];
   effectChanges: AgentEffectDiff;
 }
-/**
- * Folds a journal through `initialTransition`/`transition` WITHOUT executing
- * anything, then returns the final snapshot plus the still-owed effects
- * ({@link getAgentEffects} of the final frontier, occurrence counts taken from
- * the whole log). Crash recovery, fork resume, and time travel in one call.
- *
- * `entries` is a versioned {@link AgentLogEntry} array. A reserved
- * {@link initEntry} first envelope carries `{ type: '@agent.init', input }`,
- * so a complete log replays with no side-channel; when absent,
- * `options.input` is used instead.
- * Raised/internal events are never in the journal — replay re-derives them
- * deterministically from the machine's own logic.
- */
 declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
 /** Requires and checks every entry's recorded state/effect hashes. */
 declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: Omit<ReplayOptions, "verify">): ReplayResult<TMachine>;
@@ -299,13 +268,13 @@ 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.
+ * present. Accepts either a `kind: 'text'` `AgentEffect` (the step-path shape
+ * from `getAgentEffects`) or an {@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).
+ * caller to `resolveDecision(request, executors.decide, ...)` instead. Always
+ * returns both the normalized `output` and 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 {
@@ -314,10 +283,7 @@ interface TextEffectLike {
   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<{
+declare function executeAgentRequest(requestOrEffect: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<{
   output: unknown;
   raw: unknown;
 }>;
@@ -514,73 +480,36 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   error: unknown;
   snapshot: SnapshotFrom<TMachine>;
 }));
+/**
+ * Fields a JSON projection keeps VERBATIM: {@link TRACE_ENVELOPE_KEYS} (the
+ * envelope, the `type`/`status`/`cause` discriminants, and the payload fields
+ * that are already plain strings) plus `usage.dropped`'s `reason`, which is a
+ * string literal — sanitizing it is the identity, so it keeps its literal type.
+ * Every other payload field narrows to {@link JsonValue}. @internal
+ */
+type TraceVerbatimKey = (typeof TRACE_ENVELOPE_KEYS)[number] | "reason";
+/** One trace variant's JSON projection. Homomorphic, so `?` modifiers survive. @internal */
+type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue };
+/**
+ * `raw` is written only when `includeRaw` was set, so it is optional on the
+ * JSON side even though the live trace always carries it. @internal
+ */
+type WithOptionalRaw<T> = "raw" extends keyof T ? Omit<T, "raw"> & {
+  raw?: JsonValue;
+} : T;
 /**
  * The JSON-safe projection of an {@link AgentTraceEvent} produced by
  * {@link serializeTraceEvent}: the envelope fields are unchanged, and every
  * payload field that can hold a live object (snapshots, machine events, request
  * objects, raw SDK results, errors) is narrowed to a {@link JsonValue}. Safe to
  * hand straight to `JSON.stringify` for a JSONL trace file.
+ *
+ * DERIVED from {@link AgentTraceEvent}, so a new trace variant cannot silently
+ * miss the JSON side. `src/serialize-trace-event.test.ts` pins the result to
+ * the shape this type had when it was hand-maintained.
  */
-type JsonSerializableTraceEvent = {
-  schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
-  runId: string;
-  seq: number;
-  timestamp: string;
-  machineId: string;
-  machineVersion: string;
-} & ({
-  type: "run.start";
-  input?: JsonValue;
-  snapshot?: JsonValue;
-  event?: JsonValue;
-} | {
-  type: "request.start";
-  request: JsonValue;
-} | {
-  type: "request.end";
-  request: JsonValue;
-  output: JsonValue; /** Present only when `includeRaw` was set; the raw executor result, sanitized. */
-  raw?: JsonValue;
-  reasoning?: string; /** Present only when the executor reported it; plain numbers, passed through as-is. */
-  usage?: JsonValue;
-} | {
-  type: "request.error";
-  request: JsonValue;
-  error: JsonValue;
-} | {
-  type: "stream.chunk";
-  request: JsonValue;
-  chunk: string;
-} | {
-  type: "machine.transition";
-  snapshot: JsonValue;
-  event: JsonValue;
-  eventId?: string;
-} | {
-  type: "emit";
-  event: JsonValue;
-} | {
-  type: "usage.dropped";
-  event: JsonValue;
-  reason: "settled";
-} | {
-  type: "run.end";
-  status: "done";
-  output: JsonValue;
-  snapshot: JsonValue;
-} | {
-  type: "run.end";
-  status: "idle";
-  snapshot: JsonValue;
-  pendingUserInputs?: JsonValue;
-  persistedSnapshot?: JsonValue;
-} | {
-  type: "run.end";
-  status: "error";
-  cause: RunAgentErrorCause;
-  error: JsonValue;
-  snapshot: JsonValue;
-});
+type JsonSerializableTraceEvent = AgentTraceEvent extends infer TEvent ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
+declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "timestamp", "machineId", "machineVersion", "type", "status", "cause", "eventId", "reasoning", "chunk"];
 /**
  * Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
  * the form the trace stream is actually sold for (one `JSON.stringify` per line
@@ -624,8 +553,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). */
@@ -760,11 +696,21 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * with no extra wiring — read it with `getAgentMessages(snapshot)`.
    */
   messages?: AgentMessage[] | ((prior: AgentMessage[]) => AgentMessage[]);
-  /** Fires for each streamed chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest} that produced it (parallel states can interleave multiple streams). Purely observational. */
+  /**
+   * Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
+   * chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
+   * that produced it (parallel states can interleave multiple streams). Purely
+   * observational.
+   */
   onChunk?: (chunk: string, info: {
     request: AgentRequest;
   }) => void;
-  /** Fires once per resolved text/decision request with its normalized output and the raw executor result (tool calls, usage, …) — the seam for tracing/observability and event-sourced replay logging. */
+  /**
+   * Sugar over {@link onTrace}'s `request.end` events: fires once per resolved
+   * text/decision request with its normalized output and the raw executor
+   * result (tool calls, usage, …) — the seam for tracing/observability and
+   * event-sourced replay logging.
+   */
   onResult?: (request: AgentStepRequest, result: {
     output: unknown;
     raw: unknown;
@@ -779,8 +725,9 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
   /** Fires a single ordered stream of run/request/chunk/transition/emit/end events. Intended for eval traces, JSONL logs, and adapter-owned telemetry/exporters. */
   onTrace?: (event: AgentTraceEvent<TMachine>) => void;
   /**
-   * Fires on every machine transition (snapshot + causing event). Pure
-   * observation — progress UIs, logging, tracing. Cannot send events.
+   * Sugar over {@link onTrace}'s `machine.transition` events: fires on every
+   * root-machine transition (snapshot + causing event). Pure observation —
+   * progress UIs, logging, tracing. Cannot send events.
    */
   onTransition?: (snapshot: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine>) => void;
   /**
@@ -901,6 +848,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`/
@@ -1061,4 +1022,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 { AgentEffectDiff as A, createReplayEntry as B, AgentStateRequest as C, AGENT_INIT_EVENT_TYPE as D, executeAgentRequest as E, AgentUsageEvent as F, replay as G, getAgentEffects as H, CreateReplayEntryOptions as I, verifyReplay as K, GetAgentEffectsOptions as L, AgentLogPatchOperation as M, AgentReplayDivergenceError as N, AGENT_USAGE_EVENT_TYPE as O, AgentReplayMachineMismatchError as P, ReplayOptions as R, traceTransitions as S, AgentStepRequest as T, getCallUsage as U, diffEventLogs as V, initEntry 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, AgentEventLogDiff as j, AgentEffect as k, AgentUserInputExecutor as l, RunAgentErrorCause as m, AgentActorSession as n, AgentRunMeta as o, PendingUserInput as p, AgentIdleError as r, AgentSnapshotVersionMismatchError as s, AGENT_TRACE_SCHEMA_VERSION as t, GenerateResult as u, generateResult as v, AgentRequest as w, serializeTraceEvent as x, inspectTransitions as y, ReplayResult as z };
+export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, replay as G, diffEventLogs as H, AgentUsageEvent as I, verifyReplay 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, initEntry 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, 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-2MnlQTkB.d.mts → run-agent-COHoCgQd.d.mts}

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-9Bqg5rZB.mjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.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-C5kbjaDz.mjs";
-import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-BkUNtyOF.mjs";
+import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-DQW8_DWW.mjs";
+import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-BrC9Q1xW.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
@@ -111,24 +111,6 @@ interface AgentUsageEvent extends EventObject {
   /** The reporting text request's registered `name`, when it declared one. */
   name?: string;
 }
-/**
- * Reads a settled call's token usage off a RAW executor result — the same
- * normalization `runAgent` applies before it delivers
- * {@link AGENT_USAGE_EVENT_TYPE}. Returns `undefined` when the executor
- * reported none.
- *
- * The seam for the step-loop path, where the host holds the raw result itself:
- *
- * ```ts
- * const { output, raw } = await executeAgentRequest(effect, executors, { verbose: true });
- * const usage = getCallUsage(raw);
- * if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
- * append(effect.toDoneEvent(output));
- * ```
- *
- * See "Token usage on this path" in docs/steps.md for the full loop.
- */
-declare function getCallUsage(raw: unknown): AgentCallUsage | undefined;
 /** Options controlling the durable envelope created by {@link createReplayEntry}. */
 interface CreateReplayEntryOptions {
   /** Explicit machine version; defaults to the machine's structural hash. */
@@ -257,19 +239,6 @@ interface AgentEventLogDiff<TMachine extends AnyStateMachine> {
   stateChanges: AgentLogPatchOperation[];
   effectChanges: AgentEffectDiff;
 }
-/**
- * Folds a journal through `initialTransition`/`transition` WITHOUT executing
- * anything, then returns the final snapshot plus the still-owed effects
- * ({@link getAgentEffects} of the final frontier, occurrence counts taken from
- * the whole log). Crash recovery, fork resume, and time travel in one call.
- *
- * `entries` is a versioned {@link AgentLogEntry} array. A reserved
- * {@link initEntry} first envelope carries `{ type: '@agent.init', input }`,
- * so a complete log replays with no side-channel; when absent,
- * `options.input` is used instead.
- * Raised/internal events are never in the journal — replay re-derives them
- * deterministically from the machine's own logic.
- */
 declare function replay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: ReplayOptions): ReplayResult<TMachine>;
 /** Requires and checks every entry's recorded state/effect hashes. */
 declare function verifyReplay<TMachine extends AnyStateMachine>(machine: TMachine, entries: readonly AgentLogEntry[], options?: Omit<ReplayOptions, "verify">): ReplayResult<TMachine>;
@@ -299,13 +268,13 @@ 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.
+ * present. Accepts either a `kind: 'text'` `AgentEffect` (the step-path shape
+ * from `getAgentEffects`) or an {@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).
+ * caller to `resolveDecision(request, executors.decide, ...)` instead. Always
+ * returns both the normalized `output` and 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 {
@@ -314,10 +283,7 @@ interface TextEffectLike {
   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<{
+declare function executeAgentRequest(requestOrEffect: AgentRequest | TextEffectLike, executors: Partial<AgentRequestExecutors>): Promise<{
   output: unknown;
   raw: unknown;
 }>;
@@ -514,73 +480,36 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   error: unknown;
   snapshot: SnapshotFrom<TMachine>;
 }));
+/**
+ * Fields a JSON projection keeps VERBATIM: {@link TRACE_ENVELOPE_KEYS} (the
+ * envelope, the `type`/`status`/`cause` discriminants, and the payload fields
+ * that are already plain strings) plus `usage.dropped`'s `reason`, which is a
+ * string literal — sanitizing it is the identity, so it keeps its literal type.
+ * Every other payload field narrows to {@link JsonValue}. @internal
+ */
+type TraceVerbatimKey = (typeof TRACE_ENVELOPE_KEYS)[number] | "reason";
+/** One trace variant's JSON projection. Homomorphic, so `?` modifiers survive. @internal */
+type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue };
+/**
+ * `raw` is written only when `includeRaw` was set, so it is optional on the
+ * JSON side even though the live trace always carries it. @internal
+ */
+type WithOptionalRaw<T> = "raw" extends keyof T ? Omit<T, "raw"> & {
+  raw?: JsonValue;
+} : T;
 /**
  * The JSON-safe projection of an {@link AgentTraceEvent} produced by
  * {@link serializeTraceEvent}: the envelope fields are unchanged, and every
  * payload field that can hold a live object (snapshots, machine events, request
  * objects, raw SDK results, errors) is narrowed to a {@link JsonValue}. Safe to
  * hand straight to `JSON.stringify` for a JSONL trace file.
+ *
+ * DERIVED from {@link AgentTraceEvent}, so a new trace variant cannot silently
+ * miss the JSON side. `src/serialize-trace-event.test.ts` pins the result to
+ * the shape this type had when it was hand-maintained.
  */
-type JsonSerializableTraceEvent = {
-  schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
-  runId: string;
-  seq: number;
-  timestamp: string;
-  machineId: string;
-  machineVersion: string;
-} & ({
-  type: "run.start";
-  input?: JsonValue;
-  snapshot?: JsonValue;
-  event?: JsonValue;
-} | {
-  type: "request.start";
-  request: JsonValue;
-} | {
-  type: "request.end";
-  request: JsonValue;
-  output: JsonValue; /** Present only when `includeRaw` was set; the raw executor result, sanitized. */
-  raw?: JsonValue;
-  reasoning?: string; /** Present only when the executor reported it; plain numbers, passed through as-is. */
-  usage?: JsonValue;
-} | {
-  type: "request.error";
-  request: JsonValue;
-  error: JsonValue;
-} | {
-  type: "stream.chunk";
-  request: JsonValue;
-  chunk: string;
-} | {
-  type: "machine.transition";
-  snapshot: JsonValue;
-  event: JsonValue;
-  eventId?: string;
-} | {
-  type: "emit";
-  event: JsonValue;
-} | {
-  type: "usage.dropped";
-  event: JsonValue;
-  reason: "settled";
-} | {
-  type: "run.end";
-  status: "done";
-  output: JsonValue;
-  snapshot: JsonValue;
-} | {
-  type: "run.end";
-  status: "idle";
-  snapshot: JsonValue;
-  pendingUserInputs?: JsonValue;
-  persistedSnapshot?: JsonValue;
-} | {
-  type: "run.end";
-  status: "error";
-  cause: RunAgentErrorCause;
-  error: JsonValue;
-  snapshot: JsonValue;
-});
+type JsonSerializableTraceEvent = AgentTraceEvent extends infer TEvent ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
+declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "timestamp", "machineId", "machineVersion", "type", "status", "cause", "eventId", "reasoning", "chunk"];
 /**
  * Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
  * the form the trace stream is actually sold for (one `JSON.stringify` per line
@@ -624,8 +553,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). */
@@ -760,11 +696,21 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
    * with no extra wiring — read it with `getAgentMessages(snapshot)`.
    */
   messages?: AgentMessage[] | ((prior: AgentMessage[]) => AgentMessage[]);
-  /** Fires for each streamed chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest} that produced it (parallel states can interleave multiple streams). Purely observational. */
+  /**
+   * Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
+   * chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
+   * that produced it (parallel states can interleave multiple streams). Purely
+   * observational.
+   */
   onChunk?: (chunk: string, info: {
     request: AgentRequest;
   }) => void;
-  /** Fires once per resolved text/decision request with its normalized output and the raw executor result (tool calls, usage, …) — the seam for tracing/observability and event-sourced replay logging. */
+  /**
+   * Sugar over {@link onTrace}'s `request.end` events: fires once per resolved
+   * text/decision request with its normalized output and the raw executor
+   * result (tool calls, usage, …) — the seam for tracing/observability and
+   * event-sourced replay logging.
+   */
   onResult?: (request: AgentStepRequest, result: {
     output: unknown;
     raw: unknown;
@@ -779,8 +725,9 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
   /** Fires a single ordered stream of run/request/chunk/transition/emit/end events. Intended for eval traces, JSONL logs, and adapter-owned telemetry/exporters. */
   onTrace?: (event: AgentTraceEvent<TMachine>) => void;
   /**
-   * Fires on every machine transition (snapshot + causing event). Pure
-   * observation — progress UIs, logging, tracing. Cannot send events.
+   * Sugar over {@link onTrace}'s `machine.transition` events: fires on every
+   * root-machine transition (snapshot + causing event). Pure observation —
+   * progress UIs, logging, tracing. Cannot send events.
    */
   onTransition?: (snapshot: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine>) => void;
   /**
@@ -901,6 +848,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`/
@@ -1061,4 +1022,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 { AgentEffectDiff as A, createReplayEntry as B, AgentStateRequest as C, AGENT_INIT_EVENT_TYPE as D, executeAgentRequest as E, AgentUsageEvent as F, replay as G, getAgentEffects as H, CreateReplayEntryOptions as I, verifyReplay as K, GetAgentEffectsOptions as L, AgentLogPatchOperation as M, AgentReplayDivergenceError as N, AGENT_USAGE_EVENT_TYPE as O, AgentReplayMachineMismatchError as P, ReplayOptions as R, traceTransitions as S, AgentStepRequest as T, getCallUsage as U, diffEventLogs as V, initEntry 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, AgentEventLogDiff as j, AgentEffect as k, AgentUserInputExecutor as l, RunAgentErrorCause as m, AgentActorSession as n, AgentRunMeta as o, PendingUserInput as p, AgentIdleError as r, AgentSnapshotVersionMismatchError as s, AGENT_TRACE_SCHEMA_VERSION as t, GenerateResult as u, generateResult as v, AgentRequest as w, serializeTraceEvent as x, inspectTransitions as y, ReplayResult as z };
+export { AgentEffect as A, ReplayResult as B, traceTransitions as C, executeAgentRequest as D, AgentStepRequest as E, AgentReplayMachineMismatchError as F, replay as G, diffEventLogs as H, AgentUsageEvent as I, verifyReplay 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, initEntry 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, 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 };