@statelyai/agent 2.0.0-alpha.25 → 2.0.0-alpha.27

package/dist/testing.d.cts

@@ -1,7 +1,7 @@
-import { u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
-import { Z as AgentError, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BFEOxyxv.cjs";
-import { d as RunAgentOptions, f as RunAgentResult } from "./run-agent-BOfoJg5B.cjs";
-import { _ as ScriptedExecutorsScript, g as ScriptedExecutors, h as ScriptedDecisionValue, m as ScriptedDecisionEntry, p as ScriptedByName, t as MetaOfSnapshot, v as ScriptedTextEntry, y as createScriptedExecutors } from "./utils-RalRn9sk.cjs";
+import { u as ChosenEvent } from "./types-hR5f5YXa.cjs";
+import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-IjfYy9DP.cjs";
+import { c as AgentRunResult, d as AgentRuntimeOptions, o as AgentRunInit } from "./run-agent-ByO-Bxyd.cjs";
+import { t as MetaOfSnapshot } from "./utils-o4YRdHJX.cjs";
 import { AnyMachineSnapshot, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/verify.d.ts
@@ -415,11 +415,13 @@ interface TrajectoryMatch {
  * @example Trajectory assertions in a test
  * ```ts
  * const statePath: unknown[] = [];
- * const result = await runAgent(machine, {
- *   input,
- *   executors,
- *   onTransition: (snapshot) => statePath.push(snapshot.value),
- * });
+ * const result = await runToQuiescence(
+ *   createAgentRuntime(machine, {
+ *     executors,
+ *     onTransition: (snapshot) => statePath.push(snapshot.value),
+ *   }),
+ *   { input },
+ * );
  *
  * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
  * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
@@ -435,6 +437,20 @@ interface TrajectoryMatch {
 declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
 //#endregion
 //#region src/seam.d.ts
+/**
+ * One scripted answer in a {@link RunSeamOptions.scripts} queue: the request's
+ * output value (a string, or the object a structured request declares), or a
+ * function of the {@link AgentTextRequest} returning one.
+ *
+ * An entry is taken as the executor result (instead of the value itself)
+ * only when its OWN keys are a `result` plus, optionally, `messages`/`usage`/
+ * `raw` — that is how an entry reports token `usage`. Anything else, including
+ * an object that merely happens to have a `result` key alongside its own data
+ * (`{ result: 'draft', confidence: 0.9 }`), is the output value. For a
+ * structured request whose declared output is exactly `{ result }` (or
+ * `{ result, usage }`), wrap it once more: `{ result: { result: '…' } }`.
+ */
+type SeamScriptEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
 /**
  * Which model call is under test: the Nth call with this request `name` (the
  * `setupAgent({ requests })` key, or `createTextLogic({ name })`). Name the
@@ -466,7 +482,7 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   /** 0-based index of this pause within the run. */
   turn: number;
   /** The `idle` result that produced the pause. */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
 }
 /**
  * One text call in a {@link runSeam} run's ledger, in call order — the receipt
@@ -497,7 +513,7 @@ interface SeamSlice {
 }
 /** Options for {@link runSeam}. */
 interface RunSeamOptions<TMachine extends AnyStateMachine> {
-  /** Machine input, passed straight through to `runAgent`. */
+  /** Machine input, passed straight through to `runToQuiescence`. */
   input?: InputFrom<TMachine>;
   /**
    * The call plan: scripted answers per key, consumed in order. A key is a
@@ -505,12 +521,12 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * machine whose requests are named routes by name and an unnamed one routes
    * by model.
    *
-   * Entries follow {@link ScriptedTextEntry} conventions (a value, an
+   * Entries follow {@link SeamScriptEntry} conventions (a value, an
    * `{ result, usage? }` object, or a function of the request). A queue that
    * runs dry throws; set {@link RunSeamOptions.repeatLast} to replay its last
    * entry instead.
    */
-  scripts?: Record<string, ScriptedTextEntry[]>;
+  scripts?: Record<string, SeamScriptEntry[]>;
   /**
    * Replay the LAST entry of a queue once it is exhausted, so a live seam that
    * sends the run down a longer branch still finds an answer. Off by default:
@@ -534,20 +550,21 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
   /** Maximum idle pauses to answer before stopping. Default `12`. */
   maxTurns?: number;
   /**
-   * Base executors merged UNDER the seam routing — supply `decide` (e.g. from
-   * `createScriptedExecutors({ decisions })`) for a machine that also decides.
+   * Base executors merged UNDER the seam routing — supply `decide` (a plain
+   * function of the decision request, or `createAiSdkExecutors` over a mock
+   * model) for a machine that also decides.
    * Text slots are always owned by the routing.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /** Passed through to `runAgent`: actor implementations merged onto the machine. */
-  actors?: RunAgentOptions<TMachine>["actors"];
+  /** Passed through to `createAgentRuntime`: actor implementations merged onto the machine. */
+  actors?: (AgentRuntimeOptions<TMachine> & AgentRunInit<TMachine>)["actors"];
 }
 /** What {@link runSeam} returns: the seam's own answer, plus the run it caused. */
 interface RunSeamResult<TMachine extends AnyStateMachine> {
   /**
-   * The final `runAgent` result. `usage` accounts for the last leg.
+   * The final `runToQuiescence` result. `usage` accounts for the last leg.
    */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
   /** What the seam call returned, or `undefined` when the run never reached it. */
   seamOutput: unknown;
   /**
@@ -583,8 +600,8 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  * @example No API key: the seam is scripted too, so the whole thing runs offline.
  * ```ts
  * const run = await runSeam(emailDrafter, {
- *   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
- *   seam: { request: 'evaluatePrompt' },
+ *   scripts: { writeFollowUps: [followUps], emailDrafter: [draft] },
+ *   seam: { request: 'writeFollowUps' },
  *   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
  * });
  *
@@ -599,4 +616,4 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  */
 declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type RunSeamOptions, type RunSeamResult, type ScriptedByName, type ScriptedDecisionEntry, type ScriptedDecisionValue, type ScriptedExecutors, type ScriptedExecutorsScript, type ScriptedTextEntry, type SeamCall, type SeamRef, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, createScriptedExecutors, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, 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 TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };

package/dist/testing.d.mts

@@ -1,7 +1,7 @@
-import { u as ChosenEvent } from "./types-tA3SdczG.mjs";
-import { Z as AgentError, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-hZSiRUo1.mjs";
-import { d as RunAgentOptions, f as RunAgentResult } from "./run-agent-CG343kFs.mjs";
-import { _ as ScriptedExecutorsScript, g as ScriptedExecutors, h as ScriptedDecisionValue, m as ScriptedDecisionEntry, p as ScriptedByName, t as MetaOfSnapshot, v as ScriptedTextEntry, y as createScriptedExecutors } from "./utils-C1p37X_c.mjs";
+import { u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
+import { Z as AgentError, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-D-czVPYp.mjs";
+import { c as AgentRunResult, d as AgentRuntimeOptions, o as AgentRunInit } from "./run-agent-COXXc0RW.mjs";
+import { t as MetaOfSnapshot } from "./utils-_q7F-AZu.mjs";
 import { AnyMachineSnapshot, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
 
 //#region src/verify.d.ts
@@ -415,11 +415,13 @@ interface TrajectoryMatch {
  * @example Trajectory assertions in a test
  * ```ts
  * const statePath: unknown[] = [];
- * const result = await runAgent(machine, {
- *   input,
- *   executors,
- *   onTransition: (snapshot) => statePath.push(snapshot.value),
- * });
+ * const result = await runToQuiescence(
+ *   createAgentRuntime(machine, {
+ *     executors,
+ *     onTransition: (snapshot) => statePath.push(snapshot.value),
+ *   }),
+ *   { input },
+ * );
  *
  * const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
  * expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
@@ -435,6 +437,20 @@ interface TrajectoryMatch {
 declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
 //#endregion
 //#region src/seam.d.ts
+/**
+ * One scripted answer in a {@link RunSeamOptions.scripts} queue: the request's
+ * output value (a string, or the object a structured request declares), or a
+ * function of the {@link AgentTextRequest} returning one.
+ *
+ * An entry is taken as the executor result (instead of the value itself)
+ * only when its OWN keys are a `result` plus, optionally, `messages`/`usage`/
+ * `raw` — that is how an entry reports token `usage`. Anything else, including
+ * an object that merely happens to have a `result` key alongside its own data
+ * (`{ result: 'draft', confidence: 0.9 }`), is the output value. For a
+ * structured request whose declared output is exactly `{ result }` (or
+ * `{ result, usage }`), wrap it once more: `{ result: { result: '…' } }`.
+ */
+type SeamScriptEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
 /**
  * Which model call is under test: the Nth call with this request `name` (the
  * `setupAgent({ requests })` key, or `createTextLogic({ name })`). Name the
@@ -466,7 +482,7 @@ interface SeamTurn<TMachine extends AnyStateMachine> {
   /** 0-based index of this pause within the run. */
   turn: number;
   /** The `idle` result that produced the pause. */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
 }
 /**
  * One text call in a {@link runSeam} run's ledger, in call order — the receipt
@@ -497,7 +513,7 @@ interface SeamSlice {
 }
 /** Options for {@link runSeam}. */
 interface RunSeamOptions<TMachine extends AnyStateMachine> {
-  /** Machine input, passed straight through to `runAgent`. */
+  /** Machine input, passed straight through to `runToQuiescence`. */
   input?: InputFrom<TMachine>;
   /**
    * The call plan: scripted answers per key, consumed in order. A key is a
@@ -505,12 +521,12 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
    * machine whose requests are named routes by name and an unnamed one routes
    * by model.
    *
-   * Entries follow {@link ScriptedTextEntry} conventions (a value, an
+   * Entries follow {@link SeamScriptEntry} conventions (a value, an
    * `{ result, usage? }` object, or a function of the request). A queue that
    * runs dry throws; set {@link RunSeamOptions.repeatLast} to replay its last
    * entry instead.
    */
-  scripts?: Record<string, ScriptedTextEntry[]>;
+  scripts?: Record<string, SeamScriptEntry[]>;
   /**
    * Replay the LAST entry of a queue once it is exhausted, so a live seam that
    * sends the run down a longer branch still finds an answer. Off by default:
@@ -534,20 +550,21 @@ interface RunSeamOptions<TMachine extends AnyStateMachine> {
   /** Maximum idle pauses to answer before stopping. Default `12`. */
   maxTurns?: number;
   /**
-   * Base executors merged UNDER the seam routing — supply `decide` (e.g. from
-   * `createScriptedExecutors({ decisions })`) for a machine that also decides.
+   * Base executors merged UNDER the seam routing — supply `decide` (a plain
+   * function of the decision request, or `createAiSdkExecutors` over a mock
+   * model) for a machine that also decides.
    * Text slots are always owned by the routing.
    */
   executors?: Partial<AgentRequestExecutors>;
-  /** Passed through to `runAgent`: actor implementations merged onto the machine. */
-  actors?: RunAgentOptions<TMachine>["actors"];
+  /** Passed through to `createAgentRuntime`: actor implementations merged onto the machine. */
+  actors?: (AgentRuntimeOptions<TMachine> & AgentRunInit<TMachine>)["actors"];
 }
 /** What {@link runSeam} returns: the seam's own answer, plus the run it caused. */
 interface RunSeamResult<TMachine extends AnyStateMachine> {
   /**
-   * The final `runAgent` result. `usage` accounts for the last leg.
+   * The final `runToQuiescence` result. `usage` accounts for the last leg.
    */
-  result: RunAgentResult<TMachine>;
+  result: AgentRunResult<TMachine>;
   /** What the seam call returned, or `undefined` when the run never reached it. */
   seamOutput: unknown;
   /**
@@ -583,8 +600,8 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  * @example No API key: the seam is scripted too, so the whole thing runs offline.
  * ```ts
  * const run = await runSeam(emailDrafter, {
- *   scripts: { promptEvaluator: [vague, complete], emailDrafter: [draft] },
- *   seam: { request: 'evaluatePrompt' },
+ *   scripts: { writeFollowUps: [followUps], emailDrafter: [draft] },
+ *   seam: { request: 'writeFollowUps' },
  *   respond: ({ state }) => (state === 'prompting' ? { type: 'PROMPT_SUBMITTED', prompt } : null),
  * });
  *
@@ -599,4 +616,4 @@ interface RunSeamResult<TMachine extends AnyStateMachine> {
  */
 declare function runSeam<TMachine extends AnyStateMachine>(machine: TMachine, options: RunSeamOptions<TMachine>): Promise<RunSeamResult<TMachine>>;
 //#endregion
-export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type RunSeamOptions, type RunSeamResult, type ScriptedByName, type ScriptedDecisionEntry, type ScriptedDecisionValue, type ScriptedExecutors, type ScriptedExecutorsScript, type ScriptedTextEntry, type SeamCall, type SeamRef, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, createScriptedExecutors, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };
+export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AssertAgentMachineOptions, type CanReachResult, type ExplorePathsOptions, 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 TrajectoryEvent, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, explorePaths, lintAgentMachine, matchesTrajectory, runSeam, simulateAgent };