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

package/dist/testing.mjs

@@ -1,7 +1,6 @@
-import { $ as getStateMeta, F as normalizeGeneratorResult, N as getCallUsage, st as AgentError } from "./event-log-GPZO9p7_.mjs";
-import { m as isRecord } from "./decision-Bl_rKQnU.mjs";
-import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-CuQT1xSS.mjs";
-import { a as explorePaths, i as canReach, n as AgentUnknownStateError, o as lintAgentMachine, r as assertAgentMachine, s as simulateAgent, t as AgentLintError } from "./verify-B5qGC5WN.mjs";
+import { $ as getStateMeta, F as normalizeGeneratorResult, N as getCallUsage, lt as isRecord, ut as AgentError } from "./event-log-DE430ZCa.mjs";
+import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-DWZ1uyBJ.mjs";
+import { a as explorePaths, i as canReach, n as AgentUnknownStateError, o as lintAgentMachine, r as assertAgentMachine, s as simulateAgent, t as AgentLintError } from "./verify-BH5e0XLK.mjs";
 //#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
@@ -320,7 +319,7 @@ async function runSeam(machine, options) {
 			...event ? { event } : {}
 		});
 		if (result.status !== "idle" || turn === maxTurns) break;
-		const next = options.respond?.({
+		const next = await options.respond?.({
 			snapshot: result.snapshot,
 			state: result.snapshot.value,
 			meta: getStateMeta(result.snapshot),
@@ -360,13 +359,36 @@ async function runSeam(machine, options) {
 	};
 }
 //#endregion
+//#region src/internal/trace-states.ts
+/** The `value` of a trace event's `from` or `snapshot`. @internal */
+function valueOf(holder) {
+	return isRecord(holder) ? holder.value : void 0;
+}
+/** A decision request on its first attempt (no failed attempts yet). @internal */
+function isFirstDecision(request) {
+	return isRecord(request) && request.kind === "decision" && (!Array.isArray(request.attempts) || request.attempts.length === 0);
+}
+/**
+* Every active leaf of a state value as a dot path:
+* `'a'` → `['a']`; `{ a: 'b' }` → `['a.b']`; `{ p: { x: 'one', y: {} } }` → `['p.x.one', 'p.y']`.
+* @internal
+*/
+function statePaths(value, prefix = "") {
+	if (typeof value === "string") return [prefix + value];
+	if (!isRecord(value)) return [];
+	const entries = Object.entries(value);
+	if (entries.length === 0) return prefix ? [prefix.slice(0, -1)] : [];
+	return entries.flatMap(([key, child]) => statePaths(child, `${prefix}${key}.`));
+}
+//#endregion
 //#region src/fold-traces.ts
 /**
 * Folds many runs' traces into per-state stats: how many runs visited each
-* state, how many of those failed, and how many options the guards withheld
-* at decisions made there. Pure; reads only:
+* state, how many of those failed, how many options the guards withheld
+* at decisions made there, and how many events it ignored. Pure; reads only:
 *
-* - `machine.transition`: the run visited `from.value` and `snapshot.value`.
+* - `machine.transition`: the run visited `from.value` and `snapshot.value`;
+*   with `ignored`, each of those states ignored one event.
 * - `request.start` of a decision, first attempt only: its `request.withheld`
 *   counts toward the state the run was in, the `from.value` of the
 *   transition its choice causes.
@@ -392,7 +414,8 @@ function foldTraces(traces, options) {
 				state,
 				visits: 0,
 				failures: 0,
-				withheld: 0
+				withheld: 0,
+				ignored: 0
 			};
 			stats.set(state, entry);
 		}
@@ -409,6 +432,7 @@ function foldTraces(traces, options) {
 			for (const state of statePaths(valueOf(event.from))) visit(state);
 			current = statePaths(valueOf(event.snapshot));
 			for (const state of current) visit(state);
+			if (event.ignored === true) for (const state of current) statsFor(state).ignored++;
 		} else if (event.type === "request.start" && isFirstDecision(event.request)) {
 			const withheld = event.request.withheld;
 			if (!Array.isArray(withheld)) continue;
@@ -423,18 +447,142 @@ function foldTraces(traces, options) {
 	}
 	return [...stats.values()];
 }
-function valueOf(holder) {
-	return isRecord(holder) ? holder.value : void 0;
+//#endregion
+//#region src/decision-requests.ts
+/**
+* The decisions a run asked for, read from its trace: each decision's first
+* `request.start`, with the states the run was in. A trace is one run's events,
+* live or serialized with `serializeTraceEvent`. Retries of the same decision
+* are left out, so each decision appears once.
+*
+* Use the requests as eval rows (run a decider on each and compare its event
+* with a label) or as probe inputs for a policy. A serialized request keeps its
+* `options`, `metadata`, `system`, and `prompt`; event schemas do not survive
+* serialization, so replay closed choices (`options`) rather than open ones.
+*
+* @example
+* ```ts no-check
+* const rows = traces.flatMap((trace) => getDecisionRequests(trace, { name: "chooseResolution" }));
+* for (const { request } of rows) console.log((await decide(request)).event);
+* ```
+*/
+function getDecisionRequests(trace, options = {}) {
+	const requests = [];
+	let current = [];
+	for (const event of trace) if (event.type === "machine.transition") current = statePaths(valueOf(event.snapshot));
+	else if (event.type === "request.start" && isFirstDecision(event.request)) {
+		if (options.name !== void 0 && event.request.name !== options.name) continue;
+		requests.push({
+			states: [...current],
+			request: event.request
+		});
+	}
+	return requests;
 }
-function isFirstDecision(request) {
-	return isRecord(request) && request.kind === "decision" && (!Array.isArray(request.attempts) || request.attempts.length === 0);
+//#endregion
+//#region src/compare-runs.ts
+/**
+* Runs every scenario through a baseline and a candidate implementation and
+* labels each difference, so a port can show where it behaves like the code it
+* replaces and where it differs on purpose.
+*
+* Parity is outcome-level: the terminal outcome and the effects in the world,
+* not the sequence of tool calls, since a machine usually reorders steps. A
+* candidate that broke no rule where the baseline broke one is intended, even
+* when the outcome matches. A difference also counts as intended when only the
+* candidate reached the scenario's `expected` outcome. Every other difference,
+* and every candidate rule break, is a regression for a person to review.
+*
+* Runs are sequential, baseline first. A run that throws is recorded with
+* outcome `'threw'` and the error message as its `detail`. Parity holds for
+* these scenarios and these runs only; with a live model, run it more than once.
+*
+* @example
+* ```ts no-check
+* const report = await compareRuns({
+*   scenarios,
+*   baseline: async (s) => toParityRun(await runRawLoop(s)),
+*   candidate: async (s) => toParityRun(await runDesk(s)),
+* });
+* expect(report.ok).toBe(true);
+* ```
+*/
+async function compareRuns(options) {
+	const scenarios = [];
+	const counts = {
+		same: 0,
+		intended: 0,
+		regression: 0
+	};
+	for (const scenario of options.scenarios) {
+		const baseline = await settle(() => options.baseline(scenario));
+		const candidate = await settle(() => options.candidate(scenario));
+		const { label, reason } = labelRun(scenario.expected, baseline, candidate);
+		counts[label]++;
+		scenarios.push({
+			id: scenario.id,
+			scenario,
+			label,
+			reason,
+			baseline,
+			candidate
+		});
+	}
+	return {
+		scenarios,
+		counts,
+		ok: counts.regression === 0
+	};
 }
-function statePaths(value, prefix = "") {
-	if (typeof value === "string") return [prefix + value];
-	if (!isRecord(value)) return [];
-	const entries = Object.entries(value);
-	if (entries.length === 0) return prefix ? [prefix.slice(0, -1)] : [];
-	return entries.flatMap(([key, child]) => statePaths(child, `${prefix}${key}.`));
+async function settle(run) {
+	try {
+		return await run();
+	} catch (error) {
+		return {
+			outcome: "threw",
+			detail: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function labelRun(expected, baseline, candidate) {
+	if (candidate.violations?.length) return {
+		label: "regression",
+		reason: `candidate broke a rule: ${list(candidate.violations)}`
+	};
+	if (candidate.outcome === "threw") return {
+		label: "regression",
+		reason: `candidate threw: ${String(candidate.detail)}`
+	};
+	if (baseline.violations?.length) return {
+		label: "intended",
+		reason: `baseline broke a rule: ${list(baseline.violations)}`
+	};
+	const sameOutcome = baseline.outcome === candidate.outcome;
+	if (sameOutcome && structurallyEqual(baseline.effects, candidate.effects)) return {
+		label: "same",
+		reason: ""
+	};
+	if (expected !== void 0 && candidate.outcome === expected && baseline.outcome !== expected) return {
+		label: "intended",
+		reason: `only the candidate reached the expected '${expected}'`
+	};
+	return {
+		label: "regression",
+		reason: sameOutcome ? "effects differ" : `outcome differs: ${baseline.outcome} → ${candidate.outcome}`
+	};
+}
+function list(items) {
+	return items.map((item) => typeof item === "string" ? item : JSON.stringify(item)).join(", ");
+}
+function structurallyEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+	if (a instanceof Map || b instanceof Map) return a instanceof Map && b instanceof Map && structurallyEqual([...a], [...b]);
+	if (a instanceof Set || b instanceof Set) return a instanceof Set && b instanceof Set && structurallyEqual([...a], [...b]);
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => structurallyEqual(item, b[index]));
+	if (!isRecord(a) || !isRecord(b)) return false;
+	const keys = Object.keys(a);
+	return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && structurallyEqual(a[key], b[key]));
 }
 //#endregion
-export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, explorePaths, foldTraces, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, compareRuns, explorePaths, foldTraces, getDecisionRequests, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };

package/dist/{text-logic-BDbGjYMh.d.mts → text-logic-BwdrDpO9.d.mts}

@@ -130,9 +130,13 @@ declare function parseAgentEvent<TSource extends AnyStateMachine | AnyMachineSna
  * ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
  * any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
  * never offers it to a model.
+ *
+ * Pass `actor: "agent"` for the list a model may choose from: it also drops an
+ * event the state handles through a transition tagged `meta: { actor: "human" }`.
  */
 declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas"> & {
   eventTypes?: readonly string[];
+  actor?: "agent";
 }): AgentEventDescriptor[];
 //#endregion
 //#region src/decision.d.ts
@@ -228,7 +232,7 @@ interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1
  *
  * export const chooseMove = createDecisionLogic({
  *   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
- *   model: 'openai/gpt-5.4-mini',
+ *   model: 'openai/gpt-6-luna',
  *   system: 'You are playing a turn-based game. Choose exactly one legal move.',
  *   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
  *   allowedEvents: ({ input }) =>
@@ -733,7 +737,7 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
  * export const tellJoke = createTextLogic({
  *   mode: 'stream',
  *   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
- *   model: 'openai/gpt-5.4-mini',
+ *   model: 'openai/gpt-6-luna',
  *   system: 'You tell short, punchy jokes.',
  *   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
  * });

package/dist/{text-logic-9fv1i9aK.d.cts → text-logic-j9hShB7d.d.cts}

@@ -130,9 +130,13 @@ declare function parseAgentEvent<TSource extends AnyStateMachine | AnyMachineSna
  * ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
  * any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
  * never offers it to a model.
+ *
+ * Pass `actor: "agent"` for the list a model may choose from: it also drops an
+ * event the state handles through a transition tagged `meta: { actor: "human" }`.
  */
 declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas"> & {
   eventTypes?: readonly string[];
+  actor?: "agent";
 }): AgentEventDescriptor[];
 //#endregion
 //#region src/decision.d.ts
@@ -228,7 +232,7 @@ interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1
  *
  * export const chooseMove = createDecisionLogic({
  *   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
- *   model: 'openai/gpt-5.4-mini',
+ *   model: 'openai/gpt-6-luna',
  *   system: 'You are playing a turn-based game. Choose exactly one legal move.',
  *   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
  *   allowedEvents: ({ input }) =>
@@ -733,7 +737,7 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
  * export const tellJoke = createTextLogic({
  *   mode: 'stream',
  *   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
- *   model: 'openai/gpt-5.4-mini',
+ *   model: 'openai/gpt-6-luna',
  *   system: 'You tell short, punchy jokes.',
  *   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
  * });

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

@@ -1,4 +1,4 @@
-import { t as AgentCallUsage } from "./text-logic-BDbGjYMh.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-R1NTmLxY.d.cts → usage-Bl4nK8D-.d.mts}

@@ -1,4 +1,4 @@
-import { t as AgentCallUsage } from "./text-logic-9fv1i9aK.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-Dtb16p1p.cjs");
-const require_setup_agent = require("./setup-agent-DTF3NQg3.cjs");
-const require_verify = require("./verify-Cqghu4gz.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-DlbgwsIJ.cjs";
-import { l as ExplorePathsOptions } from "./verify-DYH_2VzU.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-tsc3vm5I.mjs";
-import { l as ExplorePathsOptions } from "./verify-CBuYIpsa.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-GPZO9p7_.mjs";
-import { i as setupAgentFromConfig } from "./setup-agent-DniLvDu7.mjs";
-import { a as explorePaths, o as lintAgentMachine } from "./verify-B5qGC5WN.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-B5qGC5WN.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-GPZO9p7_.mjs";
-import { d as getAcceptedEvents, l as resolveDecision, m as isRecord, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-Bl_rKQnU.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-DYH_2VzU.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-9fv1i9aK.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-Cqghu4gz.cjs → verify-CS_xxvVU.cjs}

@@ -1,5 +1,5 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.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 = [{}];