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

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

@@ -1,4 +1,4 @@
-import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-9Bqg5rZB.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";
 
@@ -16,9 +16,11 @@ interface AgentEventDescriptor {
   toolName: string;
   inputSchema?: StandardSchemaV1;
 }
-/** Registered event payload schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
+/** Registered schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
 interface AgentSchemas {
   events?: Record<string, StandardSchemaV1>;
+  /** Machine input schema; `runAgent` validates `options.input` against it. */
+  input?: StandardSchemaV1;
 }
 /** Shared options threaded through step discovery ({@link getAgentRequests}/{@link getAcceptedEvents}) — snapshot for event legality, event schemas for payload validation/tool schemas, and registered actor source logics. */
 interface AgentRequestOptions {
@@ -387,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.
@@ -702,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-rMe7x6NR.d.cts → types-DYpK3QF4.d.mts}

@@ -36,6 +36,33 @@ interface StandardSchemaV1<Input = unknown, Output = Input> {
 }
 /** The validated output type of a {@link StandardSchemaV1}. */
 type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/**
+ * The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
+ * passes in, before defaults are filled and transforms applied. Standard Schema
+ * carries both sides (`~standard.types.input` / `.output`), so a schema
+ * declaring a defaulted field makes that field optional here and required in
+ * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * accepts as machine `input` and what the `context` factory then sees.
+ */
+type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
+/**
+ * Phantom brand carrying a machine's declared input schema on the machine type.
+ *
+ * XState resolves `schemas.input` to a single type and uses it for both
+ * `createActor`'s `input` option and the `context: ({ input })` factory, so the
+ * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
+ * `createMachine` brands the machine's input type with the schema itself, which
+ * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * `context` factory keeps the strict validated side.
+ *
+ * The key is a `~`-prefixed phantom property (the same convention Standard
+ * Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
+ * have to be exported as a runtime value for declaration emit to name it in
+ * every machine type it touches.
+ */
+type WithAgentInputSchema<TInputSchema> = {
+  readonly "~agent.inputSchema"?: TInputSchema;
+};
 /** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
 type EventPayload<T> = T extends Record<string, never> ? unknown : T;
 /**
@@ -157,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
@@ -216,4 +244,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };
+export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };

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

@@ -36,6 +36,33 @@ interface StandardSchemaV1<Input = unknown, Output = Input> {
 }
 /** The validated output type of a {@link StandardSchemaV1}. */
 type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
+/**
+ * The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
+ * passes in, before defaults are filled and transforms applied. Standard Schema
+ * carries both sides (`~standard.types.input` / `.output`), so a schema
+ * declaring a defaulted field makes that field optional here and required in
+ * {@link InferOutput} — which is exactly the split between what `runAgent`
+ * accepts as machine `input` and what the `context` factory then sees.
+ */
+type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
+/**
+ * Phantom brand carrying a machine's declared input schema on the machine type.
+ *
+ * XState resolves `schemas.input` to a single type and uses it for both
+ * `createActor`'s `input` option and the `context: ({ input })` factory, so the
+ * caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
+ * `createMachine` brands the machine's input type with the schema itself, which
+ * lets `AgentInputFrom` recover the looser input side for `runAgent` while the
+ * `context` factory keeps the strict validated side.
+ *
+ * The key is a `~`-prefixed phantom property (the same convention Standard
+ * Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
+ * have to be exported as a runtime value for declaration emit to name it in
+ * every machine type it touches.
+ */
+type WithAgentInputSchema<TInputSchema> = {
+  readonly "~agent.inputSchema"?: TInputSchema;
+};
 /** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
 type EventPayload<T> = T extends Record<string, never> ? unknown : T;
 /**
@@ -157,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
@@ -216,4 +244,4 @@ type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEv
   input: TInput;
 }) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
 //#endregion
-export { UserMessage as C, ToolResultPart as S, StandardSchemaV1 as _, AgentToolChoice as a, ToolCallPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, NormalizedEventSchemas as g, InferOutput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, SystemMessage as v, ToolMessage as x, TextPart as y };
+export { ToolResultPart as C, ToolMessage as S, WithAgentInputSchema as T, NormalizedEventSchemas as _, AgentToolChoice as a, TextPart as b, AgentTools as c, ChosenEvent as d, EventUnion as f, InferOutput as g, InferInput as h, AgentTool as i, AllowedEvents as l, ImagePart as m, AgentMessage as n, AgentToolDescriptor as o, FilePart as p, AgentSnapshotStore as r, AgentToolExecute as s, AgentEventSchemaInputMap as t, AssistantMessage as u, StandardSchemaV1 as v, UserMessage as w, ToolCallPart as x, SystemMessage as y };

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.14",
+  "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.",