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

package/dist/{run-agent-cToZ3K42.cjs → run-agent-ctLCvNgL.cjs}

@@ -1,6 +1,6 @@
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
-const require_event_log_store = require("./event-log-store-bCdskPNS.cjs");
+const require_event_log = require("./event-log-BZRfBRd7.cjs");
+const require_decision = require("./decision-CIb7ddIv.cjs");
+const require_event_log_store = require("./event-log-store-DZR4IIWe.cjs");
 let xstate = require("xstate");
 let xstate_durable = require("xstate/durable");
 //#region src/run-agent.ts
@@ -918,6 +918,8 @@ function createAgentRuntime(machine, options = {}) {
 	let traceSeq = 0;
 	const machineId = machine.config.id ?? machine.id ?? "(machine)";
 	const machineVersion = require_event_log.resolveMachineVersion(machine);
+	if (options.metadata !== void 0) require_event_log.assertJsonSerializable(options.metadata, "metadata");
+	const initMetadata = options.metadata === void 0 ? void 0 : structuredClone(options.metadata);
 	const onTrace = createTraceDispatch({
 		onTrace: (payload) => {
 			options.onTrace?.({
@@ -1370,16 +1372,23 @@ function createAgentRuntime(machine, options = {}) {
 						logIndex: resumeEvents.length
 					};
 					seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+						...initMetadata,
 						...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
 						migratedFrom
 					});
 				}
 			} else if (init.snapshot !== void 0) {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			} else {
 				logExecutionId = crypto.randomUUID();
-				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
+				seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], {
+					...initMetadata,
+					executionId: logExecutionId
+				});
 			}
 			const resumedHistory = [...logEntries];
 			const siteCallCounts = /* @__PURE__ */ new Map();

package/dist/{setup-agent-DniLvDu7.mjs → setup-agent-7rV_cujV.mjs}

@@ -1,5 +1,5 @@
-import { A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, G as missingActor, H as getAgentExecutionOptions, K as setAgentExecutionOptions, T as DECIDE_ACTOR, k as builtinTextActors, ot as validateSchemaSync } from "./event-log-GPZO9p7_.mjs";
-import { r as createDecideActor } from "./decision-Bl_rKQnU.mjs";
+import { A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, G as missingActor, H as getAgentExecutionOptions, K as setAgentExecutionOptions, T as DECIDE_ACTOR, k as builtinTextActors, ot as validateSchemaSync } from "./event-log-DJCMHek_.mjs";
+import { r as createDecideActor } from "./decision-BHkvuImD.mjs";
 import { machineFromJSON, setup } from "xstate";
 //#region src/workflow-config.ts
 /**

package/dist/{setup-agent-tsc3vm5I.d.mts → setup-agent-CGELn1qZ.d.mts}

@@ -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.mjs";
-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-BDbGjYMh.mjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-D8UphgEA.mjs";
+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-BRYOPWvY.mjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BkM3z02Y.mjs";
 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> {

package/dist/{setup-agent-DlbgwsIJ.d.cts → setup-agent-CLPCkXsu.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-9fv1i9aK.cjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-R1NTmLxY.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 { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
 //#region src/interaction.d.ts
 interface AgentInteractionEvent<TType extends string = string> {

package/dist/{setup-agent-DTF3NQg3.cjs → setup-agent-DoUk7EdC.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-BZRfBRd7.cjs");
+const require_decision = require("./decision-CIb7ddIv.cjs");
 let xstate = require("xstate");
 //#region src/workflow-config.ts
 /**

package/dist/tanstack-ai.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
-const require_model_source = require("./model-source-DjJPjGSP.cjs");
+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");
 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-9fv1i9aK.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 { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -195,7 +195,7 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
  * ```ts
  * import { openaiText } from '@tanstack/ai-openai';
  *
- * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-5.4-mini') } });
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */

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-BDbGjYMh.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 { AnyStateMachine } from "xstate";
 import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
 import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -195,7 +195,7 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
  * ```ts
  * import { openaiText } from '@tanstack/ai-openai';
  *
- * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-5.4-mini') } });
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */

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-GPZO9p7_.mjs";
-import { c as renderDecisionAttempts } from "./decision-Bl_rKQnU.mjs";
-import { t as resolveModelSource } from "./model-source-C7FFP2Sj.mjs";
+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 { chat, maxIterations } from "@tanstack/ai";
 //#region src/tanstack-ai/index.ts
 /**

package/dist/testing.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-Dtb16p1p.cjs");
-const require_decision = require("./decision-oevZnkBe.cjs");
-const require_run_agent = require("./run-agent-cToZ3K42.cjs");
-const require_verify = require("./verify-Cqghu4gz.cjs");
+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");
 //#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
@@ -438,10 +438,116 @@ function statePaths(value, prefix = "") {
 	return entries.flatMap(([key, child]) => statePaths(child, `${prefix}${key}.`));
 }
 //#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
+	};
+}
+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 (!require_decision.isRecord(a) || !require_decision.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
 exports.AgentLintError = require_verify.AgentLintError;
 exports.AgentUnknownStateError = require_verify.AgentUnknownStateError;
 exports.assertAgentMachine = require_verify.assertAgentMachine;
 exports.canReach = require_verify.canReach;
+exports.compareRuns = compareRuns;
 exports.explorePaths = require_verify.explorePaths;
 exports.foldTraces = foldTraces;
 exports.lintAgentMachine = require_verify.lintAgentMachine;

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-9fv1i9aK.cjs";
-import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-C9ubX8Tx.cjs";
+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 { 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-DYH_2VzU.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 { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -320,4 +320,85 @@ export declare function foldTraces<TTrace extends readonly {
   readonly type: string;
 }[]>(traces: Iterable<TTrace>, options: FoldTracesOptions<TTrace>): StateStats[];
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type FoldTracesOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, 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 };
+//#region src/compare-runs.d.ts
+/** One run of one scenario, reduced to what parity compares. See {@link compareRuns}. */
+interface ParityRun {
+  /** How the run ended: a final state name, or the label of the loop's return. `'threw'` marks a run that threw. */
+  outcome: string;
+  /** What the run changed in the world, compared structurally. Sort lists whose order does not matter. */
+  effects?: unknown;
+  /** The rules the run broke, from ground truth. Any entry marks the run as rule-breaking. */
+  violations?: readonly unknown[];
+  /** Anything else to keep in the report. Not compared. */
+  detail?: unknown;
+}
+/**
+ * How one scenario's candidate run relates to its baseline run.
+ *
+ * - `same`: same outcome, same effects, and neither run broke a rule.
+ * - `intended`: the candidate broke no rule, and the baseline broke one (even
+ *   with the same outcome and effects), or the baseline missed the scenario's
+ *   `expected` outcome that the candidate reached.
+ * - `regression`: the candidate broke a rule, or they differ for any other reason.
+ */
+type ParityLabel = "same" | "intended" | "regression";
+/** One scenario's row in a {@link ParityReport}. */
+interface ParityResult<TScenario> {
+  id: string;
+  scenario: TScenario;
+  label: ParityLabel;
+  /** Why the label was given, in a few words. Empty for `same`. */
+  reason: string;
+  baseline: ParityRun;
+  candidate: ParityRun;
+}
+/** The result of {@link compareRuns}. */
+interface ParityReport<TScenario> {
+  scenarios: ParityResult<TScenario>[];
+  counts: Record<ParityLabel, number>;
+  /** True when no scenario is a `regression`. */
+  ok: boolean;
+}
+/** Options for {@link compareRuns}. */
+interface CompareRunsOptions<TScenario extends {
+  id: string;
+  expected?: string;
+}> {
+  scenarios: readonly TScenario[];
+  /** Runs the existing implementation (the loop) on one scenario. */
+  baseline: (scenario: TScenario) => Promise<ParityRun>;
+  /** Runs the replacement (the machine) on one scenario. */
+  candidate: (scenario: TScenario) => Promise<ParityRun>;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function compareRuns<TScenario extends {
+  id: string;
+  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 };

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-BDbGjYMh.mjs";
-import { f as AgentRuntimeOptions, l as AgentRunResult, o as AgentRunInit } from "./run-agent-CxSyZmIE.mjs";
+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 { 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-CBuYIpsa.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 { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 //#region src/trajectory.d.ts
 /** An event-shaped trajectory item: anything with a string `type`. */
@@ -320,4 +320,85 @@ export declare function foldTraces<TTrace extends readonly {
   readonly type: string;
 }[]>(traces: Iterable<TTrace>, options: FoldTracesOptions<TTrace>): StateStats[];
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type FoldTracesOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, 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 };
+//#region src/compare-runs.d.ts
+/** One run of one scenario, reduced to what parity compares. See {@link compareRuns}. */
+interface ParityRun {
+  /** How the run ended: a final state name, or the label of the loop's return. `'threw'` marks a run that threw. */
+  outcome: string;
+  /** What the run changed in the world, compared structurally. Sort lists whose order does not matter. */
+  effects?: unknown;
+  /** The rules the run broke, from ground truth. Any entry marks the run as rule-breaking. */
+  violations?: readonly unknown[];
+  /** Anything else to keep in the report. Not compared. */
+  detail?: unknown;
+}
+/**
+ * How one scenario's candidate run relates to its baseline run.
+ *
+ * - `same`: same outcome, same effects, and neither run broke a rule.
+ * - `intended`: the candidate broke no rule, and the baseline broke one (even
+ *   with the same outcome and effects), or the baseline missed the scenario's
+ *   `expected` outcome that the candidate reached.
+ * - `regression`: the candidate broke a rule, or they differ for any other reason.
+ */
+type ParityLabel = "same" | "intended" | "regression";
+/** One scenario's row in a {@link ParityReport}. */
+interface ParityResult<TScenario> {
+  id: string;
+  scenario: TScenario;
+  label: ParityLabel;
+  /** Why the label was given, in a few words. Empty for `same`. */
+  reason: string;
+  baseline: ParityRun;
+  candidate: ParityRun;
+}
+/** The result of {@link compareRuns}. */
+interface ParityReport<TScenario> {
+  scenarios: ParityResult<TScenario>[];
+  counts: Record<ParityLabel, number>;
+  /** True when no scenario is a `regression`. */
+  ok: boolean;
+}
+/** Options for {@link compareRuns}. */
+interface CompareRunsOptions<TScenario extends {
+  id: string;
+  expected?: string;
+}> {
+  scenarios: readonly TScenario[];
+  /** Runs the existing implementation (the loop) on one scenario. */
+  baseline: (scenario: TScenario) => Promise<ParityRun>;
+  /** Runs the replacement (the machine) on one scenario. */
+  candidate: (scenario: TScenario) => Promise<ParityRun>;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare function compareRuns<TScenario extends {
+  id: string;
+  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 };

package/dist/testing.mjs

@@ -1,7 +1,7 @@
-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, 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";
 //#region src/trajectory.ts
 /**
 * Classifies one item. Event-shaped things (log entries, events) become events;
@@ -437,4 +437,109 @@ function statePaths(value, prefix = "") {
 	return entries.flatMap(([key, child]) => statePaths(child, `${prefix}${key}.`));
 }
 //#endregion
-export { AgentLintError, AgentUnknownStateError, assertAgentMachine, canReach, explorePaths, foldTraces, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+//#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
+	};
+}
+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, compareRuns, explorePaths, foldTraces, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };

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

@@ -228,7 +228,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 +733,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-DmciuVUQ.d.cts}

@@ -228,7 +228,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 +733,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-BkM3z02Y.d.mts}

@@ -1,4 +1,4 @@
-import { t as AgentCallUsage } from "./text-logic-BDbGjYMh.mjs";
+import { t as AgentCallUsage } from "./text-logic-BRYOPWvY.mjs";
 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-Cm_ovz9V.d.cts}

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