@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 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 — description`. */
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 ? ` — ${oneLine(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 ? ` — ${oneLine(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 ? ` — ${oneLine(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" ? ` — ${oneLine(property.description)}` : "";
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 — description`. */
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 ? ` — ${oneLine(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 ? ` — ${oneLine(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 ? ` — ${oneLine(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" ? ` — ${oneLine(property.description)}` : "";
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 answer holds one event by construction.
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 — time travel with no side effects.
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 on a tool with no `execute` — a client-side tool, whose 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.
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—storage, durable execution, retries, queues, and tool-loop interruption recovery—remain with the framework.
414
+ Framework-owned concerns (storage, durable execution, retries, queues, and tool-loop interruption recovery) remain with the framework.
@@ -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 — Decide how to handle the ticket
411
+ triaging - Decide how to handle the ticket
412
412
  on ESCALATE → escalated
413
- on REPLY → drafting; sets tone — Draft a reply
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) — A human owns it now
421
+ escalated (final) - A human owns it now
422
422
  Events:
423
- REPLY — Answer the ticket directly
424
- tone: "formal" | "casual" — Reply tone
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 `*`.
@@ -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 — the actor, in-flight requests, stream chunks — is derived and disposable.
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 — synchronous, 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).
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 }` — the lineage and position of the log it caches.
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 — a fork or a sibling thread can sit at the same index.
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 — the new segment's init entry carries that snapshot — so every result is replayable.
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
 
@@ -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 just a function, so the machine runs anywhere a function does.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statelyai/agent",
3
- "version": "2.0.0-alpha.37",
3
+ "version": "2.0.0-alpha.38",
4
4
  "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
5
5
  "keywords": [
6
6
  "agent",