@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.
- package/CHANGELOG.md +51 -0
- package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
- package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
- package/dist/ai-sdk.cjs +4 -4
- package/dist/ai-sdk.d.cts +2 -3
- package/dist/ai-sdk.d.mts +2 -3
- package/dist/ai-sdk.mjs +4 -4
- package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
- package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
- package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
- package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
- package/dist/effects-B9IvUPVh.mjs +23 -0
- package/dist/effects-DrWcUGgc.cjs +34 -0
- package/dist/evals.cjs +810 -0
- package/dist/evals.d.cts +595 -0
- package/dist/evals.d.mts +595 -0
- package/dist/evals.mjs +801 -0
- package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
- package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
- package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
- package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
- package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
- package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
- package/dist/index.cjs +136 -98
- package/dist/index.d.cts +73 -134
- package/dist/index.d.mts +73 -134
- package/dist/index.mjs +117 -75
- package/dist/internal-BzlpzSux.d.cts +14 -0
- package/dist/internal-BzlpzSux.d.mts +14 -0
- package/dist/log.cjs +2 -3
- package/dist/log.d.cts +2 -2
- package/dist/log.d.mts +2 -2
- package/dist/log.mjs +3 -3
- package/dist/machines.cjs +1 -719
- package/dist/machines.d.cts +2 -424
- package/dist/machines.d.mts +2 -424
- package/dist/machines.mjs +2 -709
- package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
- package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
- package/dist/openai.cjs +3 -3
- package/dist/openai.d.cts +2 -3
- package/dist/openai.d.mts +2 -3
- package/dist/openai.mjs +3 -3
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +77 -0
- package/dist/policy.d.cts +143 -0
- package/dist/policy.d.mts +143 -0
- package/dist/policy.mjs +75 -0
- package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
- package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
- package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
- package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
- package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
- package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
- package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
- package/dist/tanstack-ai.cjs +4 -4
- package/dist/tanstack-ai.d.cts +2 -3
- package/dist/tanstack-ai.d.mts +2 -3
- package/dist/tanstack-ai.mjs +4 -4
- package/dist/testing.cjs +122 -996
- package/dist/testing.d.cts +36 -695
- package/dist/testing.d.mts +36 -695
- package/dist/testing.mjs +112 -977
- package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
- package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
- package/dist/trajectory-BFjXaooB.d.cts +96 -0
- package/dist/trajectory-BFjXaooB.d.mts +96 -0
- package/dist/trajectory-BUXj_1Ue.mjs +152 -0
- package/dist/trajectory-CoZSv4wF.cjs +157 -0
- package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
- package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
- package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
- package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
- package/dist/validate.cjs +4 -4
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +4 -4
- package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
- package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
- package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
- package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
- package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
- package/docs/advanced.md +5 -5
- package/docs/choosing-a-run-mode.md +7 -7
- package/docs/debugging.md +6 -8
- package/docs/decisions.md +6 -5
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +14 -16
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +22 -29
- package/docs/human-in-the-loop.md +5 -8
- package/docs/index.md +4 -4
- package/docs/judgments.md +5 -7
- package/docs/langgraph-comparison.md +6 -6
- package/docs/machines-as-data.md +12 -17
- package/docs/machines-presets.md +17 -120
- package/docs/machines.md +13 -13
- package/docs/models-and-providers.md +19 -25
- package/docs/multi-agent.md +1 -1
- package/docs/observability.md +6 -8
- package/docs/persistence.md +15 -25
- package/docs/quickstart.md +4 -4
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +72 -7
- package/docs/text-requests.md +10 -12
- package/docs/thinking-in-state-machines.md +8 -8
- package/docs/tools.md +10 -12
- package/docs/upgrading.md +1 -1
- package/docs/usage-and-budgets.md +51 -56
- package/docs/validate-and-repair.md +9 -14
- package/docs/verify.md +53 -7
- package/docs/xstate-4-and-5-apps.md +19 -28
- package/llms.txt +1 -1
- package/package.json +31 -6
- package/readme.md +32 -24
- package/dist/internal-C3Lqu538.d.cts +0 -43
- package/dist/internal-DUcdhk-i.d.mts +0 -43
- package/dist/types-DQUOOaZO.d.cts +0 -238
- package/dist/types-DQUOOaZO.d.mts +0 -238
- package/skills/add-evals/SKILL.md +0 -152
- package/skills/add-traces/SKILL.md +0 -152
- package/skills/build-machine/SKILL.md +0 -84
- package/skills/generate-machine/SKILL.md +0 -335
- package/skills/graph-engineering/SKILL.md +0 -43
- package/skills/improve-machine/SKILL.md +0 -261
- package/skills/improve-machine/reference.md +0 -101
- package/skills/loop-to-machine/SKILL.md +0 -205
- package/skills/loop-to-machine/policy.md +0 -154
- 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.** `
|
|
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
|
|
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/
|
|
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
|
-
<!--
|
|
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
|
|
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
|
|
88
|
-
|
|
|
89
|
-
| `createAsyncLogic is not a function`
|
|
90
|
-
| `Cannot find module '…/node_modules/xstate/durable'`
|
|
91
|
-
|
|
|
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
|
|
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
|
-
|
|
99
|
-
cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
|
|
107
|
+
npx skills add statelyai/skills
|
|
100
108
|
```
|
|
101
109
|
|
|
102
|
-
| Skill
|
|
103
|
-
|
|
|
104
|
-
| [`graph-engineering`](https://github.com/statelyai/
|
|
105
|
-
| [`loop-to-machine`](https://github.com/statelyai/
|
|
106
|
-
| [`build-machine`](https://github.com/statelyai/
|
|
107
|
-
| [`generate-machine`](https://github.com/statelyai/
|
|
108
|
-
| [`add-traces`](https://github.com/statelyai/
|
|
109
|
-
| [`add-evals`](https://github.com/statelyai/
|
|
110
|
-
| [`improve-machine`](https://github.com/statelyai/
|
|
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 };
|