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

package/dist/{text-logic-C7anC7qX.d.mts → text-logic-DQW8_DWW.d.mts}

@@ -1,4 +1,4 @@
-import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-CTBhMnFu.mjs";
+import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
 import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
 
@@ -389,6 +389,27 @@ interface AgentUsage {
 }
 /** One model call's reported usage — {@link AgentUsage} without the run-level `modelCalls` count. What an executor puts on its result's `usage` field. */
 type AgentCallUsage = Omit<AgentUsage, "modelCalls">;
+/**
+ * Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
+ * result's `usage` field, keeping only finite numbers — the same normalization
+ * `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+ * when the result reports no usage at all. Works for our `{ output, usage }`
+ * envelope, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
+ * the same flat field names), and for any custom executor that follows the
+ * shape.
+ *
+ * The seam for the step-loop path, where the host holds the raw result itself:
+ *
+ * ```ts
+ * const { output, raw } = await executeAgentRequest(effect, executors);
+ * const usage = getCallUsage(raw);
+ * if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+ * append(effect.toDoneEvent(output));
+ * ```
+ *
+ * See "Token usage on this path" in docs/steps.md for the full loop.
+ */
+declare function getCallUsage(raw: unknown): AgentCallUsage | undefined;
 /**
  * Inline input for the `agent.userInput` builtin actor — a human-input request
  * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
@@ -704,4 +725,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  */
 declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExhaustedError as A, AgentRequestOptions as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, ResolveDecisionOptions as F, getAcceptedEvents as H, renderDecisionAttempts as I, resolveDecision as L, AgentDecisionRequest as M, DecisionAttempt as N, parseStructuredEnvelope as O, DecisionLogicConfig as P, AgentEventDescriptor as R, bindRequestExecutor as S, getAgentOutputMode as T, parseAgentEvent as U, AgentRequestSource as V, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventToolNameResolver as z };
+export { AgentDecisionExecutor as A, AgentEventToolNameResolver as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogicConfig as F, AgentRequestSource as H, ResolveDecisionOptions as I, renderDecisionAttempts as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, resolveDecision as R, bindRequestExecutor as S, getAgentOutputMode as T, getAcceptedEvents as U, AgentRequestOptions as V, parseAgentEvent as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventDescriptor as z };

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.17",
   "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

@@ -71,6 +71,14 @@
         "$ref": "#/$defs/State"
       }
     },
+    "suspendedTags": {
+      "description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) suspension predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "meta": {
       "$ref": "#/$defs/JsonObject"
     }
@@ -483,10 +491,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.",