@statelyai/agent 2.0.0-alpha.34 → 2.0.0-alpha.36

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 +124 -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-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
  13. package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
  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-BcQ-9NRT.d.cts} +91 -9
  43. package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.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-BIKcbVXV.d.mts} +4 -4
  46. package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
  47. package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
  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 +536 -67
  53. package/dist/testing.d.cts +197 -180
  54. package/dist/testing.d.mts +197 -180
  55. package/dist/testing.mjs +532 -67
  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-DoP0Oi84.d.mts} +1 -1
  61. package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -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-Bink-Drw.cjs +2304 -0
  69. package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
  70. package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
  71. package/dist/verify-Dpz1u5Pe.mjs +2251 -0
  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 +311 -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 +136 -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 +54 -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 +516 -0
  111. package/docs/validate-and-repair.md +253 -0
  112. package/docs/verify.md +487 -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 +81 -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 -190
  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,4 +1,4 @@
1
- import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
1
+ import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, d as AllowedEvents, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.mjs";
2
2
  import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
3
3
  //#region src/errors.d.ts
4
4
  /**
@@ -139,6 +139,25 @@ declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<
139
139
  actor?: "agent";
140
140
  }): AgentEventDescriptor[];
141
141
  //#endregion
142
+ //#region src/decision-strategy.d.ts
143
+ /**
144
+ * How a decision is split into model calls:
145
+ * - `'direct'`: one decide call over every candidate event.
146
+ * - `'pick-then-fill'`: pick the event type first (a closed choice over bare
147
+ * `{ type }` options), then fill its payload: nothing to fill, a second
148
+ * closed choice over the enumerated payloads when every field is finite,
149
+ * else a structured `generateText` call with `fillModel`.
150
+ * - `'grouped'`: pick a group of event types, then decide within it.
151
+ * - `'auto'` (default): `'pick-then-fill'` with a `fillModel`; `'grouped'` over
152
+ * more than {@link GROUPED_EVENT_THRESHOLD} events in at least two groups;
153
+ * else `'direct'`.
154
+ */
155
+ type DecisionStrategy = "direct" | "pick-then-fill" | "grouped" | "auto";
156
+ /** Above this many candidate events, `'auto'` groups them (when two groups or more exist). */
157
+ declare const GROUPED_EVENT_THRESHOLD = 24;
158
+ /** The most payloads a finite payload schema may enumerate to be filled by a closed choice. */
159
+ declare const MAX_FINITE_PAYLOADS = 32;
160
+ //#endregion
142
161
  //#region src/decision.d.ts
143
162
  /**
144
163
  * Inline input for the `agent.decide` builtin actor — the zero-config
@@ -163,6 +182,15 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
163
182
  * `allowedEvents` with no entry here are offered as `{ type }`.
164
183
  */
165
184
  payloads?: Partial<Record<TEvent, Record<string, unknown>[]>>;
185
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
186
+ strategy?: DecisionStrategy;
187
+ /** Model ref that fills open payload fields under `'pick-then-fill'` (and selects it under `'auto'`). */
188
+ fillModel?: TModel;
189
+ /**
190
+ * Named groups of event types for `'grouped'`. Types in no group are
191
+ * grouped by their prefix before the first `.`.
192
+ */
193
+ groups?: Record<string, readonly TEvent[]>;
166
194
  maxRetries?: number;
167
195
  temperature?: number;
168
196
  maxOutputTokens?: number;
@@ -191,6 +219,12 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
191
219
  /** Framework-native messages, passed through without conversion. */
192
220
  messages?: ResolveTextLogicValue<any[] | undefined, InferOutput<TInputSchema>>;
193
221
  allowedEvents?: AllowedEvents<TEvent, InferOutput<TInputSchema>>;
222
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
223
+ strategy?: DecisionStrategy;
224
+ /** Model ref that fills open payload fields under `'pick-then-fill'` (and selects it under `'auto'`). */
225
+ fillModel?: TModel;
226
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
227
+ groups?: Record<string, readonly TEvent[]>;
194
228
  maxRetries?: number;
195
229
  temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
196
230
  maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -277,6 +311,12 @@ interface AgentDecisionRequest {
277
311
  * closed choices, so a `request.start` trace shows what the guards blocked.
278
312
  */
279
313
  withheld?: ChosenEvent[];
314
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
315
+ strategy?: DecisionStrategy;
316
+ /** Model ref that fills open payload fields under `'pick-then-fill'`. */
317
+ fillModel?: string;
318
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
319
+ groups?: Record<string, readonly string[]>;
280
320
  /**
281
321
  * Prior failed attempts for THIS decision. Empty on the first attempt.
282
322
  * Adapters render these into the provider request so retries converge.
@@ -453,6 +493,12 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
453
493
  * {@link resolveDecision} return that union.
454
494
  */
455
495
  canTake?: (event: TEvent) => boolean;
496
+ /**
497
+ * The decision's invoke-level idempotency key. Each attempt's executor
498
+ * `info.callKey` is this plus the attempt ordinal (`<key>.<attempt>`), and a
499
+ * strategy's sub-calls add their role (`<key>.<attempt>.pick`).
500
+ */
501
+ callKey?: string;
456
502
  }
457
503
  /**
458
504
  * Validation + retry core for decisions. No provider mechanics — the
@@ -481,12 +527,48 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
481
527
  * });
482
528
  * ```
483
529
  */
484
- declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
530
+ declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide" | "generateText">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
531
+ //#endregion
532
+ //#region src/act.d.ts
533
+ /**
534
+ * Inline input for the `agent.act` builtin actor: one model call whose tools
535
+ * are the invoking state's accepted events (plus any plain `tools`). The model
536
+ * calls them in any order across up to `maxSteps` steps of the host's tool
537
+ * loop; each event call is delivered to the machine and answered with what it
538
+ * did (`{ state?, changed? }`). Typed against the machine's own event schemas.
539
+ */
540
+ interface AgentActInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> {
541
+ /** Semantic request identity. Defaults to the invoke occurrence id. */
542
+ name?: string;
543
+ model: TModel;
544
+ system?: string;
545
+ prompt?: string;
546
+ /** Framework-native messages, passed through without conversion. */
547
+ messages?: any[];
548
+ /** Event types offered as tools, intersected with what the state accepts. Omitted means all of them. */
549
+ allowedEvents?: AllowedEvents<TEvent>;
550
+ /** Plain tools offered beside the event tools. */
551
+ tools?: AgentTools;
552
+ /** Bounds the host's tool loop. Default {@link DEFAULT_ACT_MAX_STEPS}. */
553
+ maxSteps?: number;
554
+ temperature?: number;
555
+ maxOutputTokens?: number;
556
+ topP?: number;
557
+ topK?: number;
558
+ seed?: number;
559
+ stopSequences?: string[];
560
+ metadata?: TMetadata;
561
+ }
562
+ /** The `agent.act` builtin's tool-loop bound when its input sets no `maxSteps`. */
563
+ declare const DEFAULT_ACT_MAX_STEPS = 20;
564
+ /** What an event tool answers once the invoking state has exited. */
565
+ declare const ACT_STATE_EXITED = "state exited; stopped";
485
566
  //#endregion
486
567
  //#region src/text-logic.d.ts
487
568
  declare const GENERATE_TEXT_ACTOR: "agent.generateText";
488
569
  declare const STREAM_TEXT_ACTOR: "agent.streamText";
489
570
  declare const DECIDE_ACTOR: "agent.decide";
571
+ declare const ACT_ACTOR: "agent.act";
490
572
  /** Whether a text request should be resolved with `generateText` (one-shot) or `streamText` (chunked, via `onChunk`). */
491
573
  type AgentRequestMode = "generate" | "stream";
492
574
  /** A `setupAgent({ models })` model registry, mapping short model refs to provider-specific model values. */
@@ -658,11 +740,12 @@ interface AgentTextResult<TOutput = unknown, TMessage = AgentMessage> {
658
740
  /** Framework-native response messages, exactly as the executor returned them. */
659
741
  messages: TMessage[];
660
742
  }
661
- /** The three `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
743
+ /** The `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
662
744
  type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
663
745
  [GENERATE_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
664
746
  [STREAM_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
665
747
  [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
748
+ [ACT_ACTOR]: AsyncActorLogic<unknown, AgentActInput<TEvent, Record<string, unknown>, TModel>>;
666
749
  };
667
750
  /**
668
751
  * Validates a raw model/executor output against `schema`, returning the
@@ -932,4 +1015,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
932
1015
  */
933
1016
  declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
934
1017
  //#endregion
935
- export { AgentError as $, AgentDecisionExhaustedError as A, ResolveDecisionOptions as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentExecutorDecisionRequest as F, AgentEventDescriptor as G, createDecisionRequest as H, CreateDecisionRequestOptions as I, AgentRequestSource as J, AgentInvalidEventPayloadError as K, DecisionAttempt as L, AgentDecisionOption as M, AgentDecisionRejection as N, providerOutputSchema as O, AgentDecisionRequest as P, parseAgentEvent as Q, DecisionLogic as R, createTextLogic as S, getCallUsage as T, renderDecisionAttempts as U, createDecisionLogic as V, resolveDecision as W, EventFromSnapshot as X, AgentSchemas as Y, getAcceptedEvents as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTruncatedError as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestOptions as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, DecisionLogicConfig as z };
1018
+ export { AgentRequestOptions as $, AgentActInput as A, DecisionAttempt as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentDecisionOption as F, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, providerOutputSchema as O, AgentDecisionInput as P, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, getCallUsage as T, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentRequestSource as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, ACT_STATE_EXITED as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, CreateDecisionRequestOptions as z };
@@ -1,4 +1,4 @@
1
- import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
1
+ import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, d as AllowedEvents, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.cjs";
2
2
  import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
3
3
  //#region src/errors.d.ts
4
4
  /**
@@ -139,6 +139,25 @@ declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<
139
139
  actor?: "agent";
140
140
  }): AgentEventDescriptor[];
141
141
  //#endregion
142
+ //#region src/decision-strategy.d.ts
143
+ /**
144
+ * How a decision is split into model calls:
145
+ * - `'direct'`: one decide call over every candidate event.
146
+ * - `'pick-then-fill'`: pick the event type first (a closed choice over bare
147
+ * `{ type }` options), then fill its payload: nothing to fill, a second
148
+ * closed choice over the enumerated payloads when every field is finite,
149
+ * else a structured `generateText` call with `fillModel`.
150
+ * - `'grouped'`: pick a group of event types, then decide within it.
151
+ * - `'auto'` (default): `'pick-then-fill'` with a `fillModel`; `'grouped'` over
152
+ * more than {@link GROUPED_EVENT_THRESHOLD} events in at least two groups;
153
+ * else `'direct'`.
154
+ */
155
+ type DecisionStrategy = "direct" | "pick-then-fill" | "grouped" | "auto";
156
+ /** Above this many candidate events, `'auto'` groups them (when two groups or more exist). */
157
+ declare const GROUPED_EVENT_THRESHOLD = 24;
158
+ /** The most payloads a finite payload schema may enumerate to be filled by a closed choice. */
159
+ declare const MAX_FINITE_PAYLOADS = 32;
160
+ //#endregion
142
161
  //#region src/decision.d.ts
143
162
  /**
144
163
  * Inline input for the `agent.decide` builtin actor — the zero-config
@@ -163,6 +182,15 @@ interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<
163
182
  * `allowedEvents` with no entry here are offered as `{ type }`.
164
183
  */
165
184
  payloads?: Partial<Record<TEvent, Record<string, unknown>[]>>;
185
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
186
+ strategy?: DecisionStrategy;
187
+ /** Model ref that fills open payload fields under `'pick-then-fill'` (and selects it under `'auto'`). */
188
+ fillModel?: TModel;
189
+ /**
190
+ * Named groups of event types for `'grouped'`. Types in no group are
191
+ * grouped by their prefix before the first `.`.
192
+ */
193
+ groups?: Record<string, readonly TEvent[]>;
166
194
  maxRetries?: number;
167
195
  temperature?: number;
168
196
  maxOutputTokens?: number;
@@ -191,6 +219,12 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
191
219
  /** Framework-native messages, passed through without conversion. */
192
220
  messages?: ResolveTextLogicValue<any[] | undefined, InferOutput<TInputSchema>>;
193
221
  allowedEvents?: AllowedEvents<TEvent, InferOutput<TInputSchema>>;
222
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
223
+ strategy?: DecisionStrategy;
224
+ /** Model ref that fills open payload fields under `'pick-then-fill'` (and selects it under `'auto'`). */
225
+ fillModel?: TModel;
226
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
227
+ groups?: Record<string, readonly TEvent[]>;
194
228
  maxRetries?: number;
195
229
  temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
196
230
  maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -277,6 +311,12 @@ interface AgentDecisionRequest {
277
311
  * closed choices, so a `request.start` trace shows what the guards blocked.
278
312
  */
279
313
  withheld?: ChosenEvent[];
314
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
315
+ strategy?: DecisionStrategy;
316
+ /** Model ref that fills open payload fields under `'pick-then-fill'`. */
317
+ fillModel?: string;
318
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
319
+ groups?: Record<string, readonly string[]>;
280
320
  /**
281
321
  * Prior failed attempts for THIS decision. Empty on the first attempt.
282
322
  * Adapters render these into the provider request so retries converge.
@@ -453,6 +493,12 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
453
493
  * {@link resolveDecision} return that union.
454
494
  */
455
495
  canTake?: (event: TEvent) => boolean;
496
+ /**
497
+ * The decision's invoke-level idempotency key. Each attempt's executor
498
+ * `info.callKey` is this plus the attempt ordinal (`<key>.<attempt>`), and a
499
+ * strategy's sub-calls add their role (`<key>.<attempt>.pick`).
500
+ */
501
+ callKey?: string;
456
502
  }
457
503
  /**
458
504
  * Validation + retry core for decisions. No provider mechanics — the
@@ -481,12 +527,48 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
481
527
  * });
482
528
  * ```
483
529
  */
484
- declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
530
+ declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide" | "generateText">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
531
+ //#endregion
532
+ //#region src/act.d.ts
533
+ /**
534
+ * Inline input for the `agent.act` builtin actor: one model call whose tools
535
+ * are the invoking state's accepted events (plus any plain `tools`). The model
536
+ * calls them in any order across up to `maxSteps` steps of the host's tool
537
+ * loop; each event call is delivered to the machine and answered with what it
538
+ * did (`{ state?, changed? }`). Typed against the machine's own event schemas.
539
+ */
540
+ interface AgentActInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> {
541
+ /** Semantic request identity. Defaults to the invoke occurrence id. */
542
+ name?: string;
543
+ model: TModel;
544
+ system?: string;
545
+ prompt?: string;
546
+ /** Framework-native messages, passed through without conversion. */
547
+ messages?: any[];
548
+ /** Event types offered as tools, intersected with what the state accepts. Omitted means all of them. */
549
+ allowedEvents?: AllowedEvents<TEvent>;
550
+ /** Plain tools offered beside the event tools. */
551
+ tools?: AgentTools;
552
+ /** Bounds the host's tool loop. Default {@link DEFAULT_ACT_MAX_STEPS}. */
553
+ maxSteps?: number;
554
+ temperature?: number;
555
+ maxOutputTokens?: number;
556
+ topP?: number;
557
+ topK?: number;
558
+ seed?: number;
559
+ stopSequences?: string[];
560
+ metadata?: TMetadata;
561
+ }
562
+ /** The `agent.act` builtin's tool-loop bound when its input sets no `maxSteps`. */
563
+ declare const DEFAULT_ACT_MAX_STEPS = 20;
564
+ /** What an event tool answers once the invoking state has exited. */
565
+ declare const ACT_STATE_EXITED = "state exited; stopped";
485
566
  //#endregion
486
567
  //#region src/text-logic.d.ts
487
568
  declare const GENERATE_TEXT_ACTOR: "agent.generateText";
488
569
  declare const STREAM_TEXT_ACTOR: "agent.streamText";
489
570
  declare const DECIDE_ACTOR: "agent.decide";
571
+ declare const ACT_ACTOR: "agent.act";
490
572
  /** Whether a text request should be resolved with `generateText` (one-shot) or `streamText` (chunked, via `onChunk`). */
491
573
  type AgentRequestMode = "generate" | "stream";
492
574
  /** A `setupAgent({ models })` model registry, mapping short model refs to provider-specific model values. */
@@ -658,11 +740,12 @@ interface AgentTextResult<TOutput = unknown, TMessage = AgentMessage> {
658
740
  /** Framework-native response messages, exactly as the executor returned them. */
659
741
  messages: TMessage[];
660
742
  }
661
- /** The three `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
743
+ /** The `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
662
744
  type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
663
745
  [GENERATE_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
664
746
  [STREAM_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
665
747
  [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
748
+ [ACT_ACTOR]: AsyncActorLogic<unknown, AgentActInput<TEvent, Record<string, unknown>, TModel>>;
666
749
  };
667
750
  /**
668
751
  * Validates a raw model/executor output against `schema`, returning the
@@ -932,4 +1015,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
932
1015
  */
933
1016
  declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
934
1017
  //#endregion
935
- export { AgentError as $, AgentDecisionExhaustedError as A, ResolveDecisionOptions as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentExecutorDecisionRequest as F, AgentEventDescriptor as G, createDecisionRequest as H, CreateDecisionRequestOptions as I, AgentRequestSource as J, AgentInvalidEventPayloadError as K, DecisionAttempt as L, AgentDecisionOption as M, AgentDecisionRejection as N, providerOutputSchema as O, AgentDecisionRequest as P, parseAgentEvent as Q, DecisionLogic as R, createTextLogic as S, getCallUsage as T, renderDecisionAttempts as U, createDecisionLogic as V, resolveDecision as W, EventFromSnapshot as X, AgentSchemas as Y, getAcceptedEvents as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTruncatedError as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentRequestOptions as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, DecisionLogicConfig as z };
1018
+ export { AgentRequestOptions as $, AgentActInput as A, DecisionAttempt as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentDecisionOption as F, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, providerOutputSchema as O, AgentDecisionInput as P, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, getCallUsage as T, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentRequestSource as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, ACT_STATE_EXITED as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, CreateDecisionRequestOptions as z };
@@ -235,4 +235,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
235
235
  input: TInput;
236
236
  }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
237
237
  //#endregion
238
- export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolDescriptor as a, ToolCallPart as b, AllowedEvents as c, EventUnion as d, FilePart as f, NormalizedEventSchemas as g, InferOutput as h, AgentToolChoice as i, AssistantMessage as l, InferInput as m, AgentMessage as n, AgentToolExecute as o, ImagePart as p, AgentTool as r, AgentTools as s, AgentEventSchemaInputMap as t, ChosenEvent as u, SystemMessage as v, WithAgentInputSchema as w, ToolMessage as x, TextPart as y };
238
+ export { UserMessage as A, StandardSchemaV1 as C, ToolMessage as D, ToolCallPart as E, ToolResultOutput as O, ProviderOptions as S, TextPart as T, FilePart as _, AgentToolChoice as a, InferOutput as b, AgentToolSchema as c, AllowedEvents as d, AssistantMessage as f, EventUnion as g, EventPayload as h, AgentTool as i, WithAgentInputSchema as j, ToolResultPart as k, AgentTools as l, DataContent as m, AgentEventSchemaInputMap as n, AgentToolDescriptor as o, ChosenEvent as p, AgentMessage as r, AgentToolExecute as s, AgentEventSchemaInput as t, AllowedEventPattern as u, ImagePart as v, SystemMessage as w, NormalizedEventSchemas as x, InferInput as y };
@@ -235,4 +235,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
235
235
  input: TInput;
236
236
  }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
237
237
  //#endregion
238
- export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolDescriptor as a, ToolCallPart as b, AllowedEvents as c, EventUnion as d, FilePart as f, NormalizedEventSchemas as g, InferOutput as h, AgentToolChoice as i, AssistantMessage as l, InferInput as m, AgentMessage as n, AgentToolExecute as o, ImagePart as p, AgentTool as r, AgentTools as s, AgentEventSchemaInputMap as t, ChosenEvent as u, SystemMessage as v, WithAgentInputSchema as w, ToolMessage as x, TextPart as y };
238
+ export { UserMessage as A, StandardSchemaV1 as C, ToolMessage as D, ToolCallPart as E, ToolResultOutput as O, ProviderOptions as S, TextPart as T, FilePart as _, AgentToolChoice as a, InferOutput as b, AgentToolSchema as c, AllowedEvents as d, AssistantMessage as f, EventUnion as g, EventPayload as h, AgentTool as i, WithAgentInputSchema as j, ToolResultPart as k, AgentTools as l, DataContent as m, AgentEventSchemaInputMap as n, AgentToolDescriptor as o, ChosenEvent as p, AgentMessage as r, AgentToolExecute as s, AgentEventSchemaInput as t, AllowedEventPattern as u, ImagePart as v, SystemMessage as w, NormalizedEventSchemas as x, InferInput as y };
@@ -1,4 +1,4 @@
1
- import { t as AgentCallUsage } from "./text-logic-CV_4KGr6.cjs";
1
+ import { t as AgentCallUsage } from "./text-logic-BqxalgMr.mjs";
2
2
  import { EventObject } from "xstate";
3
3
  //#region src/usage.d.ts
4
4
  /** Reserved event delivered after a model call reports token usage. */
@@ -1,4 +1,4 @@
1
- import { t as AgentCallUsage } from "./text-logic-Ckh-rJFV.mjs";
1
+ import { t as AgentCallUsage } from "./text-logic-CSf9bqpP.cjs";
2
2
  import { EventObject } from "xstate";
3
3
  //#region src/usage.d.ts
4
4
  /** Reserved event delivered after a model call reports token usage. */