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

package/dist/{run-agent-ByO-Bxyd.d.cts → run-agent-CTlMc3Jb.d.cts}

@@ -1,23 +1,9 @@
-import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-hR5f5YXa.cjs";
-import { K as AgentRequestSource, M as AgentDecisionRequest, U as AgentEventDescriptor, Z as AgentError, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-IjfYy9DP.cjs";
-import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-2xzFmgr2.cjs";
-import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom } from "xstate";
+import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.cjs";
+import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-DmciuVUQ.cjs";
+import { n as AgentUsageEvent } from "./usage-Cm_ovz9V.cjs";
+import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-CLAC9q2Y.cjs";
+import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
 import { DurableExecution } from "xstate/durable";
-
-//#region src/usage.d.ts
-/** Reserved event delivered after a model call reports token usage. */
-declare const AGENT_USAGE_EVENT_TYPE: "@agent.usage";
-/** Machine-owned usage signal. Handle it with an ordinary XState transition. */
-interface AgentUsageEvent extends EventObject {
-  type: typeof AGENT_USAGE_EVENT_TYPE;
-  usage: AgentCallUsage;
-  kind?: "text" | "decision";
-  id?: string;
-  src?: string;
-  model?: string;
-  name?: string;
-}
-//#endregion
 //#region src/steps.d.ts
 /**
  * A pending text request surfaced by step discovery ({@link getAgentRequests}
@@ -81,11 +67,13 @@ type AgentTransitionHandler<TMachine extends AnyStateMachine> = (snapshot: Snaps
  */
 declare const AGENT_TRACE_SCHEMA_VERSION = 1;
 type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
-  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
+  /** The {@link AGENT_TRACE_SCHEMA_VERSION} the event was produced with. */
+  schemaVersion: typeof AGENT_TRACE_SCHEMA_VERSION;
   runId: string;
   seq: number;
   timestamp: string;
-  machineId: string; /** The machine's own `version`, else its structural hash. */
+  machineId: string;
+  /** The machine's own `version`, else its structural hash. */
   machineVersion: string;
 } & ({
   type: "run.start";
@@ -122,6 +110,15 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   chunk: string;
 } | {
   type: "machine.transition";
+  /**
+   * Where the event arrived: the state value before this transition. The
+   * first transition of a stream (the init event, or the restore on
+   * resume) has no earlier state, so its `from.value` is its own
+   * `snapshot.value`. An object so more of the prior snapshot can join it.
+   */
+  from: {
+    value: StateValue;
+  };
   snapshot: SnapshotFrom<TMachine>;
   event: EventFromLogic<TMachine>;
 } | {
@@ -132,7 +129,8 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
    * tokens still fold into {@link AgentRunResult.usage}; only the machine
    * event is dropped. */
   type: "usage.dropped";
-  event: AgentUsageEvent; /** `'settled'`: the call settled after the run's cycle had resolved. */
+  event: AgentUsageEvent;
+  /** `'settled'`: the call settled after the run's cycle had resolved. */
   reason: "settled";
 } | ({
   type: "run.end";
@@ -159,7 +157,7 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
  */
 type TraceVerbatimKey = (typeof TRACE_ENVELOPE_KEYS)[number] | "reason";
 /** One trace variant's JSON projection. Homomorphic, so `?` modifiers survive. @internal */
-type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue };
+type JsonProjectedTraceVariant<TEvent> = { [K in keyof TEvent]: K extends TraceVerbatimKey ? TEvent[K] : JsonValue; };
 /**
  * `raw` is written only when `includeRaw` was set, so it is optional on the
  * JSON side even though the live trace always carries it. @internal
@@ -178,7 +176,7 @@ type WithOptionalRaw<T> = "raw" extends keyof T ? Omit<T, "raw"> & {
  * miss the JSON side. `src/serialize-trace-event.test.ts` pins the result to
  * the shape this type had when it was hand-maintained.
  */
-type JsonSerializableTraceEvent = AgentTraceEvent extends infer TEvent ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
+type JsonSerializableTraceEvent = AgentTraceEvent extends (infer TEvent) ? TEvent extends unknown ? WithOptionalRaw<JsonProjectedTraceVariant<TEvent>> : never : never;
 declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "timestamp", "machineId", "machineVersion", "type", "status", "cause", "reasoning", "finishReason", "chunk"];
 /**
  * Projects an {@link AgentTraceEvent} into a guaranteed JSON-safe envelope —
@@ -253,6 +251,14 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
    * the same state. Set `false` for a smaller, unverifiable log.
    */
   verification?: boolean;
+  /**
+   * Host-owned JSON stored on the log's `@agent.init` entry when this run
+   * starts a log: what produced the run, such as a policy version, the model
+   * ids, or the scenario. A resume keeps the stamp of the run that started
+   * the log; a version bridge, which opens a new log segment, takes this
+   * run's. `executionId` and `migratedFrom` are reserved and cannot be set here.
+   */
+  metadata?: Record<string, JsonValue$1>;
   /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
   actors?: Record<string, AnyActorLogic>;
   /**
@@ -292,7 +298,7 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
    */
   on?: { [TType in EmittedFrom<TMachine>["type"] | "*"]?: (emitted: EmittedFrom<TMachine> & (TType extends "*" ? unknown : {
     type: TType;
-  })) => void };
+  })) => void; };
   /**
    * Raw xstate inspection passthrough: fires for every inspection event in
    * the whole actor system — root machine, invoked child machines, spawned
@@ -549,8 +555,15 @@ interface AgentRunStart<TMachine extends AnyStateMachine> {
 interface AgentRuntime<TMachine extends AnyStateMachine> {
   /** Opens the run: a fresh start from `input`, a resume from `snapshot`, or recovery from a log. */
   start(init?: AgentRunStart<TMachine>): Promise<[SnapshotFrom<TMachine>, AgentEffects]>;
-  /** Applies one event: journals it, traces it, and returns the next state plus its effects. */
-  transition(state: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine> | AgentTimerEvent): [SnapshotFrom<TMachine>, AgentEffects];
+  /**
+   * Applies one event: journals it, traces it, and returns the next state plus
+   * its effects. `options.attempts` records the failed attempts of a decider
+   * the host ran itself (e.g. `decideNext`'s `attempts`) on the event's entry
+   * as `entry.attempts`. Replay ignores them; an empty list is not journaled.
+   */
+  transition(state: SnapshotFrom<TMachine>, event: EventFromLogic<TMachine> | AgentTimerEvent, options?: {
+    attempts?: DecisionAttempt[];
+  }): [SnapshotFrom<TMachine>, AgentEffects];
   /** Starts the effects' work and returns once it is accepted, not once it finishes. */
   execute(effects: AgentEffects): Promise<void>;
   /** The next event that arrived, or `undefined` once the run is quiescent. */
@@ -570,6 +583,12 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
    * due is delivered the same way, as an {@link AgentTimerEvent}.
    */
   event?: EventFromLogic<TMachine> | AgentTimerEvent;
+  /**
+   * The failed attempts of the decider the host ran to choose `event` (e.g.
+   * `decideNext`'s `attempts`), journaled on `event`'s entry as
+   * `entry.attempts`. Replay ignores them.
+   */
+  attempts?: DecisionAttempt[];
 }
 /**
  * The blocking host: opens the run, delivers `event` if given, then applies
@@ -578,6 +597,51 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
  * own stop policy; this one is for scripts and tests.
  */
 declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
+/** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
+interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
+  /**
+   * Answers an idle state for a host that can block for it. When given,
+   * {@link runAgent} loops: each time the run settles `idle`, it calls
+   * `onIdle` with the idle snapshot, persists the run, and resumes from that
+   * persisted snapshot with the returned event — until the run is `done` or
+   * `error`. Each pass is a fresh {@link createAgentRuntime} over the same
+   * options, so nothing of the earlier pass is held across the wait; the log
+   * travels with the result (or the store's thread), so the final `events`
+   * replays every pass, and `maxModelCalls` bounds the whole call. An answer
+   * the idle state does not handle ends the loop: the result is `idle` with
+   * {@link AgentRunResult.ignored} set, not another call to `onIdle`.
+   *
+   * A host that cannot block for the answer (a request handler, a durable
+   * object) leaves this out, stores `result.persist()`, and calls
+   * {@link runAgent} again later with `{ snapshot, event }`.
+   */
+  onIdle?: (snapshot: SnapshotFrom<TMachine>) => Promise<EventFromLogic<TMachine>>;
+}
+/**
+ * Runs `machine` to quiescence in one call: {@link createAgentRuntime} over
+ * `options`, then {@link runToQuiescence} with the same object as its init.
+ * One options object carries both halves (`executors`, `store`, callbacks,
+ * and `input` | `snapshot` + `event`), and the result is the same
+ * {@link AgentRunResult}. With {@link AgentRunOptions.onIdle}, idle states are
+ * answered in place and the call returns only `done` or `error`.
+ *
+ * Reach for {@link createAgentRuntime} directly when the host needs the loop
+ * itself: a non-blocking durable host, events pushed mid-run, or a custom stop
+ * or checkpoint policy.
+ *
+ * @example
+ * ```ts
+ * const result = await runAgent(machine, { input: { topic }, executors });
+ * if (result.status === "done") console.log(result.output);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Resume a run a request handler left idle.
+ * const result = await runAgent(machine, { executors, snapshot, event });
+ * ```
+ */
+declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRunOptions<TMachine>): Promise<AgentRunResult<TMachine>>;
 /**
  * Creates the helpers for one run of `machine`: executors bound to its
  * requests, the write-ahead log, traces, the budget, and a mailbox over
@@ -601,7 +665,7 @@ declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: Agen
  * while (r.status === 'idle') {
  *   const event = await promptUser(getAcceptedEvents(r.snapshot));
  *   r = await runToQuiescence(createAgentRuntime(machine, { executors }), {
- *     snapshot: r.snapshot,
+ *     snapshot: r.persist(),
  *     event,
  *   });
  * }
@@ -647,7 +711,8 @@ declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, acto
  * ```
  *
  * Only ROOT-actor transitions are traced (matching the runtime's
- * `machine.transition`); child-actor transitions are ignored. Attribute the
+ * `machine.transition`); child-actor transitions are ignored. Each event's
+ * `from.value` is the root's previous state value, tracked per root actor. Attribute the
  * event via its envelope `runId`.
  *
  * By design this path has NO `run.start`/`run.end` events: `createActor` has no
@@ -669,4 +734,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
  */
 declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
 //#endregion
-export { serializeTraceEvent as C, AGENT_USAGE_EVENT_TYPE as D, AgentStepRequest as E, AgentUsageEvent as O, runToQuiescence as S, AgentRequest as T, InspectedActorRef as _, AgentRunErrorCause as a, inspectTransitions as b, AgentRunResult as c, AgentRuntimeOptions as d, AgentSnapshotDivergedError as f, AgentTransitionHandler as g, AgentTraceEvent as h, AgentMaxModelCallsExceededError as i, AgentRunStart as l, AgentTimerScheduler as m, AgentEffects as n, AgentRunInit as o, AgentTimerEvent as p, AgentInputFrom as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRuntime as u, JsonSerializableTraceEvent as v, traceTransitions as w, isAgentIdle as x, createAgentRuntime as y };
+export { runAgent as C, AgentRequest as D, traceTransitions as E, AgentStepRequest as O, isAgentIdle as S, serializeTraceEvent as T, AgentTransitionHandler as _, AgentRunErrorCause as a, createAgentRuntime as b, AgentRunOptions as c, AgentRuntime as d, AgentRuntimeOptions as f, AgentTraceEvent as g, AgentTimerScheduler as h, AgentMaxModelCallsExceededError as i, AgentRunResult as l, AgentTimerEvent as m, AgentEffects as n, AgentRunInit as o, AgentSnapshotDivergedError as p, AgentInputFrom as r, AgentRunMeta as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunStart as u, InspectedActorRef as v, runToQuiescence as w, inspectTransitions as x, JsonSerializableTraceEvent as y };