@statelyai/agent 2.0.0-alpha.35 → 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 +111 -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 +399 -20
  53. package/dist/testing.d.cts +196 -255
  54. package/dist/testing.d.mts +196 -255
  55. package/dist/testing.mjs +395 -20
  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 -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
package/dist/index.d.cts CHANGED
@@ -1,10 +1,11 @@
1
- import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolDescriptor, b as ToolCallPart, c as AllowedEvents, d as EventUnion, f as FilePart, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, l as AssistantMessage, m as InferInput, n as AgentMessage, o as AgentToolExecute, p as ImagePart, r as AgentTool, s as AgentTools, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.cjs";
2
- import { $ as AgentError, A as AgentDecisionExhaustedError, B as ResolveDecisionOptions, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentExecutorDecisionRequest, G as AgentEventDescriptor, H as createDecisionRequest, I as CreateDecisionRequestOptions, J as AgentRequestSource, K as AgentInvalidEventPayloadError, L as DecisionAttempt, M as AgentDecisionOption, N as AgentDecisionRejection, O as providerOutputSchema, P as AgentDecisionRequest, Q as parseAgentEvent, R as DecisionLogic, S as createTextLogic, T as getCallUsage, U as renderDecisionAttempts, V as createDecisionLogic, W as resolveDecision, X as EventFromSnapshot, Y as AgentSchemas, Z as getAcceptedEvents, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, et as AgentTruncatedError, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestOptions, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as DecisionLogicConfig } from "./text-logic-CV_4KGr6.cjs";
3
- import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BDiJKyv9.cjs";
4
- import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-BtfeFfF6.cjs";
5
- import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-B1-Eqviq.cjs";
6
- import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-BzXehP7R.cjs";
7
- import { a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, u as systemMessage } from "./utils-ebVpCYoF.cjs";
1
+ import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as FilePart, a as AgentToolChoice, b as InferOutput, c as AgentToolSchema, d as AllowedEvents, f as AssistantMessage, g as EventUnion, h as EventPayload, i as AgentTool, j as WithAgentInputSchema, k as ToolResultPart, l as AgentTools, m as DataContent, n as AgentEventSchemaInputMap, o as AgentToolDescriptor, p as ChosenEvent, r as AgentMessage, s as AgentToolExecute, t as AgentEventSchemaInput, u as AllowedEventPattern, v as ImagePart, w as SystemMessage, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.cjs";
2
+ import { $ as AgentRequestOptions, A as AgentActInput, B as DecisionAttempt, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentDecisionOption, G as createDecisionRequest, H as DecisionLogicConfig, I as AgentDecisionRejection, J as DecisionStrategy, K as renderDecisionAttempts, L as AgentDecisionRequest, M as AgentDecisionExecutor, N as AgentDecisionExhaustedError, O as providerOutputSchema, P as AgentDecisionInput, Q as AgentInvalidEventPayloadError, R as AgentExecutorDecisionRequest, S as createTextLogic, T as getCallUsage, U as ResolveDecisionOptions, V as DecisionLogic, W as createDecisionLogic, X as MAX_FINITE_PAYLOADS, Y as GROUPED_EVENT_THRESHOLD, Z as AgentEventDescriptor, _ as TextLogic, a as AgentModelRef, at as AgentError, b as TextLogicExecutor, c as AgentRequestExecutorInfo, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, g as ProviderStructuredOutput, h as BuiltinAgentActors, i as AgentModelMap, it as parseAgentEvent, j as DEFAULT_ACT_MAX_STEPS, k as ACT_STATE_EXITED, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, nt as EventFromSnapshot, o as AgentOutputMode, ot as AgentTruncatedError, p as AgentTextResult, q as resolveDecision, r as AgentFinishReason, rt as getAcceptedEvents, s as AgentRequestExecutor, t as AgentCallUsage, tt as AgentSchemas, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as CreateDecisionRequestOptions } from "./text-logic-CSf9bqpP.cjs";
3
+ import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-HtnrUsl9.cjs";
4
+ import { C as AgentInteractionEvent, D as eventFromInteraction, E as GetInteractionOptions, O as getInteraction, S as AgentInteractionDescriptor, T as AgentInteractionMeta, _ as FromConfigOptions, a as WithAgentEvents, b as AgentInteraction, c as getAgentSchemas, d as AgentWorkflowActorConfig, f as AgentWorkflowConfig, g as AgentWorkflowTransitionConfig, h as AgentWorkflowStateConfig, i as SetupAgentResult, k as interactionMetaSchema, l as setupAgent, m as AgentWorkflowRequestConfig, n as AgentSchemaPack, o as WithAgentUsageEvent, p as AgentWorkflowInvokeConfig, r as AgentUsageEventPayload, s as createAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActionConfig, v as FromConfigResult, w as AgentInteractionEventMeta, x as AgentInteractionChoice, y as SchemaCompiler } from "./setup-agent-jlo4vtaZ.cjs";
5
+ import { A as AgentStepRequest, C as inspectTransitions, D as serializeTraceEvent, E as runToQuiescence, O as traceTransitions, S as createAgentRuntime, T as runAgent, _ as AgentTraceEvent, a as AgentMaxModelCallsExceededError, b as JsonSerializableTraceEvent, c as AgentRunMeta, d as AgentRunStart, f as AgentRuntime, g as AgentTimerScheduler, h as AgentTimerEvent, i as AgentInputFrom, k as AgentRequest, l as AgentRunOptions, m as AgentSnapshotDivergedError, n as AgentEffects, o as AgentRunErrorCause, p as AgentRuntimeOptions, r as AgentInbox, s as AgentRunInit, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunResult, v as AgentTransitionHandler, w as isAgentIdle, x as createAgentInbox, y as InspectedActorRef } from "./run-agent-BcQ-9NRT.cjs";
6
+ import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-bc4ICGcS.cjs";
7
+ import { n as PresetMachine } from "./internal-C3Lqu538.cjs";
8
+ import { M as Recorder, a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, t as MetaOfSnapshot, u as systemMessage } from "./utils-7lSa4H-i.cjs";
8
9
  import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
9
10
  //#region src/type-helpers.d.ts
10
11
  type SchemaAt<T, TKey extends PropertyKey> = T extends {
@@ -76,6 +77,17 @@ export declare function isAgentMessages(value: unknown): value is AgentMessage[]
76
77
  interface DescribeMachineOptions {
77
78
  /** Marks the state nodes active in this snapshot with `*`. */
78
79
  snapshot?: AnyMachineSnapshot;
80
+ /**
81
+ * Prints each transition written as a function under its line, so one read
82
+ * shows both where it goes and what it computes.
83
+ */
84
+ source?: boolean;
85
+ /**
86
+ * Functions the machine's transitions call by name (guards, reducers), each
87
+ * printed with its source in a `Helpers` section, so a call such as
88
+ * `withinLimit(context.turn, context.limit)` can be read through.
89
+ */
90
+ helpers?: Record<string, (...args: never[]) => unknown>;
79
91
  }
80
92
  /**
81
93
  * Describes a machine in plain text for a model to read. The machine's
@@ -92,7 +104,11 @@ interface DescribeMachineOptions {
92
104
  * A transition written as a function shows the targets its source names
93
105
  * (`→ review (conditional)` when it may decline or pick among several),
94
106
  * `(stays)` when its source has no `target`, or `→ ?` when no target can be
95
- * read. A `setupAgent.fromConfig(...)` machine is read from its config, so
107
+ * read (a variable's value, a helper call's result). Function sources are
108
+ * parsed, so every return path counts: ternaries, `&&`/`||`, early returns and
109
+ * local constants. With `source: true`, each function is printed under its
110
+ * line, along with entry and exit actions; pass `helpers` to print the
111
+ * functions they call by name. A `setupAgent.fromConfig(...)` machine is read from its config, so
96
112
  * its targets, guards and context patches are always known.
97
113
  *
98
114
  * @example
@@ -132,6 +148,14 @@ interface DecideNextOptions<TSnapshot extends AnyMachineSnapshot = AnyMachineSna
132
148
  /** Retries after a failed choice. Default `2`. */
133
149
  maxRetries?: number;
134
150
  signal?: AbortSignal;
151
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
152
+ strategy?: DecisionStrategy;
153
+ /** Model ref that fills open payload fields under `'pick-then-fill'`. */
154
+ fillModel?: string;
155
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
156
+ groups?: Record<string, readonly string[]>;
157
+ /** Fills open payload fields with `fillModel`. */
158
+ generateText?: AgentRequestExecutor;
135
159
  }
136
160
  /** Result of {@link decideNext}. */
137
161
  interface DecideNextResult<TEvent = ChosenEvent> {
@@ -233,6 +257,139 @@ interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<Age
233
257
  */
234
258
  export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
235
259
  //#endregion
260
+ //#region src/wrap-workflow.d.ts
261
+ /** The effects a wrapped workflow calls: async functions, by name. */
262
+ type WorkflowEffects<TEffects> = { [K in keyof TEffects]: (...args: never[]) => PromiseLike<unknown>; };
263
+ /** What a wrapped workflow's `run` gets besides its input and effects. */
264
+ interface WorkflowRunContext {
265
+ /** Aborted when the run is aborted or the machine stops the workflow. */
266
+ signal: AbortSignal;
267
+ }
268
+ /** Options for {@link wrapWorkflow}. */
269
+ interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>> {
270
+ /** The machine id. */
271
+ id: string;
272
+ /** The machine version, for the event log. Default `"1"`. */
273
+ version?: string;
274
+ /** Every side effect the workflow makes: model calls, tools, writes. */
275
+ effects: TEffects;
276
+ /**
277
+ * The existing workflow. It must reach the outside world only through
278
+ * `effects`; a call it makes around them is invisible to the machine, to
279
+ * traces, and to {@link Recorder} recordings. It gets its own deep copy of
280
+ * a plain-data input, free to mutate; an input holding class instances or
281
+ * functions is passed as is. An effect that resolves to a stream (anything
282
+ * `for await` reads) settles once the stream is read, with its chunks.
283
+ */
284
+ run: (input: TInput, effects: TEffects, context: WorkflowRunContext) => PromiseLike<TOutput>;
285
+ /**
286
+ * Maps an effect's arguments, result, or error before it is journaled as an
287
+ * event. Return a redacted value for secrets and private records: every
288
+ * `effect.*` event reaches traces, the event log, and the inspector.
289
+ * Default: journal each value as is (JSON-safe).
290
+ */
291
+ redact?: (name: string, part: "args" | "result" | "error", value: unknown) => unknown;
292
+ }
293
+ /** An effect call, as the machine sees it. `call` pairs it with its result. */
294
+ interface EffectCallEvent {
295
+ type: "effect.call";
296
+ name: string;
297
+ /** 0-based, across all effects of the run. */
298
+ call: number;
299
+ /** The arguments, JSON-safe. */
300
+ args: JsonValue[];
301
+ }
302
+ /** An effect call that resolved. */
303
+ interface EffectDoneEvent {
304
+ type: "effect.done";
305
+ name: string;
306
+ call: number;
307
+ /**
308
+ * The resolved value, JSON-safe (`null` for `undefined`). For a stream, the
309
+ * chunks read, or `{ chunks, returned }` when a generator returned a value.
310
+ */
311
+ result: JsonValue;
312
+ }
313
+ /** An effect call that rejected. */
314
+ interface EffectErrorEvent {
315
+ type: "effect.error";
316
+ name: string;
317
+ call: number;
318
+ /** The error, JSON-safe: `{ name, message, stack?, code? }`. */
319
+ error: JsonValue;
320
+ }
321
+ /** The wrapped machine's context. */
322
+ type WrappedWorkflowContext<TInput, TOutput> = {
323
+ input: TInput;
324
+ /** What the workflow returned, once it did. */
325
+ output?: TOutput;
326
+ /** Effect calls started. */
327
+ calls: number;
328
+ /** Effect calls that rejected. */
329
+ failures: number;
330
+ };
331
+ /** Options for {@link WrappedWorkflow.run}: `runAgent` options that fit a black box, plus fakes and a recorder. */
332
+ interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<AgentRunOptions<WrappedWorkflowMachine<TInput, TOutput>>, "signal" | "inspect" | "onTransition" | "onTrace" | "onEvent" | "metadata" | "verification"> {
333
+ /** Replaces some effects for this run: fakes, stubs, replay wrappers. */
334
+ effects?: Partial<TEffects>;
335
+ /**
336
+ * Wraps every function effect with `recorder.fn(name, fn)` and records the
337
+ * result with `recorder.output`, so `recorder.recording` is a golden run.
338
+ */
339
+ recorder?: Recorder;
340
+ }
341
+ /** The result of {@link wrapWorkflow}. */
342
+ interface WrappedWorkflow<TInput, TOutput, TEffects> {
343
+ /**
344
+ * `running` invokes the workflow and counts its effect calls; `done` is
345
+ * final with the workflow's result as output. A rejection is unhandled, so
346
+ * the run settles `{ status: "error", cause: "machine" }` with the thrown
347
+ * error. Runs with `runAgent`, `describeMachine`, `canReach` and the inspector.
348
+ */
349
+ machine: WrappedWorkflowMachine<TInput, TOutput>;
350
+ /**
351
+ * Runs the machine with `runAgent` and returns what the workflow returned,
352
+ * or rethrows what it threw (the same error object). `signal` reaches the
353
+ * workflow, which decides what an abort means, as it did before: a
354
+ * workflow that returns an `aborted` result still returns it. Once it
355
+ * aborts, an effect call throws `signal.reason` instead of running.
356
+ */
357
+ run(input: TInput, options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput>): Promise<TOutput>;
358
+ }
359
+ /** The events a {@link wrapWorkflow} machine handles. */
360
+ type WrappedWorkflowEvent = EffectCallEvent | EffectDoneEvent | EffectErrorEvent;
361
+ /** The machine {@link wrapWorkflow} returns. */
362
+ type WrappedWorkflowMachine<TInput, TOutput> = PresetMachine<WrappedWorkflowContext<TInput, TOutput>, TInput, TOutput, WrappedWorkflowEvent>;
363
+ /**
364
+ * Wraps an existing async workflow, unchanged, as an agent machine: step 0 of
365
+ * a strangler-fig retrofit. Pass every side effect it makes as `effects`; each
366
+ * call becomes an `effect.call` event, then `effect.done` or `effect.error`, so
367
+ * it shows up in transitions, traces, the event log and the inspector.
368
+ *
369
+ * What it buys today: inspection and traces of a workflow nobody rewrote, a
370
+ * recorded baseline (`run(input, { recorder })`, or `checkParity` from
371
+ * `@statelyai/agent/testing`), `signal` to abort it, and a seam to carve
372
+ * phases out of, one at a time.
373
+ *
374
+ * What it does not: the workflow is a black box. The machine has one state
375
+ * for all of it, so there is no resume in the middle of the function (a
376
+ * resumed run starts it again), and `canReach` or `explorePaths` prove nothing
377
+ * about what happens inside. Those arrive per phase, as phases move into
378
+ * states. Effect arguments and results are journaled JSON-safe; values that
379
+ * are not JSON lose what JSON cannot hold.
380
+ *
381
+ * @example
382
+ * ```ts
383
+ * const support = wrapWorkflow({
384
+ * id: "support",
385
+ * effects: { generate, lookupOrder, issueRefund },
386
+ * run: (input: Ticket, effects) => legacyRunTicket(input, effects),
387
+ * });
388
+ * const reply = await support.run(ticket); // what legacyRunTicket returned
389
+ * ```
390
+ */
391
+ export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>>(config: WrapWorkflowConfig<TInput, TOutput, TEffects>): WrappedWorkflow<TInput, TOutput, TEffects>;
392
+ //#endregion
236
393
  //#region src/provide-executors.d.ts
237
394
  /** Options for {@link provideExecutors}. */
238
395
  interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
@@ -279,6 +436,8 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
279
436
  * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
280
437
  * candidate events, guard `canTake`, and auto-delivery of the chosen event,
281
438
  * mirroring `createAgentRuntime` but without its model-call counting)
439
+ * - `agent.act` → `executors.generateText` (accepted events as tools, each
440
+ * call sent to the invoking actor)
282
441
  *
283
442
  * Pass `options.onTrace` to observe request-level trace events (identical in
284
443
  * shape to `createAgentRuntime`'s); pair it with {@link traceTransitions} on the actor's
@@ -301,4 +460,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
301
460
  */
302
461
  export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
303
462
  //#endregion
304
- export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
463
+ export { ACT_STATE_EXITED, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActInput, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInbox, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type BuiltinAgentActors, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, DEFAULT_ACT_MAX_STEPS, type DataContent, type DecideNextOptions, type DecideNextResult, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DecisionStrategy, type DescribeMachineOptions, type DoneActorEventOf, type EffectCallEvent, type EffectDoneEvent, type EffectErrorEvent, type EventFromSnapshot, type EventOf, type EventPayload, type EventUnion, type FilePart, type FromConfigOptions, type FromConfigResult, GROUPED_EVENT_THRESHOLD, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, MAX_FINITE_PAYLOADS, type MetaOf, type MetaOfSnapshot, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SetupAgentResult, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentInputSchema, type WithAgentUsageEvent, type WorkflowEffects, type WorkflowRunContext, type WrapWorkflowConfig, type WrappedWorkflow, type WrappedWorkflowContext, type WrappedWorkflowEvent, type WrappedWorkflowMachine, type WrappedWorkflowRunOptions, assistantMessage, bindRequestExecutor, createAgentInbox, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
package/dist/index.d.mts CHANGED
@@ -1,10 +1,11 @@
1
- import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolDescriptor, b as ToolCallPart, c as AllowedEvents, d as EventUnion, f as FilePart, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, l as AssistantMessage, m as InferInput, n as AgentMessage, o as AgentToolExecute, p as ImagePart, r as AgentTool, s as AgentTools, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.mjs";
2
- import { $ as AgentError, A as AgentDecisionExhaustedError, B as ResolveDecisionOptions, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentExecutorDecisionRequest, G as AgentEventDescriptor, H as createDecisionRequest, I as CreateDecisionRequestOptions, J as AgentRequestSource, K as AgentInvalidEventPayloadError, L as DecisionAttempt, M as AgentDecisionOption, N as AgentDecisionRejection, O as providerOutputSchema, P as AgentDecisionRequest, Q as parseAgentEvent, R as DecisionLogic, S as createTextLogic, T as getCallUsage, U as renderDecisionAttempts, V as createDecisionLogic, W as resolveDecision, X as EventFromSnapshot, Y as AgentSchemas, Z as getAcceptedEvents, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, et as AgentTruncatedError, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestOptions, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as DecisionLogicConfig } from "./text-logic-Ckh-rJFV.mjs";
3
- import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DOoVUGVq.mjs";
4
- import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-C6nqzv_X.mjs";
5
- import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-BGdx5913.mjs";
6
- import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-CWjN6lmM.mjs";
7
- import { a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, u as systemMessage } from "./utils-BnXdWih3.mjs";
1
+ import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as FilePart, a as AgentToolChoice, b as InferOutput, c as AgentToolSchema, d as AllowedEvents, f as AssistantMessage, g as EventUnion, h as EventPayload, i as AgentTool, j as WithAgentInputSchema, k as ToolResultPart, l as AgentTools, m as DataContent, n as AgentEventSchemaInputMap, o as AgentToolDescriptor, p as ChosenEvent, r as AgentMessage, s as AgentToolExecute, t as AgentEventSchemaInput, u as AllowedEventPattern, v as ImagePart, w as SystemMessage, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.mjs";
2
+ import { $ as AgentRequestOptions, A as AgentActInput, B as DecisionAttempt, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentDecisionOption, G as createDecisionRequest, H as DecisionLogicConfig, I as AgentDecisionRejection, J as DecisionStrategy, K as renderDecisionAttempts, L as AgentDecisionRequest, M as AgentDecisionExecutor, N as AgentDecisionExhaustedError, O as providerOutputSchema, P as AgentDecisionInput, Q as AgentInvalidEventPayloadError, R as AgentExecutorDecisionRequest, S as createTextLogic, T as getCallUsage, U as ResolveDecisionOptions, V as DecisionLogic, W as createDecisionLogic, X as MAX_FINITE_PAYLOADS, Y as GROUPED_EVENT_THRESHOLD, Z as AgentEventDescriptor, _ as TextLogic, a as AgentModelRef, at as AgentError, b as TextLogicExecutor, c as AgentRequestExecutorInfo, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, g as ProviderStructuredOutput, h as BuiltinAgentActors, i as AgentModelMap, it as parseAgentEvent, j as DEFAULT_ACT_MAX_STEPS, k as ACT_STATE_EXITED, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, nt as EventFromSnapshot, o as AgentOutputMode, ot as AgentTruncatedError, p as AgentTextResult, q as resolveDecision, r as AgentFinishReason, rt as getAcceptedEvents, s as AgentRequestExecutor, t as AgentCallUsage, tt as AgentSchemas, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as CreateDecisionRequestOptions } from "./text-logic-BqxalgMr.mjs";
3
+ import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DoP0Oi84.mjs";
4
+ import { C as AgentInteractionEvent, D as eventFromInteraction, E as GetInteractionOptions, O as getInteraction, S as AgentInteractionDescriptor, T as AgentInteractionMeta, _ as FromConfigOptions, a as WithAgentEvents, b as AgentInteraction, c as getAgentSchemas, d as AgentWorkflowActorConfig, f as AgentWorkflowConfig, g as AgentWorkflowTransitionConfig, h as AgentWorkflowStateConfig, i as SetupAgentResult, k as interactionMetaSchema, l as setupAgent, m as AgentWorkflowRequestConfig, n as AgentSchemaPack, o as WithAgentUsageEvent, p as AgentWorkflowInvokeConfig, r as AgentUsageEventPayload, s as createAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActionConfig, v as FromConfigResult, w as AgentInteractionEventMeta, x as AgentInteractionChoice, y as SchemaCompiler } from "./setup-agent-BIKcbVXV.mjs";
5
+ import { A as AgentStepRequest, C as inspectTransitions, D as serializeTraceEvent, E as runToQuiescence, O as traceTransitions, S as createAgentRuntime, T as runAgent, _ as AgentTraceEvent, a as AgentMaxModelCallsExceededError, b as JsonSerializableTraceEvent, c as AgentRunMeta, d as AgentRunStart, f as AgentRuntime, g as AgentTimerScheduler, h as AgentTimerEvent, i as AgentInputFrom, k as AgentRequest, l as AgentRunOptions, m as AgentSnapshotDivergedError, n as AgentEffects, o as AgentRunErrorCause, p as AgentRuntimeOptions, r as AgentInbox, s as AgentRunInit, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunResult, v as AgentTransitionHandler, w as isAgentIdle, x as createAgentInbox, y as InspectedActorRef } from "./run-agent-C86drZtN.mjs";
6
+ import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-BBS8so8a.mjs";
7
+ import { n as PresetMachine } from "./internal-DUcdhk-i.mjs";
8
+ import { M as Recorder, a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, t as MetaOfSnapshot, u as systemMessage } from "./utils-CBbKw2fM.mjs";
8
9
  import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
9
10
  //#region src/type-helpers.d.ts
10
11
  type SchemaAt<T, TKey extends PropertyKey> = T extends {
@@ -76,6 +77,17 @@ export declare function isAgentMessages(value: unknown): value is AgentMessage[]
76
77
  interface DescribeMachineOptions {
77
78
  /** Marks the state nodes active in this snapshot with `*`. */
78
79
  snapshot?: AnyMachineSnapshot;
80
+ /**
81
+ * Prints each transition written as a function under its line, so one read
82
+ * shows both where it goes and what it computes.
83
+ */
84
+ source?: boolean;
85
+ /**
86
+ * Functions the machine's transitions call by name (guards, reducers), each
87
+ * printed with its source in a `Helpers` section, so a call such as
88
+ * `withinLimit(context.turn, context.limit)` can be read through.
89
+ */
90
+ helpers?: Record<string, (...args: never[]) => unknown>;
79
91
  }
80
92
  /**
81
93
  * Describes a machine in plain text for a model to read. The machine's
@@ -92,7 +104,11 @@ interface DescribeMachineOptions {
92
104
  * A transition written as a function shows the targets its source names
93
105
  * (`→ review (conditional)` when it may decline or pick among several),
94
106
  * `(stays)` when its source has no `target`, or `→ ?` when no target can be
95
- * read. A `setupAgent.fromConfig(...)` machine is read from its config, so
107
+ * read (a variable's value, a helper call's result). Function sources are
108
+ * parsed, so every return path counts: ternaries, `&&`/`||`, early returns and
109
+ * local constants. With `source: true`, each function is printed under its
110
+ * line, along with entry and exit actions; pass `helpers` to print the
111
+ * functions they call by name. A `setupAgent.fromConfig(...)` machine is read from its config, so
96
112
  * its targets, guards and context patches are always known.
97
113
  *
98
114
  * @example
@@ -132,6 +148,14 @@ interface DecideNextOptions<TSnapshot extends AnyMachineSnapshot = AnyMachineSna
132
148
  /** Retries after a failed choice. Default `2`. */
133
149
  maxRetries?: number;
134
150
  signal?: AbortSignal;
151
+ /** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
152
+ strategy?: DecisionStrategy;
153
+ /** Model ref that fills open payload fields under `'pick-then-fill'`. */
154
+ fillModel?: string;
155
+ /** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
156
+ groups?: Record<string, readonly string[]>;
157
+ /** Fills open payload fields with `fillModel`. */
158
+ generateText?: AgentRequestExecutor;
135
159
  }
136
160
  /** Result of {@link decideNext}. */
137
161
  interface DecideNextResult<TEvent = ChosenEvent> {
@@ -233,6 +257,139 @@ interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<Age
233
257
  */
234
258
  export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
235
259
  //#endregion
260
+ //#region src/wrap-workflow.d.ts
261
+ /** The effects a wrapped workflow calls: async functions, by name. */
262
+ type WorkflowEffects<TEffects> = { [K in keyof TEffects]: (...args: never[]) => PromiseLike<unknown>; };
263
+ /** What a wrapped workflow's `run` gets besides its input and effects. */
264
+ interface WorkflowRunContext {
265
+ /** Aborted when the run is aborted or the machine stops the workflow. */
266
+ signal: AbortSignal;
267
+ }
268
+ /** Options for {@link wrapWorkflow}. */
269
+ interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>> {
270
+ /** The machine id. */
271
+ id: string;
272
+ /** The machine version, for the event log. Default `"1"`. */
273
+ version?: string;
274
+ /** Every side effect the workflow makes: model calls, tools, writes. */
275
+ effects: TEffects;
276
+ /**
277
+ * The existing workflow. It must reach the outside world only through
278
+ * `effects`; a call it makes around them is invisible to the machine, to
279
+ * traces, and to {@link Recorder} recordings. It gets its own deep copy of
280
+ * a plain-data input, free to mutate; an input holding class instances or
281
+ * functions is passed as is. An effect that resolves to a stream (anything
282
+ * `for await` reads) settles once the stream is read, with its chunks.
283
+ */
284
+ run: (input: TInput, effects: TEffects, context: WorkflowRunContext) => PromiseLike<TOutput>;
285
+ /**
286
+ * Maps an effect's arguments, result, or error before it is journaled as an
287
+ * event. Return a redacted value for secrets and private records: every
288
+ * `effect.*` event reaches traces, the event log, and the inspector.
289
+ * Default: journal each value as is (JSON-safe).
290
+ */
291
+ redact?: (name: string, part: "args" | "result" | "error", value: unknown) => unknown;
292
+ }
293
+ /** An effect call, as the machine sees it. `call` pairs it with its result. */
294
+ interface EffectCallEvent {
295
+ type: "effect.call";
296
+ name: string;
297
+ /** 0-based, across all effects of the run. */
298
+ call: number;
299
+ /** The arguments, JSON-safe. */
300
+ args: JsonValue[];
301
+ }
302
+ /** An effect call that resolved. */
303
+ interface EffectDoneEvent {
304
+ type: "effect.done";
305
+ name: string;
306
+ call: number;
307
+ /**
308
+ * The resolved value, JSON-safe (`null` for `undefined`). For a stream, the
309
+ * chunks read, or `{ chunks, returned }` when a generator returned a value.
310
+ */
311
+ result: JsonValue;
312
+ }
313
+ /** An effect call that rejected. */
314
+ interface EffectErrorEvent {
315
+ type: "effect.error";
316
+ name: string;
317
+ call: number;
318
+ /** The error, JSON-safe: `{ name, message, stack?, code? }`. */
319
+ error: JsonValue;
320
+ }
321
+ /** The wrapped machine's context. */
322
+ type WrappedWorkflowContext<TInput, TOutput> = {
323
+ input: TInput;
324
+ /** What the workflow returned, once it did. */
325
+ output?: TOutput;
326
+ /** Effect calls started. */
327
+ calls: number;
328
+ /** Effect calls that rejected. */
329
+ failures: number;
330
+ };
331
+ /** Options for {@link WrappedWorkflow.run}: `runAgent` options that fit a black box, plus fakes and a recorder. */
332
+ interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<AgentRunOptions<WrappedWorkflowMachine<TInput, TOutput>>, "signal" | "inspect" | "onTransition" | "onTrace" | "onEvent" | "metadata" | "verification"> {
333
+ /** Replaces some effects for this run: fakes, stubs, replay wrappers. */
334
+ effects?: Partial<TEffects>;
335
+ /**
336
+ * Wraps every function effect with `recorder.fn(name, fn)` and records the
337
+ * result with `recorder.output`, so `recorder.recording` is a golden run.
338
+ */
339
+ recorder?: Recorder;
340
+ }
341
+ /** The result of {@link wrapWorkflow}. */
342
+ interface WrappedWorkflow<TInput, TOutput, TEffects> {
343
+ /**
344
+ * `running` invokes the workflow and counts its effect calls; `done` is
345
+ * final with the workflow's result as output. A rejection is unhandled, so
346
+ * the run settles `{ status: "error", cause: "machine" }` with the thrown
347
+ * error. Runs with `runAgent`, `describeMachine`, `canReach` and the inspector.
348
+ */
349
+ machine: WrappedWorkflowMachine<TInput, TOutput>;
350
+ /**
351
+ * Runs the machine with `runAgent` and returns what the workflow returned,
352
+ * or rethrows what it threw (the same error object). `signal` reaches the
353
+ * workflow, which decides what an abort means, as it did before: a
354
+ * workflow that returns an `aborted` result still returns it. Once it
355
+ * aborts, an effect call throws `signal.reason` instead of running.
356
+ */
357
+ run(input: TInput, options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput>): Promise<TOutput>;
358
+ }
359
+ /** The events a {@link wrapWorkflow} machine handles. */
360
+ type WrappedWorkflowEvent = EffectCallEvent | EffectDoneEvent | EffectErrorEvent;
361
+ /** The machine {@link wrapWorkflow} returns. */
362
+ type WrappedWorkflowMachine<TInput, TOutput> = PresetMachine<WrappedWorkflowContext<TInput, TOutput>, TInput, TOutput, WrappedWorkflowEvent>;
363
+ /**
364
+ * Wraps an existing async workflow, unchanged, as an agent machine: step 0 of
365
+ * a strangler-fig retrofit. Pass every side effect it makes as `effects`; each
366
+ * call becomes an `effect.call` event, then `effect.done` or `effect.error`, so
367
+ * it shows up in transitions, traces, the event log and the inspector.
368
+ *
369
+ * What it buys today: inspection and traces of a workflow nobody rewrote, a
370
+ * recorded baseline (`run(input, { recorder })`, or `checkParity` from
371
+ * `@statelyai/agent/testing`), `signal` to abort it, and a seam to carve
372
+ * phases out of, one at a time.
373
+ *
374
+ * What it does not: the workflow is a black box. The machine has one state
375
+ * for all of it, so there is no resume in the middle of the function (a
376
+ * resumed run starts it again), and `canReach` or `explorePaths` prove nothing
377
+ * about what happens inside. Those arrive per phase, as phases move into
378
+ * states. Effect arguments and results are journaled JSON-safe; values that
379
+ * are not JSON lose what JSON cannot hold.
380
+ *
381
+ * @example
382
+ * ```ts
383
+ * const support = wrapWorkflow({
384
+ * id: "support",
385
+ * effects: { generate, lookupOrder, issueRefund },
386
+ * run: (input: Ticket, effects) => legacyRunTicket(input, effects),
387
+ * });
388
+ * const reply = await support.run(ticket); // what legacyRunTicket returned
389
+ * ```
390
+ */
391
+ export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>>(config: WrapWorkflowConfig<TInput, TOutput, TEffects>): WrappedWorkflow<TInput, TOutput, TEffects>;
392
+ //#endregion
236
393
  //#region src/provide-executors.d.ts
237
394
  /** Options for {@link provideExecutors}. */
238
395
  interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
@@ -279,6 +436,8 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
279
436
  * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
280
437
  * candidate events, guard `canTake`, and auto-delivery of the chosen event,
281
438
  * mirroring `createAgentRuntime` but without its model-call counting)
439
+ * - `agent.act` → `executors.generateText` (accepted events as tools, each
440
+ * call sent to the invoking actor)
282
441
  *
283
442
  * Pass `options.onTrace` to observe request-level trace events (identical in
284
443
  * shape to `createAgentRuntime`'s); pair it with {@link traceTransitions} on the actor's
@@ -301,4 +460,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
301
460
  */
302
461
  export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
303
462
  //#endregion
304
- export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
463
+ export { ACT_STATE_EXITED, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActInput, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInbox, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type BuiltinAgentActors, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, DEFAULT_ACT_MAX_STEPS, type DataContent, type DecideNextOptions, type DecideNextResult, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DecisionStrategy, type DescribeMachineOptions, type DoneActorEventOf, type EffectCallEvent, type EffectDoneEvent, type EffectErrorEvent, type EventFromSnapshot, type EventOf, type EventPayload, type EventUnion, type FilePart, type FromConfigOptions, type FromConfigResult, GROUPED_EVENT_THRESHOLD, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, MAX_FINITE_PAYLOADS, type MetaOf, type MetaOfSnapshot, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SetupAgentResult, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentInputSchema, type WithAgentUsageEvent, type WorkflowEffects, type WorkflowRunContext, type WrapWorkflowConfig, type WrappedWorkflow, type WrappedWorkflowContext, type WrappedWorkflowEvent, type WrappedWorkflowMachine, type WrappedWorkflowRunOptions, assistantMessage, bindRequestExecutor, createAgentInbox, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };