@statelyai/agent 2.0.0-alpha.37 → 2.0.0-alpha.38
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 +6 -0
- package/dist/index.cjs +5 -5
- package/dist/index.mjs +5 -5
- package/docs/decisions.md +1 -1
- package/docs/event-log.md +1 -1
- package/docs/hosts.md +2 -2
- package/docs/machines-as-data.md +5 -5
- package/docs/persistence.md +5 -5
- package/docs/quickstart.md +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# @statelyai/agent
|
|
2
2
|
|
|
3
|
+
## 2.0.0-alpha.38
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#226](https://github.com/statelyai/agent/pull/226) [`11fe8e7`](https://github.com/statelyai/agent/commit/11fe8e75b7ec3255a41cc9b2460abbbdcac5d572) Thanks [@davidkpiano](https://github.com/davidkpiano)! - `describeMachine` separates descriptions with ` - ` instead of an em dash, so its output is plain ASCII.
|
|
8
|
+
|
|
3
9
|
## 2.0.0-alpha.37
|
|
4
10
|
|
|
5
11
|
### Patch Changes
|
package/dist/index.cjs
CHANGED
|
@@ -686,7 +686,7 @@ function targetsInSource(source, code, choice) {
|
|
|
686
686
|
const conditional = parts.length > 1 || !choice && (read.declines || read.stays);
|
|
687
687
|
return `${parts.join(", ")}${conditional ? " (conditional)" : ""}`;
|
|
688
688
|
}
|
|
689
|
-
/** One transition, as a line: `on GO (human) if context.ready → review; sets draft
|
|
689
|
+
/** One transition, as a line: `on GO (human) if context.ready → review; sets draft - description`. */
|
|
690
690
|
function transitionLine(source, head, transition, options = {}) {
|
|
691
691
|
const code = codeOf(transition);
|
|
692
692
|
let to;
|
|
@@ -715,7 +715,7 @@ function transitionLine(source, head, transition, options = {}) {
|
|
|
715
715
|
to = "?";
|
|
716
716
|
sets = [];
|
|
717
717
|
}
|
|
718
|
-
return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? `
|
|
718
|
+
return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` - ${oneLine(description)}` : ""}`;
|
|
719
719
|
}
|
|
720
720
|
function formatMs(ms) {
|
|
721
721
|
if (ms < 1e3) return `${ms}ms`;
|
|
@@ -779,7 +779,7 @@ function stateLine(node, json) {
|
|
|
779
779
|
const tags = node.tags.length ? ` [tags: ${node.tags.join(", ")}]` : "";
|
|
780
780
|
const interaction = node.meta?.interaction;
|
|
781
781
|
const label = !interaction ? "" : typeof interaction.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : typeof interaction.label === "function" ? " [interaction: computed label]" : " [interaction]";
|
|
782
|
-
const description = node.description ? `
|
|
782
|
+
const description = node.description ? ` - ${oneLine(node.description)}` : "";
|
|
783
783
|
return `${node.key}${marker}${tags}${label}${description}`;
|
|
784
784
|
}
|
|
785
785
|
/** The machine's events with their schema descriptions and fields, sorted by type. */
|
|
@@ -796,13 +796,13 @@ function eventLines(machine) {
|
|
|
796
796
|
}
|
|
797
797
|
const direct = schemas[type].description;
|
|
798
798
|
const description = typeof schema?.description === "string" ? schema.description : typeof direct === "string" ? direct : void 0;
|
|
799
|
-
lines.push(` ${type}${description ? `
|
|
799
|
+
lines.push(` ${type}${description ? ` - ${oneLine(description)}` : ""}`);
|
|
800
800
|
const properties = isObject(schema?.properties) ? schema.properties : {};
|
|
801
801
|
const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
|
|
802
802
|
for (const [field, property] of Object.entries(properties)) {
|
|
803
803
|
if (!isObject(property)) continue;
|
|
804
804
|
const fieldType = Array.isArray(property.enum) ? property.enum.map((value) => JSON.stringify(value)).join(" | ") : Array.isArray(property.type) ? property.type.join(" | ") : typeof property.type === "string" ? property.type : void 0;
|
|
805
|
-
const fieldDescription = typeof property.description === "string" ? `
|
|
805
|
+
const fieldDescription = typeof property.description === "string" ? ` - ${oneLine(property.description)}` : "";
|
|
806
806
|
lines.push(` ${field}${required.has(field) ? "" : "?"}${fieldType ? `: ${fieldType}` : ""}${fieldDescription}`);
|
|
807
807
|
}
|
|
808
808
|
}
|
package/dist/index.mjs
CHANGED
|
@@ -685,7 +685,7 @@ function targetsInSource(source, code, choice) {
|
|
|
685
685
|
const conditional = parts.length > 1 || !choice && (read.declines || read.stays);
|
|
686
686
|
return `${parts.join(", ")}${conditional ? " (conditional)" : ""}`;
|
|
687
687
|
}
|
|
688
|
-
/** One transition, as a line: `on GO (human) if context.ready → review; sets draft
|
|
688
|
+
/** One transition, as a line: `on GO (human) if context.ready → review; sets draft - description`. */
|
|
689
689
|
function transitionLine(source, head, transition, options = {}) {
|
|
690
690
|
const code = codeOf(transition);
|
|
691
691
|
let to;
|
|
@@ -714,7 +714,7 @@ function transitionLine(source, head, transition, options = {}) {
|
|
|
714
714
|
to = "?";
|
|
715
715
|
sets = [];
|
|
716
716
|
}
|
|
717
|
-
return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? `
|
|
717
|
+
return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` - ${oneLine(description)}` : ""}`;
|
|
718
718
|
}
|
|
719
719
|
function formatMs(ms) {
|
|
720
720
|
if (ms < 1e3) return `${ms}ms`;
|
|
@@ -778,7 +778,7 @@ function stateLine(node, json) {
|
|
|
778
778
|
const tags = node.tags.length ? ` [tags: ${node.tags.join(", ")}]` : "";
|
|
779
779
|
const interaction = node.meta?.interaction;
|
|
780
780
|
const label = !interaction ? "" : typeof interaction.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : typeof interaction.label === "function" ? " [interaction: computed label]" : " [interaction]";
|
|
781
|
-
const description = node.description ? `
|
|
781
|
+
const description = node.description ? ` - ${oneLine(node.description)}` : "";
|
|
782
782
|
return `${node.key}${marker}${tags}${label}${description}`;
|
|
783
783
|
}
|
|
784
784
|
/** The machine's events with their schema descriptions and fields, sorted by type. */
|
|
@@ -795,13 +795,13 @@ function eventLines(machine) {
|
|
|
795
795
|
}
|
|
796
796
|
const direct = schemas[type].description;
|
|
797
797
|
const description = typeof schema?.description === "string" ? schema.description : typeof direct === "string" ? direct : void 0;
|
|
798
|
-
lines.push(` ${type}${description ? `
|
|
798
|
+
lines.push(` ${type}${description ? ` - ${oneLine(description)}` : ""}`);
|
|
799
799
|
const properties = isObject(schema?.properties) ? schema.properties : {};
|
|
800
800
|
const required = new Set(Array.isArray(schema?.required) ? schema.required : []);
|
|
801
801
|
for (const [field, property] of Object.entries(properties)) {
|
|
802
802
|
if (!isObject(property)) continue;
|
|
803
803
|
const fieldType = Array.isArray(property.enum) ? property.enum.map((value) => JSON.stringify(value)).join(" | ") : Array.isArray(property.type) ? property.type.join(" | ") : typeof property.type === "string" ? property.type : void 0;
|
|
804
|
-
const fieldDescription = typeof property.description === "string" ? `
|
|
804
|
+
const fieldDescription = typeof property.description === "string" ? ` - ${oneLine(property.description)}` : "";
|
|
805
805
|
lines.push(` ${field}${required.has(field) ? "" : "?"}${fieldType ? `: ${fieldType}` : ""}${fieldDescription}`);
|
|
806
806
|
}
|
|
807
807
|
}
|
package/docs/decisions.md
CHANGED
|
@@ -170,7 +170,7 @@ Retry behavior:
|
|
|
170
170
|
|
|
171
171
|
Core validates and retries. It never calls a model. Coercing the model into choosing exactly one option is the host's responsibility. The shipped AI SDK, OpenAI, and TanStack AI executors offer two modes, set by the `decideMode` option on each adapter:
|
|
172
172
|
|
|
173
|
-
- `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The
|
|
173
|
+
- `'object'` (default for object payloads): one structured-output call. An open choice answers `{ event }`, where `event` is one candidate event, `type` included. Root unions of object payloads become separate event variants. A closed choice answers `{ choice }`, an enum of option ids. The schema allows only one event per answer.
|
|
174
174
|
- `'tool'`: one tool per candidate event under a forced tool choice. Parallel tool calls are turned off where the provider allows it, and an answer that still calls more than one tool is rejected.
|
|
175
175
|
- A function of the request picks the mode per request. Returning `undefined` uses the default: `'object'` when every payload can be represented as object variants, otherwise `'tool'`. This avoids unsupported `allOf` schemas in strict structured-output providers.
|
|
176
176
|
|
package/docs/event-log.md
CHANGED
|
@@ -154,7 +154,7 @@ const { snapshot, persistedSnapshot } = replay(machine, entries);
|
|
|
154
154
|
```
|
|
155
155
|
|
|
156
156
|
- The first entry seeds the fold: `input` folds from `initialTransition`, `snapshot` restores purely and the rest of the log folds onto it.
|
|
157
|
-
- `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log
|
|
157
|
+
- `replay(machine, entries.slice(0, n))` rebuilds the state as of any point in the log, with no side effects.
|
|
158
158
|
- Journaled child sessions are rebound to the sessions the current fold minted, so completions still apply.
|
|
159
159
|
|
|
160
160
|
## Verification
|
package/docs/hosts.md
CHANGED
|
@@ -131,7 +131,7 @@ Decisions follow `decideMode`:
|
|
|
131
131
|
- `'tool'`: one function tool per candidate event, with `tool_choice: 'required'` and `parallel_tool_calls: false`. Function tools are sent with `strict: false`, since the Responses API defaults strict mode on and arbitrary JSON Schema may fall outside it.
|
|
132
132
|
- An answer the adapter cannot read as one event comes back as `rejected`, and the runtime retries it. See [Coercion](decisions.md#coercion).
|
|
133
133
|
|
|
134
|
-
`generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early
|
|
134
|
+
`generateText` runs the tool loop host-side. Each step that comes back with function calls runs the request's tools, appends the calls and one `function_call_output` item per result, and asks again. The replay is stateless: calls go back without their item ids, and reasoning items are left out. An incomplete turn, such as one cut off at `max_output_tokens`, never runs its calls, and an incomplete decision throws instead of choosing. A `failed` response throws on both paths, with its error code and message. The request's `maxSteps` bounds the number of OpenAI calls; the default is one, so a single-step request behaves as before. A tool that throws, a call to a tool the request did not offer, and arguments that are not JSON go back to the model as error results. The loop also ends early when the model calls a client-side tool (one with no `execute`). The call is handed back with `finishReason: 'tool-calls'` and the raw response. Every step's `usage` is summed onto the one result the run aggregates. `modelCalls` reports the steps, and a loop that throws after a step records them on the error, so the run's budget counts them.
|
|
135
135
|
|
|
136
136
|
`toolChoice` maps onto `tool_choice`: `'auto'`, `'none'`, and `'required'` pass through, and `{ type: 'tool', name }` becomes `{ type: 'function', name }`. It is sent on the first step only, so a forced choice cannot re-fire every step and burn the step budget.
|
|
137
137
|
|
|
@@ -411,4 +411,4 @@ const result = await run;
|
|
|
411
411
|
|
|
412
412
|
`provideExecutors(machine, executors)` binds the executors onto the machine so a plain `createActor` runs it, for an application that owns the actor or embeds the agent machine in a larger XState system. See [Advanced](advanced.md).
|
|
413
413
|
|
|
414
|
-
Framework-owned concerns
|
|
414
|
+
Framework-owned concerns (storage, durable execution, retries, queues, and tool-loop interruption recovery) remain with the framework.
|
package/docs/machines-as-data.md
CHANGED
|
@@ -408,9 +408,9 @@ The machine's `description` is its goal, so it leads the text. An excerpt:
|
|
|
408
408
|
Machine ticket
|
|
409
409
|
Goal: Answer the customer's ticket so they never write back.
|
|
410
410
|
States (initial: triaging):
|
|
411
|
-
triaging
|
|
411
|
+
triaging - Decide how to handle the ticket
|
|
412
412
|
on ESCALATE → escalated
|
|
413
|
-
on REPLY → drafting; sets tone
|
|
413
|
+
on REPLY → drafting; sets tone - Draft a reply
|
|
414
414
|
invoke agent.decide
|
|
415
415
|
error → escalated
|
|
416
416
|
checking (choice)
|
|
@@ -418,10 +418,10 @@ States (initial: triaging):
|
|
|
418
418
|
choice if isRetryable → drafting
|
|
419
419
|
choice else → escalated
|
|
420
420
|
sent (final) [tags: done]
|
|
421
|
-
escalated (final)
|
|
421
|
+
escalated (final) - A human owns it now
|
|
422
422
|
Events:
|
|
423
|
-
REPLY
|
|
424
|
-
tone: "formal" | "casual"
|
|
423
|
+
REPLY - Answer the ticket directly
|
|
424
|
+
tone: "formal" | "casual" - Reply tone
|
|
425
425
|
```
|
|
426
426
|
|
|
427
427
|
- **States:** one line each, indented by depth, with the type, tags, `meta.interaction.label`, and description. Pass `snapshot` to mark the active states with `*`.
|
package/docs/persistence.md
CHANGED
|
@@ -4,7 +4,7 @@ The [event log](event-log.md) is the durable artifact. A snapshot is a cache ove
|
|
|
4
4
|
|
|
5
5
|
- The log is an ordered array of the external inputs the machine received. A run is fully reconstructed from it.
|
|
6
6
|
- The persisted snapshot is the machine's serialized state at one point. It lets a resume skip the fold.
|
|
7
|
-
- Live run state
|
|
7
|
+
- Live run state (the actor, in-flight requests, stream chunks) is derived and disposable.
|
|
8
8
|
|
|
9
9
|
## Persist the log
|
|
10
10
|
|
|
@@ -19,7 +19,7 @@ const result = await runToQuiescence(createAgentRuntime(machine, { store, thread
|
|
|
19
19
|
- A rejected write stops the run: `{ status: "error", cause: "journal" }`.
|
|
20
20
|
- `threadId` is required whenever `store` is given.
|
|
21
21
|
|
|
22
|
-
`onEvent` remains the observer seam
|
|
22
|
+
`onEvent` remains the observer seam. It is synchronous and never awaited. Persisting there is at-least-once: a crash between an entry and the host's flush loses it. See [Record a log](event-log.md#record-a-log).
|
|
23
23
|
|
|
24
24
|
`result.events` is a complete, self-contained segment: its first entry is the reserved `@agent.init` entry, so it replays with no side channel.
|
|
25
25
|
|
|
@@ -143,7 +143,7 @@ Run it in CI next to the machine's other tests. It needs no API key.
|
|
|
143
143
|
|
|
144
144
|
## Snapshot as cache
|
|
145
145
|
|
|
146
|
-
`persist()` output carries `agentMeta: { machineId, version, logId, logIndex }
|
|
146
|
+
`persist()` output carries `agentMeta: { machineId, version, logId, logIndex }`: the lineage and position of the log it caches.
|
|
147
147
|
|
|
148
148
|
Pass `snapshot` alongside `events` to skip the fold:
|
|
149
149
|
|
|
@@ -155,13 +155,13 @@ const resumed = await runToQuiescence(createAgentRuntime(machine, { executors })
|
|
|
155
155
|
});
|
|
156
156
|
```
|
|
157
157
|
|
|
158
|
-
- Fast path: `agentMeta.logId` names the log, `logIndex` equals the log length, and the snapshot's state hash matches the tail entry's `verification.stateHash`. Length alone is not enough
|
|
158
|
+
- Fast path: `agentMeta.logId` names the log, `logIndex` equals the log length, and the snapshot's state hash matches the tail entry's `verification.stateHash`. Length alone is not enough, because a fork or a sibling thread can sit at the same index.
|
|
159
159
|
- Otherwise the log is replayed and the run resumes from the replayed state.
|
|
160
160
|
- A cache that disagrees with the state the log replays to throws `AgentSnapshotDivergedError` (code `snapshot-diverged`). Drop the snapshot and resume from `events` alone.
|
|
161
161
|
|
|
162
162
|
A snapshot is never authoritative within a version. Snapshot only at quiescent points: a mid-flight snapshot cannot carry in-flight request state, but the log can.
|
|
163
163
|
|
|
164
|
-
Resuming from a snapshot with no log also yields a self-contained log
|
|
164
|
+
Resuming from a snapshot with no log also yields a self-contained log (the new segment's init entry carries that snapshot), so every result is replayable.
|
|
165
165
|
|
|
166
166
|
## Version bridge
|
|
167
167
|
|
package/docs/quickstart.md
CHANGED
|
@@ -85,7 +85,7 @@ Requests have a semantic `name`, resolved `input`, model reference, schemas,
|
|
|
85
85
|
prompt/messages, and tools. The machine owns control flow; the executor owns
|
|
86
86
|
the provider call.
|
|
87
87
|
|
|
88
|
-
An executor is
|
|
88
|
+
An executor is a function, so the machine runs anywhere a function does.
|
|
89
89
|
When several requests each need their own canned answer, the executor routes on
|
|
90
90
|
`request.name`. See [Evals](evals.md#testing-without-a-provider).
|
|
91
91
|
|
package/package.json
CHANGED