@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.
- package/CHANGELOG.md +111 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +399 -20
- package/dist/testing.d.cts +196 -255
- package/dist/testing.d.mts +196 -255
- package/dist/testing.mjs +395 -20
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -192
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
package/llms.txt
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Stately Agent
|
|
2
|
+
|
|
3
|
+
> Agent logic as typed XState state machines: the machine owns control flow and decides what is legal, the host executes model calls. Deterministic, inspectable, resumable, and runnable in any stack.
|
|
4
|
+
|
|
5
|
+
`@statelyai/agent` 2.0 is in alpha. Pin an exact version.
|
|
6
|
+
|
|
7
|
+
## XState v6
|
|
8
|
+
|
|
9
|
+
Not v5: transitions are plain functions returning `{ target, context }` (no `assign`), guards are inline JS, targets are objects, actors use `createAsyncLogic`. `transition(machine, snapshot, event)` from `xstate` shows what one event does without running anything. `describeMachine(machine, { source: true, helpers })` lists every state, each target a transition can return, its code, and the helpers it calls.
|
|
10
|
+
|
|
11
|
+
## Docs
|
|
12
|
+
|
|
13
|
+
- [Agents](docs/index.md): Author AI agents as typed XState state machines, where the machine decides and the host executes.
|
|
14
|
+
- [Quickstart](docs/quickstart.md): Install @statelyai/agent and run your first agent machine end to end.
|
|
15
|
+
- [Thinking in state machines](docs/thinking-in-state-machines.md): A design tutorial. Take one hand-rolled agent loop, name the states hiding inside it, and turn them into a machine you can test, resume, and inspect.
|
|
16
|
+
- [Scope and ecosystem boundaries](docs/scope.md): What Stately Agent owns, what the host owns, and where specialized libraries fit.
|
|
17
|
+
- [Agent machines](docs/machines.md): Author an agent machine as a typed XState state machine that decides what your agent can do, while the host executes model calls.
|
|
18
|
+
- [Decisions](docs/decisions.md): Let the model choose one currently-legal machine event, validated and retried by the machine before it is taken. Covers closed choices over concrete events, decision-model executors, and `decideNext` for plain XState machines.
|
|
19
|
+
- [Environment and policy](docs/environment-and-policy.md): Split an agent into a fixed environment that people author and verify, and a policy that a model can write and, experimentally, improve inside it.
|
|
20
|
+
- [Text requests](docs/text-requests.md): Declare typed model calls on an agent machine and invoke them from a state, parsing structured or streamed output.
|
|
21
|
+
- [Tools](docs/tools.md): Define tools, attach them to a text request, and let the host run the tool loop while the machine stays in one state.
|
|
22
|
+
- [Judgments with the AI SDK](docs/judgments.md): Ask classification, grading, relevance, and yes/no questions with the AI SDK's experimental_decide and Jev, and branch on the typed answers in a machine.
|
|
23
|
+
- [Messages](docs/messages.md): Build and store conversation history as a parts-based message model that mirrors the AI SDK without depending on it.
|
|
24
|
+
- [Preset machines](docs/machines-presets.md): Factories for proven agent shapes (tool loop, sequential, router, parallel, loop, supervisor, handoff) that return ordinary, inspectable agent machines.
|
|
25
|
+
- [Choosing a run mode](docs/choosing-a-run-mode.md): Three ways to execute the same agent machine, what each one owns, and which to reach for.
|
|
26
|
+
- [Hosts and executors](docs/hosts.md): Give an agent machine the executor functions that call a model, and choose between the shipped AI SDK adapter or your own.
|
|
27
|
+
- [Use in any stack](docs/any-stack.md): One agent machine runs unchanged in a local script, an HTTP route, or an edge runtime. Only the executors are host-specific.
|
|
28
|
+
- [Use in an XState 4 or 5 app](docs/xstate-4-and-5-apps.md): Isolate @statelyai/agent behind a workspace package so an app on XState 4 or 5 can call an agent without upgrading.
|
|
29
|
+
- [The step API](docs/steps.md): The pure `(state, event) => (state, requests)` view of an agent machine, so any host (durable workflow, queue, test, replay) can run it without `runAgent`.
|
|
30
|
+
- [Advanced: bare XState actors and hand-written executors](docs/advanced.md): Bind executors onto a machine with `provideExecutors` to run it as a plain XState actor, and write a `{ result, messages? }` executor without an adapter.
|
|
31
|
+
- [Where state lives](docs/persistence.md): The two durable artifacts an agent run produces, what each one holds, and how to restore from them.
|
|
32
|
+
- [The event log](docs/event-log.md): The event log is the source of truth. Append external inputs, replay deterministically, fork, read back failed decision attempts, and implement a store that can list its threads; primitives in `@statelyai/agent/log`.
|
|
33
|
+
- [Human in the loop](docs/human-in-the-loop.md): Pause an agent for human input by settling idle, render the wait's choices and free-text field, persist the snapshot anywhere, and resume in a different process.
|
|
34
|
+
- [Models and providers](docs/models-and-providers.md): Reuse models and executors from other AI frameworks via AI SDK LanguageModel objects and OpenAI-compatible endpoints.
|
|
35
|
+
- [Observability](docs/observability.md): Watch an agent run locally in the Stately Inspector, ship its versioned trace stream to OpenTelemetry, and replay any run from the snapshot it traced.
|
|
36
|
+
- [Usage and budgets](docs/usage-and-budgets.md): Read token usage off a run, cap runaway loops with maxModelCalls, and enforce turn and token budgets as ordinary machine guards.
|
|
37
|
+
- [Debugging](docs/debugging.md): Find out why an agent did the wrong thing, using the inspector, the trace stream, scripted reproduction, and the static linter.
|
|
38
|
+
- [Multi-agent composition](docs/multi-agent.md): Compose agent machines today by invoking them as child actors, exposing sub-agents as host-owned tools, and coordinating siblings through events.
|
|
39
|
+
- [Machines as data](docs/machines-as-data.md): Author an agent machine as a JSON or YAML config and lower it into the same runnable XState machine that setupAgent builds in TypeScript, and describe any machine as text for a model with `describeMachine`.
|
|
40
|
+
- [Generating machines with an LLM](docs/generate-machines.md): Have a model author the agent workflow itself, then run the generated config through every pre-run gate with `verifyAgentConfig` before a single model call runs inside it.
|
|
41
|
+
- [Testing and verification](docs/verify.md): Statically lint, simulate, and explore agent machines without any API keys or model calls, from `@statelyai/agent/testing`. Exploration branches on payloads and invoke outputs, and `canReach` returns a shortest witness or a complete unreachability result.
|
|
42
|
+
- [Evals](docs/evals.md): Score agent runs on output, trajectory, and token budget using the seams runAgent already returns, with plain vitest or a vendor harness like Braintrust.
|
|
43
|
+
- [Coming from LangGraph](docs/langgraph-comparison.md): A term-by-term translation of LangGraph concepts, the same agent built both ways, an honest dimension-by-dimension comparison, and the ported examples.
|
|
44
|
+
- [Migrating from a hand-rolled loop](docs/from-a-loop.md): Convert a while-loop agent into an agent machine one step at a time, then, experimentally, improve a software-factory loop's triage from its traces without loosening its rules.
|
|
45
|
+
- [Agent patterns](docs/patterns.md): Common agent patterns (ReAct, reflection, plan-and-execute, RAG, supervisor, and more) as copy-paste XState machines, one runnable file each.
|
|
46
|
+
- [Statechart policy examples](docs/statechart-policy-examples.md): Three examples that put consequential decisions in visible machine states: consensus review, booking compensation, and deadline escalation.
|
|
47
|
+
- [Validate and repair model output with a loop](docs/validate-and-repair.md): Check model output with your own host code, feed the failure back as a repair prompt, and cap the loop in the machine.
|
|
48
|
+
- [Post-alpha roadmap](docs/roadmap.md): Work deliberately deferred past the 2.0 alpha, and why.
|
|
49
|
+
|
|
50
|
+
## Examples
|
|
51
|
+
|
|
52
|
+
- [Examples index](https://github.com/statelyai/agent/blob/next/examples/README.md): every runnable example, one flat directory each with an `index.ts` entrypoint, dual-mode against a real model or injected mocks.
|
|
53
|
+
- [Readme](readme.md): the pitch, the install command, and a complete machine that runs with no API key.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statelyai/agent",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.36",
|
|
4
4
|
"description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -22,6 +22,9 @@
|
|
|
22
22
|
"dist",
|
|
23
23
|
"schemas",
|
|
24
24
|
"skills",
|
|
25
|
+
"docs",
|
|
26
|
+
"!docs/snippet-globals.ts",
|
|
27
|
+
"llms.txt",
|
|
25
28
|
"CHANGELOG.md"
|
|
26
29
|
],
|
|
27
30
|
"type": "module",
|
|
@@ -165,6 +168,7 @@
|
|
|
165
168
|
"@opentelemetry/api": "^1.9.1",
|
|
166
169
|
"@opentelemetry/context-async-hooks": "^2.12.0",
|
|
167
170
|
"@opentelemetry/sdk-trace-base": "^2.12.0",
|
|
171
|
+
"@statelyai/sdk": "0.45.0",
|
|
168
172
|
"@tanstack/ai": "^0.66.0",
|
|
169
173
|
"@types/node": "^22.20.5",
|
|
170
174
|
"@types/react": "^19.3.0",
|
|
@@ -183,7 +187,7 @@
|
|
|
183
187
|
"twoslash": "^0.3.9",
|
|
184
188
|
"typescript": "^7.0.2",
|
|
185
189
|
"vitest": "^5.0.3",
|
|
186
|
-
"xstate": "6.0.0-
|
|
190
|
+
"xstate": "6.0.0-beta.0",
|
|
187
191
|
"zod": "^4.6.5"
|
|
188
192
|
},
|
|
189
193
|
"peerDependencies": {
|
|
@@ -192,7 +196,7 @@
|
|
|
192
196
|
"ai": "*",
|
|
193
197
|
"ajv": "*",
|
|
194
198
|
"openai": "*",
|
|
195
|
-
"xstate": "6.0.0-
|
|
199
|
+
"xstate": "6.0.0-beta.0"
|
|
196
200
|
},
|
|
197
201
|
"peerDependenciesMeta": {
|
|
198
202
|
"@opentelemetry/api": {
|
|
@@ -214,6 +218,9 @@
|
|
|
214
218
|
"engines": {
|
|
215
219
|
"node": ">=22"
|
|
216
220
|
},
|
|
221
|
+
"dependencies": {
|
|
222
|
+
"acorn": "^8.19.0"
|
|
223
|
+
},
|
|
217
224
|
"scripts": {
|
|
218
225
|
"build": "tsdown",
|
|
219
226
|
"demo": "pnpm --filter @statelyai/agent-demo dev",
|
package/readme.md
CHANGED
|
@@ -2,7 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
**Make invalid agent actions impossible.**
|
|
4
4
|
|
|
5
|
-
Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere. The machine owns control flow; the model only ever picks a legal event.
|
|
5
|
+
Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere. The machine owns control flow; the model only ever picks a legal event.
|
|
6
|
+
|
|
7
|
+
What you get:
|
|
8
|
+
|
|
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
|
+
- **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).
|
|
12
|
+
|
|
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).
|
|
6
14
|
|
|
7
15
|
Stately Agent adds model requests and decisions to XState:
|
|
8
16
|
|
|
@@ -10,29 +18,35 @@ Stately Agent adds model requests and decisions to XState:
|
|
|
10
18
|
- Your application chooses the model, runs the requests, and stores the state.
|
|
11
19
|
- The model proposes an event; the machine decides whether it is allowed and what happens next.
|
|
12
20
|
|
|
13
|
-
Environment and policy:
|
|
14
|
-
|
|
15
|
-
- The environment is code you own and can verify; the policy is something a model can write inside it.
|
|
16
|
-
- The environment holds the rules and invariants as TypeScript states and guards, fixed and checked with `canReach`.
|
|
17
|
-
- The policy is a JSON machine a model can author and improve from traces, gated before it runs and promoted only on a measured gain. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md).
|
|
18
|
-
|
|
19
21
|
Stately Agent 2 is in alpha. APIs may change before the stable release.
|
|
20
22
|
|
|
21
23
|
[Documentation](https://stately.ai/docs/packages/agent) · [Examples](https://github.com/statelyai/agent/blob/next/examples/README.md) · [XState](https://github.com/statelyai/xstate)
|
|
22
24
|
|
|
23
|
-
##
|
|
25
|
+
## Starting points
|
|
26
|
+
|
|
27
|
+
### Greenfield: a new agent
|
|
24
28
|
|
|
25
29
|
- **Author a new agent.** Build a machine from states, decisions, and typed requests; run it locally with `runAgent`, test it with no API key, then use it in any framework or runtime with zero machine changes. See the [Quickstart](https://github.com/statelyai/agent/blob/next/docs/quickstart.md) and [Use in any stack](https://github.com/statelyai/agent/blob/next/docs/any-stack.md).
|
|
26
|
-
- **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).
|
|
27
30
|
- **Copy a known pattern.** ReAct, reflection, plan-and-execute, RAG, supervisor, and more, each a single runnable file you lift in 60 seconds. See [Agent patterns](https://github.com/statelyai/agent/blob/next/docs/patterns.md).
|
|
28
|
-
|
|
31
|
+
|
|
32
|
+
### Brownfield: an existing agent
|
|
33
|
+
|
|
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).
|
|
37
|
+
|
|
38
|
+
## Environment and policy
|
|
39
|
+
|
|
40
|
+
- The environment is code you own and can verify; the policy is something a model can write inside it.
|
|
41
|
+
- The environment holds the rules and invariants as TypeScript states and guards, fixed and checked with `canReach`.
|
|
42
|
+
- The policy is a JSON machine a model can author and, experimentally, improve from traces, gated before it runs and promoted only on a measured gain. See [Environment and policy](https://github.com/statelyai/agent/blob/next/docs/environment-and-policy.md).
|
|
29
43
|
|
|
30
44
|
## Install
|
|
31
45
|
|
|
32
46
|
<!-- install command matching the package prerelease channel and package.json peers -->
|
|
33
47
|
|
|
34
48
|
```sh
|
|
35
|
-
pnpm add @statelyai/agent@alpha xstate@6.0.0-
|
|
49
|
+
pnpm add @statelyai/agent@alpha xstate@6.0.0-beta.0 zod
|
|
36
50
|
```
|
|
37
51
|
|
|
38
52
|
XState is pinned while its experimental durable restoration API evolves.
|
|
@@ -61,7 +75,7 @@ Upgrading from an earlier alpha: see [Upgrading between alphas](https://github.c
|
|
|
61
75
|
|
|
62
76
|
Requirements:
|
|
63
77
|
|
|
64
|
-
- Node 22 or newer, and XState exactly `6.0.0-
|
|
78
|
+
- Node 22 or newer, and XState exactly `6.0.0-beta.0`.
|
|
65
79
|
- TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
|
|
66
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.
|
|
67
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`.
|
|
@@ -74,11 +88,11 @@ An app that already uses XState 4 or 5 keeps it: put the agent in its own worksp
|
|
|
74
88
|
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
|
75
89
|
| `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
|
|
76
90
|
| `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
|
|
77
|
-
| `unmet peer dependency "xstate@6.0.0-
|
|
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 |
|
|
78
92
|
|
|
79
93
|
## Agent skills
|
|
80
94
|
|
|
81
|
-
The package ships agent skills in `node_modules/@statelyai/agent/skills
|
|
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/`):
|
|
82
96
|
|
|
83
97
|
```sh
|
|
84
98
|
mkdir -p .claude/skills
|
|
@@ -89,10 +103,11 @@ cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
|
|
|
89
103
|
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
90
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 |
|
|
91
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 |
|
|
92
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` |
|
|
93
108
|
| [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
|
|
94
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 |
|
|
95
|
-
| [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) | Improves a policy from traces
|
|
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 |
|
|
96
111
|
|
|
97
112
|
## Quick start
|
|
98
113
|
|
|
@@ -32,9 +32,11 @@ List:
|
|
|
32
32
|
|
|
33
33
|
- the decision states: an `agent.decide` invoke, a `decision` tag, or a state a host answers with `decideNext`. A machine whose model choice is the output of a text request (a tool call it then checks) has no decision states: eval that choice at the **request** level with `runSeam`;
|
|
34
34
|
- the person's steps: idle states a person answers (`meta.interaction`, the runner's `onIdle`). What the person decides is ground truth, not something to eval; the routing after their answer is a rule;
|
|
35
|
-
- the guards. `describeMachine` shows where a transition function can go and marks it `(conditional)
|
|
35
|
+
- the guards. `describeMachine` shows where a transition function can go and marks it `(conditional)`; `describeMachine(machine, { source: true })` also prints each function, so its guard logic is in the same read;
|
|
36
36
|
- the sentinel states and the final states.
|
|
37
37
|
|
|
38
|
+
**No model decisions.** When the machine has no decision states and its model only picks tools inside one text request (a scheduler, a tool runner), eval two levels: **rule** evals for every guard, cap, and approval rule (an "always allow" rule on both sides of its pattern; the barrier before execute; cancel), and **stats** from traces (`foldTraces` per state, approve/reject counts per tool). Skip decision evals. Add request evals only if a person can label which tool calls were right. The objective is rule violations (0) plus the per-state failure and cost numbers `improve-machine` reads.
|
|
39
|
+
|
|
38
40
|
## 2. Map the request to states
|
|
39
41
|
|
|
40
42
|
Turn the user's words into states. "Evals for the approval logic" means every state and guard that touches approval: the guard that routes a refund over the threshold, the approval step and each answer to it, the sentinel check before the payment, and the final states they lead to. Write the mapping down:
|
|
@@ -35,6 +35,8 @@ export const deskMachine = deskSetup.createMachine({ id: "refund-desk", version:
|
|
|
35
35
|
|
|
36
36
|
Also name the **decider version**: whatever produces the model's answers. It is the policy machine's `version` when there is one. Otherwise it is a label for the model, its settings, and its prompts (`gpt-6-luna.xhigh.p<hash of the prompts>`); this holds for a machine with only text requests too. When the prompts are private to another module (a route file), export a prompt version from that module rather than guessing; a release or commit id is the fallback. In tests it is the stand-in model's name (`careful`). Runs by different deciders must never share a label.
|
|
37
37
|
|
|
38
|
+
**No decider.** A machine with no model decisions (a scheduler, a tool runner whose model only picks tools inside one text request) still stamps a decider version: whatever decides what runs. That is the version of the policy engine or approval rules the guards read (`rules.v4`, a hash of the persisted rules file), plus the request config version when a text request picks tools. Stamp both in `metadata` (`rulesVersion`, `requestVersion`). Thread ids keep the formats below; a non-empty thread resumes with its original stamp, so a run under a changed rule set or request config never resumes an old thread: start a new one (`prod:<domain id>:<rulesVersion>:<requestVersion>`). A version bridge (`docs/persistence.md`) applies only when the machine `version` changes, with the old `events` and a `snapshot`; a changed rule set or request config alone never bridges. A changed rule set must never share a label with the old one. `getDecisionAttempts` is always empty here; record approval verdicts as events so they reach the log.
|
|
39
|
+
|
|
38
40
|
- Every log entry carries `machineVersion`. Without a declared `version` it falls back to a structural hash that skips functions, and in XState v6 the guards and targets live in transition functions. Changing a guard would not change the hash.
|
|
39
41
|
- Bump `version` on every behavior change. Adding recording is not one: it only observes. `improve-machine` bumps the policy's on promotion.
|
|
40
42
|
- A test-only variant built from the same factory (a loosened guard) gets its own `version` (`"1-loose"`), so its runs are never mistaken for the real machine's.
|
|
@@ -44,7 +46,7 @@ Also name the **decider version**: whatever produces the model's answers. It is
|
|
|
44
46
|
- **Tests and local runs:** `createInMemoryEventLogStore()` from `@statelyai/agent/log`, or write each thread's `result.events` to a JSON file after the run.
|
|
45
47
|
- **Production:** implement `AgentEventLogStore` against your database and check it with `assertEventLogStoreConformance`. Implement the optional `listThreads` so a split can be paged by prefix.
|
|
46
48
|
|
|
47
|
-
Pass it with a `threadId`. The store is write-ahead: no model call starts until the entries before it are durable.
|
|
49
|
+
Pass it with a `threadId`. The store is write-ahead: no model call starts until the entries before it are durable. A runner that calls `runAgent` itself (a ported workflow's) takes these as an `options` argument it passes through; add that argument rather than copying the runner.
|
|
48
50
|
|
|
49
51
|
```ts
|
|
50
52
|
const result = await runAgent(deskMachine, { input, executors, store, threadId, metadata });
|
|
@@ -63,6 +65,9 @@ A thread id is how runs are found later. Use a prefix scheme and keep it in one
|
|
|
63
65
|
| ------------------------ | -------------------------------------------- |
|
|
64
66
|
| Scenario runs for evals | `<split>:<deciderVersion>:<scenarioId>:r<k>`, `k` = the repeat index |
|
|
65
67
|
| Production | `prod:<domain id>` (ticket id, session id) |
|
|
68
|
+
| Production, no decider | `prod:<domain id>:<rulesVersion>:<requestVersion>` |
|
|
69
|
+
|
|
70
|
+
With no decider, `<deciderVersion>` in a scenario thread id is `<rulesVersion>.<requestVersion>`.
|
|
66
71
|
|
|
67
72
|
`store.listThreads?.({ prefix: "train:careful:" })` then pages through one split of one decider. `listThreads` is optional on a custom store.
|
|
68
73
|
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: build-machine
|
|
3
|
+
description: Build a new @statelyai/agent machine in TypeScript from a product spec and prove its invariants. Use when asked to build an agent from scratch whose rules need thresholds, counters, caps, spawned fan-out, timers, or any-time events (cancel, takeover, interrupt) — anything the JSON config's truthy-only guards cannot express — and when asked to prove a spec's invariants with canReach or explorePaths.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Build an agent machine
|
|
7
|
+
|
|
8
|
+
The spec's invariants become structure, then proofs. A rule that lives in a prompt is not an invariant.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
invariants → machine → scenario tests → proofs → crash/resume → inspector → hand back
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Use `generate-machine` instead when the whole spec fits a JSON `AgentWorkflowConfig`: truthy guards, no counters, no spawn.
|
|
15
|
+
|
|
16
|
+
## 1. List the invariants
|
|
17
|
+
|
|
18
|
+
Write each spec rule as one sentence a search can falsify: "`book_table` never runs without a `CONFIRM` for its key", "at most 8 model turns". Ask the user for thresholds and caps you cannot read from the spec; decide the mechanics yourself.
|
|
19
|
+
|
|
20
|
+
## 2. Make each one structural
|
|
21
|
+
|
|
22
|
+
| Rule shape | Structure |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| Needs approval first | A waiting state the effect state is entered only from, on the approval event |
|
|
25
|
+
| A cap (turns, retries, rejections) | A counter in `context`, checked inline in the transition that would exceed it |
|
|
26
|
+
| A threshold (confidence ≥ 0.8) | An inline guard in the transition function |
|
|
27
|
+
| Any time (cancel, takeover, interrupt) | A root-level `on` handler targeting a final state, or a state-scoped `on` in every state that must accept it |
|
|
28
|
+
| Wait for all parallel work | Children (`enq.spawn` or parallel invokes) plus a join that counts settled results |
|
|
29
|
+
| Timeout / SLA | An `after` transition |
|
|
30
|
+
| Token budget | A root `on: { '@agent.usage': … }` fold plus a guard |
|
|
31
|
+
|
|
32
|
+
- Write guards inline and keep targets in the transition function, so `describeMachine` can read them.
|
|
33
|
+
- Pass `events` to `setupAgent`, even `events: {}`, so built-in events (`@agent.usage`, `xstate.error.actor`) are typed.
|
|
34
|
+
- A state reachable only when a rule breaks (a sentinel) makes the proof one line. A `canReach` predicate works without one.
|
|
35
|
+
|
|
36
|
+
## 3. Scenario tests
|
|
37
|
+
|
|
38
|
+
At least one test per rule: the happy path, then each failure mode. Fake models with scripted executors or `MockLanguageModelV3` from `ai/test`. Test runtime behavior a search cannot see: an aborted signal reaching the executor, a late model answer after a cancel.
|
|
39
|
+
|
|
40
|
+
## 4. Prove
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { canReach, explorePaths } from "@statelyai/agent/testing";
|
|
44
|
+
|
|
45
|
+
const result = await canReach(machine, (s) => s.matches("writing") && s.context.succeeded < 2, {
|
|
46
|
+
outputs: { plan: [twoQueries, fiveQueries], search: [hits, []] },
|
|
47
|
+
errors: { search: [new Error("down")] },
|
|
48
|
+
interleave: "pending",
|
|
49
|
+
});
|
|
50
|
+
expect(result).toMatchObject({ reachable: false, complete: true });
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- **Fork everything.** List at least two outputs per src, plus `errors`. A src with one output resolves without a fork and never appears in a path.
|
|
54
|
+
- **Any-time rules need `interleave: "pending"`**, so events arrive while work is in flight.
|
|
55
|
+
- **Rules across children** need `children: "coupled"`.
|
|
56
|
+
- **Timers fire** as events, in any order (`timers: "ignore"` turns that off and marks the result incomplete). **Usage** is offered only for root text requests listed in `usage: { src: [{ totalTokens: 500 }] }`; usage inside child machines is test-only.
|
|
57
|
+
- **A machine that reads `output.messages`** needs `textOutput(result, { messages })` from `@statelyai/agent/testing` as the canned output.
|
|
58
|
+
- **`complete: true` or it is not a proof.** Read `unexplored` and `unexpandedEvents` when it is false. Add `payloads` for events with fields, and `dedupeBy` over the context fields guards read when the search explodes.
|
|
59
|
+
- **Long-lived machines never complete.** Every path ends at `maxDepth`. Report a bounded proof: `reachable: false` with only max-depth notes, at a stated depth.
|
|
60
|
+
- **Mutation check.** Weaken each guard in a throwaway copy and confirm the proof finds a witness. A proof that cannot fail proves nothing.
|
|
61
|
+
- Record each rule you could not prove and why. It stays covered by tests only.
|
|
62
|
+
|
|
63
|
+
## 5. Crash and resume
|
|
64
|
+
|
|
65
|
+
Run with a store and a thread id, kill the run mid-flight (throw from an executor, or exit the process), then call `runAgent` again with the same store and `threadId`.
|
|
66
|
+
|
|
67
|
+
- A completed model call never runs again. An in-flight one re-runs with the same `info.callKey`.
|
|
68
|
+
- A plain actor (`createAsyncLogic`) in flight at the crash re-runs. It gets no call key, so derive an idempotency key from the domain (the ticket id, the booking key) and dedupe in the effect.
|
|
69
|
+
- Assert the side-effect ledger, not just the final state: each effect once, same output as an uninterrupted run.
|
|
70
|
+
|
|
71
|
+
## 6. Inspect
|
|
72
|
+
|
|
73
|
+
Run one scenario with `inspect: inspector.inspect` from `@statelyai/sdk`. Each actor registers once and the root's states arrive in order, across `onIdle` passes too. The SDK's `node-relay` needs `ws` installed.
|
|
74
|
+
|
|
75
|
+
## 7. Hand back
|
|
76
|
+
|
|
77
|
+
- The invariant list, each with proved / bounded / test-only and the method.
|
|
78
|
+
- The commands that rerun tests, proofs, and the crash test.
|
|
79
|
+
- What you could not prove and why.
|
|
80
|
+
|
|
81
|
+
Then route to `add-traces` (step 2 of `graph-engineering`).
|
|
@@ -31,7 +31,7 @@ import { describeMachine } from "@statelyai/agent";
|
|
|
31
31
|
const text = describeMachine(machine); // "Machine <id>", then "Goal: …", states, transitions, events
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
Pass `{ snapshot }` to mark the active states with `*`. Concept page: [Environment and policy](
|
|
34
|
+
Pass `{ snapshot }` to mark the active states with `*`. Concept page: [Environment and policy](../../docs/environment-and-policy.md).
|
|
35
35
|
|
|
36
36
|
## 1. Read the schema
|
|
37
37
|
|
|
@@ -9,10 +9,10 @@ Four steps, in order. Each one needs the one before it.
|
|
|
9
9
|
|
|
10
10
|
| Step | Skill | Done when |
|
|
11
11
|
| --- | --- | --- |
|
|
12
|
-
| 1. Make it a state machine | `loop-to-machine` (existing code) or `generate-machine` (from scratch) | Rules are guards and the sentinel is unreachable (`canReach`). From existing code: the parity report has no unreviewed regressions. From scratch: every `verifyAgentConfig` gate passes |
|
|
12
|
+
| 1. Make it a state machine | `loop-to-machine` (existing code), `build-machine` (from scratch, TypeScript), or `generate-machine` (from scratch, when the spec fits JSON) | Rules are guards and the sentinel is unreachable (`canReach`). From existing code: the parity report has no unreviewed regressions. From scratch: every invariant is proved complete or listed as not proved, or every `verifyAgentConfig` gate passes |
|
|
13
13
|
| 2. Add traces | `add-traces` | Every run leaves a stamped log thread that replays to its final state |
|
|
14
14
|
| 3. Add evals | `add-evals` | Evals per state at the cheapest level, an objective, baseline numbers per split |
|
|
15
|
-
| 4. Self-improve | `improve-machine` | A pull request with one policy change and its held-out scorecard, or a report that none helped |
|
|
15
|
+
| 4. Self-improve (experimental) | `improve-machine` | A pull request with one policy change and its held-out scorecard, or a report that none helped |
|
|
16
16
|
|
|
17
17
|
## Find where the project is
|
|
18
18
|
|
|
@@ -21,13 +21,23 @@ Check in this order and start at the first step that is not done:
|
|
|
21
21
|
1. Does the code path production actually runs go through a machine (`setupAgent`, `createMachine`, an `AgentWorkflowConfig`)? Follow the route or entry point to the model call; a machine that nothing calls does not count. If the path is a loop or ad-hoc code, step 1.
|
|
22
22
|
2. Do runs persist to an event log store with a declared machine `version` and a `metadata` stamp? If not, step 2.
|
|
23
23
|
3. Is there an objective over ground truth, and evals that name the states they cover? If not, step 3.
|
|
24
|
-
4. Otherwise, step 4.
|
|
24
|
+
4. Otherwise, step 4, which is experimental: say so when you route there. A machine with no decision point (a tool loop, a scheduler: the model picks tools inside one text request) still goes to step 4: `improve-machine`'s "No decision points" branch, which turns traces into approval-rule, cap, and request-wording proposals.
|
|
25
|
+
|
|
26
|
+
From scratch, pick `build-machine` when a rule needs a threshold, a counter, spawned fan-out, a timer, or an any-time event: the JSON config's guards are truthy-only. Pick `generate-machine` when every rule is a truthy check.
|
|
25
27
|
|
|
26
28
|
Tell the user which step you are starting at and why, in one line, then load that skill.
|
|
27
29
|
|
|
28
30
|
## Across all steps
|
|
29
31
|
|
|
32
|
+
- **XState v6, not v5.** Most training data is v5; v6 differs:
|
|
33
|
+
- A transition is a plain function: `({ context, event }) => ({ target, context })`. There is no `assign`; return the new context.
|
|
34
|
+
- Guards are inline JS in that function. Named guards are optional, not required.
|
|
35
|
+
- Targets are objects (`{ target: "b" }`), never bare strings.
|
|
36
|
+
- Actors: `createAsyncLogic`, not `fromPromise`. Done/error events are `{ type: "xstate.done.actor", actorId, output }` and `{ type: "xstate.error.actor", actorId, error }`.
|
|
37
|
+
- **Keep targets in the transition function.** `describeMachine` parses each function and lists every target it can return. A target from a helper (`=> resolveRound(context)`) or a variable reads as `→ ?`: have the helper return data and pick the target inline. Pass `{ source: true }` to read each function under its line, and `helpers: { name: fn }` for the functions they call by name.
|
|
38
|
+
- **To see what one event does, call `transition`.** It is pure and runs nothing; see [loop-to-machine](../loop-to-machine/SKILL.md#inspect-one-event).
|
|
30
39
|
- **The environment is people's code.** Rules, guards, invariants, and the sentinel change only by human review. No step rewrites them on its own.
|
|
40
|
+
- **No decision point is not a dead end.** Steps 2–4 still apply: traces stamp the request config or approval-rules version, evals are rule checks and per-state stats, and improvement proposes changes for a person to review.
|
|
31
41
|
- **Ground truth scores everything.** Outcomes and effects in the world, labeled by people. A model never grades its own runs.
|
|
32
42
|
- **Ask for labels and rules; decide the mechanics.** Expected outcomes, thresholds, the objective, and the train/held-out split are the user's. File layout, test names, and helper code are yours.
|
|
33
43
|
- **Hand back between steps.** Finish one step's hand-back before starting the next, unless the user asked for several in one go.
|
|
@@ -1,17 +1,19 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: improve-machine
|
|
3
|
-
description: Improve a @statelyai/agent policy machine (a TypeScript setupAgent machine or a JSON AgentWorkflowConfig) from its run traces toward its goal, inside a fixed environment machine, with gates and a held-out promotion rule, and hand the result to a person as a pull request. Use when asked to "improve this agent", "self-improve", "optimize the playbook from traces", "tune the policy", "make the agent cheaper or more accurate", or "why is my agent failing" for a machine whose runs are persisted to an event log store.
|
|
3
|
+
description: Experimental. Improve a @statelyai/agent policy machine (a TypeScript setupAgent machine or a JSON AgentWorkflowConfig) from its run traces toward its goal, inside a fixed environment machine, with gates and a held-out promotion rule, and hand the result to a person as a pull request. Use when asked to "improve this agent", "self-improve", "optimize the playbook from traces", "tune the policy", "make the agent cheaper or more accurate", or "why is my agent failing" for a machine whose runs are persisted to an event log store.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Improve an agent machine
|
|
7
7
|
|
|
8
|
+
> **Experimental:** self-improvement is experimental. The gates are stable, but the round itself may change, and on a loop with no decision point it mostly proposes wording, cap, and approval-rule changes. Code-level causes come back as change requests for a person. Tell the user this skill is experimental before the first round.
|
|
9
|
+
|
|
8
10
|
You improve a **policy**: the machine that decides how the agent works toward its goal, written in TypeScript or as a JSON `AgentWorkflowConfig`. It runs inside an **environment**: a TypeScript machine whose states and guards encode the rules of the world and the business invariants. One round changes the policy once and measures it:
|
|
9
11
|
|
|
10
12
|
```
|
|
11
13
|
locate inputs → read traces → diagnose → propose one diff → gate (≤ 3 repairs) → replay train → replay held-out → recommend or discard → record → pull request
|
|
12
14
|
```
|
|
13
15
|
|
|
14
|
-
This is step 4 of 4, after `loop-to-machine`, `add-traces`, and `add-evals`. To author a JSON policy from scratch, use the `generate-machine` skill. Concept page: [Environment and policy](
|
|
16
|
+
This is step 4 of 4, after `loop-to-machine`, `add-traces`, and `add-evals`. To author a JSON policy from scratch, use the `generate-machine` skill. Concept page: [Environment and policy](../../docs/environment-and-policy.md).
|
|
15
17
|
|
|
16
18
|
## Hard rules
|
|
17
19
|
|
|
@@ -46,6 +48,23 @@ For a TypeScript policy, before the first round:
|
|
|
46
48
|
- **List the environment files** (the environment machine, its guards, the world and its tools) and record a hash of each. Any change to them fails the round. The runner is not one of them, but its diff may contain only the routing line.
|
|
47
49
|
- **Keep the policy a machine.** A diff may add states, `choice` branches, guards over facts, helpers in the policy file, or change a prompt or a model ref. It may not turn the policy into a free function, call tools the environment owns, or import from the environment anything but its schemas, types, constants, and exported guard functions.
|
|
48
50
|
|
|
51
|
+
## No decision points
|
|
52
|
+
|
|
53
|
+
A tool loop or a scheduler has no `agent.decide`: the model picks tools inside one text request and the machine only gates. There is no policy to diff. Traces still drive change, as proposals a person reviews:
|
|
54
|
+
|
|
55
|
+
| Proposal | Evidence from traces | Goes to |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| An approval rule ("always allow `read_file` under `src/`", "always block `rm -rf`") | Approve/reject verdicts grouped by tool and argument pattern, counted from the log's approval events; `foldTraces` rows for the approval state; `traceCoverage` for approval handlers no run exercised (propose nothing for those) | Environment change request |
|
|
58
|
+
| A cap or threshold (retry cap, max steps, batch size) | Runs ending in the cap's failure final, and how close passing runs came to it | Environment change request |
|
|
59
|
+
| Prompt or tool-description wording of the text request | The rounds below, scored by the objective | A versioned request config the improver may edit |
|
|
60
|
+
|
|
61
|
+
- **Approval rules and caps are environment.** Write each as a change request ([reference.md](reference.md)) with the counts, the pattern, and thread ids. Never write a persisted "always allow" rule yourself. Propose a rule only from a pattern with no rejection and no violation in the training runs, and say how many runs it rests on.
|
|
62
|
+
- **The request config is the policy.** Move the request's system prompt and tool descriptions into one file with a `version` (`requests/agent.ts`, or JSON), and stamp that version as the decider version (`add-traces`). The move itself is a one-time environment edit, like the routing line when a policy is first introduced: it changes the request's declaration to import the config and nothing else, it is behavior-preserving (replay the training runs before and after), and it goes in the same pull request as `v0` of the config. Re-record the environment hash after it. From then on, one round changes the config once, through the same rounds, replays, and pull request as a policy.
|
|
63
|
+
- **Gates for a request-config diff:** environment files hash as recorded; the diff changes wording only, never tool names, input schemas, or the offered tool set (that changes the call shape, so it is an environment change); the overfit check; the rule evals from `add-evals` still pass.
|
|
64
|
+
- **Prompt text in code you may not edit** (a TypeScript `private` method or any other method looked up on the instance): install the config by overriding that method on the instance; a native `#private` method cannot be overridden, so it needs an injection point in the code (an environment change request), and make `v0` byte-identical to the old text. Event-log replay does not re-run model calls, so prove it from recorded calls: `checkParity` (or `createRecorder` with `compareRecordings`) between the old method and `v0` must show no `call-args` divergence.
|
|
65
|
+
- **A value lost between states.** `foldTraces` counts visits and outcomes per state, not what context carried. When one state collects most failures, compare the context entering it with what the state before produced. A value dropped on the way is an environment change request, often the biggest win of the round.
|
|
66
|
+
- **Propose, never promote** applies to all three.
|
|
67
|
+
|
|
49
68
|
## 1. Locate the inputs
|
|
50
69
|
|
|
51
70
|
Find all six before changing anything. If one is missing, stop and ask.
|