@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.12

package/dist/ai-sdk.cjs

@@ -1,6 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_events = require("./events-CRQj3VtP.cjs");
-const require_decision = require("./decision-D8wJrM8W.cjs");
+const require_decision = require("./decision-dWGhBh0P.cjs");
 let ai = require("ai");
 //#region src/ai-sdk/mappers.ts
 /**
@@ -24,7 +23,7 @@ function toAiSdkTools(tools) {
 			})]);
 			continue;
 		}
-		if (require_events.isStandardSchema(descriptor.inputSchema)) {
+		if (require_decision.isStandardSchema(descriptor.inputSchema)) {
 			entries.push([name, descriptor]);
 			continue;
 		}
@@ -80,7 +79,7 @@ function toAiSdkToolChoice(toolChoice) {
 }
 /** `true` when the request should use AI SDK structured `Output.object`. */
 function isStructuredOutputRequest(request) {
-	return require_events.getAgentOutputMode(request.outputSchema) === "structured";
+	return require_decision.getAgentOutputMode(request.outputSchema) === "structured";
 }
 /**
 * Extracts the first complete top-level JSON value from `text`, or returns
@@ -214,7 +213,7 @@ function createAiSdkExecutors(options) {
 			...maxStepsSetting(request)
 		};
 		if (isStructuredOutputRequest(request)) {
-			const envelope = require_events.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
+			const envelope = require_decision.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
 			const structuredOutput = withJsonRepair(ai.Output.object({ schema: envelope }));
 			const canRetry = !request.tools || Object.keys(request.tools).length === 0;
 			let result;

package/dist/ai-sdk.d.cts

@@ -1,5 +1,5 @@
-import { m as ChosenEvent } from "./types-C9QiMjre.cjs";
-import { i as AgentRequestExecutor, k as AgentDecisionExecutor, s as AgentRequestExecutors } from "./text-logic-Ckhr2kKC.cjs";
+import { d as ChosenEvent } from "./types-QbEfCVny.cjs";
+import { O as AgentDecisionExecutor, a as AgentRequestExecutor, c as AgentRequestExecutors } from "./text-logic-CorGzucG.cjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts
@@ -52,6 +52,9 @@ type AiSdkGenerateResult = {
    * `reasoning: true` and the model produced it (see the structured-output
    * envelope in {@link buildEnvelopeSchema}). Never enters machine context/output. */
   reasoning?: string;
+  /** The call's token usage. Its flat `inputTokens`/`outputTokens`/`totalTokens`/
+   * `reasoningTokens`/`cachedInputTokens` fields are what `runAgent` folds into
+   * the run result's aggregated `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
   toolCalls: TypedToolCall<ToolSet>[];
@@ -59,13 +62,13 @@ type AiSdkGenerateResult = {
 };
 /** Raw result shape from {@link AiSdkExecutors.streamText} — the `{ output }` envelope carrying the fully-accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata for `onResult`. */
 type AiSdkStreamResult = {
-  output: string;
+  output: string; /** The stream's final (awaited) usage; aggregated into the run result's `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
 };
 /** Raw result shape from {@link AiSdkExecutors.decide} — the chosen event plus the AI SDK call metadata, delivered per decision attempt to `onResult`. */
 type AiSdkDecideResult = {
-  event: ChosenEvent;
+  event: ChosenEvent; /** This attempt's usage; aggregated into the run result's `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
 };

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
-import { m as ChosenEvent } from "./types-qm00QF91.mjs";
-import { i as AgentRequestExecutor, k as AgentDecisionExecutor, s as AgentRequestExecutors } from "./text-logic-CaKqgX4Y.mjs";
+import { d as ChosenEvent } from "./types-_FXoFBGO.mjs";
+import { O as AgentDecisionExecutor, a as AgentRequestExecutor, c as AgentRequestExecutors } from "./text-logic-DjR5PUVz.mjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts
@@ -52,6 +52,9 @@ type AiSdkGenerateResult = {
    * `reasoning: true` and the model produced it (see the structured-output
    * envelope in {@link buildEnvelopeSchema}). Never enters machine context/output. */
   reasoning?: string;
+  /** The call's token usage. Its flat `inputTokens`/`outputTokens`/`totalTokens`/
+   * `reasoningTokens`/`cachedInputTokens` fields are what `runAgent` folds into
+   * the run result's aggregated `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
   toolCalls: TypedToolCall<ToolSet>[];
@@ -59,13 +62,13 @@ type AiSdkGenerateResult = {
 };
 /** Raw result shape from {@link AiSdkExecutors.streamText} — the `{ output }` envelope carrying the fully-accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata for `onResult`. */
 type AiSdkStreamResult = {
-  output: string;
+  output: string; /** The stream's final (awaited) usage; aggregated into the run result's `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
 };
 /** Raw result shape from {@link AiSdkExecutors.decide} — the chosen event plus the AI SDK call metadata, delivered per decision attempt to `onResult`. */
 type AiSdkDecideResult = {
-  event: ChosenEvent;
+  event: ChosenEvent; /** This attempt's usage; aggregated into the run result's `AgentUsage`. */
   usage: LanguageModelUsage;
   finishReason: FinishReason;
 };

package/dist/ai-sdk.mjs

@@ -1,5 +1,4 @@
-import { L as isStandardSchema, d as buildEnvelopeSchema, h as getAgentOutputMode } from "./events-JiVPYrct.mjs";
-import { l as renderDecisionAttempts } from "./decision-C3k4ve51.mjs";
+import { J as isStandardSchema, T as getAgentOutputMode, b as buildEnvelopeSchema, l as renderDecisionAttempts } from "./decision-BezSD_YC.mjs";
 import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
 //#region src/ai-sdk/mappers.ts
 /**

package/dist/{events-JiVPYrct.mjs → decision-BezSD_YC.mjs}

@@ -1,4 +1,5 @@
-import { createAsyncLogic, getNextTransitions } from "xstate";
+import { t as AgentError } from "./errors-CeSXQx0v.mjs";
+import { createAsyncLogic, createLogic, getNextTransitions } from "xstate";
 //#region src/utils.ts
 /**
 * Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
@@ -174,8 +175,7 @@ function getAgentMessages(snapshot) {
 * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
 * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
 * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
-* can't read directly — see the `ai-sdk` tool pass-through and `openai-compat`
-* tool serialization.
+* can't read directly — see the `ai-sdk` tool pass-through.
 */
 function isStandardSchema(value) {
 	return typeof value === "object" && value !== null && "~standard" in value;
@@ -236,6 +236,24 @@ function getMachineSuspensionPredicate(machine) {
 	const config = machine.config;
 	return config ? machineSuspensionPredicates.get(config) : void 0;
 }
+/**
+* Lint-reachability sidecar for `fromConfig` machines.
+*
+* Static transition targets declared by the source config of a
+* `setupAgent.fromConfig` machine, as `dotted state path → declared target
+* strings` (every `on`/`always`/`after`/`onDone`/`choice` target plus each
+* invoke's `onDone`/`onError`). The JSON layer folds a transition that carries a
+* context patch into an opaque resolver function, erasing its target from
+* `machine.config` — so `lintAgentMachine`'s reachability walk reads the
+* targets from here instead. Keyed on the machine's root `config` object (like
+* {@link machineSuspensionPredicates}) so it survives `machine.provide(...)`.
+*/
+const machineStaticTransitionTargets = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineStaticTransitionTargets} map carried by `machine` (via its root `config`), if any. */
+function getMachineStaticTransitionTargets(machine) {
+	const config = machine.config;
+	return config ? machineStaticTransitionTargets.get(config) : void 0;
+}
 const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
 /** Text/decision logics created WITH their own executor (withExecutor or the
 * factory's second arg) — these are runnable as-is, so runAgent's bind check
@@ -243,7 +261,7 @@ const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
 const executorBoundLogics = /* @__PURE__ */ new WeakSet();
 function missingActor(src) {
 	const logic = createAsyncLogic({ run: async () => {
-		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }).`);
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }).`);
 	} });
 	unboundPlaceholderLogics.add(logic);
 	return logic;
@@ -287,6 +305,33 @@ function parseModelRef(modelRef) {
 		modelId: modelRef.slice(slash + 1)
 	};
 }
+/** The token fields {@link AgentUsage} aggregates. @internal */
+const AGENT_USAGE_TOKEN_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"totalTokens",
+	"reasoningTokens",
+	"cachedInputTokens"
+];
+/**
+* Reads a per-call {@link AgentCallUsage} off a raw executor result's `usage`
+* field, keeping only finite numbers. Returns `undefined` when the result
+* reports no usage at all. Works for our `{ output, usage }` envelope, for a
+* raw Vercel AI SDK result (its `LanguageModelUsage` carries the same flat
+* field names), and for any custom executor that follows the shape.
+*
+* @internal
+*/
+function extractCallUsage(raw) {
+	const usage = raw?.usage;
+	if (!usage || typeof usage !== "object") return;
+	let out;
+	for (const field of AGENT_USAGE_TOKEN_FIELDS) {
+		const value = usage[field];
+		if (typeof value === "number" && Number.isFinite(value)) (out ??= {})[field] = value;
+	}
+	return out;
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -314,9 +359,16 @@ const stringOutputSchema = { "~standard": {
 		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
 	}
 } };
+const noInputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return { value };
+	}
+} };
 function createBuiltinTextActor(src, mode, outputSchema) {
 	const logic = createAsyncLogic({ run: async () => {
-		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
 	} });
 	return Object.assign(logic, {
 		kind: "statelyai.textLogic",
@@ -365,7 +417,7 @@ const builtinTextActors = {
 };
 /** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). Output is `string` — what the human typed. @internal */
 const userInputActor = createAsyncLogic({ run: async () => {
-	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${USER_INPUT_ACTOR}': ... } }).`);
+	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actors: { '${USER_INPUT_ACTOR}': ... } }).`);
 } });
 unboundPlaceholderLogics.add(userInputActor);
 /**
@@ -384,7 +436,7 @@ function resolveTextLogicValue(value, args) {
 /**
 * Creates reusable, standalone {@link TextLogic}: an actor that, when run,
 * resolves typed input to typed output via a model call. Register the
-* result under `actorSources:` and invoke it by name (equivalent to what
+* result under `actors:` and invoke it by name (equivalent to what
 * `setupAgent({ requests })` builds internally for each request entry). Pass
 * `execute` here, or bind it later with `.withExecutor(...)`, a runtime
 * adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
@@ -402,8 +454,12 @@ function resolveTextLogicValue(value, args) {
 * ```
 */
 function createTextLogic(config, execute) {
+	const schemas = {
+		input: config.schemas?.input ?? noInputSchema,
+		output: config.schemas?.output ?? stringOutputSchema
+	};
 	const request = (input) => {
-		const args = { input: validateSchemaSync(config.schemas.input, input) };
+		const args = { input: validateSchemaSync(schemas.input, input) };
 		return {
 			name: resolveTextLogicValue(config.name, args),
 			model: resolveTextLogicValue(config.model, args),
@@ -412,7 +468,7 @@ function createTextLogic(config, execute) {
 			messages: resolveTextLogicValue(config.messages, args),
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
-			outputSchema: config.schemas.output,
+			outputSchema: schemas.output,
 			reasoning: resolveTextLogicValue(config.reasoning, args),
 			temperature: resolveTextLogicValue(config.temperature, args),
 			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
@@ -425,7 +481,7 @@ function createTextLogic(config, execute) {
 	};
 	const logic = createAsyncLogic({ run: async ({ input, signal, system, self }, enq) => {
 		const resolvedRequest = request(input);
-		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or extract it with getAgentRequests(..., { actorSources }).");
+		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or extract it with getAgentEffects(..., { actors }).");
 		const result = await execute({
 			input,
 			request: resolvedRequest,
@@ -436,16 +492,16 @@ function createTextLogic(config, execute) {
 		});
 		const selfId = self?.id;
 		const output = await normalizeGeneratorResult(result, typeof selfId === "string" ? selfId : "text logic", { request: resolvedRequest });
-		return validateSchemaSync(config.schemas.output, output);
+		return validateSchemaSync(schemas.output, output);
 	} });
 	const textLogic = Object.assign(logic, {
 		kind: "statelyai.textLogic",
 		mode: config.mode ?? "generate",
-		schemas: config.schemas,
+		schemas,
 		request,
 		async execute(input, executors) {
 			const { output } = await executeAgentTextRequest(config.mode ?? "generate", "textLogic", request(input), executors);
-			return validateSchemaSync(config.schemas.output, output);
+			return validateSchemaSync(schemas.output, output);
 		},
 		withExecutor(nextExecute) {
 			return createTextLogic(config, nextExecute);
@@ -465,7 +521,7 @@ function createTextLogic(config, execute) {
 * @example
 * ```ts
 * childMachine.provide({
-*   actorSources: {
+*   actors: {
 *     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
 *   },
 * });
@@ -503,10 +559,6 @@ function getAgentOutputMode(schema) {
 	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
 	return "text";
 }
-/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
-function isStructuredOutputSchema(schema) {
-	return getAgentOutputMode(schema) === "structured";
-}
 /**
 * Builds the uniform structured-output envelope schema every structured request
 * is sent to the provider as: a root object `{ result: <inner> }`, plus — when
@@ -692,6 +744,18 @@ function matchesEventPattern(eventType, pattern) {
 	if (pattern.endsWith(".*")) return eventType.startsWith(`${pattern.slice(0, -1)}`);
 	return eventType === pattern;
 }
+/**
+* The namespace reserved for events the library itself delivers to a machine
+* (`@agent.init`, `@agent.usage`). A machine may declare transitions on them,
+* but they are never model-facing: {@link getAcceptedEvents} drops them before
+* any `allowedEvents` matching, so they cannot be offered as a decision
+* candidate (not even under a `'*'` wildcard) and {@link parseAgentEvent}
+* rejects them — a model or a wire message must not be able to forge one.
+* Matched as a prefix rather than a list so this module stays free of an import
+* cycle back to `effects.ts`, where the constants live.
+* @internal
+*/
+const RESERVED_AGENT_EVENT_PREFIX = "@agent.";
 /** True when an `allowedEvents` entry is a wildcard pattern rather than a concrete event type. @internal */
 function isEventPattern(entry) {
 	return entry === "*" || entry.endsWith(".*");
@@ -734,13 +798,29 @@ function parseAgentEvent(snapshot, event, options = {}) {
 	}
 	return event;
 }
+/**
+* Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
+* a model can be offered (via `resolveDecision`/an adapter's tool-per-event
+* mapping). **Filters by event TYPE only** — it does not evaluate guards, so
+* a type-legal-but-guard-rejected event can still appear here. Guard
+* legality is checked separately, at decision-resolution time, via
+* `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
+* {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
+* declared `allowedEvents` set — entries may be exact types or wildcard
+* patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
+*
+* XState-internal (`xstate.*`) and library-reserved
+* ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
+* any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
+* never offers it to a model.
+*/
 function getAcceptedEvents(snapshot, options = {}) {
 	const eventTypes = options.eventTypes;
 	const seen = /* @__PURE__ */ new Set();
 	const usedToolNames = /* @__PURE__ */ new Set();
 	return getNextTransitions(snapshot).flatMap((transitionDefinition) => {
 		const eventType = transitionDefinition.eventType;
-		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
+		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || eventType.startsWith(RESERVED_AGENT_EVENT_PREFIX) || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
 		seen.add(eventType);
 		const defaultToolName = sanitizeEventToolName(eventType);
 		const toolName = options.eventToolName ? options.eventToolName({
@@ -756,4 +836,231 @@ function getAcceptedEvents(snapshot, options = {}) {
 	});
 }
 //#endregion
-export { assistantMessage as A, toolMessage as B, agentExecutionOptions as C, isUnboundPlaceholder as D, getRegisteredAgentExecutionOptions as E, getMachineStructuralHash as F, validateSchemaSync as H, getStateMeta as I, isStandardSchema as L, getAgentMessages as M, getJsonSchema as N, machineSuspensionPredicates as O, getJsonSchemaSync as P, persistSnapshot as R, userInputActor as S, getMachineSuspensionPredicate as T, userMessage as V, isTextLogic as _, sanitizeEventToolName as a, parseOutput as b, PLAN_ACTOR as c, buildEnvelopeSchema as d, builtinTextActors as f, isStructuredOutputSchema as g, getAgentOutputMode as h, parseAgentEvent as i, findNonSerializableContextPaths as j, missingActor as k, USER_INPUT_ACTOR as l, executeAgentTextRequest as m, isEventPattern as n, DECIDE_ACTOR as o, createTextLogic as p, matchesEventPattern as r, INTERPRET_SOURCE as s, getAcceptedEvents as t, bindRequestExecutor as u, normalizeGeneratorResult as v, executorBoundLogics as w, parseStructuredEnvelope as x, parseModelRef as y, systemMessage as z };
+//#region src/decision.ts
+function decideRequestFromInput(input) {
+	const allowedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input) ?? [];
+	return {
+		kind: "decision",
+		id: "",
+		model: input.model,
+		system: input.system,
+		prompt: input.prompt,
+		messages: input.messages,
+		events: allowedEventTypes.filter((type) => !isEventPattern(type)).map((type) => ({
+			type,
+			toolName: sanitizeEventToolName(type)
+		})),
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function decideActorWithExecutor(execute) {
+	const logic = createAsyncLogic({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error(`'${DECIDE_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actors: { '${DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		const resolvedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input);
+		if (resolvedEventTypes === void 0) throw new Error(`'${DECIDE_ACTOR}' input has omitted \`allowedEvents\`, which means "all currently-legal events" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare \`allowedEvents\` explicitly to use this actor here.`);
+		if (resolvedEventTypes.some(isEventPattern)) throw new Error(`'${DECIDE_ACTOR}' input uses wildcard \`allowedEvents\` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.`);
+		return resolveDecision(decideRequestFromInput(input), execute, {
+			maxRetries: input.maxRetries ?? 2,
+			signal
+		});
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input),
+		withExecutor: (nextExecute) => decideActorWithExecutor(nextExecute)
+	});
+}
+function createDecideActor() {
+	return decideActorWithExecutor();
+}
+/**
+* Reserved event type the `agent.plan` builtin adds to every step's
+* candidates as the explicit "no further action needed" move. Choosing it
+* ends the plan (`stopped: 'done'`); it is never sent to the machine, so
+* machines need no no-op sentinel event of their own.
+*/
+const PLAN_DONE_EVENT_TYPE = "agent.plan.done";
+function createPlanActor() {
+	const logic = createLogic({
+		context: ({ input }) => ({
+			applied: [],
+			stepsRemaining: input.maxSteps ?? 8,
+			stopped: null
+		}),
+		run: ({ context, event }) => event.type === "plan.applied" ? { context: {
+			...context,
+			applied: [...context.applied, event.event],
+			stepsRemaining: context.stepsRemaining - 1
+		} } : event.type === "plan.ended" ? {
+			context: {
+				...context,
+				stopped: event.stopped
+			},
+			status: "done",
+			output: {
+				steps: context.applied,
+				stopped: event.stopped
+			}
+		} : void 0
+	});
+	return Object.assign(logic, {
+		kind: "statelyai.planLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input)
+	});
+}
+const PLAN_LEDGER_SCOPE = {
+	emit: () => {},
+	self: { id: "agent.plan.ledger" }
+};
+/**
+* Builds a fresh plan ledger snapshot from resolved plan input — the shared
+* starting point for BOTH hosts (the step path reads the invoke child's own
+* initial snapshot; runAgent seeds a local ledger with this). @internal
+*/
+function initialPlanLedger(logic, input) {
+	return logic.getInitialSnapshot(PLAN_LEDGER_SCOPE, input);
+}
+/**
+* Advances a plan ledger by one {@link PlanLedgerEvent}, returning the next
+* snapshot (unwrapping `createLogic`'s `[snapshot, effects]` tuple). Pure — no
+* mutation of the input snapshot. @internal
+*/
+function advancePlanLedger(logic, snapshot, event) {
+	const result = logic.transition(snapshot, event, PLAN_LEDGER_SCOPE);
+	return Array.isArray(result) ? result[0] : result;
+}
+/** Type guard: true for the `agent.plan` builtin logic (checks the `kind` marker). @internal */
+function isPlanLogic(logic) {
+	return !!logic && logic.kind === "statelyai.planLogic";
+}
+function resolveAllowedEventTypes(allowedEvents, input) {
+	if (allowedEvents === void 0) return;
+	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
+	return typeof resolved === "string" ? [resolved] : resolved;
+}
+/** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
+function isDecisionLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
+}
+/**
+* Thrown by {@link resolveDecision} when every attempt (up to
+* `maxRetries + 1` of them) fails one of the three checks recorded in
+* {@link DecisionAttempt.failure}. Carries the full `attempts` list for
+* diagnostics; a machine typically routes this via the decision invoke's
+* `onError`.
+*/
+var AgentDecisionExhaustedError = class extends AgentError {
+	attempts;
+	constructor(attempts) {
+		super("decision-exhausted", `Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
+		this.name = "AgentDecisionExhaustedError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Renders a decision request's prior failed `attempts` into feedback messages
+* a host appends to the model call so retries converge — the transport-agnostic
+* "your last choice failed because X, choose again from Y" logic every adapter
+* and raw-SDK host repeats. Returns one `user`-role {@link AgentMessage} per
+* attempt (empty when there are none); adapters map each onto their wire
+* message shape (`attempt.content` is always a string). Core never rewrites the
+* request itself — this only turns the recorded attempts into messages.
+*
+* @example
+* ```ts
+* const messages = [...baseMessages, ...renderDecisionAttempts(request)];
+* ```
+*/
+function renderDecisionAttempts(request) {
+	const types = request.events.map((event) => event.type).join(", ") || "(none)";
+	return request.attempts.map((attempt) => userMessage(`Your previous choice failed: ${attempt.reason}. Choose again from: ${types}`));
+}
+/**
+* Validation + retry core for decisions. No provider mechanics — the
+* `executor` is responsible for making the model choose an event; this
+* function only validates the choice and retries on failure, up to
+* `options.maxRetries` (default 2, i.e. up to 3 attempts total).
+*
+* Each attempt is checked in order and can fail one of three ways (recorded
+* as a {@link DecisionAttempt}): `'unknown-event'` (the chosen `type` is not
+* among `request.events`), `'invalid-payload'` (the payload fails that
+* event's schema), or `'rejected-by-guard'` (passes both checks but
+* `options.canTake` returns `false` — a type/payload-legal event the
+* machine's guard rejects right now; omit `canTake` to skip this check).
+* Every prior failed attempt for this call is fed back to the executor on
+* the next attempt via `request.attempts`, so an adapter can render "your
+* last choice failed because X — try again" into the next model call; core
+* never rewrites the request itself. Exhausting all attempts throws
+* {@link AgentDecisionExhaustedError} with the full attempts list.
+*
+* @example
+* ```ts
+* const event = await resolveDecision(request, decide, {
+*   canTake: (e) => snapshot.can(e),
+* });
+* ```
+*/
+async function resolveDecision(request, executor, options = {}) {
+	const maxRetries = options.maxRetries ?? 2;
+	const attempts = [];
+	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		options.signal?.throwIfAborted();
+		const result = await executor({
+			...request,
+			attempts: [...attempts],
+			signal: options.signal
+		});
+		if (!result || typeof result !== "object" || typeof result.event !== "object" || result.event === null || typeof result.event.type !== "string") throw new Error(`decide executor must return { event: { type: string, ... } }; got ${JSON.stringify(result)}. Wrap the chosen event: return { event: { type: 'SAFE' } }.`);
+		const { event } = result;
+		const descriptor = eventsByType.get(event.type);
+		if (!descriptor) {
+			attempts.push({
+				event,
+				failure: "unknown-event",
+				reason: `'${event.type}' is not among the currently allowed events: ${request.events.map((candidate) => candidate.type).join(", ") || "(none)"}.`
+			});
+			continue;
+		}
+		let validatedEvent = event;
+		if (descriptor.inputSchema) {
+			const { type, ...payload } = event;
+			try {
+				validatedEvent = {
+					...validateSchemaSync(descriptor.inputSchema, payload),
+					type
+				};
+			} catch (error) {
+				attempts.push({
+					event,
+					failure: "invalid-payload",
+					reason: `'${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`
+				});
+				continue;
+			}
+		}
+		if (options.canTake?.(validatedEvent) === false) {
+			attempts.push({
+				event: validatedEvent,
+				failure: "rejected-by-guard",
+				reason: `'${validatedEvent.type}' is not currently takeable (guard rejected it).`
+			});
+			continue;
+		}
+		return validatedEvent;
+	}
+	throw new AgentDecisionExhaustedError(attempts);
+}
+//#endregion
+export { validateSchemaSync as $, parseStructuredEnvelope as A, missingActor as B, executeAgentTextRequest as C, normalizeGeneratorResult as D, isTextLogic as E, getMachineSuspensionPredicate as F, getJsonSchemaSync as G, findNonSerializableContextPaths as H, getRegisteredAgentExecutionOptions as I, isStandardSchema as J, getMachineStructuralHash as K, isUnboundPlaceholder as L, agentExecutionOptions as M, executorBoundLogics as N, parseModelRef as O, getMachineStaticTransitionTargets as P, userMessage as Q, machineStaticTransitionTargets as R, createTextLogic as S, getAgentOutputMode as T, getAgentMessages as U, assistantMessage as V, getJsonSchema as W, systemMessage as X, persistSnapshot as Y, toolMessage as Z, PLAN_ACTOR as _, createPlanActor as a, buildEnvelopeSchema as b, isPlanLogic as c, getAcceptedEvents as d, parseAgentEvent as f, INTERPRET_SOURCE as g, DECIDE_ACTOR as h, createDecideActor as i, userInputActor as j, parseOutput as k, renderDecisionAttempts as l, AGENT_USAGE_TOKEN_FIELDS as m, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, sanitizeEventToolName as p, getStateMeta as q, advancePlanLedger as r, isDecisionLogic as s, AgentDecisionExhaustedError as t, resolveDecision as u, USER_INPUT_ACTOR as v, extractCallUsage as w, builtinTextActors as x, bindRequestExecutor as y, machineSuspensionPredicates as z };