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

package/dist/otel.d.mts

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

package/dist/otel.mjs

@@ -32,23 +32,15 @@ function usageAttributes(usage) {
 	}
 	return attributes;
 }
-/** The model ref a request targets: text/plan carry it on `input`, a decision inline. */
+/** The model ref a request targets: text carries it on `input`, a decision inline. */
 function requestModel(request) {
 	const model = request.kind === "decision" ? request.model : request.input?.model;
 	return typeof model === "string" ? model : void 0;
 }
-/** The `src` a text/plan invoke was declared with; a decision has none. */
+/** The `src` a text invoke was declared with; a decision has none. */
 function requestSrc(request) {
 	return "src" in request && typeof request.src === "string" ? request.src : void 0;
 }
-/**
-* `gen_ai.operation.name` for a request. A plan request drives the machine
-* through a sequence of events, which semconv names `plan`; text and decision
-* requests are both single chat completions.
-*/
-function operationName(request) {
-	return request.kind === "plan" ? "plan" : "chat";
-}
 /** Best-effort JSON, never throws — content capture must not break a run. */
 function toJson(value) {
 	try {
@@ -161,10 +153,9 @@ function createOtelTraceHandler(options) {
 				const request = event.request;
 				endRequest(request.id, () => {});
 				const model = requestModel(request);
-				const operation = operationName(request);
 				const attributes = {
 					...baseAttributes,
-					"gen_ai.operation.name": operation,
+					"gen_ai.operation.name": "chat",
 					"agent.run_id": event.runId,
 					"agent.request_id": request.id,
 					"agent.request_kind": request.kind
@@ -181,9 +172,8 @@ function createOtelTraceHandler(options) {
 					const json = toJson(input.messages ?? input.prompt);
 					if (json !== void 0) attributes["gen_ai.input.messages"] = json;
 				}
-				const name = operation === "plan" ? `plan ${options.agentName ?? event.machineId}` : `chat ${model ?? request.kind}`;
-				const span = tracer.startSpan(name, {
-					kind: operation === "plan" ? SpanKind.INTERNAL : SpanKind.CLIENT,
+				const span = tracer.startSpan(`chat ${model ?? request.kind}`, {
+					kind: SpanKind.CLIENT,
 					attributes
 				}, runFor(event).context);
 				requests.set(request.id, {

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

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-_FXoFBGO.mjs";
+import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-9Bqg5rZB.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-C5kbjaDz.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
@@ -749,7 +701,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 +854,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;
@@ -1108,4 +1061,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 { 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 };

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

@@ -1,7 +1,7 @@
-import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-QbEfCVny.cjs";
+import { c as AgentTools, d as ChosenEvent, n as AgentMessage } from "./types-rMe7x6NR.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-Jkilp1Ie.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
@@ -749,7 +701,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 +854,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;
@@ -1108,4 +1061,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 { 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 };