@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.37

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 (130) hide show
  1. package/CHANGELOG.md +138 -0
  2. package/dist/act-B9hLQls6.mjs +19 -0
  3. package/dist/act-CrX0JwWY.cjs +42 -0
  4. package/dist/ai-sdk.cjs +63 -7
  5. package/dist/ai-sdk.d.cts +13 -3
  6. package/dist/ai-sdk.d.mts +13 -3
  7. package/dist/ai-sdk.mjs +63 -7
  8. package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
  9. package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
  10. package/dist/decision-object-B5zGSPFp.d.mts +15 -0
  11. package/dist/decision-object-DBcLWVvv.d.cts +15 -0
  12. package/dist/{run-agent-Ct_GZw_f.mjs → effects-BT_cSY0j.mjs} +1003 -109
  13. package/dist/{run-agent-s5D32w99.cjs → effects-DDseYtJk.cjs} +1037 -107
  14. package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
  15. package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
  16. package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
  17. package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
  18. package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
  19. package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
  20. package/dist/index.cjs +660 -286
  21. package/dist/index.d.cts +168 -9
  22. package/dist/index.d.mts +168 -9
  23. package/dist/index.mjs +639 -271
  24. package/dist/internal-C3Lqu538.d.cts +43 -0
  25. package/dist/internal-DUcdhk-i.d.mts +43 -0
  26. package/dist/log.cjs +2 -2
  27. package/dist/log.d.cts +1 -1
  28. package/dist/log.d.mts +1 -1
  29. package/dist/log.mjs +2 -2
  30. package/dist/machines.cjs +457 -41
  31. package/dist/machines.d.cts +114 -43
  32. package/dist/machines.d.mts +114 -43
  33. package/dist/machines.mjs +457 -42
  34. package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
  35. package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
  36. package/dist/openai.cjs +149 -36
  37. package/dist/openai.d.cts +28 -10
  38. package/dist/openai.d.mts +28 -10
  39. package/dist/openai.mjs +149 -36
  40. package/dist/otel.d.cts +1 -1
  41. package/dist/otel.d.mts +1 -1
  42. package/dist/{run-agent-BGdx5913.d.mts → run-agent-30mH2moE.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-DlPzBWj-.d.mts} +91 -9
  44. package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
  45. package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BaNyz6Q3.d.cts} +4 -4
  46. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-C1CG_nfX.d.mts} +4 -4
  47. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  48. package/dist/tanstack-ai.cjs +62 -4
  49. package/dist/tanstack-ai.d.cts +18 -6
  50. package/dist/tanstack-ai.d.mts +18 -6
  51. package/dist/tanstack-ai.mjs +62 -4
  52. package/dist/testing.cjs +2493 -1502
  53. package/dist/testing.d.cts +360 -256
  54. package/dist/testing.d.mts +360 -256
  55. package/dist/testing.mjs +2489 -1503
  56. package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
  57. package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
  58. package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
  59. package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
  60. package/dist/{usage-BDiJKyv9.d.cts → usage-Bm5nvpow.d.cts} +6 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-BnikdOca.d.mts} +6 -1
  62. package/dist/utils-7lSa4H-i.d.cts +403 -0
  63. package/dist/utils-CBbKw2fM.d.mts +403 -0
  64. package/dist/validate.cjs +44 -12
  65. package/dist/validate.d.cts +6 -6
  66. package/dist/validate.d.mts +6 -6
  67. package/dist/validate.mjs +44 -12
  68. package/dist/verify-ChyX6jq0.mjs +2306 -0
  69. package/dist/verify-CwlombbC.cjs +2359 -0
  70. package/dist/{verify-BQpE8hUz.d.cts → verify-DJHfEfm6.d.cts} +213 -14
  71. package/dist/{verify-CqeuEmIk.d.mts → verify-i9Hiwc5g.d.mts} +213 -14
  72. package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
  73. package/dist/with-model-calls-BkOwdroS.mjs +213 -0
  74. package/docs/act.md +102 -0
  75. package/docs/advanced.md +105 -0
  76. package/docs/any-stack.md +62 -0
  77. package/docs/choosing-a-run-mode.md +55 -0
  78. package/docs/debugging.md +29 -0
  79. package/docs/decisions.md +473 -0
  80. package/docs/environment-and-policy.md +188 -0
  81. package/docs/evals.md +509 -0
  82. package/docs/event-log.md +312 -0
  83. package/docs/from-a-loop.md +528 -0
  84. package/docs/generate-machines.md +110 -0
  85. package/docs/hosts.md +414 -0
  86. package/docs/human-in-the-loop.md +177 -0
  87. package/docs/index.md +48 -0
  88. package/docs/judgments.md +281 -0
  89. package/docs/langgraph-comparison.md +198 -0
  90. package/docs/machines-as-data.md +454 -0
  91. package/docs/machines-presets.md +198 -0
  92. package/docs/machines.md +497 -0
  93. package/docs/messages.md +67 -0
  94. package/docs/meta.json +52 -0
  95. package/docs/models-and-providers.md +268 -0
  96. package/docs/multi-agent.md +68 -0
  97. package/docs/observability.md +109 -0
  98. package/docs/patterns.md +31 -0
  99. package/docs/persistence.md +207 -0
  100. package/docs/quickstart.md +121 -0
  101. package/docs/roadmap.md +22 -0
  102. package/docs/scope.md +75 -0
  103. package/docs/statechart-policy-examples.md +69 -0
  104. package/docs/steps.md +56 -0
  105. package/docs/strangler-fig.md +323 -0
  106. package/docs/text-requests.md +250 -0
  107. package/docs/thinking-in-state-machines.md +324 -0
  108. package/docs/tools.md +249 -0
  109. package/docs/upgrading.md +37 -0
  110. package/docs/usage-and-budgets.md +518 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +492 -0
  113. package/docs/xstate-4-and-5-apps.md +161 -0
  114. package/llms.txt +53 -0
  115. package/package.json +10 -3
  116. package/readme.md +30 -15
  117. package/skills/add-evals/SKILL.md +3 -1
  118. package/skills/add-traces/SKILL.md +6 -1
  119. package/skills/build-machine/SKILL.md +84 -0
  120. package/skills/generate-machine/SKILL.md +1 -1
  121. package/skills/graph-engineering/SKILL.md +13 -3
  122. package/skills/improve-machine/SKILL.md +21 -2
  123. package/skills/loop-to-machine/SKILL.md +147 -192
  124. package/skills/loop-to-machine/reference.md +260 -0
  125. package/dist/utils-BnXdWih3.d.mts +0 -108
  126. package/dist/utils-ebVpCYoF.d.cts +0 -108
  127. package/dist/verify-Bpahmr34.mjs +0 -1241
  128. package/dist/verify-DCLZa9R0.cjs +0 -1288
  129. package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
  130. package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
@@ -1,7 +1,7 @@
1
- import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.mjs";
2
- import { $ as AgentError, G as AgentEventDescriptor, J as AgentRequestSource, L as DecisionAttempt, P as AgentDecisionRequest, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-Ckh-rJFV.mjs";
3
- import { n as AgentUsageEvent } from "./usage-DOoVUGVq.mjs";
4
- import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-CWjN6lmM.mjs";
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
5
  import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
6
  import { DurableExecution } from "xstate/durable";
7
7
  //#region src/steps.d.ts
@@ -344,8 +344,28 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
344
344
  * Default 0. Not added to this run's `usage.modelCalls`.
345
345
  */
346
346
  modelCallsSpent?: number;
347
- /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
347
+ /**
348
+ * Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with
349
+ * `signal.reason` as the error. With {@link AgentRuntimeOptions.abortWith},
350
+ * the machine sees the abort first.
351
+ */
348
352
  signal?: AbortSignal;
353
+ /**
354
+ * Routes `signal`'s abort through the machine: when it fires, `event` is
355
+ * sent into the run (see {@link AgentRuntime.send}) and the run continues
356
+ * until the machine settles, so a `cancelled` final state, cleanup
357
+ * invokes, and its output run as usual. Until the machine applies
358
+ * `event`, the host's direct `transition` events (such as
359
+ * `runToQuiescence`'s init `event`) are dropped, so the abort goes first.
360
+ * The run falls back to today's `{ status: 'error', cause: 'aborted' }`
361
+ * when the machine has no transition for `event`, when the loop never
362
+ * applies it, when the machine settles still `active` after handling it,
363
+ * or when `timeout` milliseconds pass while it is still working.
364
+ */
365
+ abortWith?: {
366
+ event: EventFromLogic<TMachine>;
367
+ timeout?: number;
368
+ };
349
369
  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
350
370
  timers?: AgentTimerScheduler;
351
371
  }
@@ -587,6 +607,32 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
587
607
  execute(effects: AgentEffects): Promise<void>;
588
608
  /** The next event that arrived, or `undefined` once the run is quiescent. */
589
609
  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
610
+ /**
611
+ * 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`
613
+ * only enqueues; the machine moves when the host loop's next `nextEvent()`
614
+ * hands the event out (a parked `nextEvent()` resolves with it) and the loop
615
+ * calls `transition`. A host that needs the event applied before it returns
616
+ * (a synchronous cancel) calls `transition(state, event)` itself instead,
617
+ * on the loop's current `state`, and keeps the loop's invariants: one
618
+ * shared `state` variable that both paths read and write, `execute` on the
619
+ * returned effects, and no `transition` once the state is not `active`. It is
620
+ * applied by the host's own `transition` call, so it is journaled and
621
+ * replayed like any other event, and reported as `result.ignored` when the
622
+ * state has no transition for it.
623
+ *
624
+ * - Before `start`: queued; the first `nextEvent()` hands it out (after the
625
+ * 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`.
628
+ * - After the run stopped (cancelled, aborted, journal failure) or the
629
+ * machine left `active` (done, error): dropped. Returns `false`.
630
+ * - After `finish`: throws {@link AgentError} `runtime-finished`.
631
+ *
632
+ * A sent event the loop never reads (the host called `finish` without
633
+ * draining `nextEvent()`) is dropped.
634
+ */
635
+ send(event: EventFromLogic<TMachine> | AgentTimerEvent): boolean;
590
636
  /** Settles the run: stops what is still running and returns the outcome. */
591
637
  finish(): Promise<AgentRunResult<TMachine>>;
592
638
  }
@@ -623,8 +669,10 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
623
669
  * {@link runAgent} loops: each time the run settles `idle`, it calls
624
670
  * `onIdle` with the idle snapshot, persists the run, and resumes from that
625
671
  * persisted snapshot with the returned event — until the run is `done` or
626
- * `error`. Each pass is a fresh {@link createAgentRuntime} over the same
627
- * options, so nothing of the earlier pass is held across the wait; the log
672
+ * `error`. `signal` aborts the wait too: the run then settles as any abort
673
+ * does. Each pass is a fresh {@link createAgentRuntime} over the same
674
+ * options, so nothing of the earlier pass is held across the wait (an
675
+ * `inspect` callback still sees one root actor); the log
628
676
  * travels with the result (or the store's thread), so the final `events`
629
677
  * replays every pass, and `maxModelCalls` bounds the whole call. An answer
630
678
  * the idle state does not handle ends the loop: the result is `idle` with
@@ -634,8 +682,42 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
634
682
  * object) leaves this out, stores `result.persist()`, and calls
635
683
  * {@link runAgent} again later with `{ snapshot, event }`.
636
684
  */
637
- onIdle?: (snapshot: SnapshotFrom<TMachine>) => Promise<EventFromLogic<TMachine>>;
685
+ onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
686
+ signal: AbortSignal | undefined;
687
+ }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>;
688
+ /**
689
+ * A send handle for events pushed mid-run (a cancel, a user message), from
690
+ * {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
691
+ * {@link AgentRuntime.send}; one sent before the run starts is delivered
692
+ * after the opening `event`. An inbox event that arrives while the run is
693
+ * idle resumes it, ahead of a pending `onIdle` answer (that answer is then
694
+ * dropped). One inbox serves one `runAgent` call.
695
+ */
696
+ inbox?: AgentInbox<EventFromLogic<TMachine>>;
638
697
  }
698
+ /** A send handle into a {@link runAgent} call. See {@link AgentRunOptions.inbox}. */
699
+ interface AgentInbox<TEvent extends EventObject = EventObject> {
700
+ /**
701
+ * Delivers `event` into the run, with the same result as
702
+ * {@link AgentRuntime.send}: `true` when queued (including before the run
703
+ * starts), `false` once the run is done, errored, stopped, or the
704
+ * `runAgent` call returned.
705
+ */
706
+ send(event: TEvent): boolean;
707
+ }
708
+ /**
709
+ * Creates a send handle for {@link AgentRunOptions.inbox}, typed by the
710
+ * machine's events.
711
+ *
712
+ * @example
713
+ * ```ts
714
+ * const inbox = createAgentInbox<EventOf<typeof machine>>();
715
+ * const run = runAgent(machine, { input, executors, inbox });
716
+ * inbox.send({ type: "CANCEL" });
717
+ * const result = await run;
718
+ * ```
719
+ */
720
+ declare function createAgentInbox<TEvent extends EventObject = EventObject>(): AgentInbox<TEvent>;
639
721
  /**
640
722
  * Runs `machine` to quiescence in one call: {@link createAgentRuntime} over
641
723
  * `options`, then {@link runToQuiescence} with the same object as its init.
@@ -753,4 +835,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
753
835
  */
754
836
  declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
755
837
  //#endregion
756
- 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 };
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 };
@@ -1,7 +1,7 @@
1
- import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.cjs";
2
- import { $ as AgentError, G as AgentEventDescriptor, J as AgentRequestSource, L as DecisionAttempt, P as AgentDecisionRequest, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-CV_4KGr6.cjs";
3
- import { n as AgentUsageEvent } from "./usage-BDiJKyv9.cjs";
4
- import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-BzXehP7R.cjs";
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
5
  import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
6
  import { DurableExecution } from "xstate/durable";
7
7
  //#region src/steps.d.ts
@@ -344,8 +344,28 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
344
344
  * Default 0. Not added to this run's `usage.modelCalls`.
345
345
  */
346
346
  modelCallsSpent?: number;
347
- /** Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with `signal.reason` as the error. */
347
+ /**
348
+ * Aborts the run; settles `{ status: 'error', cause: 'aborted' }` with
349
+ * `signal.reason` as the error. With {@link AgentRuntimeOptions.abortWith},
350
+ * the machine sees the abort first.
351
+ */
348
352
  signal?: AbortSignal;
353
+ /**
354
+ * Routes `signal`'s abort through the machine: when it fires, `event` is
355
+ * sent into the run (see {@link AgentRuntime.send}) and the run continues
356
+ * until the machine settles, so a `cancelled` final state, cleanup
357
+ * invokes, and its output run as usual. Until the machine applies
358
+ * `event`, the host's direct `transition` events (such as
359
+ * `runToQuiescence`'s init `event`) are dropped, so the abort goes first.
360
+ * The run falls back to today's `{ status: 'error', cause: 'aborted' }`
361
+ * when the machine has no transition for `event`, when the loop never
362
+ * applies it, when the machine settles still `active` after handling it,
363
+ * or when `timeout` milliseconds pass while it is still working.
364
+ */
365
+ abortWith?: {
366
+ event: EventFromLogic<TMachine>;
367
+ timeout?: number;
368
+ };
349
369
  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
350
370
  timers?: AgentTimerScheduler;
351
371
  }
@@ -587,6 +607,32 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
587
607
  execute(effects: AgentEffects): Promise<void>;
588
608
  /** The next event that arrived, or `undefined` once the run is quiescent. */
589
609
  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
610
+ /**
611
+ * 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`
613
+ * only enqueues; the machine moves when the host loop's next `nextEvent()`
614
+ * hands the event out (a parked `nextEvent()` resolves with it) and the loop
615
+ * calls `transition`. A host that needs the event applied before it returns
616
+ * (a synchronous cancel) calls `transition(state, event)` itself instead,
617
+ * on the loop's current `state`, and keeps the loop's invariants: one
618
+ * shared `state` variable that both paths read and write, `execute` on the
619
+ * returned effects, and no `transition` once the state is not `active`. It is
620
+ * applied by the host's own `transition` call, so it is journaled and
621
+ * replayed like any other event, and reported as `result.ignored` when the
622
+ * state has no transition for it.
623
+ *
624
+ * - Before `start`: queued; the first `nextEvent()` hands it out (after the
625
+ * 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`.
628
+ * - After the run stopped (cancelled, aborted, journal failure) or the
629
+ * machine left `active` (done, error): dropped. Returns `false`.
630
+ * - After `finish`: throws {@link AgentError} `runtime-finished`.
631
+ *
632
+ * A sent event the loop never reads (the host called `finish` without
633
+ * draining `nextEvent()`) is dropped.
634
+ */
635
+ send(event: EventFromLogic<TMachine> | AgentTimerEvent): boolean;
590
636
  /** Settles the run: stops what is still running and returns the outcome. */
591
637
  finish(): Promise<AgentRunResult<TMachine>>;
592
638
  }
@@ -623,8 +669,10 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
623
669
  * {@link runAgent} loops: each time the run settles `idle`, it calls
624
670
  * `onIdle` with the idle snapshot, persists the run, and resumes from that
625
671
  * persisted snapshot with the returned event — until the run is `done` or
626
- * `error`. Each pass is a fresh {@link createAgentRuntime} over the same
627
- * options, so nothing of the earlier pass is held across the wait; the log
672
+ * `error`. `signal` aborts the wait too: the run then settles as any abort
673
+ * does. Each pass is a fresh {@link createAgentRuntime} over the same
674
+ * options, so nothing of the earlier pass is held across the wait (an
675
+ * `inspect` callback still sees one root actor); the log
628
676
  * travels with the result (or the store's thread), so the final `events`
629
677
  * replays every pass, and `maxModelCalls` bounds the whole call. An answer
630
678
  * the idle state does not handle ends the loop: the result is `idle` with
@@ -634,8 +682,42 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
634
682
  * object) leaves this out, stores `result.persist()`, and calls
635
683
  * {@link runAgent} again later with `{ snapshot, event }`.
636
684
  */
637
- onIdle?: (snapshot: SnapshotFrom<TMachine>) => Promise<EventFromLogic<TMachine>>;
685
+ onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
686
+ signal: AbortSignal | undefined;
687
+ }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>;
688
+ /**
689
+ * A send handle for events pushed mid-run (a cancel, a user message), from
690
+ * {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
691
+ * {@link AgentRuntime.send}; one sent before the run starts is delivered
692
+ * after the opening `event`. An inbox event that arrives while the run is
693
+ * idle resumes it, ahead of a pending `onIdle` answer (that answer is then
694
+ * dropped). One inbox serves one `runAgent` call.
695
+ */
696
+ inbox?: AgentInbox<EventFromLogic<TMachine>>;
638
697
  }
698
+ /** A send handle into a {@link runAgent} call. See {@link AgentRunOptions.inbox}. */
699
+ interface AgentInbox<TEvent extends EventObject = EventObject> {
700
+ /**
701
+ * Delivers `event` into the run, with the same result as
702
+ * {@link AgentRuntime.send}: `true` when queued (including before the run
703
+ * starts), `false` once the run is done, errored, stopped, or the
704
+ * `runAgent` call returned.
705
+ */
706
+ send(event: TEvent): boolean;
707
+ }
708
+ /**
709
+ * Creates a send handle for {@link AgentRunOptions.inbox}, typed by the
710
+ * machine's events.
711
+ *
712
+ * @example
713
+ * ```ts
714
+ * const inbox = createAgentInbox<EventOf<typeof machine>>();
715
+ * const run = runAgent(machine, { input, executors, inbox });
716
+ * inbox.send({ type: "CANCEL" });
717
+ * const result = await run;
718
+ * ```
719
+ */
720
+ declare function createAgentInbox<TEvent extends EventObject = EventObject>(): AgentInbox<TEvent>;
639
721
  /**
640
722
  * Runs `machine` to quiescence in one call: {@link createAgentRuntime} over
641
723
  * `options`, then {@link runToQuiescence} with the same object as its init.
@@ -753,4 +835,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
753
835
  */
754
836
  declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
755
837
  //#endregion
756
- 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 };
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 };
@@ -1,5 +1,6 @@
1
- import { A as builtinTextActors, E as DECIDE_ACTOR, J as setAgentExecutionOptions, W as getAgentExecutionOptions, ct as validateSchemaSync, dt as isPlainObject, j as createTextLogic, pt as AgentError, q as missingActor, w as AGENT_USAGE_EVENT_TYPE } from "./event-log-C7jeH0y8.mjs";
2
- import { r as createDecideActor } from "./decision-COkJNjOW.mjs";
1
+ import { E as ACT_ACTOR, K as getAgentExecutionOptions, M as builtinTextActors, N as createTextLogic, O as DECIDE_ACTOR, X as setAgentExecutionOptions, Y as missingActor, ht as AgentError, pt as isPlainObject, ut as validateSchemaSync, w as AGENT_USAGE_EVENT_TYPE } from "./event-log-DkVlk3Rh.mjs";
2
+ import { r as createDecideActor } from "./decision-m5hGmHpF.mjs";
3
+ import { r as createActActor } from "./act-B9hLQls6.mjs";
3
4
  import { machineFromJSON, setup } from "xstate";
4
5
  //#region src/workflow-config.ts
5
6
  /**
@@ -600,7 +601,11 @@ function assertStateSchemaKeysExist(stateSchemas, machineStates, path = []) {
600
601
  if (stateSchema && typeof stateSchema === "object" && "states" in stateSchema && stateSchema.states) assertStateSchemaKeysExist(stateSchema.states, machineState.states, [...path, key]);
601
602
  }
602
603
  }
603
- const RESERVED_AGENT_ACTOR_KEYS = [...Object.keys(builtinTextActors), DECIDE_ACTOR];
604
+ const RESERVED_AGENT_ACTOR_KEYS = [
605
+ ...Object.keys(builtinTextActors),
606
+ DECIDE_ACTOR,
607
+ ACT_ACTOR
608
+ ];
604
609
  /**
605
610
  * The whole `agent.` actor-source namespace is reserved for the library, not
606
611
  * just the shipped builtins: a key starting with this prefix is rejected at
@@ -639,6 +644,7 @@ function createAgentActors(actors, requestActors) {
639
644
  return {
640
645
  ...builtinTextActors,
641
646
  [DECIDE_ACTOR]: createDecideActor(),
647
+ [ACT_ACTOR]: createActActor(),
642
648
  ...actors,
643
649
  ...requestActors
644
650
  };
@@ -1,6 +1,6 @@
1
- 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";
2
- import { X as EventFromSnapshot, Y as AgentSchemas, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-CV_4KGr6.cjs";
3
- import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BDiJKyv9.cjs";
1
+ import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, g as EventUnion, j as WithAgentInputSchema, l as AgentTools, n as AgentEventSchemaInputMap, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.cjs";
2
+ import { _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, nt as EventFromSnapshot, tt as AgentSchemas, v as TextLogicConfig } from "./text-logic-CSf9bqpP.cjs";
3
+ import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-Bm5nvpow.cjs";
4
4
  import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
5
5
  //#region src/interaction.d.ts
6
6
  interface AgentInteractionEvent<TType extends string = string> {
@@ -582,4 +582,4 @@ declare namespace setupAgent {
582
582
  */
583
583
  declare function getAgentSchemas(machine: AnyStateMachine): AgentSchemas | undefined;
584
584
  //#endregion
585
- export { AgentInteractionEventMeta as C, getInteraction as D, eventFromInteraction as E, interactionMetaSchema as O, AgentInteractionEvent as S, GetInteractionOptions as T, FromConfigResult as _, WithAgentUsageEvent as a, AgentInteractionChoice as b, setupAgent as c, AgentWorkflowConfig as d, AgentWorkflowInvokeConfig as f, FromConfigOptions as g, AgentWorkflowTransitionConfig as h, WithAgentEvents as i, AgentWorkflowActionConfig as l, AgentWorkflowStateConfig as m, AgentSchemaPack as n, createAgentSchemas as o, AgentWorkflowRequestConfig as p, AgentUsageEventPayload as r, getAgentSchemas as s, AgentDefaultMeta as t, AgentWorkflowActorConfig as u, SchemaCompiler as v, AgentInteractionMeta as w, AgentInteractionDescriptor as x, AgentInteraction as y };
585
+ export { AgentInteractionEvent as C, eventFromInteraction as D, GetInteractionOptions as E, getInteraction as O, AgentInteractionDescriptor as S, AgentInteractionMeta as T, FromConfigOptions as _, WithAgentEvents as a, AgentInteraction as b, getAgentSchemas as c, AgentWorkflowActorConfig as d, AgentWorkflowConfig as f, AgentWorkflowTransitionConfig as g, AgentWorkflowStateConfig as h, SetupAgentResult as i, interactionMetaSchema as k, setupAgent as l, AgentWorkflowRequestConfig as m, AgentSchemaPack as n, WithAgentUsageEvent as o, AgentWorkflowInvokeConfig as p, AgentUsageEventPayload as r, createAgentSchemas as s, AgentDefaultMeta as t, AgentWorkflowActionConfig as u, FromConfigResult as v, AgentInteractionEventMeta as w, AgentInteractionChoice as x, SchemaCompiler as y };
@@ -1,6 +1,6 @@
1
- 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";
2
- import { X as EventFromSnapshot, Y as AgentSchemas, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-Ckh-rJFV.mjs";
3
- import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DOoVUGVq.mjs";
1
+ import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, g as EventUnion, j as WithAgentInputSchema, l as AgentTools, n as AgentEventSchemaInputMap, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.mjs";
2
+ import { _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, nt as EventFromSnapshot, tt as AgentSchemas, v as TextLogicConfig } from "./text-logic-BqxalgMr.mjs";
3
+ import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BnikdOca.mjs";
4
4
  import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
5
5
  //#region src/interaction.d.ts
6
6
  interface AgentInteractionEvent<TType extends string = string> {
@@ -582,4 +582,4 @@ declare namespace setupAgent {
582
582
  */
583
583
  declare function getAgentSchemas(machine: AnyStateMachine): AgentSchemas | undefined;
584
584
  //#endregion
585
- export { AgentInteractionEventMeta as C, getInteraction as D, eventFromInteraction as E, interactionMetaSchema as O, AgentInteractionEvent as S, GetInteractionOptions as T, FromConfigResult as _, WithAgentUsageEvent as a, AgentInteractionChoice as b, setupAgent as c, AgentWorkflowConfig as d, AgentWorkflowInvokeConfig as f, FromConfigOptions as g, AgentWorkflowTransitionConfig as h, WithAgentEvents as i, AgentWorkflowActionConfig as l, AgentWorkflowStateConfig as m, AgentSchemaPack as n, createAgentSchemas as o, AgentWorkflowRequestConfig as p, AgentUsageEventPayload as r, getAgentSchemas as s, AgentDefaultMeta as t, AgentWorkflowActorConfig as u, SchemaCompiler as v, AgentInteractionMeta as w, AgentInteractionDescriptor as x, AgentInteraction as y };
585
+ export { AgentInteractionEvent as C, eventFromInteraction as D, GetInteractionOptions as E, getInteraction as O, AgentInteractionDescriptor as S, AgentInteractionMeta as T, FromConfigOptions as _, WithAgentEvents as a, AgentInteraction as b, getAgentSchemas as c, AgentWorkflowActorConfig as d, AgentWorkflowConfig as f, AgentWorkflowTransitionConfig as g, AgentWorkflowStateConfig as h, SetupAgentResult as i, interactionMetaSchema as k, setupAgent as l, AgentWorkflowRequestConfig as m, AgentSchemaPack as n, WithAgentUsageEvent as o, AgentWorkflowInvokeConfig as p, AgentUsageEventPayload as r, createAgentSchemas as s, AgentDefaultMeta as t, AgentWorkflowActionConfig as u, FromConfigResult as v, AgentInteractionEventMeta as w, AgentInteractionChoice as x, SchemaCompiler as y };
@@ -1,5 +1,6 @@
1
- const require_event_log = require("./event-log-BWSSLUff.cjs");
2
- const require_decision = require("./decision-BEsATcr1.cjs");
1
+ const require_event_log = require("./event-log-Dkc-yIYu.cjs");
2
+ const require_decision = require("./decision-CMeuNZ1g.cjs");
3
+ const require_act = require("./act-CrX0JwWY.cjs");
3
4
  let xstate = require("xstate");
4
5
  //#region src/workflow-config.ts
5
6
  /**
@@ -600,7 +601,11 @@ function assertStateSchemaKeysExist(stateSchemas, machineStates, path = []) {
600
601
  if (stateSchema && typeof stateSchema === "object" && "states" in stateSchema && stateSchema.states) assertStateSchemaKeysExist(stateSchema.states, machineState.states, [...path, key]);
601
602
  }
602
603
  }
603
- const RESERVED_AGENT_ACTOR_KEYS = [...Object.keys(require_event_log.builtinTextActors), require_event_log.DECIDE_ACTOR];
604
+ const RESERVED_AGENT_ACTOR_KEYS = [
605
+ ...Object.keys(require_event_log.builtinTextActors),
606
+ require_event_log.DECIDE_ACTOR,
607
+ require_event_log.ACT_ACTOR
608
+ ];
604
609
  /**
605
610
  * The whole `agent.` actor-source namespace is reserved for the library, not
606
611
  * just the shipped builtins: a key starting with this prefix is rejected at
@@ -639,6 +644,7 @@ function createAgentActors(actors, requestActors) {
639
644
  return {
640
645
  ...require_event_log.builtinTextActors,
641
646
  [require_event_log.DECIDE_ACTOR]: require_decision.createDecideActor(),
647
+ [require_event_log.ACT_ACTOR]: require_act.createActActor(),
642
648
  ...actors,
643
649
  ...requestActors
644
650
  };
@@ -1,8 +1,8 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_event_log = require("./event-log-BWSSLUff.cjs");
3
- const require_decision = require("./decision-BEsATcr1.cjs");
4
- const require_model_source = require("./model-source-DmhTMK39.cjs");
5
- const require_with_model_calls = require("./with-model-calls-BXYdBdcu.cjs");
2
+ const require_event_log = require("./event-log-Dkc-yIYu.cjs");
3
+ const require_decision = require("./decision-CMeuNZ1g.cjs");
4
+ const require_model_source = require("./model-source-B4WQ8Idp.cjs");
5
+ const require_with_model_calls = require("./with-model-calls-B_WLmOSl.cjs");
6
6
  let _tanstack_ai = require("@tanstack/ai");
7
7
  //#region src/tanstack-ai/index.ts
8
8
  /**
@@ -445,6 +445,25 @@ function isTruncationError(error) {
445
445
  const { code, message } = error ?? {};
446
446
  return code === "max_tokens" || code === "incomplete" || message === "max_output_tokens";
447
447
  }
448
+ function withParallelToolCallsOff(adapter, modelOptions) {
449
+ switch (adapter.name) {
450
+ case "openai": return {
451
+ parallel_tool_calls: false,
452
+ ...modelOptions
453
+ };
454
+ case "anthropic": {
455
+ const choice = modelOptions?.tool_choice;
456
+ return require_event_log.isRecord(choice) ? {
457
+ ...modelOptions,
458
+ tool_choice: {
459
+ disable_parallel_tool_use: true,
460
+ ...choice
461
+ }
462
+ } : modelOptions;
463
+ }
464
+ default: return modelOptions;
465
+ }
466
+ }
448
467
  function usageField(usage) {
449
468
  return usage ? { usage } : {};
450
469
  }
@@ -605,13 +624,46 @@ function createTanStackAiExecutors(source) {
605
624
  raw: run.chunks
606
625
  };
607
626
  };
627
+ const decideWithObject = async (request, info) => {
628
+ const { adapter, settings } = resolve(request, request);
629
+ let run;
630
+ try {
631
+ run = await runChat({
632
+ ...settings,
633
+ adapter,
634
+ ...toDecisionMessages(request),
635
+ outputSchema: require_with_model_calls.decisionObjectSchema(request),
636
+ stream: true,
637
+ agentLoopStrategy: (0, _tanstack_ai.maxIterations)(1)
638
+ }, info?.signal);
639
+ } catch (error) {
640
+ const notJson = error?.code === "structured-output-parse-failed";
641
+ if (isTruncationError(error) || notJson) return {
642
+ rejected: {
643
+ failure: "invalid-payload",
644
+ reason: "the answer was not valid JSON"
645
+ },
646
+ finishReason: isTruncationError(error) ? "length" : "other",
647
+ raw: []
648
+ };
649
+ throw error;
650
+ }
651
+ return {
652
+ ...require_with_model_calls.fromDecisionObject(request, run.structured !== void 0 ? run.structured : run.text),
653
+ ...usageField(run.usage),
654
+ finishReason: run.finishReason,
655
+ raw: run.chunks
656
+ };
657
+ };
608
658
  const decide = async (request, info) => {
659
+ if (require_with_model_calls.resolveDecisionMode(options.decideMode, request) === "object") return decideWithObject(request, info);
609
660
  const { adapter, settings } = resolve(request, {
610
661
  ...request,
611
662
  toolChoice: "required"
612
663
  });
613
664
  const run = await runChat({
614
665
  ...settings,
666
+ modelOptions: withParallelToolCallsOff(adapter, settings.modelOptions),
615
667
  adapter,
616
668
  ...toDecisionMessages(request),
617
669
  tools: toTanStackAiEventTools(request.events),
@@ -625,6 +677,12 @@ function createTanStackAiExecutors(source) {
625
677
  raw: run.chunks
626
678
  });
627
679
  if (!toolCall) return unnamed();
680
+ if (run.toolCalls.length > 1) return {
681
+ rejected: require_with_model_calls.multipleCallsRejection(run.toolCalls.map((call) => call.toolName)),
682
+ ...usageField(run.usage),
683
+ finishReason: run.finishReason,
684
+ raw: run.chunks
685
+ };
628
686
  const chosenEvent = request.events.find((event) => event.toolName === toolCall.toolName);
629
687
  if (!chosenEvent) return unnamed(toolCall);
630
688
  if (toolCall.invalid) return unnamed({
@@ -1,5 +1,6 @@
1
- import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
2
- import { G as AgentEventDescriptor, N as AgentDecisionRejection, P as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-CV_4KGr6.cjs";
1
+ import { a as AgentToolChoice, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.cjs";
2
+ import { I as AgentDecisionRejection, L as AgentDecisionRequest, Z as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-CSf9bqpP.cjs";
3
+ import { n as DecisionModeOption, t as DecisionMode } from "./decision-object-DBcLWVvv.cjs";
3
4
  import { AnyStateMachine } from "xstate";
4
5
  import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
5
6
  import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -111,6 +112,14 @@ export type TanStackAiModelMap<TKey extends string = string> = Record<TKey, TanS
111
112
  * {@link toTanStackAiModelOptions}); `modelOptions` merge key by key.
112
113
  */
113
114
  export type CreateTanStackAiExecutorsOptions<TModels extends TanStackAiModelMap = TanStackAiModelMap> = {
115
+ /**
116
+ * How a `decide` request is answered: `'object'` (default), one
117
+ * structured-output object naming the event; or `'tool'`, one tool per
118
+ * candidate event under a forced tool choice, with parallel tool calls
119
+ * turned off where the provider allows it (`openai`, `anthropic`) and a
120
+ * multi-call answer rejected. A function picks per request.
121
+ */
122
+ decideMode?: DecisionModeOption;
114
123
  settings?: TanStackAiCallSettings | ((request: AgentTextRequest | AgentDecisionRequest) => TanStackAiCallSettings | undefined);
115
124
  } & ({
116
125
  models: TModels;
@@ -194,9 +203,11 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
194
203
  * - Tools run in `chat()`'s own loop, for `generateText` and `streamText`
195
204
  * alike, bounded by the request's `maxSteps` (default 1). A tool with no
196
205
  * `execute` stops the run at its call.
197
- * - Decisions offer one tool per candidate event, with no `execute`, so the
198
- * run stops at the model's first call; the tool choice is forced where the
199
- * provider supports it (see {@link toTanStackAiModelOptions}).
206
+ * - Decisions are one structured-output object by default (`decideMode`).
207
+ * Under `decideMode: 'tool'` they offer one tool per candidate event, with
208
+ * no `execute`, so the run stops at the model's first call; the tool choice
209
+ * is forced where the provider supports it (see
210
+ * {@link toTanStackAiModelOptions}).
200
211
  *
201
212
  * Pass the options object, or pass the machine (or its `setupAgent(...)`
202
213
  * result) to reuse the `models` declared in `setupAgent({ models })`. Anything
@@ -212,4 +223,5 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
212
223
  */
213
224
  export declare function createTanStackAiExecutors<TModels extends TanStackAiModelMap>(options: CreateTanStackAiExecutorsOptions<TModels>): TanStackAiExecutors;
214
225
  export declare function createTanStackAiExecutors(machine: AnyStateMachine): TanStackAiExecutors;
215
- //#endregion
226
+ //#endregion
227
+ export type { DecisionMode, DecisionModeOption };
@@ -1,5 +1,6 @@
1
- import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
2
- import { G as AgentEventDescriptor, N as AgentDecisionRejection, P as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-Ckh-rJFV.mjs";
1
+ import { a as AgentToolChoice, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.mjs";
2
+ import { I as AgentDecisionRejection, L as AgentDecisionRequest, Z as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BqxalgMr.mjs";
3
+ import { n as DecisionModeOption, t as DecisionMode } from "./decision-object-B5zGSPFp.mjs";
3
4
  import { AnyStateMachine } from "xstate";
4
5
  import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
5
6
  import { TextActivityOptions } from "@tanstack/ai/adapters";
@@ -111,6 +112,14 @@ export type TanStackAiModelMap<TKey extends string = string> = Record<TKey, TanS
111
112
  * {@link toTanStackAiModelOptions}); `modelOptions` merge key by key.
112
113
  */
113
114
  export type CreateTanStackAiExecutorsOptions<TModels extends TanStackAiModelMap = TanStackAiModelMap> = {
115
+ /**
116
+ * How a `decide` request is answered: `'object'` (default), one
117
+ * structured-output object naming the event; or `'tool'`, one tool per
118
+ * candidate event under a forced tool choice, with parallel tool calls
119
+ * turned off where the provider allows it (`openai`, `anthropic`) and a
120
+ * multi-call answer rejected. A function picks per request.
121
+ */
122
+ decideMode?: DecisionModeOption;
114
123
  settings?: TanStackAiCallSettings | ((request: AgentTextRequest | AgentDecisionRequest) => TanStackAiCallSettings | undefined);
115
124
  } & ({
116
125
  models: TModels;
@@ -194,9 +203,11 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
194
203
  * - Tools run in `chat()`'s own loop, for `generateText` and `streamText`
195
204
  * alike, bounded by the request's `maxSteps` (default 1). A tool with no
196
205
  * `execute` stops the run at its call.
197
- * - Decisions offer one tool per candidate event, with no `execute`, so the
198
- * run stops at the model's first call; the tool choice is forced where the
199
- * provider supports it (see {@link toTanStackAiModelOptions}).
206
+ * - Decisions are one structured-output object by default (`decideMode`).
207
+ * Under `decideMode: 'tool'` they offer one tool per candidate event, with
208
+ * no `execute`, so the run stops at the model's first call; the tool choice
209
+ * is forced where the provider supports it (see
210
+ * {@link toTanStackAiModelOptions}).
200
211
  *
201
212
  * Pass the options object, or pass the machine (or its `setupAgent(...)`
202
213
  * result) to reuse the `models` declared in `setupAgent({ models })`. Anything
@@ -212,4 +223,5 @@ export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapt
212
223
  */
213
224
  export declare function createTanStackAiExecutors<TModels extends TanStackAiModelMap>(options: CreateTanStackAiExecutorsOptions<TModels>): TanStackAiExecutors;
214
225
  export declare function createTanStackAiExecutors(machine: AnyStateMachine): TanStackAiExecutors;
215
- //#endregion
226
+ //#endregion
227
+ export type { DecisionMode, DecisionModeOption };