@statelyai/agent 2.0.0-alpha.23 → 2.0.0-alpha.25

package/dist/utils-RalRn9sk.d.cts

@@ -0,0 +1,209 @@
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-B1Qs2q3q.cjs";
+import { M as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BFEOxyxv.cjs";
+import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
+
+//#region src/scripted-executors.d.ts
+/**
+ * A scripted `decide` answer: either the {@link ChosenEvent} itself (an object
+ * with a string `type`), or the executor result `{ event, reason?, usage? }`
+ * when the entry also reports a `reason` or token `usage`.
+ */
+type ScriptedDecisionValue = ChosenEvent | {
+  event: ChosenEvent;
+  reason?: string;
+  usage?: AgentCallUsage;
+};
+/**
+ * One scripted `decide` answer, or a function of the
+ * {@link AgentDecisionRequest} returning one (for choices that depend on the
+ * prompt, the candidate `events`, or the prior failed `attempts`).
+ */
+type ScriptedDecisionEntry = ScriptedDecisionValue | ((request: AgentDecisionRequest) => ScriptedDecisionValue | PromiseLike<ScriptedDecisionValue>);
+/**
+ * One scripted text answer: the request's output value (a string, or the
+ * object a structured request declares), or a function of the
+ * {@link AgentTextRequest} returning one.
+ *
+ * An entry is taken as the executor result (instead of the value itself)
+ * only when its OWN keys are a `result` plus, optionally, `messages`/`usage`/
+ * `raw` — that is how an entry reports token `usage`. Anything else, including
+ * an object that merely happens to have a `result` key alongside its own data
+ * (`{ result: 'draft', confidence: 0.9 }`), is the output value. For a
+ * structured request whose declared output is exactly `{ result }` (or
+ * `{ result, usage }`), wrap it once more: `{ result: { result: '…' } }`.
+ */
+type ScriptedTextEntry = ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => unknown) | string | number | boolean | null | object;
+/**
+ * A request-name keyed script. The key is the request's resolved `name` — the
+ * authored name, else the invoke `id`. `"*"` is the fallback route.
+ */
+type ScriptedByName<TEntry> = Record<string, TEntry | TEntry[]>;
+/** One scripted stream call: chunks, or a function producing chunks. */
+type ScriptedStreamEntry = string | readonly string[] | ((request: AgentTextRequest, info?: AgentRequestExecutorInfo) => string | readonly string[] | PromiseLike<string | readonly string[]>);
+/** A call observed by {@link createScriptedExecutors}. */
+interface ScriptedExecutorCall {
+  kind: "generateText" | "streamText" | "decide";
+  name: string;
+  input: unknown;
+  request: AgentTextRequest | AgentDecisionRequest;
+}
+/**
+ * The script {@link createScriptedExecutors} plays back. Every channel is
+ * keyed by request name and consumed in order; the last entry for a name
+ * repeats forever.
+ */
+interface ScriptedExecutorsScript {
+  /** Answers for `decide` requests, keyed by request name. */
+  decisions?: ScriptedByName<ScriptedDecisionEntry>;
+  /** Answers for generate requests, keyed by request name. */
+  text?: ScriptedByName<ScriptedTextEntry>;
+  /** Stream chunks keyed by request name. */
+  stream?: Record<string, ScriptedStreamEntry>;
+  /** Default usage attached when an entry does not provide its own. */
+  usage?: AgentCallUsage;
+}
+/** What {@link createScriptedExecutors} returns: the full executor set plus the calls it observed. */
+type ScriptedExecutors = Required<AgentRequestExecutors> & {
+  calls: ScriptedExecutorCall[];
+};
+/**
+ * Executors that replay a script instead of calling a model. Every slot is
+ * provided, so any machine binds.
+ *
+ * Answers are keyed by the request's resolved name — its authored `name`, else
+ * the invoke `id` — and `"*"` serves anything unmatched.
+ * Entries for a name are consumed in order and the last one repeats forever, so
+ * a looping machine needs no extra option. A request the script has no route
+ * for throws an ordinary `Error` from inside the executor, which reaches the
+ * machine as an actor error.
+ *
+ * Queues are copied on creation, so the caller's arrays are never mutated and
+ * each call builds a fresh, independent playthrough. Entries may be plain
+ * values or functions of the request.
+ *
+ * @example
+ * ```ts
+ * const result = await runAgent(moderationMachine, {
+ *   input: { comment: 'honestly this update is terrible', trust: 20 },
+ *   executors: createScriptedExecutors({
+ *     decisions: { moderate: [{ type: 'FLAG', reason: 'Borderline tone.' }] },
+ *   }),
+ * });
+ * ```
+ *
+ * @example Dynamic entries
+ * ```ts
+ * createScriptedExecutors({
+ *   text: { draft: (request) => `Draft about ${request.prompt}` },
+ *   decisions: { route: (request) => ({ type: request.events[0]!.type }) },
+ * });
+ * ```
+ */
+declare function createScriptedExecutors(script?: ScriptedExecutorsScript): ScriptedExecutors;
+//#endregion
+//#region src/utils.d.ts
+/** Returns the human-readable text carried by a message, ignoring non-text parts. */
+declare function getMessageText(message: AgentMessage): string;
+/**
+ * A stable, dependency-free structural fingerprint of a machine — a short hex
+ * `djb2` hash over its **structural** config only: state ids/nesting, transition
+ * event types and targets, invoke `src`s, `initial`, and any other serializable
+ * config fields. Function values (context/output builders, prompts, inline
+ * guards/actions) are excluded entirely, so two machines that differ only in
+ * their prompts or executors hash identically; adding/removing/retargeting a
+ * state or transition changes the hash.
+ *
+ * Used by {@link runAgent} to stamp settled snapshots with a `version` and to
+ * detect a structurally-edited machine on resume. It is a change detector, not
+ * a cryptographic digest — collisions are possible but unlikely for real
+ * configs. Declare `createMachine({ version })` to pin an explicit version instead.
+ */
+declare function getMachineStructuralHash(machine: AnyStateMachine): string;
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+declare function userMessage(content: string | Array<TextPart | ImagePart | FilePart>): UserMessage;
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+declare function assistantMessage(content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>): AssistantMessage;
+/** Builds a {@link SystemMessage}. */
+declare function systemMessage(content: string): SystemMessage;
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+declare function toolMessage(content: Array<ToolResultPart>): ToolMessage;
+type MetaOfSnapshot<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+}> = NonNullable<ReturnType<TSnapshot["getMeta"]>[keyof ReturnType<TSnapshot["getMeta"]>]>;
+/**
+ * Returns the merged `meta` of a snapshot's active state(s) — the typed
+ * replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+ *
+ * `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+ * state, but parallel/nested machines can have several. This shallow-merges
+ * every active state's meta into one object and returns `{}` when no active
+ * state declares meta.
+ *
+ * Merge order is fixed and does not depend on XState's internal node order:
+ * entries are sorted by structural depth (the state node's distance from the
+ * root, regardless of custom `id` strings), then by state id lexicographically,
+ * and merged in that order. So a deeper state's key wins over an ancestor's,
+ * and between equal-depth parallel siblings the later state id alphabetically
+ * wins.
+ *
+ * The return type is recovered from the snapshot's own `getMeta()` type, so a
+ * schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+ * output type. Pass an explicit `TMeta` to override when the snapshot is
+ * untyped (e.g. `AnyMachineSnapshot`).
+ *
+ * @example HITL: read the current state's interaction protocol off an idle
+ * snapshot to render for a human.
+ * ```ts
+ * const { interaction } = getStateMeta(result.snapshot);
+ * ```
+ */
+declare function getStateMeta<TSnapshot extends {
+  getMeta(): Record<string, unknown>;
+} = AnyMachineSnapshot, TMeta = MetaOfSnapshot<TSnapshot>>(snapshot: TSnapshot): Partial<TMeta>;
+/**
+ * Renders a snapshot's state value as one deterministic string, so a log line,
+ * a progress field, or a test assertion reads the same on every run.
+ *
+ * - An atomic state is its own name: `'writing'`.
+ * - A nested state joins with dots: `{ review: { editing: 'draft' } }` →
+ *   `'review.editing.draft'`.
+ * - A parallel state brackets its regions, sorted by region name, so key order
+ *   never leaks into the string: `{ p: { left: 'x', right: { a: 'b' } } }` →
+ *   `'p:{left.x,right.a.b}'`.
+ *
+ * Prefer this over `String(snapshot.value)`, which renders every non-atomic
+ * value as `[object Object]`.
+ *
+ * @example
+ * ```ts
+ * onTransition: (snapshot) => console.log(getStatePath(snapshot));
+ * ```
+ */
+declare function getStatePath(snapshot: {
+  value: StateValue;
+  status?: string;
+} | StateValue): string;
+/**
+ * Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+ * the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+ * (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+ * can't read directly — see the `ai-sdk` tool pass-through.
+ */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/**
+ * Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+ * `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+ * `z.toJSONSchema`), awaiting it when the producer is async. Returns
+ * `undefined` when the schema doesn't expose the extension. Use this to build
+ * a provider request's `response_format`/tool `parameters` from a schema.
+ */
+declare function getJsonSchema(schema?: StandardSchemaV1): Promise<Record<string, unknown> | undefined>;
+/**
+ * Synchronous variant of {@link getJsonSchema}, for call sites that can't
+ * await (building tool/event descriptors inline). An async JSON Schema
+ * producer is treated as absent (returns `undefined`) — in practice Zod's
+ * `z.toJSONSchema` resolves synchronously.
+ */
+declare function getJsonSchemaSync(schema?: StandardSchemaV1): Record<string, unknown> | undefined;
+//#endregion
+export { ScriptedExecutorsScript as _, getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, ScriptedExecutors as g, ScriptedDecisionValue as h, getJsonSchemaSync as i, isStandardSchema as l, ScriptedDecisionEntry as m, assistantMessage as n, getMessageText as o, ScriptedByName as p, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u, ScriptedTextEntry as v, createScriptedExecutors as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.23",
+  "version": "2.0.0-alpha.25",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",
@@ -48,6 +48,16 @@
         "default": "./dist/ai-sdk.cjs"
       }
     },
+    "./log": {
+      "import": {
+        "types": "./dist/log.d.mts",
+        "default": "./dist/log.mjs"
+      },
+      "require": {
+        "types": "./dist/log.d.cts",
+        "default": "./dist/log.cjs"
+      }
+    },
     "./machines": {
       "import": {
         "types": "./dist/machines.d.mts",
@@ -78,6 +88,16 @@
         "default": "./dist/otel.cjs"
       }
     },
+    "./testing": {
+      "import": {
+        "types": "./dist/testing.d.mts",
+        "default": "./dist/testing.mjs"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
+    },
     "./validate": {
       "import": {
         "types": "./dist/validate.d.mts",
@@ -123,7 +143,7 @@
     "typescript": "^5.9.3",
     "valibot": "^1.4.2",
     "vitest": "^4.1.11",
-    "xstate": "6.0.0-alpha.48",
+    "xstate": "6.0.0-alpha.57",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -131,7 +151,7 @@
     "ai": "^7.0.0",
     "ajv": "^8.20.0",
     "openai": ">=5.0.0 <8",
-    "xstate": ">=6.0.0-alpha.46 <6.0.0"
+    "xstate": ">=6.0.0-alpha.57 <6.0.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -168,7 +188,7 @@
     "check:dts": "tsc -p fixtures/dts-consumer/tsconfig.json",
     "test": "vitest",
     "test:live": "LIVE_TESTS=1 vitest --run",
-    "test:ci": "vitest --run && pnpm run test:cloudflare && pnpm run build && pnpm --filter @statelyai/agent-demo test",
+    "test:ci": "vitest --run && pnpm run build && pnpm run test:cloudflare && pnpm --filter @statelyai/agent-demo test",
     "changeset": "changeset",
     "release": "changeset publish",
     "version": "changeset version"

package/readme.md

@@ -139,9 +139,9 @@ const liveResult = await runAgent(refundMachine, {
 });
 ```
 
-For a machine with several requests, `createScriptedExecutors` holds ordered answers keyed by request name. See [Evals](docs/evals.md#scripted-executors).
+For a machine with several requests, `createScriptedExecutors` from `@statelyai/agent/testing` holds ordered answers keyed by request name. See [Evals](docs/evals.md#scripted-executors).
 
-Passing a `defineModels` registry to `setupAgent({ models })` types the machine's model refs and supplies the AI SDK executor by default; explicit `executors` override it. Core does not import the AI SDK. See [Hosts and executors](docs/hosts.md).
+Passing the same `models` map to `setupAgent({ models })` types the machine's model refs. Executors are always explicit, and core does not import the AI SDK. See [Hosts and executors](docs/hosts.md).
 
 ## Architecture
 

package/skills/generate-machine/SKILL.md

@@ -27,7 +27,7 @@ Rules the runtime enforces. Each one maps to a build error or a lint diagnostic:
 - A model call is either a named `requests` entry invoked with `src: "<requestName>"`, or an inline invoke with `src: "agent.decide"` plus an `allowedEvents` list.
 - A state invoking `agent.decide` MUST handle every allowed event in its `on`.
 - An `agent.decide` invoke has no `onDone` (a decision produces no output). Use `onError` for the retries-exhausted path.
-- A request invoke reads its result via `onDone.assign` from `"{{ event.output.<field> }}"`.
+- A request invoke resolves with `{ result, messages }`, so `onDone.assign` reads its result from `"{{ event.output.result.<field> }}"` (`"{{ event.output.result }}"` for a plain-text request). A non-request `actors` invoke reads `"{{ event.output.<field> }}"` directly.
 - Every path must reach a `"type": "final"` state, and each final state needs an `output` when `schemas.output` is declared.
 - Do not invent guard or action names. Only `"{{ }}"` guards, `assign`, and `emit` exist unless the host tells you which named guards/actions it implements.
 - Model refs are strings (`"openai/gpt-5.4-mini"`); the host resolves them.
@@ -113,7 +113,7 @@ Reference config — decision, text request, idle human step, one final state:
         "input": { "ticket": "{{ context.ticket }}" },
         "onDone": {
           "target": "awaitingApproval",
-          "assign": { "reply": "{{ event.output.reply }}" }
+          "assign": { "reply": "{{ event.output.result.reply }}" }
         }
       }
     },
@@ -191,8 +191,7 @@ Lowering is itself a gate: it throws on an unresolved named guard/action and on
 ## 5. Lint
 
 ```ts
-import { lintAgentMachine } from "@statelyai/agent";
-
+import { lintAgentMachine } from "@statelyai/agent/testing";
 const diagnostics = lintAgentMachine(machine);
 lintAgentMachine(machine, { throw: true }); // throws AgentLintError on error-severity findings
 ```
@@ -206,8 +205,7 @@ The one that bites most often is `decide-without-events`: an `allowedEvents` lis
 Lint is structural. A dry run proves a path actually settles. No API key needed.
 
 ```ts
-import { simulateAgent } from "@statelyai/agent";
-
+import { simulateAgent } from "@statelyai/agent/testing";
 const dryRun = await simulateAgent(machine, {
   input: { ticket: "" },
   script: {