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

package/dist/{setup-agent-CLPCkXsu.d.cts → setup-agent-yFFVXf5s.d.cts}

@@ -1,6 +1,6 @@
 import { _ as StandardSchemaV1, d as EventUnion, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, m as InferInput, s as AgentTools, t as AgentEventSchemaInputMap, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.cjs";
-import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-DmciuVUQ.cjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-Cm_ovz9V.cjs";
+import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-j9hShB7d.cjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BYqv7VBw.cjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
 //#region src/interaction.d.ts
 interface AgentInteractionEvent<TType extends string = string> {
@@ -84,13 +84,21 @@ interface AgentInteractionDescriptor<TEvent extends string = string> {
  */
 interface AgentInteractionMeta<TEvent extends string = string> {
   interaction?: AgentInteractionDescriptor<TEvent>;
+  /**
+   * On a transition: `"human"` means a person sends its event, never a model.
+   * Model-facing decisions (`agent.decide`, `decideNext`) withhold an event a
+   * state handles through a transition tagged this way. Read from object
+   * transitions only; a transition written as a function cannot be tagged.
+   */
+  actor?: "human";
 }
 /**
  * A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
  * reads: an object whose optional `interaction` declares a `label` (a string
  * with `{context.path}` interpolation, or a function of the context), an
  * `events` map of choices, payload `choices` (an array, or a context path to
- * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
+ * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers; and
+ * an optional `actor: "human"`, which tags a transition as sent by a person. This is
  * the default `meta` type `setupAgent` gives a machine; pass it to
  * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
  * schema pack by hand.

package/dist/tanstack-ai.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_decision = require("./decision-CIb7ddIv.cjs");
-const require_model_source = require("./model-source-BCKg4qJ1.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_decision = require("./decision-Iys2hzg3.cjs");
+const require_model_source = require("./model-source-DQ7KgJaT.cjs");
 let _tanstack_ai = require("@tanstack/ai");
 //#region src/tanstack-ai/index.ts
 /**

package/dist/tanstack-ai.d.cts

@@ -1,5 +1,5 @@
 import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
-import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-DmciuVUQ.cjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-j9hShB7d.cjs";
 import { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";

package/dist/tanstack-ai.d.mts

@@ -1,5 +1,5 @@
 import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
-import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BRYOPWvY.mjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BwdrDpO9.mjs";
 import { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";

package/dist/tanstack-ai.mjs

@@ -1,6 +1,6 @@
-import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, ct as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-DJCMHek_.mjs";
-import { c as renderDecisionAttempts } from "./decision-BHkvuImD.mjs";
-import { t as resolveModelSource } from "./model-source-BaHwJ1wK.mjs";
+import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, dt as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-DE430ZCa.mjs";
+import { c as renderDecisionAttempts } from "./decision-DqO018Tp.mjs";
+import { t as resolveModelSource } from "./model-source-CXsSZPq0.mjs";
 import { chat, maxIterations } from "@tanstack/ai";
 //#region src/tanstack-ai/index.ts
 /**

package/dist/testing.cjs

@@ -1,8 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_decision = require("./decision-CIb7ddIv.cjs");
-const require_run_agent = require("./run-agent-ctLCvNgL.cjs");
-const require_verify = require("./verify-CVlsTZ-V.cjs");
+const require_event_log = require("./event-log-Bdww2l1D.cjs");
+const require_run_agent = require("./run-agent-tmk58M0x.cjs");
+const require_verify = require("./verify-CS_xxvVU.cjs");
 //#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
@@ -10,9 +9,9 @@ const require_verify = require("./verify-CVlsTZ-V.cjs");
 * @internal
 */
 function normalize(item) {
-	if (require_decision.isRecord(item)) {
+	if (require_event_log.isRecord(item)) {
 		const nested = item["event"];
-		if (require_decision.isRecord(nested) && typeof nested["type"] === "string") return {
+		if (require_event_log.isRecord(nested) && typeof nested["type"] === "string") return {
 			kind: "event",
 			event: nested
 		};
@@ -33,7 +32,7 @@ function normalize(item) {
 /** Every leaf of a state value as a dot path (`{ review: 'editing' }` → `review.editing`). @internal */
 function statePaths$1(value) {
 	if (typeof value === "string") return [value];
-	if (!require_decision.isRecord(value)) return [];
+	if (!require_event_log.isRecord(value)) return [];
 	return Object.entries(value).flatMap(([key, child]) => statePaths$1(child).map((path) => `${key}.${path}`));
 }
 /**
@@ -46,7 +45,7 @@ function stateMatchesPath(path, value) {
 function deepEqual(a, b) {
 	if (Object.is(a, b)) return true;
 	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
-	if (!require_decision.isRecord(a) || !require_decision.isRecord(b)) return false;
+	if (!require_event_log.isRecord(a) || !require_event_log.isRecord(b)) return false;
 	const keys = Object.keys(a);
 	return keys.length === Object.keys(b).length && keys.every((key) => deepEqual(a[key], b[key]));
 }
@@ -178,7 +177,7 @@ function isTextResult(value) {
 */
 async function resolveSeamScriptEntry(entry, request, info) {
 	const value = typeof entry === "function" ? await entry(request, info) : entry;
-	return require_decision.isRecord(value) && isTextResult(value) ? value : { result: value };
+	return require_event_log.isRecord(value) && isTextResult(value) ? value : { result: value };
 }
 /** Names a pending text request in an error message. @internal */
 function describeText(request) {
@@ -188,7 +187,7 @@ function describeText(request) {
 * Stream semantics with no model: the whole text lands as one chunk. @internal
 */
 function emitScriptedChunk(result, info) {
-	const text = require_decision.isRecord(result) ? result["result"] : void 0;
+	const text = require_event_log.isRecord(result) ? result["result"] : void 0;
 	if (typeof text === "string") info?.onChunk?.(text);
 }
 /**
@@ -196,7 +195,7 @@ function emitScriptedChunk(result, info) {
 * @internal
 */
 async function seamOutputOf(result, request) {
-	if (!require_decision.isRecord(result)) return;
+	if (!require_event_log.isRecord(result)) return;
 	return await require_event_log.normalizeGeneratorResult(result, `seam '${request.name ?? request.model}'`);
 }
 /**
@@ -321,7 +320,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: require_event_log.getStateMeta(result.snapshot),
@@ -361,13 +360,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 require_event_log.isRecord(holder) ? holder.value : void 0;
+}
+/** A decision request on its first attempt (no failed attempts yet). @internal */
+function isFirstDecision(request) {
+	return require_event_log.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 (!require_event_log.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.
@@ -393,7 +415,8 @@ function foldTraces(traces, options) {
 				state,
 				visits: 0,
 				failures: 0,
-				withheld: 0
+				withheld: 0,
+				ignored: 0
 			};
 			stats.set(state, entry);
 		}
@@ -410,6 +433,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;
@@ -424,18 +448,37 @@ function foldTraces(traces, options) {
 	}
 	return [...stats.values()];
 }
-function valueOf(holder) {
-	return require_decision.isRecord(holder) ? holder.value : void 0;
-}
-function isFirstDecision(request) {
-	return require_decision.isRecord(request) && request.kind === "decision" && (!Array.isArray(request.attempts) || request.attempts.length === 0);
-}
-function statePaths(value, prefix = "") {
-	if (typeof value === "string") return [prefix + value];
-	if (!require_decision.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/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;
 }
 //#endregion
 //#region src/compare-runs.ts
@@ -538,7 +581,7 @@ function structurallyEqual(a, b) {
 	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 (!require_decision.isRecord(a) || !require_decision.isRecord(b)) return false;
+	if (!require_event_log.isRecord(a) || !require_event_log.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]));
 }
@@ -550,6 +593,7 @@ exports.canReach = require_verify.canReach;
 exports.compareRuns = compareRuns;
 exports.explorePaths = require_verify.explorePaths;
 exports.foldTraces = foldTraces;
+exports.getDecisionRequests = getDecisionRequests;
 exports.lintAgentMachine = require_verify.lintAgentMachine;
 exports.matchesTrajectory = matchesTrajectory;
 exports.runSeam = runSeam;

package/dist/testing.d.cts

@@ -1,7 +1,7 @@
-import { c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-DmciuVUQ.cjs";
-import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-CTlMc3Jb.cjs";
+import { P as AgentExecutorDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-j9hShB7d.cjs";
+import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-B5opVUxx.cjs";
 import { t as MetaOfSnapshot } from "./utils-ebVpCYoF.cjs";
-import { _ as explorePaths, a as AgentPathTerminal, c as CanReachResult, d as SimulateAgentOptions, f as SimulateAgentResult, g as canReach, h as assertAgentMachine, i as AgentPathReport, l as ExplorePathsOptions, m as SimulationTrailEntry, n as AgentLintError, o as AgentUnknownStateError, p as SimulationScript, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as LintAgentMachineOptions, v as lintAgentMachine, y as simulateAgent } from "./verify-Dzwd4Mvk.cjs";
+import { _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-CPKDPMwY.cjs";
 import { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -204,10 +204,10 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
   candidate?: AgentRequestExecutor;
   /**
    * The simulated user. Called at every idle pause; return the event to send,
-   * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
-   * first idle pause.
+   * or `null`/`undefined` to stop the run there, directly or as a promise (a
+   * real async client). Omitted, the run stops at the first idle pause.
    */
-  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined;
+  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined | PromiseLike<EventFromLogic<TMachine> | null | undefined>;
   /** Maximum idle pauses to answer before stopping. Default `12`. */
   maxTurns?: number;
   /**
@@ -288,6 +288,8 @@ interface StateStats {
   failures: number;
   /** Options withheld by the guards at decisions made in this state, summed over runs. */
   withheld: number;
+  /** Events this state ignored (`machine.transition` with `ignored`), summed over runs. */
+  ignored: number;
 }
 /** Options for {@link foldTraces}. */
 interface FoldTracesOptions<TTrace> {
@@ -296,10 +298,11 @@ interface FoldTracesOptions<TTrace> {
 }
 /**
  * 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.
@@ -320,6 +323,40 @@ export declare function foldTraces<TTrace extends readonly {
   readonly type: string;
 }[]>(traces: Iterable<TTrace>, options: FoldTracesOptions<TTrace>): StateStats[];
 //#endregion
+//#region src/decision-requests.d.ts
+/** One decision a run asked for. See {@link getDecisionRequests}. */
+interface TracedDecisionRequest {
+  /** The active states when the decision was asked, as dot paths (one per parallel region). */
+  states: string[];
+  /** The request as the executor received it, on its first attempt. */
+  request: AgentExecutorDecisionRequest;
+}
+/** Options for {@link getDecisionRequests}. */
+interface GetDecisionRequestsOptions {
+  /** Keep only requests with this `name` (the `agent.decide` input's `name`). */
+  name?: string;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function getDecisionRequests(trace: Iterable<{
+  readonly type: string;
+}>, options?: GetDecisionRequestsOptions): TracedDecisionRequest[];
+//#endregion
 //#region src/compare-runs.d.ts
 /** One run of one scenario, reduced to what parity compares. See {@link compareRuns}. */
 interface ParityRun {
@@ -401,4 +438,4 @@ export declare function compareRuns<TScenario extends {
   expected?: string;
 }>(options: CompareRunsOptions<TScenario>): Promise<ParityReport<TScenario>>;
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type CompareRunsOptions, type ExplorePathsOptions, type FoldTracesOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateStats, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, simulateAgent };
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CompareRunsOptions, type ExplorePathsOptions, type ExploreSnapshot, type FoldTracesOptions, type GetDecisionRequestsOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateStats, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, simulateAgent };

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BRYOPWvY.mjs";
-import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-CAVt5R-r.mjs";
+import { P as AgentExecutorDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BwdrDpO9.mjs";
+import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-D4MwS5GY.mjs";
 import { t as MetaOfSnapshot } from "./utils-BnXdWih3.mjs";
-import { _ as explorePaths, a as AgentPathTerminal, c as CanReachResult, d as SimulateAgentOptions, f as SimulateAgentResult, g as canReach, h as assertAgentMachine, i as AgentPathReport, l as ExplorePathsOptions, m as SimulationTrailEntry, n as AgentLintError, o as AgentUnknownStateError, p as SimulationScript, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as LintAgentMachineOptions, v as lintAgentMachine, y as simulateAgent } from "./verify-Cn86rT8l.mjs";
+import { _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-tkymWz6X.mjs";
 import { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -204,10 +204,10 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
   candidate?: AgentRequestExecutor;
   /**
    * The simulated user. Called at every idle pause; return the event to send,
-   * or `null`/`undefined` to stop the run there. Omitted, the run stops at the
-   * first idle pause.
+   * or `null`/`undefined` to stop the run there, directly or as a promise (a
+   * real async client). Omitted, the run stops at the first idle pause.
    */
-  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined;
+  respond?: (turn: SeamTurn<TMachine>) => EventFromLogic<TMachine> | null | undefined | PromiseLike<EventFromLogic<TMachine> | null | undefined>;
   /** Maximum idle pauses to answer before stopping. Default `12`. */
   maxTurns?: number;
   /**
@@ -288,6 +288,8 @@ interface StateStats {
   failures: number;
   /** Options withheld by the guards at decisions made in this state, summed over runs. */
   withheld: number;
+  /** Events this state ignored (`machine.transition` with `ignored`), summed over runs. */
+  ignored: number;
 }
 /** Options for {@link foldTraces}. */
 interface FoldTracesOptions<TTrace> {
@@ -296,10 +298,11 @@ interface FoldTracesOptions<TTrace> {
 }
 /**
  * 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.
@@ -320,6 +323,40 @@ export declare function foldTraces<TTrace extends readonly {
   readonly type: string;
 }[]>(traces: Iterable<TTrace>, options: FoldTracesOptions<TTrace>): StateStats[];
 //#endregion
+//#region src/decision-requests.d.ts
+/** One decision a run asked for. See {@link getDecisionRequests}. */
+interface TracedDecisionRequest {
+  /** The active states when the decision was asked, as dot paths (one per parallel region). */
+  states: string[];
+  /** The request as the executor received it, on its first attempt. */
+  request: AgentExecutorDecisionRequest;
+}
+/** Options for {@link getDecisionRequests}. */
+interface GetDecisionRequestsOptions {
+  /** Keep only requests with this `name` (the `agent.decide` input's `name`). */
+  name?: string;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function getDecisionRequests(trace: Iterable<{
+  readonly type: string;
+}>, options?: GetDecisionRequestsOptions): TracedDecisionRequest[];
+//#endregion
 //#region src/compare-runs.d.ts
 /** One run of one scenario, reduced to what parity compares. See {@link compareRuns}. */
 interface ParityRun {
@@ -401,4 +438,4 @@ export declare function compareRuns<TScenario extends {
   expected?: string;
 }>(options: CompareRunsOptions<TScenario>): Promise<ParityReport<TScenario>>;
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type CompareRunsOptions, type ExplorePathsOptions, type FoldTracesOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateStats, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, simulateAgent };
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CompareRunsOptions, type ExplorePathsOptions, type ExploreSnapshot, type FoldTracesOptions, type GetDecisionRequestsOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateStats, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, simulateAgent };

package/dist/testing.mjs

@@ -1,7 +1,6 @@
-import { $ as getStateMeta, F as normalizeGeneratorResult, N as getCallUsage, st as AgentError } from "./event-log-DJCMHek_.mjs";
-import { m as isRecord } from "./decision-BHkvuImD.mjs";
-import { p as runToQuiescence, s as createAgentRuntime } from "./run-agent-BpHqkaZw.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-COFWyprJ.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,37 @@ function foldTraces(traces, options) {
 	}
 	return [...stats.values()];
 }
-function valueOf(holder) {
-	return isRecord(holder) ? holder.value : void 0;
-}
-function isFirstDecision(request) {
-	return isRecord(request) && request.kind === "decision" && (!Array.isArray(request.attempts) || request.attempts.length === 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}.`));
+//#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;
 }
 //#endregion
 //#region src/compare-runs.ts
@@ -542,4 +585,4 @@ function structurallyEqual(a, b) {
 	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, compareRuns, explorePaths, foldTraces, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, compareRuns, explorePaths, foldTraces, getDecisionRequests, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };

package/dist/{text-logic-BRYOPWvY.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

package/dist/{text-logic-DmciuVUQ.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