@statelyai/agent 2.0.0-alpha.38 → 2.0.0-alpha.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
  3. package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
  4. package/dist/ai-sdk.cjs +4 -4
  5. package/dist/ai-sdk.d.cts +2 -3
  6. package/dist/ai-sdk.d.mts +2 -3
  7. package/dist/ai-sdk.mjs +4 -4
  8. package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
  9. package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
  10. package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
  11. package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
  12. package/dist/effects-B9IvUPVh.mjs +23 -0
  13. package/dist/effects-DrWcUGgc.cjs +34 -0
  14. package/dist/evals.cjs +810 -0
  15. package/dist/evals.d.cts +595 -0
  16. package/dist/evals.d.mts +595 -0
  17. package/dist/evals.mjs +801 -0
  18. package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
  19. package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
  20. package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
  21. package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
  22. package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
  23. package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
  24. package/dist/index.cjs +142 -97
  25. package/dist/index.d.cts +97 -141
  26. package/dist/index.d.mts +97 -141
  27. package/dist/index.mjs +123 -74
  28. package/dist/internal-BzlpzSux.d.cts +14 -0
  29. package/dist/internal-BzlpzSux.d.mts +14 -0
  30. package/dist/log.cjs +2 -3
  31. package/dist/log.d.cts +2 -2
  32. package/dist/log.d.mts +2 -2
  33. package/dist/log.mjs +3 -3
  34. package/dist/machine-input-0YTPcnCm.mjs +27 -0
  35. package/dist/machine-input-DU3owLUr.cjs +32 -0
  36. package/dist/machines.cjs +1 -719
  37. package/dist/machines.d.cts +2 -424
  38. package/dist/machines.d.mts +2 -424
  39. package/dist/machines.mjs +2 -709
  40. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  41. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  42. package/dist/openai.cjs +3 -3
  43. package/dist/openai.d.cts +2 -3
  44. package/dist/openai.d.mts +2 -3
  45. package/dist/openai.mjs +3 -3
  46. package/dist/otel.d.cts +1 -1
  47. package/dist/otel.d.mts +1 -1
  48. package/dist/policy.cjs +77 -0
  49. package/dist/policy.d.cts +143 -0
  50. package/dist/policy.d.mts +143 -0
  51. package/dist/policy.mjs +75 -0
  52. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-BO9RSb7i.d.cts} +33 -40
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-BxkeuAYR.d.mts} +33 -40
  54. package/dist/{effects-DDseYtJk.cjs → run-agent-COdR9FpM.cjs} +175 -228
  55. package/dist/{effects-BT_cSY0j.mjs → run-agent-D3gW9wfd.mjs} +176 -211
  56. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  57. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  58. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  59. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  60. package/dist/tanstack-ai.cjs +4 -4
  61. package/dist/tanstack-ai.d.cts +2 -3
  62. package/dist/tanstack-ai.d.mts +2 -3
  63. package/dist/tanstack-ai.mjs +4 -4
  64. package/dist/testing.cjs +122 -996
  65. package/dist/testing.d.cts +36 -695
  66. package/dist/testing.d.mts +36 -695
  67. package/dist/testing.mjs +112 -977
  68. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  69. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  70. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  71. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  72. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  73. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  74. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  75. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  76. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  77. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  78. package/dist/validate.cjs +4 -4
  79. package/dist/validate.d.cts +2 -2
  80. package/dist/validate.d.mts +2 -2
  81. package/dist/validate.mjs +4 -4
  82. package/dist/{verify-DJHfEfm6.d.cts → verify-CIu4mqIZ.d.mts} +56 -6
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-CTHlmBbh.d.cts} +56 -6
  84. package/dist/{verify-ChyX6jq0.mjs → verify-Cacz6XSk.mjs} +170 -46
  85. package/dist/{verify-CwlombbC.cjs → verify-D8UDqU4l.cjs} +170 -46
  86. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  87. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  88. package/docs/advanced.md +5 -5
  89. package/docs/choosing-a-run-mode.md +7 -7
  90. package/docs/debugging.md +6 -8
  91. package/docs/decisions.md +5 -4
  92. package/docs/environment-and-policy.md +1 -1
  93. package/docs/evals.md +57 -43
  94. package/docs/event-log.md +13 -15
  95. package/docs/from-a-loop.md +3 -3
  96. package/docs/generate-machines.md +4 -4
  97. package/docs/hosts.md +25 -30
  98. package/docs/human-in-the-loop.md +5 -8
  99. package/docs/index.md +4 -4
  100. package/docs/judgments.md +5 -7
  101. package/docs/langgraph-comparison.md +6 -6
  102. package/docs/machines-as-data.md +7 -12
  103. package/docs/machines-presets.md +17 -120
  104. package/docs/machines.md +13 -13
  105. package/docs/models-and-providers.md +19 -25
  106. package/docs/multi-agent.md +1 -1
  107. package/docs/observability.md +6 -8
  108. package/docs/persistence.md +10 -20
  109. package/docs/quickstart.md +3 -3
  110. package/docs/statechart-policy-examples.md +1 -1
  111. package/docs/steps.md +5 -6
  112. package/docs/strangler-fig.md +105 -33
  113. package/docs/text-requests.md +10 -12
  114. package/docs/thinking-in-state-machines.md +8 -8
  115. package/docs/tools.md +10 -12
  116. package/docs/upgrading.md +1 -1
  117. package/docs/usage-and-budgets.md +51 -56
  118. package/docs/validate-and-repair.md +9 -14
  119. package/docs/verify.md +54 -7
  120. package/docs/xstate-4-and-5-apps.md +19 -28
  121. package/llms.txt +1 -1
  122. package/package.json +31 -6
  123. package/readme.md +32 -24
  124. package/dist/internal-C3Lqu538.d.cts +0 -43
  125. package/dist/internal-DUcdhk-i.d.mts +0 -43
  126. package/dist/types-DQUOOaZO.d.cts +0 -238
  127. package/dist/types-DQUOOaZO.d.mts +0 -238
  128. package/skills/add-evals/SKILL.md +0 -152
  129. package/skills/add-traces/SKILL.md +0 -152
  130. package/skills/build-machine/SKILL.md +0 -84
  131. package/skills/generate-machine/SKILL.md +0 -335
  132. package/skills/graph-engineering/SKILL.md +0 -43
  133. package/skills/improve-machine/SKILL.md +0 -261
  134. package/skills/improve-machine/reference.md +0 -101
  135. package/skills/loop-to-machine/SKILL.md +0 -205
  136. package/skills/loop-to-machine/policy.md +0 -154
  137. package/skills/loop-to-machine/reference.md +0 -260
@@ -1,8 +1,7 @@
1
- import { C as StandardSchemaV1, j as WithAgentInputSchema, l as AgentTools, y as InferInput } from "./types-DQUOOaZO.mjs";
2
- import { B as DecisionAttempt, L as AgentDecisionRequest, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BqxalgMr.mjs";
3
- import { n as AgentUsageEvent } from "./usage-BnikdOca.mjs";
4
- import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-BBS8so8a.mjs";
5
- import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
1
+ import { B as DecisionAttempt, L as AgentDecisionRequest, Lt as WithAgentInputSchema, Tt as InferInput, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, ht as AgentTools, kt as StandardSchemaV1, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.cjs";
2
+ import { n as AgentUsageEvent } from "./usage-DvGcoK6x.cjs";
3
+ import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-aFXK6yZX.cjs";
4
+ import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
5
  import { DurableExecution } from "xstate/durable";
7
6
  //#region src/steps.d.ts
8
7
  /**
@@ -208,6 +207,8 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
208
207
  declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
209
208
  includeRaw?: boolean;
210
209
  }): JsonSerializableTraceEvent;
210
+ /** The action implementations `machine.provide` accepts for `TMachine`. */
211
+ type ProvidedActions<TMachine extends AnyStateMachine> = NonNullable<Parameters<TMachine["provide"]>[0]["actions"]>;
211
212
  /**
212
213
  * Options for {@link createAgentRuntime}: what the runtime binds and observes.
213
214
  * The run's `input`/`snapshot`/`events` go to {@link AgentRuntime.start} (or
@@ -272,6 +273,13 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
272
273
  metadata?: Record<string, JsonValue$1>;
273
274
  /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
274
275
  actors?: Record<string, AnyActorLogic>;
276
+ /**
277
+ * Action implementations for this run, merged onto the machine before
278
+ * binding: sugar for `machine.provide({ actions })`. Each key must be an
279
+ * action declared in `setupAgent`, with the same params. Build them per run
280
+ * to close over live objects (a store, a session) that cannot go in context.
281
+ */
282
+ actions?: ProvidedActions<TMachine>;
275
283
  /**
276
284
  * Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
277
285
  * chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
@@ -361,9 +369,12 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
361
369
  * when the machine has no transition for `event`, when the loop never
362
370
  * applies it, when the machine settles still `active` after handling it,
363
371
  * or when `timeout` milliseconds pass while it is still working.
372
+ *
373
+ * `event` can be a function of `signal.reason`, so aborts with different
374
+ * reasons (a pause and a stop) send different events.
364
375
  */
365
376
  abortWith?: {
366
- event: EventFromLogic<TMachine>;
377
+ event: EventFromLogic<TMachine> | ((reason: unknown) => EventFromLogic<TMachine>);
367
378
  timeout?: number;
368
379
  };
369
380
  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
@@ -609,7 +620,8 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
609
620
  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
610
621
  /**
611
622
  * Delivers a host event (a cancel, a user message, a host-owned timer) into
612
- * the run's mailbox, behind whatever already arrived. Asynchronous: `send`
623
+ * the run, behind earlier host sends and ahead of completions not yet handed
624
+ * out. Asynchronous: `send`
613
625
  * only enqueues; the machine moves when the host loop's next `nextEvent()`
614
626
  * hands the event out (a parked `nextEvent()` resolves with it) and the loop
615
627
  * calls `transition`. A host that needs the event applied before it returns
@@ -623,8 +635,9 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
623
635
  *
624
636
  * - Before `start`: queued; the first `nextEvent()` hands it out (after the
625
637
  * init event a host delivers itself). Returns `true`.
626
- * - While an effect, child or timer is in flight: queued in arrival order
627
- * with their completions. Returns `true`.
638
+ * - While an effect, child or timer is in flight: queued behind earlier
639
+ * host sends, and handed out before any completion the run holds, so
640
+ * actors that settle in microtasks cannot keep it waiting. Returns `true`.
628
641
  * - After the run stopped (cancelled, aborted, journal failure) or the
629
642
  * machine left `active` (done, error): dropped. Returns `false`.
630
643
  * - After `finish`: throws {@link AgentError} `runtime-finished`.
@@ -655,13 +668,6 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
655
668
  */
656
669
  attempts?: DecisionAttempt[];
657
670
  }
658
- /**
659
- * The blocking host: opens the run, delivers `event` if given, then applies
660
- * every event that arrives until the run is quiescent, and returns the
661
- * outcome. A request handler or durable engine writes the same loop with its
662
- * own stop policy; this one is for scripts and tests.
663
- */
664
- declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
665
671
  /** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
666
672
  interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
667
673
  /**
@@ -681,17 +687,24 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
681
687
  * A host that cannot block for the answer (a request handler, a durable
682
688
  * object) leaves this out, stores `result.persist()`, and calls
683
689
  * {@link runAgent} again later with `{ snapshot, event }`.
690
+ *
691
+ * `"inbox"`: each idle state waits for the next `inbox.send` (a resume
692
+ * after a pause), with no answer of its own. Needs `inbox`.
684
693
  */
685
- onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
694
+ onIdle?: ((snapshot: SnapshotFrom<TMachine>, options: {
686
695
  signal: AbortSignal | undefined;
687
- }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>;
696
+ }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>) | "inbox";
688
697
  /**
689
698
  * A send handle for events pushed mid-run (a cancel, a user message), from
690
699
  * {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
691
700
  * {@link AgentRuntime.send}; one sent before the run starts is delivered
692
701
  * after the opening `event`. An inbox event that arrives while the run is
693
702
  * idle resumes it, ahead of a pending `onIdle` answer (that answer is then
694
- * dropped). One inbox serves one `runAgent` call.
703
+ * dropped). Without `onIdle`, the run returns at the first idle state
704
+ * (an event that lands while that pass is finishing still resumes it), and
705
+ * a `send` after `runAgent` returns gets `false`: a pause that waits for a
706
+ * resume needs `onIdle` as well (`onIdle: "inbox"` when only the inbox
707
+ * answers). One inbox serves one `runAgent` call.
695
708
  */
696
709
  inbox?: AgentInbox<EventFromLogic<TMachine>>;
697
710
  }
@@ -779,26 +792,6 @@ declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, o
779
792
  * `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
780
793
  */
781
794
  declare function createAgentRuntime<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRuntimeOptions<TMachine>): AgentRuntime<TMachine>;
782
- /**
783
- * The actor handed to an {@link inspectTransitions} handler: an
784
- * {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
785
- * transition to the root machine or a specific invoked child (xstate's static
786
- * `ActorRef` type omits them, but they are always present at runtime).
787
- */
788
- type InspectedActorRef = AnyActorRef & {
789
- id: string;
790
- src?: string | AnyActorLogic;
791
- };
792
- /**
793
- * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
794
- * {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
795
- * `@xstate.transition` events and hands the handler the typed
796
- * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
797
- * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
798
- * the manual `event.type === '@xstate.transition'` filtering and the snapshot/
799
- * actorRef casts.
800
- */
801
- declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
802
795
  /**
803
796
  * An xstate `inspect` handler that emits `machine.transition` trace events onto
804
797
  * `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
@@ -835,4 +828,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
835
828
  */
836
829
  declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
837
830
  //#endregion
838
- export { AgentStepRequest as A, inspectTransitions as C, serializeTraceEvent as D, runToQuiescence as E, traceTransitions as O, createAgentRuntime as S, runAgent as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, JsonSerializableTraceEvent as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRequest as k, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, isAgentIdle as w, createAgentInbox as x, InspectedActorRef as y };
831
+ export { runAgent as C, AgentStepRequest as D, AgentRequest as E, isAgentIdle as S, traceTransitions as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, createAgentInbox as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, serializeTraceEvent as w, createAgentRuntime as x, JsonSerializableTraceEvent as y };
@@ -1,8 +1,7 @@
1
- import { C as StandardSchemaV1, j as WithAgentInputSchema, l as AgentTools, y as InferInput } from "./types-DQUOOaZO.cjs";
2
- import { B as DecisionAttempt, L as AgentDecisionRequest, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-CSf9bqpP.cjs";
3
- import { n as AgentUsageEvent } from "./usage-Bm5nvpow.cjs";
4
- import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-bc4ICGcS.cjs";
5
- import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
1
+ import { B as DecisionAttempt, L as AgentDecisionRequest, Lt as WithAgentInputSchema, Tt as InferInput, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, ht as AgentTools, kt as StandardSchemaV1, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.mjs";
2
+ import { n as AgentUsageEvent } from "./usage-B4B-TQSV.mjs";
3
+ import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-DYun526m.mjs";
4
+ import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
5
  import { DurableExecution } from "xstate/durable";
7
6
  //#region src/steps.d.ts
8
7
  /**
@@ -208,6 +207,8 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
208
207
  declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
209
208
  includeRaw?: boolean;
210
209
  }): JsonSerializableTraceEvent;
210
+ /** The action implementations `machine.provide` accepts for `TMachine`. */
211
+ type ProvidedActions<TMachine extends AnyStateMachine> = NonNullable<Parameters<TMachine["provide"]>[0]["actions"]>;
211
212
  /**
212
213
  * Options for {@link createAgentRuntime}: what the runtime binds and observes.
213
214
  * The run's `input`/`snapshot`/`events` go to {@link AgentRuntime.start} (or
@@ -272,6 +273,13 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
272
273
  metadata?: Record<string, JsonValue$1>;
273
274
  /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
274
275
  actors?: Record<string, AnyActorLogic>;
276
+ /**
277
+ * Action implementations for this run, merged onto the machine before
278
+ * binding: sugar for `machine.provide({ actions })`. Each key must be an
279
+ * action declared in `setupAgent`, with the same params. Build them per run
280
+ * to close over live objects (a store, a session) that cannot go in context.
281
+ */
282
+ actions?: ProvidedActions<TMachine>;
275
283
  /**
276
284
  * Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
277
285
  * chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
@@ -361,9 +369,12 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
361
369
  * when the machine has no transition for `event`, when the loop never
362
370
  * applies it, when the machine settles still `active` after handling it,
363
371
  * or when `timeout` milliseconds pass while it is still working.
372
+ *
373
+ * `event` can be a function of `signal.reason`, so aborts with different
374
+ * reasons (a pause and a stop) send different events.
364
375
  */
365
376
  abortWith?: {
366
- event: EventFromLogic<TMachine>;
377
+ event: EventFromLogic<TMachine> | ((reason: unknown) => EventFromLogic<TMachine>);
367
378
  timeout?: number;
368
379
  };
369
380
  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
@@ -609,7 +620,8 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
609
620
  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
610
621
  /**
611
622
  * Delivers a host event (a cancel, a user message, a host-owned timer) into
612
- * the run's mailbox, behind whatever already arrived. Asynchronous: `send`
623
+ * the run, behind earlier host sends and ahead of completions not yet handed
624
+ * out. Asynchronous: `send`
613
625
  * only enqueues; the machine moves when the host loop's next `nextEvent()`
614
626
  * hands the event out (a parked `nextEvent()` resolves with it) and the loop
615
627
  * calls `transition`. A host that needs the event applied before it returns
@@ -623,8 +635,9 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
623
635
  *
624
636
  * - Before `start`: queued; the first `nextEvent()` hands it out (after the
625
637
  * init event a host delivers itself). Returns `true`.
626
- * - While an effect, child or timer is in flight: queued in arrival order
627
- * with their completions. Returns `true`.
638
+ * - While an effect, child or timer is in flight: queued behind earlier
639
+ * host sends, and handed out before any completion the run holds, so
640
+ * actors that settle in microtasks cannot keep it waiting. Returns `true`.
628
641
  * - After the run stopped (cancelled, aborted, journal failure) or the
629
642
  * machine left `active` (done, error): dropped. Returns `false`.
630
643
  * - After `finish`: throws {@link AgentError} `runtime-finished`.
@@ -655,13 +668,6 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
655
668
  */
656
669
  attempts?: DecisionAttempt[];
657
670
  }
658
- /**
659
- * The blocking host: opens the run, delivers `event` if given, then applies
660
- * every event that arrives until the run is quiescent, and returns the
661
- * outcome. A request handler or durable engine writes the same loop with its
662
- * own stop policy; this one is for scripts and tests.
663
- */
664
- declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
665
671
  /** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
666
672
  interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
667
673
  /**
@@ -681,17 +687,24 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
681
687
  * A host that cannot block for the answer (a request handler, a durable
682
688
  * object) leaves this out, stores `result.persist()`, and calls
683
689
  * {@link runAgent} again later with `{ snapshot, event }`.
690
+ *
691
+ * `"inbox"`: each idle state waits for the next `inbox.send` (a resume
692
+ * after a pause), with no answer of its own. Needs `inbox`.
684
693
  */
685
- onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
694
+ onIdle?: ((snapshot: SnapshotFrom<TMachine>, options: {
686
695
  signal: AbortSignal | undefined;
687
- }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>;
696
+ }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>) | "inbox";
688
697
  /**
689
698
  * A send handle for events pushed mid-run (a cancel, a user message), from
690
699
  * {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
691
700
  * {@link AgentRuntime.send}; one sent before the run starts is delivered
692
701
  * after the opening `event`. An inbox event that arrives while the run is
693
702
  * idle resumes it, ahead of a pending `onIdle` answer (that answer is then
694
- * dropped). One inbox serves one `runAgent` call.
703
+ * dropped). Without `onIdle`, the run returns at the first idle state
704
+ * (an event that lands while that pass is finishing still resumes it), and
705
+ * a `send` after `runAgent` returns gets `false`: a pause that waits for a
706
+ * resume needs `onIdle` as well (`onIdle: "inbox"` when only the inbox
707
+ * answers). One inbox serves one `runAgent` call.
695
708
  */
696
709
  inbox?: AgentInbox<EventFromLogic<TMachine>>;
697
710
  }
@@ -779,26 +792,6 @@ declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, o
779
792
  * `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
780
793
  */
781
794
  declare function createAgentRuntime<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRuntimeOptions<TMachine>): AgentRuntime<TMachine>;
782
- /**
783
- * The actor handed to an {@link inspectTransitions} handler: an
784
- * {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
785
- * transition to the root machine or a specific invoked child (xstate's static
786
- * `ActorRef` type omits them, but they are always present at runtime).
787
- */
788
- type InspectedActorRef = AnyActorRef & {
789
- id: string;
790
- src?: string | AnyActorLogic;
791
- };
792
- /**
793
- * Wraps a `(snapshot, actorRef) => void` handler into a function usable as
794
- * {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
795
- * `@xstate.transition` events and hands the handler the typed
796
- * {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
797
- * transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
798
- * the manual `event.type === '@xstate.transition'` filtering and the snapshot/
799
- * actorRef casts.
800
- */
801
- declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
802
795
  /**
803
796
  * An xstate `inspect` handler that emits `machine.transition` trace events onto
804
797
  * `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
@@ -835,4 +828,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
835
828
  */
836
829
  declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
837
830
  //#endregion
838
- export { AgentStepRequest as A, inspectTransitions as C, serializeTraceEvent as D, runToQuiescence as E, traceTransitions as O, createAgentRuntime as S, runAgent as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, JsonSerializableTraceEvent as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRequest as k, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, isAgentIdle as w, createAgentInbox as x, InspectedActorRef as y };
831
+ export { runAgent as C, AgentStepRequest as D, AgentRequest as E, isAgentIdle as S, traceTransitions as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, createAgentInbox as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, serializeTraceEvent as w, createAgentRuntime as x, JsonSerializableTraceEvent as y };