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

package/dist/{setup-agent-C3ETi_HZ.cjs → setup-agent-BFA4VKpN.cjs}

@@ -1,6 +1,7 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_decision = require("./decision-DnQCQPew.cjs");
-const require_event_log_store = require("./event-log-store-yquOV1TX.cjs");
+const require_decision = require("./decision-t26zsnSR.cjs");
+const require_event_log_store = require("./event-log-store-a_TKy1gk.cjs");
+require("./validate.cjs");
 let xstate = require("xstate");
 //#region src/messages.ts
 function addMessages(resolve) {
@@ -221,7 +222,7 @@ function resolveAgentStep(machine, step, request, output, options) {
 	return createAgentStep(machine, snapshot, actions, require_decision.getRegisteredAgentExecutionOptions(machine, options));
 }
 async function executeAgentRequest(requestOrEffect, executors) {
-	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors, ...) instead.");
 	const request = "requestId" in requestOrEffect ? {
 		kind: "text",
 		id: requestOrEffect.requestId,
@@ -335,7 +336,7 @@ const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
 function createReplayEntry(machine, entries, event, options = {}) {
 	const index = entries.length;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
-	const machineVersion = options.machineVersion ?? require_decision.getMachineStructuralHash(machine);
+	const machineVersion = options.machineVersion ?? require_decision.resolveMachineVersion(machine);
 	const entry = {
 		schemaVersion: 1,
 		id: options.id ?? `evt_${String(index).padStart(8, "0")}`,
@@ -631,7 +632,7 @@ function validateReplayEntries(entries, expected, label) {
 function replay(machine, entries, options = {}) {
 	validateReplayEntries(entries, {
 		machineId: machine.config.id ?? machine.id ?? "(machine)",
-		machineVersion: options.machineVersion ?? require_decision.getMachineStructuralHash(machine)
+		machineVersion: options.machineVersion ?? require_decision.resolveMachineVersion(machine)
 	}, "Replay entries");
 	const events = toEvents(entries);
 	const initOffset = events[0]?.type === "@agent.init" ? 1 : 0;
@@ -661,13 +662,6 @@ function replay(machine, entries, options = {}) {
 		effects
 	};
 }
-/** Requires and checks every entry's recorded state/effect hashes. */
-function verifyReplay(machine, entries, options = {}) {
-	return replay(machine, entries, {
-		...options,
-		verify: "strict"
-	});
-}
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 function diffEventLogs(machine, parentEntries, forkEntries, options = {}) {
 	let commonLength = 0;
@@ -1135,14 +1129,14 @@ function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
 	}
 	return tags;
 }
-function resolveSuspensionPredicate(config, options) {
-	if (options.isSuspended) return options.isSuspended;
-	const suspendedTags = config.suspendedTags ?? [];
-	if (!suspendedTags.length) return;
+function resolveIdlePredicate(config, options) {
+	if (options.isIdle) return options.isIdle;
+	const idleTags = config.idleTags ?? [];
+	if (!idleTags.length) return;
 	const declaredTags = collectDeclaredStateTags(config.states);
-	const unknown = suspendedTags.filter((tag) => !declaredTags.has(tag));
-	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'suspendedTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
-	return (snapshot) => suspendedTags.some((tag) => snapshot.hasTag(tag));
+	const unknown = idleTags.filter((tag) => !declaredTags.has(tag));
+	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'idleTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
+	return (snapshot) => idleTags.some((tag) => snapshot.hasTag(tag));
 }
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
@@ -1174,8 +1168,8 @@ function setupAgentFromConfig(config, options) {
 		models: {}
 	});
 	if (machine.config) require_decision.machineStaticTransitionTargets.set(machine.config, translation.transitionTargets);
-	const isSuspended = resolveSuspensionPredicate(config, options);
-	if (isSuspended && machine.config) require_decision.machineSuspensionPredicates.set(machine.config, isSuspended);
+	const isIdle = resolveIdlePredicate(config, options);
+	if (isIdle && machine.config) require_decision.machineIdlePredicates.set(machine.config, isIdle);
 	return {
 		machine,
 		schemas
@@ -1389,9 +1383,9 @@ function setupAgent(config) {
 			assertStateSchemaKeysExist(config.states, machineConfig?.states);
 			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
 			require_decision.agentExecutionOptions.set(machine, machineOptions);
-			if (config.isSuspended) {
+			if (config.isIdle) {
 				const rootConfig = machine.config;
-				if (rootConfig) require_decision.machineSuspensionPredicates.set(rootConfig, config.isSuspended);
+				if (rootConfig) require_decision.machineIdlePredicates.set(rootConfig, config.isIdle);
 			}
 			return machine;
 		},
@@ -1482,13 +1476,22 @@ const RESERVED_AGENT_ACTOR_KEYS = [
 	require_decision.DECIDE_ACTOR
 ];
 /**
+* The whole `agent.` actor-source namespace is reserved for the library, not
+* just the shipped builtins: a key starting with this prefix is rejected at
+* setup time so a future builtin can never collide with (or be shadowed by) a
+* user source. Name your own sources without it.
+*/
+const RESERVED_AGENT_KEY_PREFIX = "agent.";
+/**
 * Runtime guards over the user-supplied `actors`/`requests` keys, in one walk
 * of both groups:
 *
-* 1. A key in the reserved `agent.*` builtin namespace is rejected. Without
-*    this, the builtins-first spread in {@link createAgentActors} lets such a
-*    key overwrite the builtin (`agent.decide`, …) silently. Deliberate
-*    override of a builtin is still possible after the machine is created, via
+* 1. A key in the reserved `agent.` namespace is rejected — every key with
+*    that prefix, not only today's builtins. Without this, the builtins-first
+*    spread in {@link createAgentActors} lets such a key overwrite the builtin
+*    (`agent.decide`, …) silently, and a builtin added later would start
+*    colliding with user code. Deliberate override of a builtin is still
+*    possible after the machine is created, via
 *    `machine.provide({ actors: { 'agent.decide': ... } })`.
 * 2. A key appearing in BOTH groups is almost certainly a mistake (whichever
 *    spread applies last would silently win) — fail fast with a clear message
@@ -1499,6 +1502,7 @@ function assertActorKeys(actors, requests) {
 	const groups = [["actors", actors], ["requests", requests]];
 	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
 		if (RESERVED_AGENT_ACTOR_KEYS.some((reserved) => reserved === key)) throw new Error(`setupAgent: '${groupName}' key '${key}' is a reserved builtin agent actor and cannot be redefined here (it would silently clobber the builtin). Reserved keys: ${RESERVED_AGENT_ACTOR_KEYS.join(", ")}. To deliberately override a builtin, do it on the created machine instead: machine.provide({ actors: { '${key}': ... } }).`);
+		if (key.startsWith(RESERVED_AGENT_KEY_PREFIX)) throw new Error(`setupAgent: '${groupName}' key '${key}' uses the reserved '${RESERVED_AGENT_KEY_PREFIX}' namespace, which belongs to the library (${RESERVED_AGENT_ACTOR_KEYS.join(", ")}, and anything added later). Rename it without the '${RESERVED_AGENT_KEY_PREFIX}' prefix.`);
 		const existingGroup = seenIn.get(key);
 		if (existingGroup) throw new Error(`setupAgent: key '${key}' is defined in both '${existingGroup}' and '${groupName}'. Each actor source key must be unique across 'actors' and 'requests'.`);
 		seenIn.set(key, groupName);
@@ -1635,9 +1639,3 @@ Object.defineProperty(exports, "validateReplayEntries", {
 		return validateReplayEntries;
 	}
 });
-Object.defineProperty(exports, "verifyReplay", {
-	enumerable: true,
-	get: function() {
-		return verifyReplay;
-	}
-});

package/dist/{setup-agent-BrE2zFDy.mjs → setup-agent-CPFPN06s.mjs}

@@ -1,6 +1,6 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { B as getMachineStructuralHash, F as djb2Hex, M as machineSuspensionPredicates, N as missingActor, T as agentExecutionOptions, d as USER_INPUT_ACTOR, g as executeAgentTextRequest, h as createTextLogic, j as machineStaticTransitionTargets, k as getRegisteredAgentExecutionOptions, l as DECIDE_ACTOR, m as builtinTextActors, n as createDecideActor, o as getAcceptedEvents, q as validateSchemaSync, r as isDecisionLogic, w as userInputActor, y as isTextLogic } from "./decision-C11xuud2.mjs";
-import { a as assertJsonSerializable, i as assertAgentLogEntry } from "./event-log-store-B-1fcfkT.mjs";
+import { F as djb2Hex, M as machineStaticTransitionTargets, N as missingActor, T as agentExecutionOptions, U as resolveMachineVersion, d as USER_INPUT_ACTOR, g as executeAgentTextRequest, h as createTextLogic, j as machineIdlePredicates, k as getRegisteredAgentExecutionOptions, l as DECIDE_ACTOR, m as builtinTextActors, n as createDecideActor, o as getAcceptedEvents, q as validateSchemaSync, r as isDecisionLogic, w as userInputActor, y as isTextLogic } from "./decision-DsIkEuHz.mjs";
+import { a as assertJsonSerializable, i as assertAgentLogEntry } from "./event-log-store-DmIDosD6.mjs";
 import { createMachineFromConfig, initialTransition, setup, transition } from "xstate";
 //#region src/messages.ts
 function addMessages(resolve) {
@@ -221,7 +221,7 @@ function resolveAgentStep(machine, step, request, output, options) {
 	return createAgentStep(machine, snapshot, actions, getRegisteredAgentExecutionOptions(machine, options));
 }
 async function executeAgentRequest(requestOrEffect, executors) {
-	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	if (requestOrEffect.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors, ...) instead.");
 	const request = "requestId" in requestOrEffect ? {
 		kind: "text",
 		id: requestOrEffect.requestId,
@@ -335,7 +335,7 @@ const AGENT_USAGE_EVENT_TYPE = "@agent.usage";
 function createReplayEntry(machine, entries, event, options = {}) {
 	const index = entries.length;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
-	const machineVersion = options.machineVersion ?? getMachineStructuralHash(machine);
+	const machineVersion = options.machineVersion ?? resolveMachineVersion(machine);
 	const entry = {
 		schemaVersion: 1,
 		id: options.id ?? `evt_${String(index).padStart(8, "0")}`,
@@ -631,7 +631,7 @@ function validateReplayEntries(entries, expected, label) {
 function replay(machine, entries, options = {}) {
 	validateReplayEntries(entries, {
 		machineId: machine.config.id ?? machine.id ?? "(machine)",
-		machineVersion: options.machineVersion ?? getMachineStructuralHash(machine)
+		machineVersion: options.machineVersion ?? resolveMachineVersion(machine)
 	}, "Replay entries");
 	const events = toEvents(entries);
 	const initOffset = events[0]?.type === "@agent.init" ? 1 : 0;
@@ -661,13 +661,6 @@ function replay(machine, entries, options = {}) {
 		effects
 	};
 }
-/** Requires and checks every entry's recorded state/effect hashes. */
-function verifyReplay(machine, entries, options = {}) {
-	return replay(machine, entries, {
-		...options,
-		verify: "strict"
-	});
-}
 /** Structural event-tail, logical-state, and owed-effect comparison. */
 function diffEventLogs(machine, parentEntries, forkEntries, options = {}) {
 	let commonLength = 0;
@@ -1135,14 +1128,14 @@ function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
 	}
 	return tags;
 }
-function resolveSuspensionPredicate(config, options) {
-	if (options.isSuspended) return options.isSuspended;
-	const suspendedTags = config.suspendedTags ?? [];
-	if (!suspendedTags.length) return;
+function resolveIdlePredicate(config, options) {
+	if (options.isIdle) return options.isIdle;
+	const idleTags = config.idleTags ?? [];
+	if (!idleTags.length) return;
 	const declaredTags = collectDeclaredStateTags(config.states);
-	const unknown = suspendedTags.filter((tag) => !declaredTags.has(tag));
-	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'suspendedTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
-	return (snapshot) => suspendedTags.some((tag) => snapshot.hasTag(tag));
+	const unknown = idleTags.filter((tag) => !declaredTags.has(tag));
+	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'idleTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
+	return (snapshot) => idleTags.some((tag) => snapshot.hasTag(tag));
 }
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
@@ -1174,8 +1167,8 @@ function setupAgentFromConfig(config, options) {
 		models: {}
 	});
 	if (machine.config) machineStaticTransitionTargets.set(machine.config, translation.transitionTargets);
-	const isSuspended = resolveSuspensionPredicate(config, options);
-	if (isSuspended && machine.config) machineSuspensionPredicates.set(machine.config, isSuspended);
+	const isIdle = resolveIdlePredicate(config, options);
+	if (isIdle && machine.config) machineIdlePredicates.set(machine.config, isIdle);
 	return {
 		machine,
 		schemas
@@ -1389,9 +1382,9 @@ function setupAgent(config) {
 			assertStateSchemaKeysExist(config.states, machineConfig?.states);
 			const machine = createBaseMachine(withRootOutputFromSingleFinal(machineConfig));
 			agentExecutionOptions.set(machine, machineOptions);
-			if (config.isSuspended) {
+			if (config.isIdle) {
 				const rootConfig = machine.config;
-				if (rootConfig) machineSuspensionPredicates.set(rootConfig, config.isSuspended);
+				if (rootConfig) machineIdlePredicates.set(rootConfig, config.isIdle);
 			}
 			return machine;
 		},
@@ -1482,13 +1475,22 @@ const RESERVED_AGENT_ACTOR_KEYS = [
 	DECIDE_ACTOR
 ];
 /**
+* The whole `agent.` actor-source namespace is reserved for the library, not
+* just the shipped builtins: a key starting with this prefix is rejected at
+* setup time so a future builtin can never collide with (or be shadowed by) a
+* user source. Name your own sources without it.
+*/
+const RESERVED_AGENT_KEY_PREFIX = "agent.";
+/**
 * Runtime guards over the user-supplied `actors`/`requests` keys, in one walk
 * of both groups:
 *
-* 1. A key in the reserved `agent.*` builtin namespace is rejected. Without
-*    this, the builtins-first spread in {@link createAgentActors} lets such a
-*    key overwrite the builtin (`agent.decide`, …) silently. Deliberate
-*    override of a builtin is still possible after the machine is created, via
+* 1. A key in the reserved `agent.` namespace is rejected — every key with
+*    that prefix, not only today's builtins. Without this, the builtins-first
+*    spread in {@link createAgentActors} lets such a key overwrite the builtin
+*    (`agent.decide`, …) silently, and a builtin added later would start
+*    colliding with user code. Deliberate override of a builtin is still
+*    possible after the machine is created, via
 *    `machine.provide({ actors: { 'agent.decide': ... } })`.
 * 2. A key appearing in BOTH groups is almost certainly a mistake (whichever
 *    spread applies last would silently win) — fail fast with a clear message
@@ -1499,6 +1501,7 @@ function assertActorKeys(actors, requests) {
 	const groups = [["actors", actors], ["requests", requests]];
 	for (const [groupName, group] of groups) for (const key of Object.keys(group ?? {})) {
 		if (RESERVED_AGENT_ACTOR_KEYS.some((reserved) => reserved === key)) throw new Error(`setupAgent: '${groupName}' key '${key}' is a reserved builtin agent actor and cannot be redefined here (it would silently clobber the builtin). Reserved keys: ${RESERVED_AGENT_ACTOR_KEYS.join(", ")}. To deliberately override a builtin, do it on the created machine instead: machine.provide({ actors: { '${key}': ... } }).`);
+		if (key.startsWith(RESERVED_AGENT_KEY_PREFIX)) throw new Error(`setupAgent: '${groupName}' key '${key}' uses the reserved '${RESERVED_AGENT_KEY_PREFIX}' namespace, which belongs to the library (${RESERVED_AGENT_ACTOR_KEYS.join(", ")}, and anything added later). Rename it without the '${RESERVED_AGENT_KEY_PREFIX}' prefix.`);
 		const existingGroup = seenIn.get(key);
 		if (existingGroup) throw new Error(`setupAgent: key '${key}' is defined in both '${existingGroup}' and '${groupName}'. Each actor source key must be unique across 'actors' and 'requests'.`);
 		seenIn.set(key, groupName);
@@ -1515,4 +1518,4 @@ function createAgentActors(actors, requestActors) {
 	};
 }
 //#endregion
-export { initialAgentStep as _, AGENT_USAGE_EVENT_TYPE as a, appendMessages as b, createReplayEntry as c, initEntry as d, replay as f, getInvokeEffectMetadata as g, executeAgentRequest as h, AGENT_INIT_EVENT_TYPE as i, diffEventLogs as l, verifyReplay as m, getAgentSchemas as n, AgentReplayDivergenceError as o, validateReplayEntries as p, setupAgent as r, AgentReplayMachineMismatchError as s, createAgentSchemas as t, getAgentEffects as u, resolveAgentStep as v, messagesSchema as x, transitionAgentStep as y };
+export { resolveAgentStep as _, AGENT_USAGE_EVENT_TYPE as a, messagesSchema as b, createReplayEntry as c, initEntry as d, replay as f, initialAgentStep as g, getInvokeEffectMetadata as h, AGENT_INIT_EVENT_TYPE as i, diffEventLogs as l, executeAgentRequest as m, getAgentSchemas as n, AgentReplayDivergenceError as o, validateReplayEntries as p, setupAgent as r, AgentReplayMachineMismatchError as s, createAgentSchemas as t, getAgentEffects as u, transitionAgentStep as v, appendMessages as y };

package/dist/sqlite.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log_store = require("./event-log-store-yquOV1TX.cjs");
+const require_event_log_store = require("./event-log-store-a_TKy1gk.cjs");
 //#region src/sqlite/index.ts
 function openDatabase(path) {
 	const sqlite = process.getBuiltinModule?.("node:sqlite");
@@ -80,18 +80,12 @@ function createSqliteEventLogStore(options) {
 		async length(threadId) {
 			return lengthOf(threadId);
 		},
-		async fork({ threadId, newThreadId, upToIndex, atEventId }) {
-			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
+		async fork({ threadId, newThreadId, upToIndex }) {
 			transact(() => {
 				if (lengthOf(newThreadId) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
 				const sourceLength = lengthOf(threadId);
 				if (sourceLength === 0) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
-				let upTo = upToIndex ?? sourceLength;
-				if (atEventId !== void 0) {
-					const row = db.prepare(`SELECT idx FROM ${table} WHERE thread_id = ? AND entry_id = ?`).get(threadId, atEventId);
-					if (!row) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
-					upTo = Number(row.idx) + 1;
-				}
+				const upTo = upToIndex ?? sourceLength;
 				if (upTo < 0 || upTo > sourceLength) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${sourceLength}) has no index ${upTo} to fork up to.`);
 				db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry)
            SELECT ?, idx, entry_id, entry FROM ${table} WHERE thread_id = ? AND idx < ?`).run(newThreadId, threadId, upTo);

package/dist/sqlite.d.cts

@@ -1,5 +1,5 @@
 import { r as AgentSnapshotStore } from "./types-pJ5Hn8fv.cjs";
-import { r as AgentEventLogStore } from "./event-log-store-CQJq8_v4.cjs";
+import { r as AgentEventLogStore } from "./event-log-store-Bz7HDBkE.cjs";
 
 //#region src/sqlite/index.d.ts
 /** A prepared statement, structurally compatible with `node:sqlite`'s `StatementSync`. */

package/dist/sqlite.d.mts

@@ -1,5 +1,5 @@
 import { r as AgentSnapshotStore } from "./types-DYpK3QF4.mjs";
-import { r as AgentEventLogStore } from "./event-log-store-BrC9Q1xW.mjs";
+import { r as AgentEventLogStore } from "./event-log-store-hrA1vqtN.mjs";
 
 //#region src/sqlite/index.d.ts
 /** A prepared statement, structurally compatible with `node:sqlite`'s `StatementSync`. */

package/dist/sqlite.mjs

@@ -1,4 +1,4 @@
-import { i as assertAgentLogEntry, n as AgentEventLogConflictError } from "./event-log-store-B-1fcfkT.mjs";
+import { i as assertAgentLogEntry, n as AgentEventLogConflictError } from "./event-log-store-DmIDosD6.mjs";
 //#region src/sqlite/index.ts
 function openDatabase(path) {
 	const sqlite = process.getBuiltinModule?.("node:sqlite");
@@ -79,18 +79,12 @@ function createSqliteEventLogStore(options) {
 		async length(threadId) {
 			return lengthOf(threadId);
 		},
-		async fork({ threadId, newThreadId, upToIndex, atEventId }) {
-			if (upToIndex !== void 0 && atEventId !== void 0) throw new Error("AgentEventLogStore.fork: pass either upToIndex or atEventId, not both.");
+		async fork({ threadId, newThreadId, upToIndex }) {
 			transact(() => {
 				if (lengthOf(newThreadId) > 0) throw new Error(`AgentEventLogStore.fork: newThreadId "${newThreadId}" already has entries.`);
 				const sourceLength = lengthOf(threadId);
 				if (sourceLength === 0) throw new Error(`AgentEventLogStore.fork: unknown source thread "${threadId}".`);
-				let upTo = upToIndex ?? sourceLength;
-				if (atEventId !== void 0) {
-					const row = db.prepare(`SELECT idx FROM ${table} WHERE thread_id = ? AND entry_id = ?`).get(threadId, atEventId);
-					if (!row) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" has no event id "${atEventId}".`);
-					upTo = Number(row.idx) + 1;
-				}
+				const upTo = upToIndex ?? sourceLength;
 				if (upTo < 0 || upTo > sourceLength) throw new Error(`AgentEventLogStore.fork: thread "${threadId}" (length ${sourceLength}) has no index ${upTo} to fork up to.`);
 				db.prepare(`INSERT INTO ${table} (thread_id, idx, entry_id, entry)
            SELECT ?, idx, entry_id, entry FROM ${table} WHERE thread_id = ? AND idx < ?`).run(newThreadId, threadId, upTo);

package/dist/{text-logic-VcWqO-Cl.d.cts → text-logic-Cavva1W6.d.cts}

@@ -214,14 +214,17 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * `generateText`/`streamText` — how the model is coerced into choosing
  * (tool-per-event + forced tool choice, structured output, …) is entirely
  * adapter business; core only validates and retries the returned choice (see
- * {@link resolveDecision}). The optional `reason` is carried through to
+ * {@link resolveDecision}). It takes the same `(request, info)` pair as
+ * `generateText`/`streamText` — `info` carries the host seams (`signal`,
+ * `runId`, `requestId`); `onChunk` is never set for a decision.
+ * The optional `reason` is carried through to
  * `onResult`/event-sourcing but never affects validation. Like text
  * executors' `{ output, ...extras }` envelope, any extra keys (finish reason,
  * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
  * report this attempt's tokens there and `runAgent` folds them into the run's
  * aggregated {@link AgentUsage}.
  */
-type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
+type AgentDecisionExecutor = (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
   event: ChosenEvent;
   reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
   usage?: AgentCallUsage;
@@ -252,7 +255,7 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
 }
 /**
  * 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).
  *
@@ -270,12 +273,12 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  *
  * @example
  * ```ts
- * const event = await resolveDecision(request, decide, {
+ * const event = await resolveDecision(request, executors, {
  *   canTake: (e) => snapshot.can(e),
  * });
  * ```
  */
-declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executor: AgentDecisionExecutor, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
+declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
 //#endregion
 //#region src/text-logic.d.ts
 declare const USER_INPUT_ACTOR: "agent.userInput";
@@ -352,12 +355,23 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
   topK?: number;
   seed?: number;
   stopSequences?: string[];
+  /**
+   * Bounds the HOST-side tool-call loop for this one request: the maximum
+   * number of model steps the executor may run before it must return. Omitted
+   * means single-step (one model call, tool results not fed back). Named and
+   * typed to match the AI SDK — the shipped adapter lowers it to
+   * `stopWhen: stepCountIs(maxSteps)`.
+   *
+   * This is a REQUEST budget, distinct from the machine-level `maxTurns` a
+   * preset uses for its own turn budget, and from `runAgent`'s run-wide
+   * `maxModelCalls`.
+   */
+  maxSteps?: number;
   /**
    * Host-owned per-call options. Use this for provider/runtime details such
    * as Cloudflare bindings, tracing IDs, SDK provider options, or transport
-   * hints. The machine carries it; the host decides what it means — e.g.
-   * the AI SDK adapter (`createAiSdkExecutors`) reads `metadata.maxSteps` to
-   * bound its multi-step tool-call loop for that request.
+   * hints. The machine carries it; the host decides what it means. Not the
+   * place for `maxSteps` any more — that is a typed field above.
    */
   metadata?: TMetadata;
 }
@@ -473,6 +487,8 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
   topK?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   seed?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
+  /** Bounds this request's host-side tool loop (see {@link AgentTextRequest.maxSteps}). */
+  maxSteps?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
 /** Arguments passed to a {@link TextLogicExecutor}: the typed input, the lowered {@link AgentTextRequest}, and the actor's own `signal`/`system`/`self`/`emit`. */

package/dist/{text-logic-RvnlD-An.d.mts → text-logic-Er5KkTX6.d.mts}

@@ -214,14 +214,17 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * `generateText`/`streamText` — how the model is coerced into choosing
  * (tool-per-event + forced tool choice, structured output, …) is entirely
  * adapter business; core only validates and retries the returned choice (see
- * {@link resolveDecision}). The optional `reason` is carried through to
+ * {@link resolveDecision}). It takes the same `(request, info)` pair as
+ * `generateText`/`streamText` — `info` carries the host seams (`signal`,
+ * `runId`, `requestId`); `onChunk` is never set for a decision.
+ * The optional `reason` is carried through to
  * `onResult`/event-sourcing but never affects validation. Like text
  * executors' `{ output, ...extras }` envelope, any extra keys (finish reason,
  * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
  * report this attempt's tokens there and `runAgent` folds them into the run's
  * aggregated {@link AgentUsage}.
  */
-type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
+type AgentDecisionExecutor = (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
   event: ChosenEvent;
   reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
   usage?: AgentCallUsage;
@@ -252,7 +255,7 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
 }
 /**
  * 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).
  *
@@ -270,12 +273,12 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  *
  * @example
  * ```ts
- * const event = await resolveDecision(request, decide, {
+ * const event = await resolveDecision(request, executors, {
  *   canTake: (e) => snapshot.can(e),
  * });
  * ```
  */
-declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executor: AgentDecisionExecutor, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
+declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
 //#endregion
 //#region src/text-logic.d.ts
 declare const USER_INPUT_ACTOR: "agent.userInput";
@@ -352,12 +355,23 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
   topK?: number;
   seed?: number;
   stopSequences?: string[];
+  /**
+   * Bounds the HOST-side tool-call loop for this one request: the maximum
+   * number of model steps the executor may run before it must return. Omitted
+   * means single-step (one model call, tool results not fed back). Named and
+   * typed to match the AI SDK — the shipped adapter lowers it to
+   * `stopWhen: stepCountIs(maxSteps)`.
+   *
+   * This is a REQUEST budget, distinct from the machine-level `maxTurns` a
+   * preset uses for its own turn budget, and from `runAgent`'s run-wide
+   * `maxModelCalls`.
+   */
+  maxSteps?: number;
   /**
    * Host-owned per-call options. Use this for provider/runtime details such
    * as Cloudflare bindings, tracing IDs, SDK provider options, or transport
-   * hints. The machine carries it; the host decides what it means — e.g.
-   * the AI SDK adapter (`createAiSdkExecutors`) reads `metadata.maxSteps` to
-   * bound its multi-step tool-call loop for that request.
+   * hints. The machine carries it; the host decides what it means. Not the
+   * place for `maxSteps` any more — that is a typed field above.
    */
   metadata?: TMetadata;
 }
@@ -473,6 +487,8 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
   topK?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   seed?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
+  /** Bounds this request's host-side tool loop (see {@link AgentTextRequest.maxSteps}). */
+  maxSteps?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
 /** Arguments passed to a {@link TextLogicExecutor}: the typed input, the lowered {@link AgentTextRequest}, and the actor's own `signal`/`system`/`self`/`emit`. */