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

package/dist/ai-sdk.mjs

@@ -1,7 +1,6 @@
-import { a as runAgent$1, c as setupAgent } from "./run-agent-BoAOq_0Z.mjs";
-import { J as isStandardSchema, L as getRegisteredAgentModels, T as getAgentOutputMode, l as renderDecisionAttempts, x as buildEnvelopeSchema } from "./decision-CQdrKc8k.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/index.ts
+//#region src/ai-sdk/mappers.ts
 /**
 * Maps an {@link AgentTools} map onto AI SDK `tool()` definitions. A tool that
 * already carries its own Standard Schema `inputSchema` — an AI SDK
@@ -10,8 +9,7 @@ import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText,
 * every extra property (`providerOptions`, `toModelOutput`, …) survives. A bare
 * `AgentToolExecute` function becomes a tool with an unconstrained input schema;
 * a minimal descriptor with no readable schema is converted with a permissive
-* fallback. Used internally by {@link toAiSdkCallSettings}; exported for callers
-* building AI SDK calls by hand outside `createAiSdkExecutors`.
+* fallback. Used by {@link toAiSdkCallSettings}.
 */
 function toAiSdkTools(tools) {
 	const entries = [];
@@ -44,9 +42,6 @@ function toAiSdkTools(tools) {
 	}
 	return Object.fromEntries(entries);
 }
-function maxStepsSetting(request) {
-	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: stepCountIs(request.metadata.maxSteps) } : {};
-}
 const unknownSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -54,35 +49,6 @@ const unknownSchema = { "~standard": {
 	jsonSchema: { input: () => ({}) }
 } };
 /**
-* Identity helper for a `models` map whose value is exported. Returns the map
-* unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
-* portable, nameable type — so an exported `const models = defineModels({...})`
-* needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
-* TS2742 ("inferred type cannot be named without a reference to …"). The exact
-* ref keys survive, so `createAiSdkExecutors({ models })` and
-* `setupAgent({ models })` still infer/autocomplete them.
-*
-* @example
-* ```ts
-* export const models = defineModels({
-*   quick: openai('gpt-5.4-mini'),
-*   deep: openai('gpt-5.4'),
-* });
-* // typeof models === AiSdkModelMap<'quick' | 'deep'>
-* ```
-*/
-function defineModels(models) {
-	return models;
-}
-function resolveAiSdkModel(options, modelRef) {
-	if (options.resolveModel) return options.resolveModel(modelRef);
-	const models = options.models;
-	if (!models) throw new Error(`createAiSdkExecutors: no model resolver configured for '${modelRef}'.`);
-	const model = models[modelRef];
-	if (!model) throw new Error(`createAiSdkExecutors: unknown model '${modelRef}'.`);
-	return model;
-}
-/**
 * AI SDK request-mapping settings shared by `generateText`/`streamText`.
 * `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
 * are structurally compatible by design (§1 of .scratch/p0-design.md) — the cast
@@ -147,6 +113,65 @@ function extractFirstJsonValue(text) {
 		}
 	}
 }
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+* toolChoice: 'required'" recipe from .scratch/p0-design.md §2.6. */
+function toAiSdkEventTools(events) {
+	return Object.fromEntries(events.map((event) => [event.toolName, tool({
+		description: `Choose the '${event.type}' move.`,
+		inputSchema: event.inputSchema ? event.inputSchema : unknownSchema
+	})]));
+}
+/**
+* Messages for a decision request, with prior failed `attempts` (§2.6)
+* rendered as appended user messages (via core's {@link renderDecisionAttempts})
+* so retries converge. Core never rewrites prompts — this is adapter business.
+*/
+function toDecisionMessages(request) {
+	if (!request.messages && request.attempts.length === 0) return;
+	const messages = [...request.messages ?? (request.prompt !== void 0 ? [{
+		role: "user",
+		content: request.prompt
+	}] : [])];
+	for (const attempt of renderDecisionAttempts(request)) messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return messages;
+}
+//#endregion
+//#region src/ai-sdk/index.ts
+function maxStepsSetting(request) {
+	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: stepCountIs(request.metadata.maxSteps) } : {};
+}
+/**
+* Identity helper for a `models` map whose value is exported. Returns the map
+* unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
+* portable, nameable type — so an exported `const models = defineModels({...})`
+* needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
+* TS2742 ("inferred type cannot be named without a reference to …"). The exact
+* ref keys survive, so `createAiSdkExecutors({ models })` and
+* `setupAgent({ models })` still infer/autocomplete them.
+*
+* @example
+* ```ts
+* export const models = defineModels({
+*   quick: openai('gpt-5.4-mini'),
+*   deep: openai('gpt-5.4'),
+* });
+* // typeof models === AiSdkModelMap<'quick' | 'deep'>
+* ```
+*/
+function defineModels(models) {
+	return models;
+}
+function resolveAiSdkModel(options, modelRef) {
+	if (options.resolveModel) return options.resolveModel(modelRef);
+	const models = options.models;
+	if (!models) throw new Error(`createAiSdkExecutors: no model resolver configured for '${modelRef}'.`);
+	const model = models[modelRef];
+	if (!model) throw new Error(`createAiSdkExecutors: unknown model '${modelRef}'.`);
+	return model;
+}
 function withJsonRepair(output) {
 	return {
 		...output,
@@ -274,58 +299,5 @@ function createAiSdkExecutors(options) {
 		decide
 	};
 }
-/** AI SDK host for a machine authored with `setupAgent({ models })`. */
-function runAgent(machine, options) {
-	const models = getRegisteredAgentModels(machine);
-	if (!models || Object.keys(models).length === 0) throw new Error("AI SDK runAgent: machine has no models. Pass `models` to setupAgent, or use core runAgent with explicit executors.");
-	return runAgent$1(machine, {
-		...options,
-		executors: createAiSdkExecutors({ models })
-	});
-}
-function createAgent(config) {
-	const { model, models: configuredModels, schemas, ...machineConfig } = config;
-	const models = configuredModels ?? { default: model };
-	const executors = createAiSdkExecutors({ models });
-	const machine = setupAgent({
-		...schemas,
-		models
-	}).createMachine(machineConfig);
-	return {
-		machine,
-		run(runInput, options = {}) {
-			return runAgent$1(machine, {
-				...options,
-				input: runInput,
-				executors
-			});
-		}
-	};
-}
-/** One AI SDK `tool()` per candidate event — the "tool-per-event +
-* toolChoice: 'required'" recipe from .scratch/p0-design.md §2.6. */
-function toAiSdkEventTools(events) {
-	return Object.fromEntries(events.map((event) => [event.toolName, tool({
-		description: `Choose the '${event.type}' move.`,
-		inputSchema: event.inputSchema ? event.inputSchema : unknownSchema
-	})]));
-}
-/**
-* Messages for a decision request, with prior failed `attempts` (§2.6)
-* rendered as appended user messages (via core's {@link renderDecisionAttempts})
-* so retries converge. Core never rewrites prompts — this is adapter business.
-*/
-function toDecisionMessages(request) {
-	if (!request.messages && request.attempts.length === 0) return;
-	const messages = [...request.messages ?? (request.prompt !== void 0 ? [{
-		role: "user",
-		content: request.prompt
-	}] : [])];
-	for (const attempt of renderDecisionAttempts(request)) messages.push({
-		role: "user",
-		content: attempt.content
-	});
-	return messages;
-}
 //#endregion
-export { createAgent, createAiSdkExecutors, defineModels, extractFirstJsonValue, isStructuredOutputRequest, runAgent, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };
+export { createAiSdkExecutors, defineModels };

package/dist/{decision-CQdrKc8k.mjs → decision-BezSD_YC.mjs}

@@ -1,3 +1,4 @@
+import { t as AgentError } from "./errors-CeSXQx0v.mjs";
 import { createAsyncLogic, createLogic, getNextTransitions } from "xstate";
 //#region src/utils.ts
 /**
@@ -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;
@@ -221,9 +221,6 @@ function validateSchemaSync(schema, value) {
 //#endregion
 //#region src/internal/registry.ts
 const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
-function getRegisteredAgentModels(machine) {
-	return agentExecutionOptions.get(machine)?.models;
-}
 /**
 * Machine-carried wait-state predicates, keyed on the machine's root `config`
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
@@ -239,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
@@ -246,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;
@@ -290,11 +305,44 @@ 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",
 	validate(value) {
-		return !!value && typeof value === "object" && typeof value.model === "string" ? { value } : { issues: [{ message: "Expected agent text input with a model" }] };
+		if (!value || typeof value !== "object") return { issues: [{ message: "Expected agent text input object" }] };
+		const request = value;
+		if (typeof request.model !== "string") return { issues: [{ message: "Expected agent text input with a string `model`" }] };
+		const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
+		const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
+		if (!hasPrompt && !hasMessages) return { issues: [{ message: `Agent text request${request.name ? ` '${request.name}'` : ""} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.` }] };
+		return { value: request };
 	}
 } };
 const unknownOutputSchema = { "~standard": {
@@ -311,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",
@@ -362,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);
 /**
@@ -381,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`/
@@ -399,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),
@@ -409,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),
@@ -422,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,
@@ -433,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);
@@ -462,7 +521,7 @@ function createTextLogic(config, execute) {
 * @example
 * ```ts
 * childMachine.provide({
-*   actorSources: {
+*   actors: {
 *     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
 *   },
 * });
@@ -500,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
@@ -654,7 +709,7 @@ function invalidGeneratorResult(id) {
 }
 //#endregion
 //#region src/events.ts
-/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. */
+/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. @internal */
 const EVENT_TOOL_PREFIX = "send_event_";
 function hashString(value) {
 	let hash = 5381;
@@ -689,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(".*");
@@ -731,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({
@@ -779,7 +862,7 @@ function decideRequestFromInput(input) {
 }
 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({ actorSources: { '${DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		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.`);
@@ -836,7 +919,10 @@ function createPlanActor() {
 		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input)
 	});
 }
-const PLAN_LEDGER_SCOPE = { emit: () => {} };
+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
@@ -874,11 +960,11 @@ function isDecisionLogic(value) {
 * diagnostics; a machine typically routes this via the decision invoke's
 * `onError`.
 */
-var DecisionExhaustedError = class extends Error {
+var AgentDecisionExhaustedError = class extends AgentError {
 	attempts;
 	constructor(attempts) {
-		super(`Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
-		this.name = "DecisionExhaustedError";
+		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;
 	}
 };
@@ -916,7 +1002,7 @@ function renderDecisionAttempts(request) {
 * 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 DecisionExhaustedError} with the full attempts list.
+* {@link AgentDecisionExhaustedError} with the full attempts list.
 *
 * @example
 * ```ts
@@ -931,11 +1017,13 @@ async function resolveDecision(request, executor, options = {}) {
 	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
 	for (let attempt = 0; attempt <= maxRetries; attempt++) {
 		options.signal?.throwIfAborted();
-		const { event } = await executor({
+		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({
@@ -972,7 +1060,7 @@ async function resolveDecision(request, executor, options = {}) {
 		}
 		return validatedEvent;
 	}
-	throw new DecisionExhaustedError(attempts);
+	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { validateSchemaSync as $, parseOutput as A, missingActor as B, createTextLogic as C, isTextLogic as D, isStructuredOutputSchema as E, getMachineSuspensionPredicate as F, getJsonSchemaSync as G, findNonSerializableContextPaths as H, getRegisteredAgentExecutionOptions as I, isStandardSchema as J, getMachineStructuralHash as K, getRegisteredAgentModels as L, userInputActor as M, agentExecutionOptions as N, normalizeGeneratorResult as O, executorBoundLogics as P, userMessage as Q, isUnboundPlaceholder as R, builtinTextActors as S, getAgentOutputMode as T, getAgentMessages as U, assistantMessage as V, getJsonSchema as W, systemMessage as X, persistSnapshot as Y, toolMessage as Z, INTERPRET_SOURCE as _, createPlanActor as a, bindRequestExecutor as b, isPlanLogic as c, EVENT_TOOL_PREFIX as d, getAcceptedEvents as f, DECIDE_ACTOR as g, sanitizeEventToolName as h, createDecideActor as i, parseStructuredEnvelope as j, parseModelRef as k, renderDecisionAttempts as l, parseAgentEvent as m, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, matchesEventPattern as p, getStateMeta as q, advancePlanLedger as r, isDecisionLogic as s, DecisionExhaustedError as t, resolveDecision as u, PLAN_ACTOR as v, executeAgentTextRequest as w, buildEnvelopeSchema as x, USER_INPUT_ACTOR as y, machineSuspensionPredicates as z };
+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 };