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

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-D_EyJ0Ik.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 { c as AgentTools, v as StandardSchemaV1 } from "./types-DFD28AWe.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 { c as AgentTools, v as StandardSchemaV1 } from "./types-CTBhMnFu.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-CTg57Pa4.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 { l as AgentTraceEvent } from "./run-agent-B_n4Qxye.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 { l as AgentTraceEvent } from "./run-agent-BWzo4FLv.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-B_n4Qxye.d.cts → run-agent-BxjGaVpL.d.cts}

@@ -1,7 +1,7 @@
-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 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-DZW7XWy9.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
@@ -767,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;
@@ -786,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;
   /**
@@ -1082,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 { 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 };
+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-BWzo4FLv.d.mts → run-agent-COHoCgQd.d.mts}

@@ -1,7 +1,7 @@
-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 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-C7anC7qX.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
@@ -767,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;
@@ -786,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;
   /**
@@ -1082,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 { 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 };
+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 };