@statelyai/agent 2.0.0-alpha.15 → 2.0.0-alpha.16

package/dist/{types-DFD28AWe.d.cts → types-DYpK3QF4.d.mts}

@@ -184,13 +184,14 @@ type ToolMessage = {
  */
 type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
 /**
- * A schema value on an {@link AgentToolDescriptor}. Core reads it as a
- * {@link StandardSchemaV1} (via `getJsonSchema`/`isStandardSchema`) when it can,
- * but the type is deliberately widened with `object` so an SDK-native tool —
- * whose `inputSchema` is the SDK's own union type (a Zod schema, the SDK's
- * `Schema`, a lazy thunk, …) — assigns structurally with no cast.
+ * A schema value on an {@link AgentToolDescriptor}: deliberately just `object`,
+ * because an SDK-native tool's `inputSchema` is the SDK's own union type (a Zod
+ * schema, the SDK's `Schema`, a lazy thunk, ...) and must assign structurally
+ * with no cast. The contract is runtime, not static: core narrows with
+ * `isStandardSchema` and reads {@link StandardSchemaV1} schemas via
+ * `getJsonSchema`; anything else passes through to the executor untouched.
  */
-type AgentToolSchema = StandardSchemaV1 | object;
+type AgentToolSchema = object;
 /**
  * A tool exposed to a text request, described for both the model and
  * (optionally) host execution. This is a **minimal structural contract**: any

package/dist/{types-CTBhMnFu.d.mts → types-pJ5Hn8fv.d.cts}

@@ -184,13 +184,14 @@ type ToolMessage = {
  */
 type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
 /**
- * A schema value on an {@link AgentToolDescriptor}. Core reads it as a
- * {@link StandardSchemaV1} (via `getJsonSchema`/`isStandardSchema`) when it can,
- * but the type is deliberately widened with `object` so an SDK-native tool —
- * whose `inputSchema` is the SDK's own union type (a Zod schema, the SDK's
- * `Schema`, a lazy thunk, …) — assigns structurally with no cast.
+ * A schema value on an {@link AgentToolDescriptor}: deliberately just `object`,
+ * because an SDK-native tool's `inputSchema` is the SDK's own union type (a Zod
+ * schema, the SDK's `Schema`, a lazy thunk, ...) and must assign structurally
+ * with no cast. The contract is runtime, not static: core narrows with
+ * `isStandardSchema` and reads {@link StandardSchemaV1} schemas via
+ * `getJsonSchema`; anything else passes through to the executor untouched.
  */
-type AgentToolSchema = StandardSchemaV1 | object;
+type AgentToolSchema = object;
 /**
  * A tool exposed to a text request, described for both the model and
  * (optionally) host execution. This is a **minimal structural contract**: any

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.15",
+  "version": "2.0.0-alpha.16",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
+  "keywords": [
+    "agent",
+    "ai",
+    "state machine",
+    "statechart"
+  ],
+  "homepage": "https://github.com/statelyai/agent#readme",
+  "bugs": {
+    "url": "https://github.com/statelyai/agent/issues"
+  },
+  "license": "MIT",
+  "author": "David Khourshid <david@stately.ai>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statelyai/agent.git"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "skills"
+  ],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -59,29 +80,8 @@
     },
     "./agent-workflow.json": "./schemas/agent-workflow.json"
   },
-  "files": [
-    "dist",
-    "schemas",
-    "skills"
-  ],
-  "keywords": [
-    "ai",
-    "state machine",
-    "agent",
-    "statechart"
-  ],
-  "author": "David Khourshid <david@stately.ai>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/statelyai/agent.git"
-  },
-  "homepage": "https://github.com/statelyai/agent#readme",
-  "bugs": {
-    "url": "https://github.com/statelyai/agent/issues"
-  },
-  "engines": {
-    "node": ">=22.18.0"
+  "publishConfig": {
+    "access": "public"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.25",
@@ -124,9 +124,6 @@
     "xstate": "6.0.0-alpha.25",
     "zod": "^4.3.6"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "peerDependencies": {
     "@opentelemetry/api": "^1",
     "ai": "^6.0.67",
@@ -140,6 +137,9 @@
       "optional": true
     }
   },
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "scripts": {
     "build": "tsdown",
     "demo": "pnpm --filter @statelyai/agent-demo dev",
@@ -148,7 +148,7 @@
     "typecheck": "pnpm run typecheck:src && pnpm run typecheck:examples && pnpm run typecheck:example-packages",
     "typecheck:src": "tsc --noEmit",
     "typecheck:examples": "tsc -p examples/tsconfig.json --noEmit",
-    "typecheck:example-packages": "tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-start-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit",
+    "typecheck:example-packages": "pnpm run build && tsc -p examples/next-host --noEmit && tsc -p examples/tanstack-start-host --noEmit && tsc -p examples/tanstack-ai-stream --noEmit && tsc -p examples/cloudflare-agent-host --noEmit && tsc -p examples/cloudflare-workers-ai-host --noEmit",
     "test:cloudflare": "pnpm --filter @statelyai/example-cloudflare-agent-host test && pnpm --filter @statelyai/example-cloudflare-workers-ai-host test",
     "lint": "oxlint",
     "format": "oxfmt src examples",

package/readme.md

@@ -17,7 +17,7 @@ Stately Agent 2 is in alpha. APIs may change before the stable release.
 ## Three starting points
 
 - **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 use it in any framework or runtime with zero machine changes. See the [Quickstart](docs/quickstart.md) and [Use in any stack](docs/any-stack.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).
+- **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 hand-rolled 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
@@ -120,8 +120,6 @@ When the machine reaches `refunded`, the result is:
 
 The model chooses between the events allowed in `deciding`. The `AUTO_REFUND` transition only works when the amount is at most $100. If the model chooses it for a larger amount, the guard rejects the choice and the decision is tried again.
 
-`createScriptedExecutors` plays back canned answers through the same executor contract, so the machine above runs end to end before a model is involved. **No API key needed:**
-
 ```ts
 import { createScriptedExecutors } from "@statelyai/agent";
 
@@ -131,7 +129,7 @@ const result = await runAgent(refundMachine, {
 });
 ```
 
-Swap in `createAiSdkExecutors({ models })` when you want a real model. The scripted set is what your tests keep using.
+Scripted executors run the machine above end to end with no API key; swap in `createAiSdkExecutors({ models })` for a real model. See [Hosts and executors](docs/hosts.md).
 
 ## Architecture
 
@@ -149,18 +147,7 @@ The machine never talks to a model directly, so swapping `createAiSdkExecutors`
 
 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.
 
-## Core concepts
-
-<!-- core concepts derived from setupAgent, built-in agent actors, runAgent, and XState snapshots -->
-
-- **Machines own control flow.** States, events, transitions, and guards define what can happen.
-- **Models make bounded decisions.** `agent.decide` asks a model to choose one of the events accepted by the current state.
-- **Requests are typed.** Inputs, outputs, context, and events use Standard Schema. Zod works out of the box.
-- **Your code runs the model.** `runAgent` accepts executor functions. The example uses the Vercel AI SDK adapter, but the machine does not depend on a provider.
-- **Snapshots can be stored.** An agent can stop for human input, save its XState snapshot, and resume later in another process.
-- **Runs export verified replay entries.** Every `runAgent` result carries a JSON-safe `AgentLogEntry[]` with event identity, timestamp, machine version, and state/effect hashes; pass it to `replay` or `verifyReplay` without repeating model or tool calls.
-- **Machines can be checked without model calls.** Lint their structure, simulate scripted decisions, and explore paths without an API key.
-- **Agents are XState machines.** Guards, actors, parallel states, inspection, testing, and visualization work as usual.
+The core concepts (machines owning control flow, bounded model decisions, typed requests, host-run executors, storable snapshots, verified replay entries) are in the [documentation overview](docs/index.md).
 
 ## Examples
 
@@ -174,7 +161,7 @@ The example above has one model decision and two final outcomes. Real machines a
 
 See [all examples](examples/README.md).
 
-## Learn more
+## Related
 
 - [Machines](docs/machines.md)
 - [Text requests](docs/text-requests.md)
@@ -190,5 +177,5 @@ See [all examples](examples/README.md).
 - [Observability](docs/observability.md)
 - [Usage and budgets](docs/usage-and-budgets.md)
 - [Agent patterns](docs/patterns.md)
-- [Migrating from a loop](docs/from-a-loop.md)
-- [LangGraph vs agent machines](docs/langgraph-comparison.md)
+- [Migrating from a hand-rolled loop](docs/from-a-loop.md)
+- [Coming from LangGraph](docs/langgraph-comparison.md)

package/schemas/agent-workflow.json

@@ -483,10 +483,7 @@
         },
         "guard": {
           "description": "Either a whole-string {{ }} expression evaluated as truthy/falsy, or a named guard reference resolved against the `guards` passed to setupAgent.fromConfig(config, { guards }). Object guards ({ type, params }) are rejected by the lowering.",
-          "anyOf": [
-            { "$ref": "#/$defs/ExpressionString" },
-            { "$ref": "#/$defs/Identifier" }
-          ]
+          "anyOf": [{ "$ref": "#/$defs/ExpressionString" }, { "$ref": "#/$defs/Identifier" }]
         },
         "assign": {
           "description": "Context assignments applied when this transition is taken.",