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

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 (135) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
  3. package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
  4. package/dist/ai-sdk.cjs +4 -4
  5. package/dist/ai-sdk.d.cts +2 -3
  6. package/dist/ai-sdk.d.mts +2 -3
  7. package/dist/ai-sdk.mjs +4 -4
  8. package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
  9. package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
  10. package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
  11. package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
  12. package/dist/effects-B9IvUPVh.mjs +23 -0
  13. package/dist/effects-DrWcUGgc.cjs +34 -0
  14. package/dist/evals.cjs +810 -0
  15. package/dist/evals.d.cts +595 -0
  16. package/dist/evals.d.mts +595 -0
  17. package/dist/evals.mjs +801 -0
  18. package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
  19. package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
  20. package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
  21. package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
  22. package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
  23. package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
  24. package/dist/index.cjs +136 -98
  25. package/dist/index.d.cts +73 -134
  26. package/dist/index.d.mts +73 -134
  27. package/dist/index.mjs +117 -75
  28. package/dist/internal-BzlpzSux.d.cts +14 -0
  29. package/dist/internal-BzlpzSux.d.mts +14 -0
  30. package/dist/log.cjs +2 -3
  31. package/dist/log.d.cts +2 -2
  32. package/dist/log.d.mts +2 -2
  33. package/dist/log.mjs +3 -3
  34. package/dist/machines.cjs +1 -719
  35. package/dist/machines.d.cts +2 -424
  36. package/dist/machines.d.mts +2 -424
  37. package/dist/machines.mjs +2 -709
  38. package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
  39. package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
  40. package/dist/openai.cjs +3 -3
  41. package/dist/openai.d.cts +2 -3
  42. package/dist/openai.d.mts +2 -3
  43. package/dist/openai.mjs +3 -3
  44. package/dist/otel.d.cts +1 -1
  45. package/dist/otel.d.mts +1 -1
  46. package/dist/policy.cjs +77 -0
  47. package/dist/policy.d.cts +143 -0
  48. package/dist/policy.d.mts +143 -0
  49. package/dist/policy.mjs +75 -0
  50. package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
  51. package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
  52. package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
  53. package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
  54. package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
  55. package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
  56. package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
  57. package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
  58. package/dist/tanstack-ai.cjs +4 -4
  59. package/dist/tanstack-ai.d.cts +2 -3
  60. package/dist/tanstack-ai.d.mts +2 -3
  61. package/dist/tanstack-ai.mjs +4 -4
  62. package/dist/testing.cjs +122 -996
  63. package/dist/testing.d.cts +36 -695
  64. package/dist/testing.d.mts +36 -695
  65. package/dist/testing.mjs +112 -977
  66. package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
  67. package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
  68. package/dist/trajectory-BFjXaooB.d.cts +96 -0
  69. package/dist/trajectory-BFjXaooB.d.mts +96 -0
  70. package/dist/trajectory-BUXj_1Ue.mjs +152 -0
  71. package/dist/trajectory-CoZSv4wF.cjs +157 -0
  72. package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
  73. package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
  74. package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
  75. package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
  76. package/dist/validate.cjs +4 -4
  77. package/dist/validate.d.cts +2 -2
  78. package/dist/validate.d.mts +2 -2
  79. package/dist/validate.mjs +4 -4
  80. package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
  81. package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
  82. package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
  83. package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
  84. package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
  85. package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
  86. package/docs/advanced.md +5 -5
  87. package/docs/choosing-a-run-mode.md +7 -7
  88. package/docs/debugging.md +6 -8
  89. package/docs/decisions.md +6 -5
  90. package/docs/environment-and-policy.md +1 -1
  91. package/docs/evals.md +57 -43
  92. package/docs/event-log.md +14 -16
  93. package/docs/from-a-loop.md +3 -3
  94. package/docs/generate-machines.md +4 -4
  95. package/docs/hosts.md +22 -29
  96. package/docs/human-in-the-loop.md +5 -8
  97. package/docs/index.md +4 -4
  98. package/docs/judgments.md +5 -7
  99. package/docs/langgraph-comparison.md +6 -6
  100. package/docs/machines-as-data.md +12 -17
  101. package/docs/machines-presets.md +17 -120
  102. package/docs/machines.md +13 -13
  103. package/docs/models-and-providers.md +19 -25
  104. package/docs/multi-agent.md +1 -1
  105. package/docs/observability.md +6 -8
  106. package/docs/persistence.md +15 -25
  107. package/docs/quickstart.md +4 -4
  108. package/docs/statechart-policy-examples.md +1 -1
  109. package/docs/steps.md +5 -6
  110. package/docs/strangler-fig.md +72 -7
  111. package/docs/text-requests.md +10 -12
  112. package/docs/thinking-in-state-machines.md +8 -8
  113. package/docs/tools.md +10 -12
  114. package/docs/upgrading.md +1 -1
  115. package/docs/usage-and-budgets.md +51 -56
  116. package/docs/validate-and-repair.md +9 -14
  117. package/docs/verify.md +53 -7
  118. package/docs/xstate-4-and-5-apps.md +19 -28
  119. package/llms.txt +1 -1
  120. package/package.json +31 -6
  121. package/readme.md +32 -24
  122. package/dist/internal-C3Lqu538.d.cts +0 -43
  123. package/dist/internal-DUcdhk-i.d.mts +0 -43
  124. package/dist/types-DQUOOaZO.d.cts +0 -238
  125. package/dist/types-DQUOOaZO.d.mts +0 -238
  126. package/skills/add-evals/SKILL.md +0 -152
  127. package/skills/add-traces/SKILL.md +0 -152
  128. package/skills/build-machine/SKILL.md +0 -84
  129. package/skills/generate-machine/SKILL.md +0 -335
  130. package/skills/graph-engineering/SKILL.md +0 -43
  131. package/skills/improve-machine/SKILL.md +0 -261
  132. package/skills/improve-machine/reference.md +0 -101
  133. package/skills/loop-to-machine/SKILL.md +0 -205
  134. package/skills/loop-to-machine/policy.md +0 -154
  135. package/skills/loop-to-machine/reference.md +0 -260
package/readme.md CHANGED
@@ -8,7 +8,7 @@ What you get:
8
8
 
9
9
  - **Proofs with no model.** Put the rule that must never break behind a sentinel state, then `canReach(machine, "refundedOverLimit", options)` returns `reachable: false` and `complete: true` with no API key. See [Testing and verification](https://github.com/statelyai/agent/blob/next/docs/verify.md).
10
10
  - **Resume and replay from the event log.** A paused run resumes with `runAgent(machine, { snapshot, event })`, and `replay(machine, result.events)` rebuilds any point of a run with no model calls. See [The event log](https://github.com/statelyai/agent/blob/next/docs/event-log.md).
11
- - **Checked ports.** `createRecorder` records the old loop's model and tool calls, `compareRecordings` replays them against the machine, and `compareRuns` labels every scenario `same`, `intended`, or `regression`. See [Parity with the code you replace](https://github.com/statelyai/agent/blob/next/docs/evals.md#parity-with-the-code-you-replace).
11
+ - **Checked ports.** `checkParity` records the old code's side effects, replays them against the machine, and reports every scenario where the two differ. `compareRuns` labels outcome-level differences `same`, `intended`, or `regression`. See [Parity with the code you replace](https://github.com/statelyai/agent/blob/next/docs/evals.md#parity-with-the-code-you-replace).
12
12
 
13
13
  The machine is also a diagram: stream any run to the Stately inspector with `runAgent`'s `inspect` option. See [Inspect a run](https://github.com/statelyai/agent/blob/next/docs/observability.md#inspect-a-run).
14
14
 
@@ -32,8 +32,8 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
32
32
  ### Brownfield: an existing agent
33
33
 
34
34
  - **Wrap an existing workflow, then carve it.** `wrapWorkflow` runs an async workflow unchanged inside a machine. In minutes and with no rewrite, you get inspection, traces, the event log, and a recorded baseline. Reliability proofs such as `canReach` arrive per phase, as each phase moves into states, with `checkParity` against the original after each. See [Strangler-fig retrofit](https://github.com/statelyai/agent/blob/next/docs/strangler-fig.md).
35
- - **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the shipped `loop-to-machine` skill (see [Agent skills](#agent-skills)): "Use the loop-to-machine skill to convert `src/support-agent.ts` to a machine."
36
- - **Let an agent improve its own logic (experimental).** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md).
35
+ - **Retrofit an existing agent.** Turn a `while` loop into a machine: your SDK calls, tools, and retry code become the executors; the machine replaces only the control flow. See [Migrating from a hand-rolled loop](https://github.com/statelyai/agent/blob/next/docs/from-a-loop.md). A coding agent does it with the `loop-to-machine` skill (see [Agent skills](#agent-skills)): "Use the loop-to-machine skill to convert `src/support-agent.ts` to a machine."
36
+ - **Let an agent improve its own logic (experimental).** Keep the rules in a fixed TypeScript environment and let a model rewrite the JSON policy inside it, gated by `verifyAgentConfig` and promoted only when held-out scenarios improve. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md) and the [`improve-machine` skill](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md).
37
37
 
38
38
  ## Environment and policy
39
39
 
@@ -43,13 +43,13 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
43
43
 
44
44
  ## Install
45
45
 
46
- <!-- install command matching the package prerelease channel and package.json peers -->
46
+ <!-- Match the published agent release with its published XState peer. -->
47
47
 
48
48
  ```sh
49
- pnpm add @statelyai/agent@alpha xstate@6.0.0-beta.0 zod
49
+ pnpm add @statelyai/agent@2.0.0-alpha.38 xstate@6.0.0-beta.0 zod
50
50
  ```
51
51
 
52
- XState is pinned while its experimental durable restoration API evolves.
52
+ This is the published pair as of November 11, 2026. This source checkout requires XState `6.0.0-beta.2`; use that version when building the checkout. XState is pinned while its experimental durable restoration API evolves.
53
53
 
54
54
  For the optional Vercel AI SDK executor:
55
55
 
@@ -75,7 +75,7 @@ Upgrading from an earlier alpha: see [Upgrading between alphas](https://github.c
75
75
 
76
76
  Requirements:
77
77
 
78
- - Node 22 or newer, and XState exactly `6.0.0-beta.0`.
78
+ - Node 22 or newer. This source checkout requires XState exactly `6.0.0-beta.2`; the published release above requires `6.0.0-beta.0`.
79
79
  - TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
80
80
  - A [Standard Schema](https://standardschema.dev) library: zod 4, zod 3.24 or newer, Valibot, or ArkType. `setupAgent` throws `invalid-schema` for zod 3.23 and earlier.
81
81
  - The package is ESM-first. CommonJS builds are published too, so `require()` works. Subpath imports (`@statelyai/agent/testing`) resolve under every `moduleResolution`, including `node`.
@@ -84,30 +84,38 @@ Requirements:
84
84
 
85
85
  An app that already uses XState 4 or 5 keeps it: put the agent in its own workspace package. See [Use in an XState 4 or 5 app](https://github.com/statelyai/agent/blob/next/docs/xstate-4-and-5-apps.md). If both versions land in one `node_modules`, the package fails with errors that do not mention a version:
86
86
 
87
- | Error | Cause |
88
- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
89
- | `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
90
- | `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
91
- | `unmet peer dependency "xstate@6.0.0-beta.0"` (pnpm, npm) or `has incorrect peer dependency "xstate@6.0.0-beta.0"` (yarn 1) | The install's only warning of the two above |
87
+ | Error | Cause |
88
+ | ---------------------------------------------------- | ------------------------------------------- |
89
+ | `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
90
+ | `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
91
+ | An unmet or incorrect XState peer dependency warning | The install's only warning of the two above |
92
92
 
93
93
  ## Agent skills
94
94
 
95
- The package ships agent skills in `node_modules/@statelyai/agent/skills/`, and its docs in `node_modules/@statelyai/agent/docs/` with an index in `llms.txt`. Copy the skills into your coding agent's skills directory (for Claude Code, `.claude/skills/`):
95
+ The agent skills live in [statelyai/skills](https://github.com/statelyai/skills), in the `stately-agent` plugin. The package ships its docs in `node_modules/@statelyai/agent/docs/` with an index in `llms.txt`.
96
+
97
+ In Claude Code:
98
+
99
+ ```text
100
+ /plugin marketplace add statelyai/skills
101
+ /plugin install stately-agent@stately
102
+ ```
103
+
104
+ For other coding agents:
96
105
 
97
106
  ```sh
98
- mkdir -p .claude/skills
99
- cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
107
+ npx skills add statelyai/skills
100
108
  ```
101
109
 
102
- | Skill | What it does |
103
- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
104
- | [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
105
- | [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
106
- | [`build-machine`](https://github.com/statelyai/agent/blob/next/skills/build-machine/SKILL.md) | Builds a TypeScript machine from a spec and proves its invariants |
107
- | [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
108
- | [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
109
- | [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
110
- | [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) | Experimental. Improves a policy from traces; a person reviews the pull request |
110
+ | Skill | What it does |
111
+ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
112
+ | [`graph-engineering`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
113
+ | [`loop-to-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
114
+ | [`build-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/build-machine/SKILL.md) | Builds a TypeScript machine from a spec and proves its invariants |
115
+ | [`generate-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
116
+ | [`add-traces`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
117
+ | [`add-evals`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
118
+ | [`improve-machine`](https://github.com/statelyai/skills/blob/main/plugins/stately-agent/skills/improve-machine/SKILL.md) | Experimental. Improves a policy from traces; a person reviews the pull request |
111
119
 
112
120
  ## Quick start
113
121
 
@@ -1,43 +0,0 @@
1
- import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.cjs";
2
- import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
3
- //#region src/machines/internal.d.ts
4
- /**
5
- * The machine type a preset factory returns: its context, event union, input
6
- * and output are all concrete, so callers get typed run input and
7
- * output instead of `AnyStateMachine`. The remaining slots (children, state
8
- * value/tags/config, source maps) are left permissive — a preset builds its
9
- * states dynamically, so there is no literal state schema to infer.
10
- *
11
- * @internal
12
- */
13
- type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
14
- /** One delegated unit of work, lowered to an inline text request. */
15
- interface PresetRequestEntry {
16
- /** What this entry is for. Shown to the routing/supervising model. */
17
- description?: string;
18
- /** System prompt for this entry's model call. */
19
- instructions?: string;
20
- /** Model ref (or `models` alias). Falls back to the factory's `model`. */
21
- model?: string;
22
- /** Structured output schema. Omitted means plain text. */
23
- outputSchema?: StandardSchemaV1;
24
- /** Tools the host runs inside this one request. */
25
- tools?: AgentTools;
26
- /** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
27
- maxSteps?: number;
28
- }
29
- /** One delegated unit of work, lowered to an invoked child machine. */
30
- interface PresetMachineEntry {
31
- /** What this entry is for. Shown to the routing/supervising model. */
32
- description?: string;
33
- /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
34
- machine: AnyStateMachine;
35
- /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
36
- input?: (args: {
37
- prompt: string;
38
- }) => unknown;
39
- }
40
- /** A route/branch/worker/agent entry: an inline request, or a child machine. */
41
- type PresetEntry = PresetRequestEntry | PresetMachineEntry;
42
- //#endregion
43
- export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };
@@ -1,43 +0,0 @@
1
- import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.mjs";
2
- import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
3
- //#region src/machines/internal.d.ts
4
- /**
5
- * The machine type a preset factory returns: its context, event union, input
6
- * and output are all concrete, so callers get typed run input and
7
- * output instead of `AnyStateMachine`. The remaining slots (children, state
8
- * value/tags/config, source maps) are left permissive — a preset builds its
9
- * states dynamically, so there is no literal state schema to infer.
10
- *
11
- * @internal
12
- */
13
- type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
14
- /** One delegated unit of work, lowered to an inline text request. */
15
- interface PresetRequestEntry {
16
- /** What this entry is for. Shown to the routing/supervising model. */
17
- description?: string;
18
- /** System prompt for this entry's model call. */
19
- instructions?: string;
20
- /** Model ref (or `models` alias). Falls back to the factory's `model`. */
21
- model?: string;
22
- /** Structured output schema. Omitted means plain text. */
23
- outputSchema?: StandardSchemaV1;
24
- /** Tools the host runs inside this one request. */
25
- tools?: AgentTools;
26
- /** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
27
- maxSteps?: number;
28
- }
29
- /** One delegated unit of work, lowered to an invoked child machine. */
30
- interface PresetMachineEntry {
31
- /** What this entry is for. Shown to the routing/supervising model. */
32
- description?: string;
33
- /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
34
- machine: AnyStateMachine;
35
- /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
36
- input?: (args: {
37
- prompt: string;
38
- }) => unknown;
39
- }
40
- /** A route/branch/worker/agent entry: an inline request, or a child machine. */
41
- type PresetEntry = PresetRequestEntry | PresetMachineEntry;
42
- //#endregion
43
- export { PresetRequestEntry as i, PresetMachine as n, PresetMachineEntry as r, PresetEntry as t };
@@ -1,238 +0,0 @@
1
- //#region src/types.d.ts
2
- /**
3
- * The [Standard Schema](https://standardschema.dev) interface. Every schema
4
- * this library accepts (context, events, input/output, tool schemas, …) is a
5
- * `StandardSchemaV1` — Zod, Valibot, ArkType, and hand-written validators all
6
- * implement it, so the library never depends on a specific validation
7
- * library. JSON workflow configs use a caller-provided {@link SchemaCompiler}.
8
- */
9
- interface StandardSchemaV1<Input = unknown, Output = Input> {
10
- readonly "~standard": {
11
- readonly version: 1;
12
- readonly vendor: string;
13
- readonly validate: (value: unknown) => any;
14
- readonly types?: {
15
- readonly input: Input;
16
- readonly output: Output;
17
- };
18
- readonly jsonSchema?: {
19
- readonly input?: (...args: any[]) => unknown;
20
- readonly output?: (...args: any[]) => unknown;
21
- };
22
- };
23
- }
24
- /** The validated output type of a {@link StandardSchemaV1}. */
25
- type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
26
- /**
27
- * The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
28
- * passes in, before defaults are filled and transforms applied. Standard Schema
29
- * carries both sides (`~standard.types.input` / `.output`), so a schema
30
- * declaring a defaulted field makes that field optional here and required in
31
- * {@link InferOutput} — which is exactly the split between what a run
32
- * accepts as machine `input` and what the `context` factory then sees.
33
- */
34
- type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
35
- /**
36
- * Phantom brand carrying a machine's declared input schema on the machine type.
37
- *
38
- * XState resolves `schemas.input` to a single type and uses it for both
39
- * `createActor`'s `input` option and the `context: ({ input })` factory, so the
40
- * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
41
- * `createMachine` brands the machine's input type with the schema itself, which
42
- * lets `AgentInputFrom` recover the looser input side for a run's `input` while the
43
- * `context` factory keeps the strict validated side.
44
- *
45
- * The key is a `~`-prefixed phantom property (the same convention Standard
46
- * Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
47
- * have to be exported as a runtime value for declaration emit to name it in
48
- * every machine type it touches.
49
- */
50
- type WithAgentInputSchema<TInputSchema> = {
51
- readonly "~agent.inputSchema"?: TInputSchema;
52
- };
53
- /** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
54
- type EventPayload<T> = T extends Record<string, never> ? unknown : T;
55
- /**
56
- * One entry in an event schema map: a Standard Schema for the event's
57
- * payload, or the `{}` shorthand for a payload-less event
58
- * (`events: { CONFIRM: {} }` ≡ `events: { CONFIRM: z.object({}) }`).
59
- */
60
- type AgentEventSchemaInput = StandardSchemaV1 | Record<string, never>;
61
- /** An event schema map as authored: payload schemas and/or `{}` payload-less shorthands, keyed by event type. */
62
- type AgentEventSchemaInputMap = Record<string, AgentEventSchemaInput>;
63
- /** Resolves an authored event schema map's `{}` shorthands to real (empty-payload) schemas — the type-level counterpart of the runtime normalization in `createAgentSchemas`. */
64
- type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof T]: T[K] extends StandardSchemaV1 ? T[K] : StandardSchemaV1<{}>; };
65
- /**
66
- * The discriminated event union derived from a machine's event schema map
67
- * (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
68
- * question: string }`; a `{}` shorthand entry yields its bare `{ type: K }`).
69
- * Used internally by {@link createAgentSchemas} and `setupAgent` to type a
70
- * machine's `TEvent`.
71
- */
72
- type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
73
- type: K;
74
- } & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown); }[keyof T & string];
75
- /** Raw binary or string content for an {@link ImagePart}/{@link FilePart}. */
76
- type DataContent = string | Uint8Array | ArrayBuffer;
77
- /** Provider-specific passthrough options, keyed by provider name (e.g. `{ anthropic: { cacheControl: ... } }`). */
78
- type ProviderOptions = Record<string, Record<string, unknown>>;
79
- /** A plain-text segment of a multi-part {@link AgentMessage} content array. */
80
- interface TextPart {
81
- type: "text";
82
- text: string;
83
- providerOptions?: ProviderOptions;
84
- }
85
- /**
86
- * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
87
- * JSON-serializable. Machines that persist snapshots/event logs should use
88
- * URL strings or base64-encoded strings in `image` instead.
89
- */
90
- interface ImagePart {
91
- type: "image";
92
- image: DataContent | URL;
93
- mediaType?: string;
94
- providerOptions?: ProviderOptions;
95
- }
96
- /**
97
- * Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
98
- * JSON-serializable. Machines that persist snapshots/event logs should use
99
- * URL strings or base64-encoded strings in `data` instead.
100
- */
101
- interface FilePart {
102
- type: "file";
103
- data: DataContent | URL;
104
- mediaType: string;
105
- filename?: string;
106
- providerOptions?: ProviderOptions;
107
- }
108
- /** A model-issued tool call, as an {@link AssistantMessage} content part. */
109
- interface ToolCallPart {
110
- type: "tool-call";
111
- toolCallId: string;
112
- toolName: string;
113
- input: unknown;
114
- providerOptions?: ProviderOptions;
115
- }
116
- /** The result payload of a {@link ToolResultPart}, discriminated by shape (plain text/JSON, or an error variant of either). */
117
- type ToolResultOutput = {
118
- type: "text";
119
- value: string;
120
- } | {
121
- type: "json";
122
- value: unknown;
123
- } | {
124
- type: "error-text";
125
- value: string;
126
- } | {
127
- type: "error-json";
128
- value: unknown;
129
- } | {
130
- type: "content";
131
- value: Array<TextPart | ImagePart>;
132
- };
133
- /** A tool's result, as a {@link ToolMessage} content part. */
134
- interface ToolResultPart {
135
- type: "tool-result";
136
- toolCallId: string;
137
- toolName: string;
138
- output: ToolResultOutput;
139
- providerOptions?: ProviderOptions;
140
- }
141
- /** A system-role {@link AgentMessage}. Create with {@link systemMessage}. */
142
- type SystemMessage = {
143
- role: "system";
144
- content: string;
145
- providerOptions?: ProviderOptions;
146
- };
147
- /** A user-role {@link AgentMessage}, optionally multimodal. Create with {@link userMessage}. */
148
- type UserMessage = {
149
- role: "user";
150
- content: string | Array<TextPart | ImagePart | FilePart>;
151
- providerOptions?: ProviderOptions;
152
- };
153
- /** An assistant-role {@link AgentMessage}, which may carry tool calls/results inline. Create with {@link assistantMessage}. */
154
- type AssistantMessage = {
155
- role: "assistant";
156
- content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>;
157
- providerOptions?: ProviderOptions;
158
- };
159
- /** A tool-role {@link AgentMessage} carrying one or more tool results. Create with {@link toolMessage}. */
160
- type ToolMessage = {
161
- role: "tool";
162
- content: Array<ToolResultPart>;
163
- providerOptions?: ProviderOptions;
164
- };
165
- /**
166
- * Optional framework-neutral message helpers. Requests also accept native
167
- * framework message values directly; core never converts between formats.
168
- * Store messages as plain context state: a text request's `onDone` output
169
- * carries the executor's response messages as `output.messages`.
170
- */
171
- type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
172
- /**
173
- * A schema value on an {@link AgentToolDescriptor}: deliberately just `object`,
174
- * because an SDK-native tool's `inputSchema` is the SDK's own union type (a Zod
175
- * schema, the SDK's `Schema`, a lazy thunk, ...) and must assign structurally
176
- * with no cast. The contract is runtime, not static: core narrows with
177
- * `isStandardSchema` and reads {@link StandardSchemaV1} schemas via
178
- * `getJsonSchema`; anything else passes through to the executor untouched.
179
- */
180
- type AgentToolSchema = object;
181
- /**
182
- * A tool exposed to a text request, described for both the model and
183
- * (optionally) host execution. This is a **minimal structural contract**: any
184
- * object matching it — an AI SDK `tool({...})`, an MCP-style descriptor, or a
185
- * hand-written `{ description, inputSchema, execute }` — is a valid entry, and
186
- * extra properties (`providerOptions`, `toModelOutput`, …) pass through
187
- * untouched via the index signature. `execute` is typed permissively so a
188
- * native tool's `(input, options)` executor is structurally assignable; the
189
- * SDK you built the tool with owns its precise input typing.
190
- */
191
- interface AgentToolDescriptor {
192
- /**
193
- * Text shown to the model. Typed loosely enough to accept an SDK tool whose
194
- * description is computed per call (the AI SDK v7 `tool({ description })`
195
- * accepts a function of the call's context); core never reads it.
196
- */
197
- description?: string | ((...args: any[]) => string);
198
- inputSchema?: AgentToolSchema;
199
- outputSchema?: AgentToolSchema;
200
- execute?: (...args: any[]) => unknown;
201
- [key: string]: unknown;
202
- }
203
- /** A bare tool implementation (no description/schema) — shorthand for {@link AgentToolDescriptor.execute}. */
204
- type AgentToolExecute = (input?: unknown) => unknown | Promise<unknown>;
205
- /** A tool entry in {@link AgentTools}: either a full descriptor or a bare execute function. */
206
- type AgentTool = AgentToolDescriptor | AgentToolExecute;
207
- /** The `tools` map passed on an {@link AgentTextRequest}, keyed by tool name. */
208
- type AgentTools = Record<string, AgentTool | undefined>;
209
- /** How a text request's model should select among its `tools`; `{ type: 'tool', name }` forces one specific tool. */
210
- type AgentToolChoice = "auto" | "none" | "required" | {
211
- type: "tool";
212
- name: string;
213
- };
214
- /** The event chosen and raised by a decision. */
215
- type ChosenEvent = {
216
- type: string;
217
- [key: string]: unknown;
218
- };
219
- type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${infer Rest}` ? `${Head}.*` | `${Head}.${EventWildcardsOf<Rest>}` : never;
220
- /** One `allowedEvents` entry: an exact declared event type, `'*'` (every event), or a `'prefix.*'` wildcard derived from the declared dotted event types. */
221
- type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventWildcardsOf<TEvent>;
222
- /**
223
- * Candidate event types for a decision (declared on the `agent.decide`
224
- * builtin's `allowedEvents` input). A single
225
- * entry or an array; entries are exact event types or wildcard patterns
226
- * (`'*'` for every event, `'todo.*'` for a dotted namespace). The effective
227
- * candidate set offered to the model is this declaration **intersected with
228
- * the snapshot's currently-legal events** (via `getAcceptedEvents`) —
229
- * omitting `allowedEvents` means "all currently-legal events." A resolver
230
- * function can therefore only ever narrow, never widen, the real surface.
231
- * Wildcards expand against the live snapshot, so they need a snapshot-aware
232
- * host (`createAgentRuntime`).
233
- */
234
- type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
235
- input: TInput;
236
- }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
237
- //#endregion
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 };