@statelyai/agent 2.0.0-alpha.30 → 2.0.0-alpha.31

package/dist/{usage-BkM3z02Y.d.mts → usage-BYqv7VBw.d.cts}

@@ -1,4 +1,4 @@
-import { t as AgentCallUsage } from "./text-logic-BRYOPWvY.mjs";
+import { t as AgentCallUsage } from "./text-logic-j9hShB7d.cjs";
 import { EventObject } from "xstate";
 //#region src/usage.d.ts
 /** Reserved event delivered after a model call reports token usage. */

package/dist/{usage-Cm_ovz9V.d.cts → usage-Bl4nK8D-.d.mts}

@@ -1,4 +1,4 @@
-import { t as AgentCallUsage } from "./text-logic-DmciuVUQ.cjs";
+import { t as AgentCallUsage } from "./text-logic-BwdrDpO9.mjs";
 import { EventObject } from "xstate";
 //#region src/usage.d.ts
 /** Reserved event delivered after a model call reports token usage. */

package/dist/validate.cjs

@@ -21,9 +21,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_setup_agent = require("./setup-agent-DoUk7EdC.cjs");
-const require_verify = require("./verify-CVlsTZ-V.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_setup_agent = require("./setup-agent-D0L8Anl_.cjs");
+const require_verify = require("./verify-CS_xxvVU.cjs");
 let ajv_dist_2020_js = require("ajv/dist/2020.js");
 ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
 //#region schemas/agent-workflow.json

package/dist/validate.d.cts

@@ -1,5 +1,5 @@
-import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-CLPCkXsu.cjs";
-import { l as ExplorePathsOptions } from "./verify-Dzwd4Mvk.cjs";
+import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-yFFVXf5s.cjs";
+import { u as ExplorePathsOptions } from "./verify-CPKDPMwY.cjs";
 import { AnyActorLogic, AnyStateMachine } from "xstate";
 //#region src/validate/validate-config.d.ts
 /**

package/dist/validate.d.mts

@@ -1,5 +1,5 @@
-import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-CGELn1qZ.mjs";
-import { l as ExplorePathsOptions } from "./verify-Cn86rT8l.mjs";
+import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-CPyg2ic7.mjs";
+import { u as ExplorePathsOptions } from "./verify-tkymWz6X.mjs";
 import { AnyActorLogic, AnyStateMachine } from "xstate";
 //#region src/validate/validate-config.d.ts
 /**

package/dist/validate.mjs

@@ -1,6 +1,6 @@
-import { D as STREAM_TEXT_ACTOR, E as GENERATE_TEXT_ACTOR, T as DECIDE_ACTOR } from "./event-log-DJCMHek_.mjs";
-import { i as setupAgentFromConfig } from "./setup-agent-7rV_cujV.mjs";
-import { a as explorePaths, o as lintAgentMachine } from "./verify-COFWyprJ.mjs";
+import { D as STREAM_TEXT_ACTOR, E as GENERATE_TEXT_ACTOR, T as DECIDE_ACTOR } from "./event-log-DE430ZCa.mjs";
+import { i as setupAgentFromConfig } from "./setup-agent-BaffhCcM.mjs";
+import { a as explorePaths, o as lintAgentMachine } from "./verify-BH5e0XLK.mjs";
 import Ajv2020 from "ajv/dist/2020.js";
 //#region schemas/agent-workflow.json
 var agent_workflow_default = {

package/dist/{verify-COFWyprJ.mjs → verify-BH5e0XLK.mjs}

@@ -1,6 +1,6 @@
-import { P as isTextLogic, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, X as getJsonSchemaSync, st as AgentError } from "./event-log-DJCMHek_.mjs";
-import { d as getAcceptedEvents, l as resolveDecision, m as isRecord, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-BHkvuImD.mjs";
-import { getNextTransitions, initialTransition, transition } from "xstate";
+import { P as isTextLogic, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, X as getJsonSchemaSync, lt as isRecord, ut as AgentError } from "./event-log-DE430ZCa.mjs";
+import { d as getAcceptedEvents, f as getHumanEventTypes, l as resolveDecision, n as acceptedDecisionOptions, p as isEventPattern, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-DqO018Tp.mjs";
+import { getNextTransitions, initialTransition, machineToJSON, transition } from "xstate";
 //#region src/steps.ts
 /**
 * Internal: the pure `(state, event) => (nextState, requests)` view of an
@@ -79,12 +79,15 @@ function getAgentRequests(actions, { machine, ...options } = {}) {
 			const events = options.snapshot ? getAcceptedEvents(options.snapshot, {
 				events: options.events,
 				schemas: options.schemas,
-				eventTypes: allowedEventTypes
+				eventTypes: allowedEventTypes,
+				actor: "agent"
 			}) : [];
+			const humanEventTypes = options.snapshot ? getHumanEventTypes(options.snapshot) : /* @__PURE__ */ new Set();
 			return [{
 				...decisionRequest,
 				id: params.id,
-				events
+				events,
+				...decisionRequest.options ? { options: decisionRequest.options.filter((option) => !humanEventTypes.has(option.event.type)) } : {}
 			}];
 		}
 		const textLogic = isTextLogic(registeredLogic) ? registeredLogic : void 0;
@@ -335,6 +338,45 @@ function checkDecideWithoutEvents(ctx) {
 	}
 	return out;
 }
+function literalAllowedEvents(json, path, index) {
+	let node = json;
+	for (const key of path.split(".")) node = node?.states?.[key];
+	let input = normalizeInvokes(node?.invoke)[index]?.input;
+	if (isRecord(input) && typeof input["@expr"] === "string") try {
+		input = JSON.parse(input["@expr"]);
+	} catch {
+		return;
+	}
+	const allowedEvents = isRecord(input) ? input.allowedEvents : void 0;
+	return typeof allowedEvents === "string" ? [allowedEvents] : Array.isArray(allowedEvents) ? allowedEvents : void 0;
+}
+function handlesAsHuman(config, eventType) {
+	const transitions = config.on?.[eventType];
+	return (Array.isArray(transitions) ? transitions : [transitions]).some((transition) => !!transition && typeof transition === "object" && transition.meta?.actor === "human");
+}
+function checkDecideAllowsHumanEvent(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const [index, invoke] of node.invokes.entries()) {
+		if (!isDecisionInvoke(invoke.src, ctx.actors)) continue;
+		const allowedEvents = literalAllowedEvents(ctx.json, node.path, index);
+		if (!allowedEvents) continue;
+		const configs = [
+			node.config,
+			...ancestorChain(node, ctx.index).map((ancestor) => ancestor.config),
+			ctx.config
+		];
+		for (const type of allowedEvents) {
+			if (typeof type !== "string" || isEventPattern(type) || !configs.some((config) => handlesAsHuman(config, type))) continue;
+			out.push({
+				code: "decide-allows-human-event",
+				severity: "error",
+				path: node.path,
+				message: `State '${node.path}' lets a decision choose '${type}', but a transition tagged 'meta: { actor: "human" }' handles it, so the model is never offered it. Remove '${type}' from 'allowedEvents', or drop the tag if a model may send it.`
+			});
+		}
+	}
+	return out;
+}
 function checkDirectObjectSrc(ctx) {
 	const out = [];
 	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
@@ -371,6 +413,7 @@ function checkInvokeWithoutOnError(ctx) {
 }
 const LINT_CHECKS = [
 	checkDecideWithoutEvents,
+	checkDecideAllowsHumanEvent,
 	checkDirectObjectSrc,
 	checkInvokeWithoutOnError
 ];
@@ -408,8 +451,15 @@ function lintAgentMachine(machine, options = {}) {
 	const config = machine.config ?? {};
 	const index = buildStateIndex(config);
 	const registered = getRegisteredAgentExecutionOptions(machine);
+	let json;
+	try {
+		json = machineToJSON(machine);
+	} catch {
+		json = void 0;
+	}
 	const ctx = {
 		config,
+		json,
 		index,
 		schemas: registered.schemas,
 		actors: registered.actors ?? machine.sources?.actors ?? {}

package/dist/{verify-Dzwd4Mvk.d.cts → verify-CPKDPMwY.d.cts}

@@ -1,5 +1,5 @@
 import { u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
-import { Q as AgentError } from "./text-logic-DmciuVUQ.cjs";
+import { Q as AgentError } from "./text-logic-j9hShB7d.cjs";
 import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
 //#region src/verify.d.ts
 /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
@@ -10,7 +10,7 @@ type AgentLintSeverity = "error" | "warning";
  * or config location, and `message` explains the problem and its remedy.
  */
 interface AgentLintDiagnostic {
-  code: "decide-without-events" | "direct-object-src" | "invoke-without-on-error";
+  code: "decide-without-events" | "decide-allows-human-event" | "direct-object-src" | "invoke-without-on-error";
   severity: AgentLintSeverity;
   /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
   path: string;
@@ -212,6 +212,14 @@ interface SimulateAgentResult {
  */
 declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
 /** Options for {@link explorePaths}. */
+/**
+ * The snapshot type the exploration callbacks (`payloads`, `dedupeBy`, a
+ * `canReach` predicate) receive. Import it from here rather than from your
+ * own `xstate`, which can be another version than the one this package uses.
+ */
+type ExploreSnapshot = AnyMachineSnapshot;
+/** What {@link canReach} looks for: a state id or path, or a snapshot predicate. */
+type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean);
 interface ExplorePathsOptions {
   input?: unknown;
   /** Max branch points (decisions + external-event forks) along any path. Default 8. */
@@ -274,7 +282,7 @@ interface ExplorePathsOptions {
    * were not all tried, so it is listed in `unexpandedEvents`. A type with no
    * schema at all is applied as `{ type }`.
    */
-  payloads?: (snapshot: AnyMachineSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
+  payloads?: (snapshot: ExploreSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
   /**
    * A projection of the snapshot that determines its future. Settled
    * snapshots with an equal key are explored once (again only when reached
@@ -283,7 +291,7 @@ interface ExplorePathsOptions {
    * a key that drops a field the machine reads makes the search unsound.
    * Without it, every path is explored in full.
    */
-  dedupeBy?: (snapshot: AnyMachineSnapshot) => string;
+  dedupeBy?: (snapshot: ExploreSnapshot) => string;
 }
 /** A single explored path's terminal outcome. */
 interface AgentPathTerminal {
@@ -409,6 +417,6 @@ declare class AgentUnknownStateError extends AgentError {
  * // violation.reachable → false is the safety proof
  * ```
  */
-declare function canReach(machine: AnyStateMachine, target: string | ((snapshot: AnyMachineSnapshot) => boolean), options?: ExplorePathsOptions): Promise<CanReachResult>;
+declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
-export { explorePaths as _, AgentPathTerminal as a, CanReachResult as c, SimulateAgentOptions as d, SimulateAgentResult as f, canReach as g, assertAgentMachine as h, AgentPathReport as i, ExplorePathsOptions as l, SimulationTrailEntry as m, AgentLintError as n, AgentUnknownStateError as o, SimulationScript as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, LintAgentMachineOptions as u, lintAgentMachine as v, simulateAgent as y };
+export { assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };

package/dist/{verify-CVlsTZ-V.cjs → verify-CS_xxvVU.cjs}

@@ -1,5 +1,5 @@
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_decision = require("./decision-CIb7ddIv.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
 let xstate = require("xstate");
 //#region src/steps.ts
 /**
@@ -79,12 +79,15 @@ function getAgentRequests(actions, { machine, ...options } = {}) {
 			const events = options.snapshot ? require_decision.getAcceptedEvents(options.snapshot, {
 				events: options.events,
 				schemas: options.schemas,
-				eventTypes: allowedEventTypes
+				eventTypes: allowedEventTypes,
+				actor: "agent"
 			}) : [];
+			const humanEventTypes = options.snapshot ? require_decision.getHumanEventTypes(options.snapshot) : /* @__PURE__ */ new Set();
 			return [{
 				...decisionRequest,
 				id: params.id,
-				events
+				events,
+				...decisionRequest.options ? { options: decisionRequest.options.filter((option) => !humanEventTypes.has(option.event.type)) } : {}
 			}];
 		}
 		const textLogic = require_event_log.isTextLogic(registeredLogic) ? registeredLogic : void 0;
@@ -335,6 +338,45 @@ function checkDecideWithoutEvents(ctx) {
 	}
 	return out;
 }
+function literalAllowedEvents(json, path, index) {
+	let node = json;
+	for (const key of path.split(".")) node = node?.states?.[key];
+	let input = normalizeInvokes(node?.invoke)[index]?.input;
+	if (require_event_log.isRecord(input) && typeof input["@expr"] === "string") try {
+		input = JSON.parse(input["@expr"]);
+	} catch {
+		return;
+	}
+	const allowedEvents = require_event_log.isRecord(input) ? input.allowedEvents : void 0;
+	return typeof allowedEvents === "string" ? [allowedEvents] : Array.isArray(allowedEvents) ? allowedEvents : void 0;
+}
+function handlesAsHuman(config, eventType) {
+	const transitions = config.on?.[eventType];
+	return (Array.isArray(transitions) ? transitions : [transitions]).some((transition) => !!transition && typeof transition === "object" && transition.meta?.actor === "human");
+}
+function checkDecideAllowsHumanEvent(ctx) {
+	const out = [];
+	for (const node of ctx.index.values()) for (const [index, invoke] of node.invokes.entries()) {
+		if (!isDecisionInvoke(invoke.src, ctx.actors)) continue;
+		const allowedEvents = literalAllowedEvents(ctx.json, node.path, index);
+		if (!allowedEvents) continue;
+		const configs = [
+			node.config,
+			...ancestorChain(node, ctx.index).map((ancestor) => ancestor.config),
+			ctx.config
+		];
+		for (const type of allowedEvents) {
+			if (typeof type !== "string" || require_decision.isEventPattern(type) || !configs.some((config) => handlesAsHuman(config, type))) continue;
+			out.push({
+				code: "decide-allows-human-event",
+				severity: "error",
+				path: node.path,
+				message: `State '${node.path}' lets a decision choose '${type}', but a transition tagged 'meta: { actor: "human" }' handles it, so the model is never offered it. Remove '${type}' from 'allowedEvents', or drop the tag if a model may send it.`
+			});
+		}
+	}
+	return out;
+}
 function checkDirectObjectSrc(ctx) {
 	const out = [];
 	for (const node of ctx.index.values()) for (const invoke of node.invokes) {
@@ -371,6 +413,7 @@ function checkInvokeWithoutOnError(ctx) {
 }
 const LINT_CHECKS = [
 	checkDecideWithoutEvents,
+	checkDecideAllowsHumanEvent,
 	checkDirectObjectSrc,
 	checkInvokeWithoutOnError
 ];
@@ -408,8 +451,15 @@ function lintAgentMachine(machine, options = {}) {
 	const config = machine.config ?? {};
 	const index = buildStateIndex(config);
 	const registered = require_event_log.getRegisteredAgentExecutionOptions(machine);
+	let json;
+	try {
+		json = (0, xstate.machineToJSON)(machine);
+	} catch {
+		json = void 0;
+	}
 	const ctx = {
 		config,
+		json,
 		index,
 		schemas: registered.schemas,
 		actors: registered.actors ?? machine.sources?.actors ?? {}
@@ -716,7 +766,7 @@ const MAX_ADVANCE_STEPS = 1e3;
 const FINITE_PAYLOAD_CAP = 64;
 const DEFAULT_MAX_NODES = 1e5;
 function finiteDomain(schema) {
-	if (!require_decision.isRecord(schema)) return;
+	if (!require_event_log.isRecord(schema)) return;
 	if ("const" in schema) return [schema["const"]];
 	if (Array.isArray(schema["enum"])) return schema["enum"];
 	const union = schema["anyOf"] ?? schema["oneOf"];
@@ -733,8 +783,8 @@ function finitePayloads(jsonSchema) {
 		payloads: [{}],
 		complete: false
 	};
-	if (!require_decision.isRecord(jsonSchema) || jsonSchema["type"] !== "object" && !require_decision.isRecord(jsonSchema["properties"])) return bare;
-	const properties = require_decision.isRecord(jsonSchema["properties"]) ? jsonSchema["properties"] : {};
+	if (!require_event_log.isRecord(jsonSchema) || jsonSchema["type"] !== "object" && !require_event_log.isRecord(jsonSchema["properties"])) return bare;
+	const properties = require_event_log.isRecord(jsonSchema["properties"]) ? jsonSchema["properties"] : {};
 	const required = new Set(Array.isArray(jsonSchema["required"]) ? jsonSchema["required"] : []);
 	if ([...required].some((key) => key !== "type" && !(key in properties))) return bare;
 	let product = [{}];

package/dist/{verify-Cn86rT8l.d.mts → verify-tkymWz6X.d.mts}

@@ -1,5 +1,5 @@
 import { u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
-import { Q as AgentError } from "./text-logic-BRYOPWvY.mjs";
+import { Q as AgentError } from "./text-logic-BwdrDpO9.mjs";
 import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
 //#region src/verify.d.ts
 /** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
@@ -10,7 +10,7 @@ type AgentLintSeverity = "error" | "warning";
  * or config location, and `message` explains the problem and its remedy.
  */
 interface AgentLintDiagnostic {
-  code: "decide-without-events" | "direct-object-src" | "invoke-without-on-error";
+  code: "decide-without-events" | "decide-allows-human-event" | "direct-object-src" | "invoke-without-on-error";
   severity: AgentLintSeverity;
   /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
   path: string;
@@ -212,6 +212,14 @@ interface SimulateAgentResult {
  */
 declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
 /** Options for {@link explorePaths}. */
+/**
+ * The snapshot type the exploration callbacks (`payloads`, `dedupeBy`, a
+ * `canReach` predicate) receive. Import it from here rather than from your
+ * own `xstate`, which can be another version than the one this package uses.
+ */
+type ExploreSnapshot = AnyMachineSnapshot;
+/** What {@link canReach} looks for: a state id or path, or a snapshot predicate. */
+type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean);
 interface ExplorePathsOptions {
   input?: unknown;
   /** Max branch points (decisions + external-event forks) along any path. Default 8. */
@@ -274,7 +282,7 @@ interface ExplorePathsOptions {
    * were not all tried, so it is listed in `unexpandedEvents`. A type with no
    * schema at all is applied as `{ type }`.
    */
-  payloads?: (snapshot: AnyMachineSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
+  payloads?: (snapshot: ExploreSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
   /**
    * A projection of the snapshot that determines its future. Settled
    * snapshots with an equal key are explored once (again only when reached
@@ -283,7 +291,7 @@ interface ExplorePathsOptions {
    * a key that drops a field the machine reads makes the search unsound.
    * Without it, every path is explored in full.
    */
-  dedupeBy?: (snapshot: AnyMachineSnapshot) => string;
+  dedupeBy?: (snapshot: ExploreSnapshot) => string;
 }
 /** A single explored path's terminal outcome. */
 interface AgentPathTerminal {
@@ -409,6 +417,6 @@ declare class AgentUnknownStateError extends AgentError {
  * // violation.reachable → false is the safety proof
  * ```
  */
-declare function canReach(machine: AnyStateMachine, target: string | ((snapshot: AnyMachineSnapshot) => boolean), options?: ExplorePathsOptions): Promise<CanReachResult>;
+declare function canReach(machine: AnyStateMachine, target: CanReachTarget, options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
-export { explorePaths as _, AgentPathTerminal as a, CanReachResult as c, SimulateAgentOptions as d, SimulateAgentResult as f, canReach as g, assertAgentMachine as h, AgentPathReport as i, ExplorePathsOptions as l, SimulationTrailEntry as m, AgentLintError as n, AgentUnknownStateError as o, SimulationScript as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, LintAgentMachineOptions as u, lintAgentMachine as v, simulateAgent as y };
+export { assertAgentMachine as _, AgentPathTerminal as a, lintAgentMachine as b, CanReachResult as c, ExploreSnapshot as d, LintAgentMachineOptions as f, SimulationTrailEntry as g, SimulationScript as h, AgentPathReport as i, CanReachTarget as l, SimulateAgentResult as m, AgentLintError as n, AgentUnknownStateError as o, SimulateAgentOptions as p, AgentLintSeverity as r, AssertAgentMachineOptions as s, AgentLintDiagnostic as t, ExplorePathsOptions as u, canReach as v, simulateAgent as x, explorePaths as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.30",
+  "version": "2.0.0-alpha.31",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -21,12 +21,41 @@
   "files": [
     "dist",
     "schemas",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "ai-sdk": [
+        "./dist/ai-sdk.d.mts"
+      ],
+      "log": [
+        "./dist/log.d.mts"
+      ],
+      "machines": [
+        "./dist/machines.d.mts"
+      ],
+      "openai": [
+        "./dist/openai.d.mts"
+      ],
+      "otel": [
+        "./dist/otel.d.mts"
+      ],
+      "tanstack-ai": [
+        "./dist/tanstack-ai.d.mts"
+      ],
+      "testing": [
+        "./dist/testing.d.mts"
+      ],
+      "validate": [
+        "./dist/validate.d.mts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "import": {
@@ -132,6 +161,7 @@
     "@langchain/core": "^1.2.17",
     "@langchain/openai": "^1.6.2",
     "@mastra/core": "^1.75.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.12.0",
     "@opentelemetry/sdk-trace-base": "^2.12.0",
@@ -159,7 +189,7 @@
   "peerDependencies": {
     "@opentelemetry/api": "^1",
     "@tanstack/ai": ">=0.66.0 <1",
-    "ai": "^7.0.0",
+    "ai": "^7.0.128",
     "ajv": "^8.20.0",
     "openai": ">=5.0.0 <8",
     "xstate": "6.0.0-alpha.69"
@@ -182,7 +212,7 @@
     }
   },
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsdown",

package/readme.md

@@ -14,18 +14,18 @@ Environment and policy:
 
 - The environment is code you own and can verify; the policy is something a model can write inside it.
 - The environment holds the rules and invariants as TypeScript states and guards, fixed and checked with `canReach`.
-- The policy is a JSON machine a model can author and improve from traces, gated before it runs and promoted only on a measured gain. See [Environment and policy](docs/environment-and-policy.md).
+- The policy is a JSON machine a model can author and improve from traces, gated before it runs and promoted only on a measured gain. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md).
 
 Stately Agent 2 is in alpha. APIs may change before the stable release.
 
-[Documentation](https://stately.ai/docs/packages/agent) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
+[Documentation](https://stately.ai/docs/packages/agent) · [Examples](https://github.com/statelyai/agent/blob/next/examples/README.md) · [XState](https://github.com/statelyai/xstate)
 
 ## Four starting points
 
-- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.md).
-- **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](docs/from-a-loop.md).
-- **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](docs/patterns.md).
-- **Let an agent improve its own logic.** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](docs/environment-and-policy.md) and the [`improve-machine` skill](skills/improve-machine/SKILL.md).
+- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](https://github.com/statelyai/agent/blob/next/docs/quickstart.md) and [Use in any stack](https://github.com/statelyai/agent/blob/next/docs/any-stack.md).
+- **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md).
+- **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](https://github.com/statelyai/agent/blob/next/docs/patterns.md).
+- **Let an agent improve its own logic.** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md).
 
 ## Install
 
@@ -40,7 +40,7 @@ XState is pinned while its experimental durable restoration API evolves.
 For the optional Vercel AI SDK executor:
 
 ```sh
-pnpm add ai@^7 @ai-sdk/openai@^4
+pnpm add ai@^7.0.128 @ai-sdk/openai@^4
 ```
 
 For the optional raw OpenAI SDK executor (`@statelyai/agent/openai`):
@@ -55,13 +55,43 @@ For the optional TanStack AI executor (`@statelyai/agent/tanstack-ai`):
 pnpm add @tanstack/ai @tanstack/ai-openai
 ```
 
-Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_decide` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](docs/judgments.md).
+Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_decide` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](https://github.com/statelyai/agent/blob/next/docs/judgments.md).
+
+Upgrading from an earlier alpha: see [Upgrading between alphas](https://github.com/statelyai/agent/blob/next/docs/upgrading.md). Every release's notes are in `CHANGELOG.md`, which ships in the package.
 
 Requirements:
 
-- Node 22.18 or newer, and XState `6.0.0-alpha.69`.
-- The package is ESM-first. CommonJS builds are published too, so `require()` works.
-- Provider packages must match your `ai` major: `@ai-sdk/openai@^4` pairs with `ai@^7`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer.
+- Node 22 or newer, and XState exactly `6.0.0-alpha.69`.
+- TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
+- A [Standard Schema](https://standardschema.dev) library: zod 4, zod 3.24 or newer, Valibot, or ArkType. `setupAgent` throws `invalid-schema` for zod 3.23 and earlier.
+- The package is ESM-first. CommonJS builds are published too, so `require()` works. Subpath imports (`@statelyai/agent/testing`) resolve under every `moduleResolution`, including `node`.
+- `@statelyai/agent/ai-sdk` needs `ai` 7.0.128 or newer. Provider packages must match your `ai` major: `@ai-sdk/openai@^4` pairs with `ai@^7`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer. `@statelyai/agent/openai` needs `openai` 5 or newer.
+
+An app that already uses XState 4 or 5 keeps it: put the agent in its own workspace package. See [Use in an XState 4 or 5 app](https://github.com/statelyai/agent/blob/next/docs/xstate-4-and-5-apps.md). If both versions land in one `node_modules`, the package fails with errors that do not mention a version:
+
+| Error | Cause |
+| --- | --- |
+| `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
+| `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
+| `unmet peer dependency "xstate@6.0.0-alpha.69"` (pnpm, npm) or `has incorrect peer dependency "xstate@6.0.0-alpha.69"` (yarn 1) | The install's only warning of the two above |
+
+## Agent skills
+
+The package ships agent skills in `node_modules/@statelyai/agent/skills/`. Copy them into your coding agent's skills directory (for Claude Code, `.claude/skills/`):
+
+```sh
+mkdir -p .claude/skills
+cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
+```
+
+| Skill | What it does |
+| --- | --- |
+| [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
+| [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
+| [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
+| [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
+| [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
+| [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) | Improves a policy from traces and hands the change to a person as a pull request |
 
 ## Quick start
 
@@ -159,11 +189,11 @@ const liveResult = await runAgent(refundMachine, {
 });
 ```
 
-`createAiSdkExecutors(refundMachine)` reads the `models` declared in `setupAgent({ models })`, which also type the machine's model refs. `createAiSdkExecutors({ models })` still works when the host owns the map. Executors are always explicit, and core does not import the AI SDK. See [Models and providers](docs/models-and-providers.md) and [Hosts and executors](docs/hosts.md).
+`createAiSdkExecutors(refundMachine)` reads the `models` declared in `setupAgent({ models })`, which also type the machine's model refs. `createAiSdkExecutors({ models })` still works when the host owns the map. Executors are always explicit, and core does not import the AI SDK. See [Models and providers](https://github.com/statelyai/agent/blob/next/docs/models-and-providers.md) and [Hosts and executors](https://github.com/statelyai/agent/blob/next/docs/hosts.md).
 
-For a machine with several requests, the executor routes on `request.name`, or `MockLanguageModelV3` from `ai/test` stands in for the provider behind `createAiSdkExecutors`. See [Evals](docs/evals.md#testing-without-a-provider).
+For a machine with several requests, the executor routes on `request.name`, or `MockLanguageModelV3` from `ai/test` stands in for the provider behind `createAiSdkExecutors`. See [Evals](https://github.com/statelyai/agent/blob/next/docs/evals.md#testing-without-a-provider).
 
-A host that needs the transition loop itself (a durable object, events pushed mid-run, a custom checkpoint policy) uses `createAgentRuntime` directly. See [Write your own host loop](docs/hosts.md#write-your-own-host-loop).
+A host that needs the transition loop itself (a durable object, events pushed mid-run, a custom checkpoint policy) uses `createAgentRuntime` directly. See [Write your own host loop](https://github.com/statelyai/agent/blob/next/docs/hosts.md#write-your-own-host-loop).
 
 ## Architecture
 
@@ -181,38 +211,38 @@ The machine never talks to a model directly, so swapping `createAiSdkExecutors`
 
 The example above has one model decision and two final outcomes. Real machines add approval states, retries, parallel work, child agents, and long-running waits without changing how control flow is represented.
 
-The core concepts (machines owning control flow, bounded model decisions, typed requests, host-run executors, and native XState snapshots) are in the [documentation overview](docs/index.md).
+The core concepts (machines owning control flow, bounded model decisions, typed requests, host-run executors, and native XState snapshots) are in the [documentation overview](https://github.com/statelyai/agent/blob/next/docs/index.md).
 
 ## Examples
 
 <!-- starter examples derived from examples/*/metadata.json and examples/index.ts -->
 
-- [Twenty Questions](examples/twenty-questions) shows a model choosing legal events in a loop.
-- [Chameleon](examples/chameleon) combines hidden information, sequential turns, and a human vote.
-- [Snapshot migration](examples/snapshot-migration) uses XState's native `version` and `migrate` contract.
-- [Portable XState loop](examples/portable-xstate-loop) runs the artifact through native transitions and effects.
-- [Application-owned storage](examples/file-snapshot-store) persists native XState snapshots in application code.
-- [Tool calling](examples/review-tool-calls) keeps tools and message history in the AI SDK's native format.
-- [Ticket triage](examples/triage) returns structured data from a model request.
-- [JSON agent](examples/json-agent) runs a machine defined as data.
+- [Twenty Questions](https://github.com/statelyai/agent/tree/next/examples/twenty-questions) shows a model choosing legal events in a loop.
+- [Chameleon](https://github.com/statelyai/agent/tree/next/examples/chameleon) combines hidden information, sequential turns, and a human vote.
+- [Snapshot migration](https://github.com/statelyai/agent/tree/next/examples/snapshot-migration) uses XState's native `version` and `migrate` contract.
+- [Portable XState loop](https://github.com/statelyai/agent/tree/next/examples/portable-xstate-loop) runs the artifact through native transitions and effects.
+- [Application-owned storage](https://github.com/statelyai/agent/tree/next/examples/file-snapshot-store) persists native XState snapshots in application code.
+- [Tool calling](https://github.com/statelyai/agent/tree/next/examples/review-tool-calls) keeps tools and message history in the AI SDK's native format.
+- [Ticket triage](https://github.com/statelyai/agent/tree/next/examples/triage) returns structured data from a model request.
+- [JSON agent](https://github.com/statelyai/agent/tree/next/examples/json-agent) runs a machine defined as data.
 
-See [all examples](examples/README.md).
+See [all examples](https://github.com/statelyai/agent/blob/next/examples/README.md).
 
 ## Related
 
-- [Machines](docs/machines.md)
-- [Text requests](docs/text-requests.md)
-- [Decisions](docs/decisions.md)
-- [Human in the loop](docs/human-in-the-loop.md)
-- [Testing and verification](docs/verify.md)
-- [Evals](docs/evals.md)
-- [Generating machines with an LLM](docs/generate-machines.md)
-- [Hosts and executors](docs/hosts.md)
-- [Models and providers](docs/models-and-providers.md)
-- [Use in any stack](docs/any-stack.md)
-- [Persistence](docs/persistence.md)
-- [Observability](docs/observability.md)
-- [Usage and budgets](docs/usage-and-budgets.md)
-- [Agent patterns](docs/patterns.md)
-- [Migrating from a hand-rolled loop](docs/from-a-loop.md)
-- [Coming from LangGraph](docs/langgraph-comparison.md)
+- [Machines](https://github.com/statelyai/agent/blob/next/docs/machines.md)
+- [Text requests](https://github.com/statelyai/agent/blob/next/docs/text-requests.md)
+- [Decisions](https://github.com/statelyai/agent/blob/next/docs/decisions.md)
+- [Human in the loop](https://github.com/statelyai/agent/blob/next/docs/human-in-the-loop.md)
+- [Testing and verification](https://github.com/statelyai/agent/blob/next/docs/verify.md)
+- [Evals](https://github.com/statelyai/agent/blob/next/docs/evals.md)
+- [Generating machines with an LLM](https://github.com/statelyai/agent/blob/next/docs/generate-machines.md)
+- [Hosts and executors](https://github.com/statelyai/agent/blob/next/docs/hosts.md)
+- [Models and providers](https://github.com/statelyai/agent/blob/next/docs/models-and-providers.md)
+- [Use in any stack](https://github.com/statelyai/agent/blob/next/docs/any-stack.md)
+- [Persistence](https://github.com/statelyai/agent/blob/next/docs/persistence.md)
+- [Observability](https://github.com/statelyai/agent/blob/next/docs/observability.md)
+- [Usage and budgets](https://github.com/statelyai/agent/blob/next/docs/usage-and-budgets.md)
+- [Agent patterns](https://github.com/statelyai/agent/blob/next/docs/patterns.md)
+- [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md)
+- [Coming from LangGraph](https://github.com/statelyai/agent/blob/next/docs/langgraph-comparison.md)