@statelyai/agent 2.0.0-alpha.10 → 2.0.0-alpha.11

package/dist/{text-logic-CZjyACzQ.d.cts → text-logic-Ckhr2kKC.d.cts}

@@ -4,8 +4,6 @@ import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, Mach
 //#region src/events.d.ts
 /** The invoke `src` of an {@link AgentRequest}/{@link AgentDecisionRequest} — a plain string, widened so literal `src` values still narrow in editor hints. */
 type AgentRequestSource = string & {};
-/** Default prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). Override per-request with {@link AgentEventToolNameResolver}. */
-declare const EVENT_TOOL_PREFIX: "send_event_";
 /** Customizes the tool name generated for a candidate event; see {@link AgentRequestOptions.eventToolName}. */
 type AgentEventToolNameResolver = (args: {
   eventType: string;
@@ -648,13 +646,15 @@ type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequ
 /**
  * The full set of host executors a machine's agent actors are resolved
  * with — passed to `runAgent`, `executeAgentRequest`, and
- * `TextLogic.execute`. `generateText` is required; `streamText` is only
- * needed if the machine has a `mode: 'stream'` text request, and `decide`
- * only if it uses a decision — omitting either is a bind-time error when the
- * machine actually needs it (see `runAgent`).
+ * `TextLogic.execute`. Every slot is optional: `generateText` is needed only
+ * if the machine has a `mode: 'generate'` text request, `streamText` only for
+ * a `mode: 'stream'` request, and `decide` only for a decision/plan — omitting
+ * a slot the machine actually needs is a clear bind-time error (see `runAgent`
+ * and `provideExecutors`). Adapter result sets (`AiSdkExecutors`,
+ * `OpenAiCompatExecutors`) re-require all three.
  */
 interface AgentRequestExecutors<TGenerateResult extends AgentRequestExecutorResult = AgentRequestExecutorResult, TStreamResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> {
-  generateText: AgentRequestExecutor<TGenerateResult>;
+  generateText?: AgentRequestExecutor<TGenerateResult>;
   streamText?: AgentRequestExecutor<TStreamResult>;
   decide?: AgentDecisionExecutor;
 }
@@ -707,4 +707,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };
+export { AgentDecisionInput as A, ResolveDecisionOptions as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestOptions as G, resolveDecision as H, DecisionLogic as I, matchesEventPattern as J, AgentRequestSource as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventDescriptor as U, renderDecisionAttempts as V, AgentEventToolNameResolver as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, PlanLogic as z };

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.10",
+  "version": "2.0.0-alpha.11",
   "description": "State-machine authoring layer for AI agents",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
-  "bin": {
-    "statelyai-agent": "dist/cli.mjs"
-  },
   "exports": {
     ".": {
       "import": {
@@ -40,6 +37,26 @@
         "default": "./dist/openai-compat.cjs"
       }
     },
+    "./steps": {
+      "import": {
+        "types": "./dist/steps.d.mts",
+        "default": "./dist/steps.mjs"
+      },
+      "require": {
+        "types": "./dist/steps.d.cts",
+        "default": "./dist/steps.cjs"
+      }
+    },
+    "./adapter": {
+      "import": {
+        "types": "./dist/adapter.d.mts",
+        "default": "./dist/adapter.mjs"
+      },
+      "require": {
+        "types": "./dist/adapter.d.cts",
+        "default": "./dist/adapter.cjs"
+      }
+    },
     "./zod": {
       "import": {
         "types": "./dist/zod.d.mts",
@@ -83,15 +100,20 @@
     "@cloudflare/workers-types": "^4.20260702.1",
     "@inquirer/prompts": "^8.5.2",
     "@statelyai/inspect": "^0.7.2",
+    "@types/express": "^5.0.6",
     "@types/node": "^20.16.10",
+    "@types/react": "^19.2.17",
     "agents": "0.11.5",
     "ai": "^6.0.67",
     "ajv": "^8.20.0",
     "dotenv": "^16.4.5",
+    "express": "^5.2.1",
+    "hono": "^4.12.30",
     "knip": "6.24.0",
     "openai": "^6.45.0",
     "oxfmt": "0.57.0",
     "oxlint": "1.72.0",
+    "react": "^19.2.7",
     "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
     "typescript": "^5.6.2",
@@ -126,6 +148,7 @@
     "format:check": "oxfmt --check src examples",
     "knip": "knip",
     "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run knip",
+    "check:dts": "tsc -p fixtures/dts-consumer/tsconfig.json",
     "test": "vitest",
     "test:ci": "vitest --run",
     "changeset": "changeset",

package/readme.md

@@ -2,25 +2,31 @@
 
 **The logic layer for AI agents.**
 
-Build agents as state machines, with explicit control flow you can inspect, test, visualize, and run anywhere.
+Build agents as state machines to control exactly what the agent can do. The machine owns control flow; the model only ever picks a legal event. Testing, inspection, and visualization fall out for free.
 
 Stately Agent adds model requests and decisions to XState. The state machine defines what the agent can do. Your application chooses the model, runs the requests, and stores the state.
 
-Any agent workflow or loop can be modeled as a state machine. Model calls and tools run as effects inside it. The model proposes an event. The machine decides whether it is allowed and what happens next.
+Any agent workflow or loop can be modeled as a state machine. Model calls and tools run as effects inside it. The model proposes an event. The machine decides whether it is allowed and what happens next. See [how this compares to LangGraph and hand-rolling a loop](docs/comparison.md).
 
 Stately Agent 2 is in alpha. APIs may change before the stable release.
 
 [Documentation](https://stately.ai/docs/agents) · [Examples](examples/README.md) · [XState](https://github.com/statelyai/xstate)
 
+## Three ways to start
+
+- **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 eject to any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Eject to your stack](docs/eject.md).
+- **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 loop](docs/from-a-loop.md).
+- **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](docs/patterns.md).
+
 ## Install
 
 <!-- install command matching the package prerelease channel and package.json peers -->
 
 ```sh
-pnpm add @statelyai/agent@alpha xstate@alpha zod ai @ai-sdk/openai
+pnpm add @statelyai/agent@alpha xstate@alpha zod ai@^6 @ai-sdk/openai@^3
 ```
 
-Node 22.18 or newer is required.
+Node 22.18 or newer is required. The package is ESM-only; the library targets XState v6 alpha and stays compatible with XState v5. Provider packages must match your `ai` major: `@ai-sdk/openai@^3` pairs with `ai@^6` (a bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch the `ai` peer).
 
 ## Quick start
 
@@ -30,15 +36,15 @@ This agent reviews refund requests. The model may propose an automatic refund, b
 
 ```ts
 import { openai } from "@ai-sdk/openai";
-import { defineModels, runAgent } from "@statelyai/agent/ai-sdk";
-import { setupAgent } from "@statelyai/agent";
+import { runAgent, setupAgent } from "@statelyai/agent";
+import { createAiSdkExecutors, defineModels } from "@statelyai/agent/ai-sdk";
 import { z } from "zod";
 
 const models = defineModels({
   fast: openai("gpt-5.4-mini"),
 });
 
-const agent = setupAgent({
+const agentSetup = setupAgent({
   models,
   context: z.object({
     request: z.string(),
@@ -57,7 +63,7 @@ const agent = setupAgent({
   },
 });
 
-const refundMachine = agent.createMachine({
+const refundMachine = agentSetup.createMachine({
   context: ({ input }) => input,
   initial: "deciding",
   states: {
@@ -92,6 +98,7 @@ const result = await runAgent(refundMachine, {
     request: "I was charged twice for the same order.",
     amount: 75,
   },
+  executors: createAiSdkExecutors({ models }),
 });
 
 if (result.status === "done") {
@@ -145,3 +152,6 @@ See [all examples](examples/README.md).
 - [Human in the loop](docs/human-in-the-loop.md)
 - [Testing and verification](docs/verify.md)
 - [Running on different hosts](docs/hosts.md)
+- [Eject to your stack](docs/eject.md)
+- [Agent patterns](docs/patterns.md)
+- [Migrating from a loop](docs/from-a-loop.md)

package/schemas/agent-workflow.json

@@ -6,6 +6,10 @@
   "type": "object",
   "required": ["initial", "states"],
   "properties": {
+    "$schema": {
+      "description": "JSON Schema reference an editor attaches to the config file. Ignored by the lowering.",
+      "type": "string"
+    },
     "key": {
       "description": "Stable workflow key used by tools, storage, and visual editors.",
       "type": "string",
@@ -23,11 +27,6 @@
     "description": {
       "type": "string"
     },
-    "queryLanguage": {
-      "description": "Expression language used inside {{ }} expressions. The built-in setupAgent.fromConfig lowering currently supports simple dot-path expressions over input, context, and event.",
-      "type": "string",
-      "default": "path"
-    },
     "schemas": {
       "$ref": "#/$defs/AgentSchemas"
     },

package/dist/cli.cjs

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-const require_run_agent = require("./run-agent-BFMkuI1F.cjs");
-const require_src = require("./src-D-77Ha5p.cjs");
-let node_fs = require("node:fs");
-//#region src/cli.ts
-/**
-* `statelyai-agent lint <workflow.json>` — keyless static verification for an
-* agent machine authored as data (an {@link AgentWorkflowConfig} JSON file).
-*
-* The library bundles no JSON Schema engine, so the CLI lints STRUCTURE ONLY:
-* it compiles the config with a permissive pass-through schema compiler (each
-* JSON Schema is kept as-is for structural checks, validation is a no-op) and
-* runs {@link lintAgentMachine}. Exits `1` on any error-severity finding.
-*
-* For full schema-aware linting, import the API and compile with a real engine:
-* `lintAgentMachine(setupAgent.fromConfig(config, { compileSchema }))`.
-*
-* @module
-*/
-function stubCompileSchema(jsonSchema) {
-	return { "~standard": {
-		version: 1,
-		vendor: "statelyai-agent-cli",
-		validate: (value) => ({ value }),
-		jsonSchema: { input: () => jsonSchema }
-	} };
-}
-function printUsage() {
-	process.stderr.write("Usage: statelyai-agent lint <workflow.json> [--no-schemas]\n\n  Statically verifies an agent-machine JSON config (structure-only).\n  Exits 1 on any error-severity finding.\n");
-}
-function main(argv) {
-	const args = argv.slice(2);
-	const command = args[0];
-	const file = args.find((arg, index) => index > 0 && !arg.startsWith("-"));
-	if (command !== "lint" || !file) {
-		printUsage();
-		return 2;
-	}
-	let config;
-	try {
-		config = JSON.parse((0, node_fs.readFileSync)(file, "utf8"));
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: could not read/parse '${file}': ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	let machine;
-	try {
-		machine = require_run_agent.setupAgent.fromConfig(config, { compileSchema: stubCompileSchema });
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: '${file}' is not a valid agent-machine config: ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	const diagnostics = require_src.lintAgentMachine(machine);
-	const errors = diagnostics.filter((d) => d.severity === "error");
-	const warnings = diagnostics.filter((d) => d.severity === "warning");
-	for (const d of diagnostics) {
-		const label = d.severity === "error" ? "error" : "warn ";
-		process.stdout.write(`  ${label}  ${d.code}  ${d.path}\n         ${d.message}\n`);
-	}
-	process.stdout.write(`\n${file}: ${errors.length} error(s), ${warnings.length} warning(s) (structure-only; schemas not compiled).\n`);
-	return errors.length > 0 ? 1 : 0;
-}
-process.exit(main(process.argv));
-//#endregion

package/dist/cli.d.cts

@@ -1 +0,0 @@
-export { };

package/dist/cli.d.mts

@@ -1 +0,0 @@
-export { };

package/dist/cli.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-import { c as setupAgent } from "./run-agent-BoAOq_0Z.mjs";
-import { a as lintAgentMachine } from "./src-DUeIFjv-.mjs";
-import { readFileSync } from "node:fs";
-//#region src/cli.ts
-/**
-* `statelyai-agent lint <workflow.json>` — keyless static verification for an
-* agent machine authored as data (an {@link AgentWorkflowConfig} JSON file).
-*
-* The library bundles no JSON Schema engine, so the CLI lints STRUCTURE ONLY:
-* it compiles the config with a permissive pass-through schema compiler (each
-* JSON Schema is kept as-is for structural checks, validation is a no-op) and
-* runs {@link lintAgentMachine}. Exits `1` on any error-severity finding.
-*
-* For full schema-aware linting, import the API and compile with a real engine:
-* `lintAgentMachine(setupAgent.fromConfig(config, { compileSchema }))`.
-*
-* @module
-*/
-function stubCompileSchema(jsonSchema) {
-	return { "~standard": {
-		version: 1,
-		vendor: "statelyai-agent-cli",
-		validate: (value) => ({ value }),
-		jsonSchema: { input: () => jsonSchema }
-	} };
-}
-function printUsage() {
-	process.stderr.write("Usage: statelyai-agent lint <workflow.json> [--no-schemas]\n\n  Statically verifies an agent-machine JSON config (structure-only).\n  Exits 1 on any error-severity finding.\n");
-}
-function main(argv) {
-	const args = argv.slice(2);
-	const command = args[0];
-	const file = args.find((arg, index) => index > 0 && !arg.startsWith("-"));
-	if (command !== "lint" || !file) {
-		printUsage();
-		return 2;
-	}
-	let config;
-	try {
-		config = JSON.parse(readFileSync(file, "utf8"));
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: could not read/parse '${file}': ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	let machine;
-	try {
-		machine = setupAgent.fromConfig(config, { compileSchema: stubCompileSchema });
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: '${file}' is not a valid agent-machine config: ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	const diagnostics = lintAgentMachine(machine);
-	const errors = diagnostics.filter((d) => d.severity === "error");
-	const warnings = diagnostics.filter((d) => d.severity === "warning");
-	for (const d of diagnostics) {
-		const label = d.severity === "error" ? "error" : "warn ";
-		process.stdout.write(`  ${label}  ${d.code}  ${d.path}\n         ${d.message}\n`);
-	}
-	process.stdout.write(`\n${file}: ${errors.length} error(s), ${warnings.length} warning(s) (structure-only; schemas not compiled).\n`);
-	return errors.length > 0 ? 1 : 0;
-}
-process.exit(main(process.argv));
-//#endregion
-export {};