@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/steps-CkyyyuHd.mjs

@@ -0,0 +1,379 @@
+import { E as getRegisteredAgentExecutionOptions, H as validateSchemaSync, _ as isTextLogic, a as sanitizeEventToolName, m as executeAgentTextRequest, t as getAcceptedEvents } from "./events-JiVPYrct.mjs";
+import { c as isPlanLogic, n as PLAN_DONE_EVENT_TYPE, r as advancePlanLedger, s as isDecisionLogic, u as resolveDecision } from "./decision-C3k4ve51.mjs";
+import { initialTransition, transition } from "xstate";
+//#region src/steps.ts
+/**
+* The step path: durable, per-model-call-checkpoint hosting of an agent
+* machine. Public vocabulary — `initialAgentStep`, `transitionAgentStep`,
+* `resolveAgentStep`, `getAgentRequests`, `executeAgentRequest`,
+* `resolveAgentRequests`.
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. The hand-passed-schemas
+* implementation detail behind the public {@link getAgentRequests} — it needs
+* `schemas`/`actorSources` passed explicitly, whereas `getAgentRequests`
+* pre-fills them from the machine's registered `setupAgent` options.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequestsWith(actions, options = {}) {
+	return [...actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actorSources?.[params.src];
+		if (isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	}), ...getActivePlanRequests(options)];
+}
+/**
+* Scans the live snapshot's children for active `agent.plan` (plan-logic)
+* invokes and lowers each into an {@link AgentPlanRequest} — the re-surfacing
+* half of plan discovery. Reads the applied-event trail and remaining budget
+* from the child's own ledger `context` ({@link PlanLedgerContext}), recomputes
+* the currently-legal candidates (∩ declared `allowedEvents`) plus the reserved
+* `agent.plan.done` move, and takes `stepsRemaining` from the ledger (falling
+* back to `maxSteps - applied.length` for a snapshot with no context yet).
+* Returns `[]` when no snapshot is available (candidates need a live snapshot).
+*
+* @internal
+*/
+function getActivePlanRequests(options) {
+	const snapshot = options.snapshot;
+	if (!snapshot) return [];
+	const children = snapshot.children;
+	if (!children) return [];
+	const requests = [];
+	for (const [id, child] of Object.entries(children)) {
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const src = typeof ref.src === "string" ? ref.src : void 0;
+		const logic = (src ? options.actorSources?.[src] : void 0) ?? ref.logic;
+		if (!isPlanLogic(logic)) continue;
+		const childSnapshot = ref.getSnapshot();
+		if (childSnapshot?.status !== "active") continue;
+		const input = childSnapshot.input ?? {};
+		const maxSteps = input.maxSteps ?? 8;
+		const ledger = childSnapshot.context ?? {};
+		const applied = ledger.applied ?? [];
+		const stepsRemaining = ledger.stepsRemaining ?? maxSteps - applied.length;
+		const machineEvents = getAcceptedEvents(snapshot, {
+			events: options.events,
+			schemas: options.schemas,
+			eventTypes: logic.allowedEventTypes(input) ?? void 0,
+			eventToolName: options.eventToolName
+		});
+		const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, {
+			type: PLAN_DONE_EVENT_TYPE,
+			toolName: sanitizeEventToolName(PLAN_DONE_EVENT_TYPE)
+		}];
+		requests.push({
+			kind: "plan",
+			id,
+			src: src ?? "",
+			input,
+			events,
+			applied,
+			stepsRemaining: Math.max(0, stepsRemaining)
+		});
+	}
+	return requests;
+}
+/**
+* Builds the synthetic `xstate.done.actor.<id>` event xstate's `transition()`
+* expects to resolve a spawned invoke — the event {@link resolveAgentStep}
+* applies internally.
+*
+* @internal
+*/
+function doneEvent(request, output) {
+	return {
+		type: `xstate.done.actor.${typeof request === "string" ? request : request.id}`,
+		output
+	};
+}
+/**
+* Applies a request's `output` as a done event via `transition(...)`,
+* returning the raw `[snapshot, actions]` tuple. Lower-level than
+* {@link resolveAgentStep} — that helper wraps this and also runs
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output) {
+	const event = doneEvent(request, output);
+	const result = transition(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = initialTransition(machine, input);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = transition(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Snapshot in, requests out: scans executable actions for spawned agent
+* invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+* the machine's registered `setupAgent` schemas/actorSources (so callers
+* don't pass them by hand each call) — merged with any `options` passed here,
+* which take precedence. The step path's public discovery primitive;
+* `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+* internally to populate `AgentStep.requests`.
+*/
+function getAgentRequests(machine, actions, snapshot, options = {}) {
+	return getAgentRequestsWith(actions, {
+		...getRegisteredAgentExecutionOptions(machine, options),
+		...options,
+		snapshot
+	});
+}
+async function executeAgentRequest(request, executors, options) {
+	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	assertTextExecutor(request, executors);
+	const { output, raw } = await executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	const normalizedOutput = request.input.outputSchema ? validateSchemaSync(request.input.outputSchema, output) : output;
+	return options?.verbose ? {
+		output: normalizedOutput,
+		raw
+	} : normalizedOutput;
+}
+/**
+* Resolves the current step's pending requests and returns the next
+* {@link AgentStep} — one iteration of the durable step loop, collapsing the
+* manual `request.kind` dispatch a host would otherwise write by hand.
+*
+* For each pending request, in order: a `kind: 'text'` request is run with
+* {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+* `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+* `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+* applied with {@link transitionAgentStep}. The **current** step is re-read
+* after each application — the machine may advance and its `requests` change —
+* so this always resolves against the live step, never a stale list.
+*
+* A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+* step per call. It resolves a single decision from `request.events` (wiring
+* `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+* move and `stopOn` events), then either applies the chosen machine event and
+* lets the next step re-surface the plan, or completes the plan (feeding its
+* `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+* exhausted budget / no legal events. The plan's applied trail is carried in
+* the invoke child's snapshot, so persisting the step between calls resumes the
+* plan identically.
+*
+* Missing the executor a request needs throws a clear error
+* (`generateText`/`streamText` for text, `decide` for decisions and plans).
+*
+* A complete durable host is two lines:
+*
+* ```ts
+* let step = initialAgentStep(machine, input);
+* while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+* ```
+*
+* All pending **text** requests of a step are resolved in parallel
+* (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+* their model calls run concurrently — then their outputs apply in
+* **request-array order** (deterministic for durable replay regardless of which
+* call finishes first). Decisions and plans stay **one at a time**: applying
+* either changes the set of legal candidates for what follows, so they cannot be
+* resolved against a stale snapshot. A host that instead wants strictly
+* sequential text resolution loops the manual per-request helpers
+* ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+*/
+async function resolveAgentRequests(machine, step, executors, options) {
+	const [request] = step.requests;
+	if (!request) return step;
+	if (request.kind === "decision") {
+		if (!executors.decide) throw new Error(`this step's decision request '${request.id}' needs a 'decide' executor but none was provided.`);
+		return transitionAgentStep(machine, step, await resolveDecision(request, executors.decide, {
+			canTake: (event) => step.snapshot.can(event),
+			maxRetries: options?.maxRetries
+		}), options);
+	}
+	if (request.kind === "plan") return resolvePlanRequest(machine, step, request, executors, options);
+	const textRequests = step.requests.filter((candidate) => candidate.kind === "text");
+	for (const textRequest of textRequests) assertTextExecutor(textRequest, executors);
+	const outputs = await Promise.all(textRequests.map((textRequest) => executeAgentRequest(textRequest, executors)));
+	let next = step;
+	for (let index = 0; index < textRequests.length; index++) next = resolveAgentStep(machine, next, textRequests[index], outputs[index], options);
+	return next;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+async function resolvePlanRequest(machine, step, request, executors, options) {
+	if (!executors.decide) throw new Error(`this step's plan request '${request.src}' needs a 'decide' executor but none was provided.`);
+	const stopOn = new Set(request.input.stopOn ?? []);
+	if (request.stepsRemaining <= 0) return completePlan(machine, step, request.id, request.applied, "max-steps", options);
+	if (request.events.filter((event) => event.type !== "agent.plan.done").length === 0) return completePlan(machine, step, request.id, request.applied, "no-legal-events", options);
+	const chosen = await resolveDecision(planStepDecisionRequest(request), executors.decide, {
+		maxRetries: options?.maxRetries,
+		canTake: (event) => {
+			if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+			return step.snapshot.can(event);
+		}
+	});
+	if (chosen.type === "agent.plan.done") return completePlan(machine, step, request.id, request.applied, "done", options);
+	const applied = [...request.applied, chosen];
+	advancePlanChildLedger(step.snapshot, request.id, {
+		type: "plan.applied",
+		event: chosen
+	});
+	const next = transitionAgentStep(machine, step, chosen, options);
+	if (stopOn.has(chosen.type)) {
+		if (isPlanActive(next.snapshot, request.id)) return completePlan(machine, next, request.id, applied, "stop-event", options);
+	}
+	return next;
+}
+function completePlan(machine, step, id, steps, stopped, options) {
+	return resolveAgentStep(machine, step, { id }, {
+		steps,
+		stopped
+	}, options);
+}
+function planStepDecisionRequest(request) {
+	const { input, applied, events, id } = request;
+	const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+	const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${PLAN_DONE_EVENT_TYPE}'.`;
+	return {
+		kind: "decision",
+		id: `${id}[${applied.length}]`,
+		model: input.model,
+		system: input.system,
+		prompt: `${input.prompt ?? ""}${trail}${doneHint}`,
+		messages: input.messages,
+		events,
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function advancePlanChildLedger(snapshot, id, event) {
+	const child = snapshot.children?.[id];
+	const childSnapshot = child?.getSnapshot?.();
+	if (!isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
+	Object.assign(childSnapshot, advancePlanLedger(child.logic, childSnapshot, event));
+}
+function isPlanActive(snapshot, id) {
+	return (snapshot.children?.[id])?.getSnapshot?.()?.status === "active";
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequestsWith(actions, {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+export { resolveAgentRequests as a, initialAgentStep as i, getAgentRequests as n, resolveAgentStep as o, getInvokeEffectMetadata as r, transitionAgentStep as s, executeAgentRequest as t };

package/dist/steps-MjnQI4aB.d.cts

@@ -0,0 +1,198 @@
+import { m as ChosenEvent, u as AgentTools } from "./types-C9QiMjre.cjs";
+import { G as AgentRequestOptions, K as AgentRequestSource, M as AgentPlanInput, U as AgentEventDescriptor, c as AgentRequestMode, j as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-Ckhr2kKC.cjs";
+import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, SnapshotFrom } from "xstate";
+
+//#region src/internal/registry.d.ts
+type AgentExecutionOptions = Pick<AgentRequestOptions, "schemas" | "actorSources"> & {
+  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.<id>`).
+ */
+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;
+/**
+ * One durable checkpoint on the step path: the machine's current snapshot,
+ * the executable actions that produced it, the pending
+ * {@link AgentStepRequest}s (text/decision work still to resolve), and
+ * whether the machine has reached a final state. This is the
+ * per-model-call-checkpoint path for durable hosts (Workflows, Temporal,
+ * queues, …) — a peer of `runAgent`, not a lesser version of it. Produced by
+ * {@link initialAgentStep}/{@link transitionAgentStep}/{@link resolveAgentStep}.
+ */
+interface AgentStep<TSnapshot extends AnyMachineSnapshot = AnyMachineSnapshot> {
+  snapshot: TSnapshot;
+  actions: readonly {
+    type?: string;
+    params?: unknown;
+  }[];
+  requests: AgentStepRequest[];
+  done: boolean;
+}
+/**
+ * Starts a machine and returns its first {@link AgentStep} — the step-path
+ * equivalent of `initialTransition` plus request discovery. Begins the
+ * durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+ * (via {@link executeAgentRequest} for `kind: 'text'`, or
+ * {@link resolveDecision} for `kind: 'decision'`), then advance with
+ * {@link resolveAgentStep} or {@link transitionAgentStep}.
+ */
+declare function initialAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, input?: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies an externally-sent event (e.g. a decision's chosen event, or a
+ * human's reply) and returns the next {@link AgentStep}. Accepts **either**
+ * a raw snapshot **or** a prior `AgentStep` as the second argument —
+ * `.snapshot` is unwrapped automatically, so callers can thread the whole
+ * step object through without manually plucking the snapshot out.
+ */
+declare function transitionAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, snapshotOrStep: SnapshotFrom<TMachine> | AgentStep<SnapshotFrom<TMachine>>, event: EventFromLogic<TMachine>, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Applies a resolved text request's output (a `kind: 'text'`
+ * {@link AgentRequest} — not a decision) as a done event and returns the
+ * next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+ * (which returns a {@link ChosenEvent}) and apply it with
+ * {@link transitionAgentStep} instead — a decision has no output value of
+ * its own to feed here.
+ */
+declare function resolveAgentStep<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, request: Pick<AgentRequest, "id"> | string, output: unknown, options?: Partial<AgentExecutionOptions>): AgentStep<SnapshotFrom<TMachine>>;
+/**
+ * Snapshot in, requests out: scans executable actions for spawned agent
+ * invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+ * the machine's registered `setupAgent` schemas/actorSources (so callers
+ * don't pass them by hand each call) — merged with any `options` passed here,
+ * which take precedence. The step path's public discovery primitive;
+ * `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+ * internally to populate `AgentStep.requests`.
+ */
+declare function getAgentRequests(machine: AnyActorLogic, actions: readonly {
+  type?: string;
+  params?: unknown;
+}[], snapshot?: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "eventToolName"> & Partial<AgentExecutionOptions>): AgentStepRequest[];
+/**
+ * Resolves one **text** {@link AgentRequest} against a host's
+ * {@link AgentRequestExecutors} — merges the request's tools, dispatches to
+ * `generateText`/`streamText` per `request.mode`, and validates the result
+ * against `request.input.outputSchema` if present. **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).
+ */
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>): Promise<unknown>;
+declare function executeAgentRequest(request: AgentRequest, executors: Partial<AgentRequestExecutors>, options: {
+  verbose: true;
+}): Promise<{
+  output: unknown;
+  raw: unknown;
+}>;
+/**
+ * Options for {@link resolveAgentRequests}.
+ */
+interface ResolveAgentRequestsOptions extends Partial<AgentExecutionOptions> {
+  /** Retries per decision, passed to `resolveDecision`. Default `2`. */
+  maxRetries?: number;
+}
+/**
+ * Resolves the current step's pending requests and returns the next
+ * {@link AgentStep} — one iteration of the durable step loop, collapsing the
+ * manual `request.kind` dispatch a host would otherwise write by hand.
+ *
+ * For each pending request, in order: a `kind: 'text'` request is run with
+ * {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+ * `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+ * `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+ * applied with {@link transitionAgentStep}. The **current** step is re-read
+ * after each application — the machine may advance and its `requests` change —
+ * so this always resolves against the live step, never a stale list.
+ *
+ * A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+ * step per call. It resolves a single decision from `request.events` (wiring
+ * `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+ * move and `stopOn` events), then either applies the chosen machine event and
+ * lets the next step re-surface the plan, or completes the plan (feeding its
+ * `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+ * exhausted budget / no legal events. The plan's applied trail is carried in
+ * the invoke child's snapshot, so persisting the step between calls resumes the
+ * plan identically.
+ *
+ * Missing the executor a request needs throws a clear error
+ * (`generateText`/`streamText` for text, `decide` for decisions and plans).
+ *
+ * A complete durable host is two lines:
+ *
+ * ```ts
+ * let step = initialAgentStep(machine, input);
+ * while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+ * ```
+ *
+ * All pending **text** requests of a step are resolved in parallel
+ * (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+ * their model calls run concurrently — then their outputs apply in
+ * **request-array order** (deterministic for durable replay regardless of which
+ * call finishes first). Decisions and plans stay **one at a time**: applying
+ * either changes the set of legal candidates for what follows, so they cannot be
+ * resolved against a stale snapshot. A host that instead wants strictly
+ * sequential text resolution loops the manual per-request helpers
+ * ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+ */
+declare function resolveAgentRequests<TMachine extends AnyActorLogic>(machine: TMachine, step: AgentStep<SnapshotFrom<TMachine>>, executors: Partial<AgentRequestExecutors>, options?: ResolveAgentRequestsOptions): Promise<AgentStep<SnapshotFrom<TMachine>>>;
+//#endregion
+export { ResolveAgentRequestsOptions as a, initialAgentStep as c, transitionAgentStep as d, AgentStepRequest as i, resolveAgentRequests as l, AgentRequest as n, executeAgentRequest as o, AgentStep as r, getAgentRequests as s, AgentPlanRequest as t, resolveAgentStep as u };

package/dist/steps.cjs

@@ -0,0 +1,12 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_decision = require("./decision-D8wJrM8W.cjs");
+const require_steps = require("./steps-CVe54GPP.cjs");
+exports.PLAN_DONE_EVENT_TYPE = require_decision.PLAN_DONE_EVENT_TYPE;
+exports.executeAgentRequest = require_steps.executeAgentRequest;
+exports.getAgentRequests = require_steps.getAgentRequests;
+exports.initialAgentStep = require_steps.initialAgentStep;
+exports.renderDecisionAttempts = require_decision.renderDecisionAttempts;
+exports.resolveAgentRequests = require_steps.resolveAgentRequests;
+exports.resolveAgentStep = require_steps.resolveAgentStep;
+exports.resolveDecision = require_decision.resolveDecision;
+exports.transitionAgentStep = require_steps.transitionAgentStep;

package/dist/steps.d.cts

@@ -0,0 +1,3 @@
+import { B as ResolveDecisionOptions, H as resolveDecision, K as AgentRequestSource, L as DecisionLogicConfig, P as DecisionAttempt, R as PLAN_DONE_EVENT_TYPE, U as AgentEventDescriptor, V as renderDecisionAttempts, j as AgentDecisionRequest, k as AgentDecisionExecutor } from "./text-logic-Ckhr2kKC.cjs";
+import { a as ResolveAgentRequestsOptions, c as initialAgentStep, d as transitionAgentStep, i as AgentStepRequest, l as resolveAgentRequests, n as AgentRequest, o as executeAgentRequest, r as AgentStep, s as getAgentRequests, t as AgentPlanRequest, u as resolveAgentStep } from "./steps-MjnQI4aB.cjs";
+export { type AgentDecisionExecutor, type AgentDecisionRequest, type AgentEventDescriptor, type AgentPlanRequest, type AgentRequest, type AgentRequestSource, type AgentStep, type AgentStepRequest, type DecisionAttempt, type DecisionLogicConfig, PLAN_DONE_EVENT_TYPE, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, executeAgentRequest, getAgentRequests, initialAgentStep, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, transitionAgentStep };

package/dist/steps.d.mts

@@ -0,0 +1,3 @@
+import { B as ResolveDecisionOptions, H as resolveDecision, K as AgentRequestSource, L as DecisionLogicConfig, P as DecisionAttempt, R as PLAN_DONE_EVENT_TYPE, U as AgentEventDescriptor, V as renderDecisionAttempts, j as AgentDecisionRequest, k as AgentDecisionExecutor } from "./text-logic-CaKqgX4Y.mjs";
+import { a as ResolveAgentRequestsOptions, c as initialAgentStep, d as transitionAgentStep, i as AgentStepRequest, l as resolveAgentRequests, n as AgentRequest, o as executeAgentRequest, r as AgentStep, s as getAgentRequests, t as AgentPlanRequest, u as resolveAgentStep } from "./steps-BALp1eZo.mjs";
+export { type AgentDecisionExecutor, type AgentDecisionRequest, type AgentEventDescriptor, type AgentPlanRequest, type AgentRequest, type AgentRequestSource, type AgentStep, type AgentStepRequest, type DecisionAttempt, type DecisionLogicConfig, PLAN_DONE_EVENT_TYPE, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, executeAgentRequest, getAgentRequests, initialAgentStep, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, transitionAgentStep };

package/dist/steps.mjs

@@ -0,0 +1,3 @@
+import { l as renderDecisionAttempts, n as PLAN_DONE_EVENT_TYPE, u as resolveDecision } from "./decision-C3k4ve51.mjs";
+import { a as resolveAgentRequests, i as initialAgentStep, n as getAgentRequests, o as resolveAgentStep, s as transitionAgentStep, t as executeAgentRequest } from "./steps-CkyyyuHd.mjs";
+export { PLAN_DONE_EVENT_TYPE, executeAgentRequest, getAgentRequests, initialAgentStep, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, transitionAgentStep };