@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/utils-ceStNCOh.d.cts

@@ -0,0 +1,109 @@
+import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, b as ToolCallPart, f as FilePart, l as AssistantMessage, n as AgentMessage, p as ImagePart, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-B1Qs2q3q.cjs";
+import { AnyMachineSnapshot, AnyStateMachine, StateValue } from "xstate";
+
+//#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 { getMachineStructuralHash as a, getStatePath as c, toolMessage as d, userMessage as f, getJsonSchemaSync as i, isStandardSchema as l, assistantMessage as n, getMessageText as o, getJsonSchema as r, getStateMeta as s, MetaOfSnapshot as t, systemMessage as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.24",
+  "version": "2.0.0-alpha.26",
   "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",
@@ -95,6 +115,7 @@
   },
   "devDependencies": {
     "@ai-sdk/openai": "^4.0.0",
+    "@ai-sdk/typesafe-ai": "3.0.6",
     "@anthropic-ai/sdk": "^0.120.0",
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.31.1",
@@ -108,7 +129,7 @@
     "@opentelemetry/sdk-trace-base": "^2.10.0",
     "@types/node": "^20.19.43",
     "@types/react": "^19.2.18",
-    "ai": "^7.0.0",
+    "ai": "^7.0.113",
     "ajv": "^8.20.0",
     "braintrust": "^3.28.0",
     "dotenv": "^16.6.1",
@@ -123,7 +144,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 +152,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 +189,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

@@ -40,6 +40,8 @@ For the optional raw OpenAI SDK executor (`@statelyai/agent/openai`):
 pnpm add openai
 ```
 
+Classification, grading, relevance, and yes/no checks are judgments: call the AI SDK's `experimental_evaluate` with `@ai-sdk/typesafe-ai` (`pnpm add ai @ai-sdk/typesafe-ai`) from an ordinary actor; see [Judgments with the AI SDK](docs/judgments.md).
+
 Requirements:
 
 - Node 22.18 or newer, and XState v6 alpha.46 or newer.
@@ -139,9 +141,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, the executor routes on `request.name`, or `MockLanguageModelV3` from `ai/test` stands in for the provider behind `createAiSdkExecutors`. See [Evals](docs/evals.md#testing-without-a-provider).
 
-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
 
@@ -155,7 +157,7 @@ flowchart LR
   R -->|event or output| M
 ```
 
-The machine never talks to a model directly, so swapping `createAiSdkExecutors` for `createScriptedExecutors` (or your own functions) changes nothing about the agent.
+The machine never talks to a model directly, so swapping `createAiSdkExecutors` for your own functions changes nothing about the agent.
 
 The example above has one model decision and two final outcomes. Real machines add approval states, retries, parallel work, child agents, and long-running waits without changing how control flow is represented.
 

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: {