@statelyai/agent 2.0.0-alpha.18 → 2.0.0-alpha.20

package/dist/ai-sdk.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_decision = require("./decision-DnQCQPew.cjs");
+const require_decision = require("./decision-DhsKLYAI.cjs");
+require("./validate.cjs");
 let ai = require("ai");
 //#region src/ai-sdk/mappers.ts
 /**
@@ -142,7 +143,8 @@ function toDecisionMessages(request) {
 //#endregion
 //#region src/ai-sdk/index.ts
 function maxStepsSetting(request) {
-	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: (0, ai.stepCountIs)(request.metadata.maxSteps) } : {};
+	const maxSteps = typeof request.maxSteps === "number" ? request.maxSteps : request.metadata?.maxSteps;
+	return typeof maxSteps === "number" ? { stopWhen: (0, ai.stepCountIs)(maxSteps) } : {};
 }
 /**
 * Identity helper for a `models` map whose value is exported. Returns the map

package/dist/ai-sdk.d.cts

@@ -1,5 +1,5 @@
 import { d as ChosenEvent } from "./types-pJ5Hn8fv.cjs";
-import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-VcWqO-Cl.cjs";
+import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-Cavva1W6.cjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 import { d as ChosenEvent } from "./types-DYpK3QF4.mjs";
-import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-RvnlD-An.mjs";
+import { A as AgentDecisionExecutor, l as AgentRequestExecutors, o as AgentRequestExecutor } from "./text-logic-Er5KkTX6.mjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts

package/dist/ai-sdk.mjs

@@ -1,4 +1,4 @@
-import { H as isStandardSchema, _ as getAgentOutputMode, i as renderDecisionAttempts, p as buildEnvelopeSchema } from "./decision-C11xuud2.mjs";
+import { H as isStandardSchema, _ as getAgentOutputMode, i as renderDecisionAttempts, p as buildEnvelopeSchema } from "./decision-BfhSgCc6.mjs";
 import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
 //#region src/ai-sdk/mappers.ts
 /**
@@ -141,7 +141,8 @@ function toDecisionMessages(request) {
 //#endregion
 //#region src/ai-sdk/index.ts
 function maxStepsSetting(request) {
-	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: stepCountIs(request.metadata.maxSteps) } : {};
+	const maxSteps = typeof request.maxSteps === "number" ? request.maxSteps : request.metadata?.maxSteps;
+	return typeof maxSteps === "number" ? { stopWhen: stepCountIs(maxSteps) } : {};
 }
 /**
 * Identity helper for a `models` map whose value is exported. Returns the map

package/dist/{decision-C11xuud2.mjs → decision-BfhSgCc6.mjs}

@@ -2,18 +2,9 @@ import { t as AgentError } from "./errors-CeSXQx0v.mjs";
 import { createAsyncLogic, getNextTransitions } from "xstate";
 //#region src/utils.ts
 /**
-* Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
-* shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
-* JSON-serializability: functions, `undefined`, and other non-JSON values are
-* dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
-* plain-JSON deep clone, not a live snapshot.
-*/
-function persistSnapshot(snapshot) {
-	return JSON.parse(JSON.stringify(snapshot));
-}
-/**
 * Walks a context value and returns the dot-paths of the first few values that
-* would NOT survive a JSON persist/resume round-trip (see {@link persistSnapshot}):
+* would NOT survive a JSON persist/resume round-trip (persist with XState's
+* `actor.getPersistedSnapshot()`, resume with `createActor(machine, { snapshot })`):
 * `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
 * instances (non-plain objects), and circular references. Plain objects,
 * arrays, and JSON primitives are walked/allowed. Returns `[]` for a
@@ -68,11 +59,22 @@ function findNonSerializableContextPaths(context, limit = 5) {
 * Used by {@link runAgent} to stamp settled snapshots with a `version` and to
 * detect a structurally-edited machine on resume. It is a change detector, not
 * a cryptographic digest — collisions are possible but unlikely for real
-* configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+* configs. Declare `createMachine({ version })` to pin an explicit version instead.
 */
 function getMachineStructuralHash(machine) {
 	return djb2Hex(stableStructuralString(machine.config));
 }
+/**
+* The version a machine is stamped with everywhere: an explicitly declared
+* `createMachine({ version })` when present, else its
+* {@link getMachineStructuralHash}. Single source of truth so `runAgent`,
+* `provideExecutors`/`traceTransitions` trace envelopes, and the event-log
+* helpers (`initEntry`, `createReplayEntry`, `replay`) never disagree.
+* @internal
+*/
+function resolveMachineVersion(machine) {
+	return machine.version ?? getMachineStructuralHash(machine);
+}
 function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
 	if (value === null) return "null";
 	const type = typeof value;
@@ -143,8 +145,15 @@ function toolMessage(content) {
 *
 * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
 * state, but parallel/nested machines can have several. This shallow-merges
-* every active state's meta into one object (later/deeper entries win) and
-* returns `{}` when no active state declares meta.
+* every active state's meta into one object and returns `{}` when no active
+* state declares meta.
+*
+* Merge order is fixed and does not depend on XState's internal node order:
+* entries are sorted by structural depth (the state node's distance from the
+* root, regardless of custom `id` strings), then by state id lexicographically,
+* and merged in that order. So a deeper state's key wins over an ancestor's,
+* and between equal-depth parallel siblings the later state id alphabetically
+* wins.
 *
 * The return type is recovered from the snapshot's own `getMeta()` type, so a
 * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
@@ -158,7 +167,11 @@ function toolMessage(content) {
 * ```
 */
 function getStateMeta(snapshot) {
-	return Object.assign({}, ...Object.values(snapshot.getMeta()).filter((meta) => meta != null));
+	const nodes = snapshot.nodes;
+	const depthById = new Map(nodes?.map((node) => [node.id, node.path.length]));
+	const depth = (id) => depthById.get(id) ?? id.split(".").length;
+	const entries = Object.entries(snapshot.getMeta()).filter((entry) => entry[1] != null).sort(([a], [b]) => depth(a) - depth(b) || (a < b ? -1 : a > b ? 1 : 0));
+	return Object.assign({}, ...entries.map(([, meta]) => meta));
 }
 /**
 * Reads the run-owned message log off a snapshot settled by a `runAgent` call
@@ -232,16 +245,16 @@ const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
 * the machine object itself), so a predicate registered here travels with the
 * machine through `.provide` — which is why it is keyed on `config`, not the
-* machine. Set by `setupAgent({ isSuspended })` in `createMachine` and by
-* `setupAgent.fromConfig` (its `isSuspended` option or the config's
-* `suspendedTags`), read by `runAgent` (below the host `options.isSuspended`
+* machine. Set by `setupAgent({ isIdle })` in `createMachine` and by
+* `setupAgent.fromConfig` (its `isIdle` option or the config's
+* `idleTags`), read by `runAgent` (below the host `options.isIdle`
 * override, above the timing heuristic).
 */
-const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
-/** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */
-function getMachineSuspensionPredicate(machine) {
+const machineIdlePredicates = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineIdlePredicates} predicate carried by `machine` (via its root `config`), if any. */
+function getMachineIdlePredicate(machine) {
 	const config = machine.config;
-	return config ? machineSuspensionPredicates.get(config) : void 0;
+	return config ? machineIdlePredicates.get(config) : void 0;
 }
 /**
 * Lint-reachability sidecar for `fromConfig` machines.
@@ -253,7 +266,7 @@ function getMachineSuspensionPredicate(machine) {
 * 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(...)`.
+* {@link machineIdlePredicates}) so it survives `machine.provide(...)`.
 */
 const machineStaticTransitionTargets = /* @__PURE__ */ new WeakMap();
 /** Reads the {@link machineStaticTransitionTargets} map carried by `machine` (via its root `config`), if any. */
@@ -417,6 +430,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				topK: ({ input }) => input.topK,
 				seed: ({ input }) => input.seed,
 				stopSequences: ({ input }) => input.stopSequences,
+				maxSteps: ({ input }) => input.maxSteps,
 				metadata: ({ input }) => input.metadata
 			}, execute);
 		}
@@ -488,6 +502,7 @@ function createTextLogic(config, execute) {
 			topK: resolveTextLogicValue(config.topK, args),
 			seed: resolveTextLogicValue(config.seed, args),
 			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			maxSteps: resolveTextLogicValue(config.maxSteps, args),
 			metadata: resolveTextLogicValue(config.metadata, args)
 		};
 	};
@@ -874,7 +889,7 @@ function decideActorWithExecutor(execute) {
 		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, {
+		return resolveDecision(decideRequestFromInput(input), { decide: execute }, {
 			maxRetries: input.maxRetries ?? 2,
 			signal
 		});
@@ -934,7 +949,7 @@ function renderDecisionAttempts(request) {
 }
 /**
 * Validation + retry core for decisions. No provider mechanics — the
-* `executor` is responsible for making the model choose an event; this
+* `executors.decide` 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).
 *
@@ -952,12 +967,14 @@ function renderDecisionAttempts(request) {
 *
 * @example
 * ```ts
-* const event = await resolveDecision(request, decide, {
+* const event = await resolveDecision(request, executors, {
 *   canTake: (e) => snapshot.can(e),
 * });
 * ```
 */
-async function resolveDecision(request, executor, options = {}) {
+async function resolveDecision(request, executors, options = {}) {
+	const executor = executors?.decide;
+	if (typeof executor !== "function") throw new AgentError("missing-decide-executor", "resolveDecision(request, executors, ...) takes the EXECUTOR SET (the same object executeAgentRequest takes), and this one has no 'decide' function. Build one with createAiSdkExecutors({ models }), or pass { decide }.");
 	const maxRetries = options.maxRetries ?? 2;
 	const attempts = [];
 	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
@@ -967,6 +984,9 @@ async function resolveDecision(request, executor, options = {}) {
 			...request,
 			attempts: [...attempts],
 			signal: options.signal
+		}, {
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...request.id ? { requestId: request.id } : {}
 		});
 		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;
@@ -1009,4 +1029,4 @@ async function resolveDecision(request, executor, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { isUnboundPlaceholder as A, getMachineStructuralHash as B, parseStructuredEnvelope as C, getMachineStaticTransitionTargets as D, executorBoundLogics as E, djb2Hex as F, toolMessage as G, isStandardSchema as H, findNonSerializableContextPaths as I, userMessage as K, getAgentMessages as L, machineSuspensionPredicates as M, missingActor as N, getMachineSuspensionPredicate as O, assistantMessage as P, getJsonSchema as R, parseOutput as S, agentExecutionOptions as T, persistSnapshot as U, getStateMeta as V, systemMessage as W, getAgentOutputMode as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineStaticTransitionTargets as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, validateSchemaSync as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getCallUsage as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getJsonSchemaSync as z };
+export { isUnboundPlaceholder as A, getMachineStructuralHash as B, parseStructuredEnvelope as C, getMachineIdlePredicate as D, executorBoundLogics as E, djb2Hex as F, toolMessage as G, isStandardSchema as H, findNonSerializableContextPaths as I, userMessage as K, getAgentMessages as L, machineStaticTransitionTargets as M, missingActor as N, getMachineStaticTransitionTargets as O, assistantMessage as P, getJsonSchema as R, parseOutput as S, agentExecutionOptions as T, resolveMachineVersion as U, getStateMeta as V, systemMessage as W, getAgentOutputMode as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineIdlePredicates as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, validateSchemaSync as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getCallUsage as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getJsonSchemaSync as z };

package/dist/{decision-DnQCQPew.cjs → decision-DhsKLYAI.cjs}

@@ -1,19 +1,11 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
+require("./validate.cjs");
 let xstate = require("xstate");
 //#region src/utils.ts
 /**
-* Deep-clones a snapshot to a plain-JSON value via a `JSON` round-trip, the
-* shape you persist and later feed back to `runAgent({ snapshot })`. Asserts
-* JSON-serializability: functions, `undefined`, and other non-JSON values are
-* dropped or throw exactly as `JSON.stringify`/`JSON.parse` would. Returns a
-* plain-JSON deep clone, not a live snapshot.
-*/
-function persistSnapshot(snapshot) {
-	return JSON.parse(JSON.stringify(snapshot));
-}
-/**
 * Walks a context value and returns the dot-paths of the first few values that
-* would NOT survive a JSON persist/resume round-trip (see {@link persistSnapshot}):
+* would NOT survive a JSON persist/resume round-trip (persist with XState's
+* `actor.getPersistedSnapshot()`, resume with `createActor(machine, { snapshot })`):
 * `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
 * instances (non-plain objects), and circular references. Plain objects,
 * arrays, and JSON primitives are walked/allowed. Returns `[]` for a
@@ -68,11 +60,22 @@ function findNonSerializableContextPaths(context, limit = 5) {
 * Used by {@link runAgent} to stamp settled snapshots with a `version` and to
 * detect a structurally-edited machine on resume. It is a change detector, not
 * a cryptographic digest — collisions are possible but unlikely for real
-* configs. Pass an explicit `machineVersion` to `runAgent` to override it.
+* configs. Declare `createMachine({ version })` to pin an explicit version instead.
 */
 function getMachineStructuralHash(machine) {
 	return djb2Hex(stableStructuralString(machine.config));
 }
+/**
+* The version a machine is stamped with everywhere: an explicitly declared
+* `createMachine({ version })` when present, else its
+* {@link getMachineStructuralHash}. Single source of truth so `runAgent`,
+* `provideExecutors`/`traceTransitions` trace envelopes, and the event-log
+* helpers (`initEntry`, `createReplayEntry`, `replay`) never disagree.
+* @internal
+*/
+function resolveMachineVersion(machine) {
+	return machine.version ?? getMachineStructuralHash(machine);
+}
 function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
 	if (value === null) return "null";
 	const type = typeof value;
@@ -143,8 +146,15 @@ function toolMessage(content) {
 *
 * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
 * state, but parallel/nested machines can have several. This shallow-merges
-* every active state's meta into one object (later/deeper entries win) and
-* returns `{}` when no active state declares meta.
+* every active state's meta into one object and returns `{}` when no active
+* state declares meta.
+*
+* Merge order is fixed and does not depend on XState's internal node order:
+* entries are sorted by structural depth (the state node's distance from the
+* root, regardless of custom `id` strings), then by state id lexicographically,
+* and merged in that order. So a deeper state's key wins over an ancestor's,
+* and between equal-depth parallel siblings the later state id alphabetically
+* wins.
 *
 * The return type is recovered from the snapshot's own `getMeta()` type, so a
 * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
@@ -158,7 +168,11 @@ function toolMessage(content) {
 * ```
 */
 function getStateMeta(snapshot) {
-	return Object.assign({}, ...Object.values(snapshot.getMeta()).filter((meta) => meta != null));
+	const nodes = snapshot.nodes;
+	const depthById = new Map(nodes?.map((node) => [node.id, node.path.length]));
+	const depth = (id) => depthById.get(id) ?? id.split(".").length;
+	const entries = Object.entries(snapshot.getMeta()).filter((entry) => entry[1] != null).sort(([a], [b]) => depth(a) - depth(b) || (a < b ? -1 : a > b ? 1 : 0));
+	return Object.assign({}, ...entries.map(([, meta]) => meta));
 }
 /**
 * Reads the run-owned message log off a snapshot settled by a `runAgent` call
@@ -232,16 +246,16 @@ const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
 * the machine object itself), so a predicate registered here travels with the
 * machine through `.provide` — which is why it is keyed on `config`, not the
-* machine. Set by `setupAgent({ isSuspended })` in `createMachine` and by
-* `setupAgent.fromConfig` (its `isSuspended` option or the config's
-* `suspendedTags`), read by `runAgent` (below the host `options.isSuspended`
+* machine. Set by `setupAgent({ isIdle })` in `createMachine` and by
+* `setupAgent.fromConfig` (its `isIdle` option or the config's
+* `idleTags`), read by `runAgent` (below the host `options.isIdle`
 * override, above the timing heuristic).
 */
-const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
-/** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */
-function getMachineSuspensionPredicate(machine) {
+const machineIdlePredicates = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineIdlePredicates} predicate carried by `machine` (via its root `config`), if any. */
+function getMachineIdlePredicate(machine) {
 	const config = machine.config;
-	return config ? machineSuspensionPredicates.get(config) : void 0;
+	return config ? machineIdlePredicates.get(config) : void 0;
 }
 /**
 * Lint-reachability sidecar for `fromConfig` machines.
@@ -253,7 +267,7 @@ function getMachineSuspensionPredicate(machine) {
 * 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(...)`.
+* {@link machineIdlePredicates}) so it survives `machine.provide(...)`.
 */
 const machineStaticTransitionTargets = /* @__PURE__ */ new WeakMap();
 /** Reads the {@link machineStaticTransitionTargets} map carried by `machine` (via its root `config`), if any. */
@@ -417,6 +431,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				topK: ({ input }) => input.topK,
 				seed: ({ input }) => input.seed,
 				stopSequences: ({ input }) => input.stopSequences,
+				maxSteps: ({ input }) => input.maxSteps,
 				metadata: ({ input }) => input.metadata
 			}, execute);
 		}
@@ -488,6 +503,7 @@ function createTextLogic(config, execute) {
 			topK: resolveTextLogicValue(config.topK, args),
 			seed: resolveTextLogicValue(config.seed, args),
 			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			maxSteps: resolveTextLogicValue(config.maxSteps, args),
 			metadata: resolveTextLogicValue(config.metadata, args)
 		};
 	};
@@ -874,7 +890,7 @@ function decideActorWithExecutor(execute) {
 		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, {
+		return resolveDecision(decideRequestFromInput(input), { decide: execute }, {
 			maxRetries: input.maxRetries ?? 2,
 			signal
 		});
@@ -934,7 +950,7 @@ function renderDecisionAttempts(request) {
 }
 /**
 * Validation + retry core for decisions. No provider mechanics — the
-* `executor` is responsible for making the model choose an event; this
+* `executors.decide` 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).
 *
@@ -952,12 +968,14 @@ function renderDecisionAttempts(request) {
 *
 * @example
 * ```ts
-* const event = await resolveDecision(request, decide, {
+* const event = await resolveDecision(request, executors, {
 *   canTake: (e) => snapshot.can(e),
 * });
 * ```
 */
-async function resolveDecision(request, executor, options = {}) {
+async function resolveDecision(request, executors, options = {}) {
+	const executor = executors?.decide;
+	if (typeof executor !== "function") throw new require_errors.AgentError("missing-decide-executor", "resolveDecision(request, executors, ...) takes the EXECUTOR SET (the same object executeAgentRequest takes), and this one has no 'decide' function. Build one with createAiSdkExecutors({ models }), or pass { decide }.");
 	const maxRetries = options.maxRetries ?? 2;
 	const attempts = [];
 	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
@@ -967,6 +985,9 @@ async function resolveDecision(request, executor, options = {}) {
 			...request,
 			attempts: [...attempts],
 			signal: options.signal
+		}, {
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...request.id ? { requestId: request.id } : {}
 		});
 		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;
@@ -1141,22 +1162,22 @@ Object.defineProperty(exports, "getJsonSchemaSync", {
 		return getJsonSchemaSync;
 	}
 });
-Object.defineProperty(exports, "getMachineStaticTransitionTargets", {
+Object.defineProperty(exports, "getMachineIdlePredicate", {
 	enumerable: true,
 	get: function() {
-		return getMachineStaticTransitionTargets;
+		return getMachineIdlePredicate;
 	}
 });
-Object.defineProperty(exports, "getMachineStructuralHash", {
+Object.defineProperty(exports, "getMachineStaticTransitionTargets", {
 	enumerable: true,
 	get: function() {
-		return getMachineStructuralHash;
+		return getMachineStaticTransitionTargets;
 	}
 });
-Object.defineProperty(exports, "getMachineSuspensionPredicate", {
+Object.defineProperty(exports, "getMachineStructuralHash", {
 	enumerable: true,
 	get: function() {
-		return getMachineSuspensionPredicate;
+		return getMachineStructuralHash;
 	}
 });
 Object.defineProperty(exports, "getRegisteredAgentExecutionOptions", {
@@ -1195,16 +1216,16 @@ Object.defineProperty(exports, "isUnboundPlaceholder", {
 		return isUnboundPlaceholder;
 	}
 });
-Object.defineProperty(exports, "machineStaticTransitionTargets", {
+Object.defineProperty(exports, "machineIdlePredicates", {
 	enumerable: true,
 	get: function() {
-		return machineStaticTransitionTargets;
+		return machineIdlePredicates;
 	}
 });
-Object.defineProperty(exports, "machineSuspensionPredicates", {
+Object.defineProperty(exports, "machineStaticTransitionTargets", {
 	enumerable: true,
 	get: function() {
-		return machineSuspensionPredicates;
+		return machineStaticTransitionTargets;
 	}
 });
 Object.defineProperty(exports, "missingActor", {
@@ -1243,12 +1264,6 @@ Object.defineProperty(exports, "parseStructuredEnvelope", {
 		return parseStructuredEnvelope;
 	}
 });
-Object.defineProperty(exports, "persistSnapshot", {
-	enumerable: true,
-	get: function() {
-		return persistSnapshot;
-	}
-});
 Object.defineProperty(exports, "renderDecisionAttempts", {
 	enumerable: true,
 	get: function() {
@@ -1261,6 +1276,12 @@ Object.defineProperty(exports, "resolveDecision", {
 		return resolveDecision;
 	}
 });
+Object.defineProperty(exports, "resolveMachineVersion", {
+	enumerable: true,
+	get: function() {
+		return resolveMachineVersion;
+	}
+});
 Object.defineProperty(exports, "systemMessage", {
 	enumerable: true,
 	get: function() {

package/dist/{event-log-store-CQJq8_v4.d.cts → event-log-store-Bz7HDBkE.d.cts}

@@ -107,30 +107,29 @@ interface AgentEventLogStore {
   /** The thread's current log length (0 for an unknown thread) — the next `expectedIndex`. */
   length(threadId: string): Promise<number>;
   /**
-   * Copy a prefix onto a fresh, empty `newThreadId` — either `[0, upToIndex)`
-   * or through the inclusive `atEventId`. With neither cutoff the full source
-   * is copied. The fork then appends independently. Rejects (plain `Error`) if
-   * `newThreadId` already has entries, the source/id is unknown, or both cutoff
-   * forms are supplied. Implementations may copy-on-write or physically copy;
-   * observable behavior must match a full copy.
+   * Copy the prefix `[0, upToIndex)` onto a fresh, empty `newThreadId`.
+   * Without `upToIndex` the full source is copied. The fork then appends
+   * independently. Rejects (plain `Error`) if `newThreadId` already has
+   * entries, the source is unknown, or `upToIndex` is out of range.
+   * Implementations may copy-on-write or physically copy; observable behavior
+   * must match a full copy.
    */
   fork(input: {
     threadId: string;
-    newThreadId: string;
-    upToIndex?: number; /** Inclusive event-id cutoff. Mutually exclusive with `upToIndex`. */
-    atEventId?: string;
+    newThreadId: string; /** Exclusive index cutoff. */
+    upToIndex?: number;
   }): Promise<void>;
 }
 /**
  * Rejection from {@link AgentEventLogStore.append} when the thread's stored
  * length is not the `expectedIndex` the writer held — a concurrent writer
- * appended first. `actualLength` is the length core found.
+ * appended first. `actualIndex` is the next index the store would accept.
  */
 declare class AgentEventLogConflictError extends AgentError {
   readonly threadId: string;
   readonly expectedIndex: number;
-  readonly actualLength: number;
-  constructor(threadId: string, expectedIndex: number, actualLength: number);
+  readonly actualIndex: number;
+  constructor(threadId: string, expectedIndex: number, actualIndex: number);
 }
 /**
  * In-memory reference store, and the baseline the conformance suite runs

package/dist/{event-log-store-B-1fcfkT.mjs → event-log-store-DmIDosD6.mjs}

@@ -111,7 +111,7 @@ async function assertEventLogStoreConformance(create) {
 			caught = error;
 		}
 		if (!(caught instanceof AgentEventLogConflictError)) fail("a stale expectedIndex must throw AgentEventLogConflictError");
-		if (caught.threadId !== "t" || caught.expectedIndex !== 0 || caught.actualLength !== 1) fail("conflict error must carry threadId, expectedIndex, and the actual length");
+		if (caught.threadId !== "t" || caught.expectedIndex !== 0 || caught.actualIndex !== 1) fail("conflict error must carry threadId, expectedIndex, and the actual index");
 	}
 	{
 		const store = await create();
@@ -240,10 +240,10 @@ async function assertEventLogStoreConformance(create) {
 		assertJsonEqual((await store.read("fork-1")).map((e) => e.index), [0], "fork with upToIndex 1 must copy only entry 0");
 		await store.fork({
 			threadId: "src",
-			newThreadId: "fork-id",
-			atEventId: "evt_1"
+			newThreadId: "fork-2",
+			upToIndex: 2
 		});
-		assertJsonEqual((await store.read("fork-id")).map((e) => e.id), ["evt_0", "evt_1"], "fork with atEventId must include the named entry");
+		assertJsonEqual((await store.read("fork-2")).map((e) => e.id), ["evt_0", "evt_1"], "fork with upToIndex 2 must copy entries 0 and 1 only");
 		await store.append({
 			threadId: "fork-1",
 			expectedIndex: 1,
@@ -271,6 +271,17 @@ async function assertEventLogStoreConformance(create) {
 			caughtUnknown = error;
 		}
 		if (!(caughtUnknown instanceof Error) || caughtUnknown instanceof AgentEventLogConflictError) fail("forking an unknown source thread must reject with a plain Error");
+		let caughtRange;
+		try {
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-range",
+				upToIndex: 99
+			});
+		} catch (error) {
+			caughtRange = error;
+		}
+		if (!(caughtRange instanceof Error) || caughtRange instanceof AgentEventLogConflictError) fail("forking past the source length must reject with a plain Error");
 	}
 }
 //#endregion
@@ -352,18 +363,18 @@ function assertAgentLogEntry(entry) {
 /**
 * Rejection from {@link AgentEventLogStore.append} when the thread's stored
 * length is not the `expectedIndex` the writer held — a concurrent writer
-* appended first. `actualLength` is the length core found.
+* appended first. `actualIndex` is the next index the store would accept.
 */
 var AgentEventLogConflictError = class extends AgentError {
 	threadId;
 	expectedIndex;
-	actualLength;
-	constructor(threadId, expectedIndex, actualLength) {
-		super("event-log-conflict", `AgentEventLogStore.append: length conflict on thread "${threadId}": expected length ${expectedIndex} but found ${actualLength} — a concurrent writer won.`);
+	actualIndex;
+	constructor(threadId, expectedIndex, actualIndex) {
+		super("event-log-conflict", `AgentEventLogStore.append: index conflict on thread "${threadId}": expected index ${expectedIndex} but found ${actualIndex} — a concurrent writer won.`);
 		this.name = "AgentEventLogConflictError";
 		this.threadId = threadId;
 		this.expectedIndex = expectedIndex;
-		this.actualLength = actualLength;
+		this.actualIndex = actualIndex;
 	}
 };
 /**
@@ -402,14 +413,11 @@ function createInMemoryEventLogStore() {
 		async length(threadId) {
 			return threads.get(threadId)?.length ?? 0;
 		},
-		async fork({ threadId, newThreadId, upToIndex, atEventId }) {
+		async fork({ threadId, newThreadId, upToIndex }) {
 			if ((threads.get(newThreadId)?.length ?? 0) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
 			const source = threads.get(threadId);
 			if (!source) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
-			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
-			const eventIndex = atEventId === void 0 ? void 0 : source.findIndex((entry) => entry.id === atEventId);
-			if (atEventId !== void 0 && eventIndex === -1) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
-			const upTo = eventIndex === void 0 ? upToIndex ?? source.length : eventIndex + 1;
+			const upTo = upToIndex ?? source.length;
 			if (upTo < 0 || upTo > source.length) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${source.length}) has no index ${upTo} to fork up to.`);
 			threads.set(newThreadId, source.slice(0, upTo).map((entry) => clone(entry)));
 		}