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

package/dist/{text-logic-C7WJpCIc.d.mts → text-logic-CorGzucG.d.cts}

@@ -1,23 +1,15 @@
-import { C as StandardSchemaV1, b as InferOutput, f as AllowedEvents, m as ChosenEvent, o as AgentToolChoice, r as AgentMessage, u as AgentTools } from "./types-qm00QF91.mjs";
+import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-QbEfCVny.cjs";
+import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
 import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, MachineSnapshot } from "xstate";
 
 //#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;
   defaultToolName: string;
 }) => string;
-/**
- * True when an event type matches an `allowedEvents` entry: an exact type,
- * `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
- * segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
- * `'todo'` itself — mirroring xstate's partial wildcard events).
- */
-declare function matchesEventPattern(eventType: string, pattern: string): boolean;
 /** One candidate event a decision (or {@link getAcceptedEvents} caller) may choose: its type, the synthetic tool name a model can call to pick it, and its payload schema if one is registered. */
 interface AgentEventDescriptor {
   type: string;
@@ -33,21 +25,10 @@ interface AgentRequestOptions {
   snapshot?: AnyMachineSnapshot;
   events?: Record<string, StandardSchemaV1>;
   schemas?: AgentSchemas;
-  actorSources?: Record<string, unknown>;
+  actors?: Record<string, unknown>;
   /** Customize machine-event tool names. Defaults to send_event_<TYPE>. */
   eventToolName?: AgentEventToolNameResolver;
 }
-/**
- * Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
- * a model can be offered (via `resolveDecision`/an adapter's tool-per-event
- * mapping). **Filters by event TYPE only** — it does not evaluate guards, so
- * a type-legal-but-guard-rejected event can still appear here. Guard
- * legality is checked separately, at decision-resolution time, via
- * `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
- * {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
- * declared `allowedEvents` set — entries may be exact types or wildcard
- * patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
- */
 /** Recovers a machine's event union from its snapshot type, so {@link parseAgentEvent} returns the machine-typed event without a downstream cast. @internal */
 type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer TEvent, any, any, any, any, any, any> ? TEvent : EventObject;
 /**
@@ -74,6 +55,22 @@ type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer
 declare function parseAgentEvent<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, event: {
   type: string;
 } & Record<string, unknown>, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName">): EventFromSnapshot<TSnapshot>;
+/**
+ * Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
+ * a model can be offered (via `resolveDecision`/an adapter's tool-per-event
+ * mapping). **Filters by event TYPE only** — it does not evaluate guards, so
+ * a type-legal-but-guard-rejected event can still appear here. Guard
+ * legality is checked separately, at decision-resolution time, via
+ * `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
+ * {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
+ * declared `allowedEvents` set — entries may be exact types or wildcard
+ * patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
+ *
+ * XState-internal (`xstate.*`) and library-reserved
+ * ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
+ * any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
+ * never offers it to a model.
+ */
 declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName"> & {
   eventTypes?: readonly string[];
 }): AgentEventDescriptor[];
@@ -211,21 +208,6 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
-/**
- * Actor logic for a decision: an async effect that resolves to exactly one
- * currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
- * the chosen event is delivered to the invoking actor automatically — the
- * transition it triggers usually exits the invoking state and ends the invoke.
- * Built by {@link createDecisionLogic}. Register it under `actorSources:` to reuse/export/
- * test it standalone; for a state-local, zero-config decision, use the
- * `agent.decide` builtin invoke instead.
- */
-interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends AsyncActorLogic<ChosenEvent, InferOutput<TInputSchema>> {
-  readonly kind: "statelyai.decisionLogic";
-  readonly maxRetries: number;
-  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
-  withExecutor(execute: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
-}
 /**
  * A decision request: resolves to exactly one currently-legal event. See
  * `resolveDecision`.
@@ -260,6 +242,15 @@ interface AgentDecisionRequest {
    * `info.signal`). Runtime-only — never serialized into a provider request.
    */
   signal?: AbortSignal;
+  /**
+   * The `runAgent` run this decision belongs to (`run_<n>`, matching trace
+   * events), injected by runAgent like `signal` (symmetric with the text
+   * executors' `info.runId`). Runtime-only correlation for executor
+   * middleware; unset off the runAgent path. Per-attempt context is already
+   * on the request: `id` is the durable invoke id and `attempts.length` is
+   * the current attempt index.
+   */
+  runId?: string;
 }
 /**
  * A single failed decision attempt, recorded by {@link resolveDecision} and
@@ -282,8 +273,8 @@ interface DecisionAttempt {
  * diagnostics; a machine typically routes this via the decision invoke's
  * `onError`.
  */
-declare class DecisionExhaustedError extends Error {
-  attempts: DecisionAttempt[];
+declare class AgentDecisionExhaustedError extends AgentError {
+  readonly attempts: DecisionAttempt[];
   constructor(attempts: DecisionAttempt[]);
 }
 /**
@@ -309,12 +300,15 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
  * adapter business; core only validates and retries the returned choice (see
  * {@link resolveDecision}). The optional `reason` is carried through to
  * `onResult`/event-sourcing but never affects validation. Like text
- * executors' `{ output, ...extras }` envelope, any extra keys (usage, finish
- * reason, …) flow untouched to `onResult`'s `raw`.
+ * executors' `{ output, ...extras }` envelope, any extra keys (finish reason,
+ * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
+ * report this attempt's tokens there and `runAgent` folds them into the run's
+ * aggregated {@link AgentUsage}.
  */
 type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
   event: ChosenEvent;
-  reason?: string;
+  reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
+  usage?: AgentCallUsage;
   [key: string]: unknown;
 }>;
 /**
@@ -356,7 +350,7 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
  * the next attempt via `request.attempts`, so an adapter can render "your
  * last choice failed because X — try again" into the next model call; core
  * never rewrites the request itself. Exhausting all attempts throws
- * {@link DecisionExhaustedError} with the full attempts list.
+ * {@link AgentDecisionExhaustedError} with the full attempts list.
  *
  * @example
  * ```ts
@@ -452,6 +446,34 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
+/**
+ * Aggregated model-call usage for ONE `runAgent` call — the run-level total
+ * attached to every settled {@link RunAgentResult} (and therefore to
+ * `generateResult`'s `{ output, snapshot, events, usage }`).
+ *
+ * - `modelCalls` counts every model/decision call this run made (each decision
+ *   retry counts separately) — the same seam `maxModelCalls` budgets. Always a
+ *   number, even when no executor reported tokens.
+ * - Token fields are OPTIONAL and are PARTIAL SUMS: each one sums only the
+ *   calls that reported it, and stays `undefined` when NO call reported it.
+ *   Executors that report nothing (custom hosts, test mocks) simply do not
+ *   contribute — a run mixing reporting and non-reporting calls yields a sum
+ *   over the reporting subset, not `undefined`.
+ * - Aggregation is per-run: a resumed run counts only ITS OWN calls, never the
+ *   history behind `snapshot`/`events`. Add prior runs' totals yourself if you
+ *   want a conversation-wide figure.
+ */
+interface AgentUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+  /** Model/decision calls made by this run (decision retries count separately). */
+  modelCalls: number;
+}
+/** 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">;
 /**
  * Inline input for the `agent.userInput` builtin actor — a human-input request
  * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
@@ -488,13 +510,19 @@ type ResolveTextLogicValue<TValue, TInput> = TValue | ((args: {
  * that validate it. Each request-shaping field (`model`, `system`, `prompt`,
  * …) is either a static value or a `({ input }) => value` resolver.
  */
-interface TextLogicConfig<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string> {
+interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string> {
   mode?: AgentRequestMode;
   /** Stamped onto every lowered request as {@link AgentTextRequest.name}. `setupAgent({ requests })` sets this to the request's key. */
   name?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
-  schemas: {
-    input: TInputSchema;
-    output: TOutputSchema;
+  /**
+   * The request's input/output schemas. Both are optional:
+   * - `output` defaults to a string schema (a plain text request).
+   * - `input` defaults to a schema that accepts (and types) `undefined`, so
+   *   the request takes no `input` at the invoke site.
+   */
+  schemas?: {
+    input?: TInputSchema;
+    output?: TOutputSchema;
   };
   model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
   system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
@@ -526,7 +554,7 @@ type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema exte
 /**
  * Actor logic for a text request: an async effect that resolves typed input
  * to typed, schema-validated output via a model call. Built by
- * {@link createTextLogic}; register under `actorSources:` and invoke by name, or
+ * {@link createTextLogic}; register under `actors:` and invoke by name, or
  * bind an executor later with `withExecutor`. The `agent.generateText`/
  * `agent.streamText` builtins and `setupAgent({ requests })` entries are
  * both `TextLogic` under the hood.
@@ -542,14 +570,10 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
   execute(input: InferOutput<TInputSchema>, executors: AgentRequestExecutors): Promise<InferOutput<TOutputSchema>>;
   withExecutor(execute: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 }
-/** Extracts a {@link TextLogic}'s validated input type. */
-type TextLogicInput<TLogic extends TextLogic> = TLogic extends TextLogic<infer TInputSchema, StandardSchemaV1, infer _TMetadata> ? InferOutput<TInputSchema> : never;
-/** Extracts a {@link TextLogic}'s validated output type. */
-type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<StandardSchemaV1, infer TOutputSchema, infer _TMetadata> ? InferOutput<TOutputSchema> : never;
 /**
  * Creates reusable, standalone {@link TextLogic}: an actor that, when run,
  * resolves typed input to typed output via a model call. Register the
- * result under `actorSources:` and invoke it by name (equivalent to what
+ * result under `actors:` and invoke it by name (equivalent to what
  * `setupAgent({ requests })` builds internally for each request entry). Pass
  * `execute` here, or bind it later with `.withExecutor(...)`, a runtime
  * adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
@@ -566,7 +590,7 @@ type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<Standa
  * });
  * ```
  */
-declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function createTextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * Binds a child machine's {@link TextLogic} to a raw
  * {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
@@ -578,7 +602,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * @example
  * ```ts
  * childMachine.provide({
- *   actorSources: {
+ *   actors: {
  *     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
  *   },
  * });
@@ -588,12 +612,18 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
- * Passthrough fields (usage, toolCalls, finishReason, raw, …) are allowed
- * alongside `output` and preserved on the raw result. {@link normalizeGeneratorResult}
+ * Passthrough fields (toolCalls, finishReason, raw, …) are allowed alongside
+ * `output` and preserved on the raw result. {@link normalizeGeneratorResult}
  * unwraps `output`; a non-envelope return is a runtime error.
+ *
+ * `usage` is the one passthrough field core reads: report this call's tokens
+ * there and `runAgent` folds them into the run's aggregated
+ * {@link AgentUsage}. Optional — an executor that reports nothing still counts
+ * toward `modelCalls`.
  */
 type AgentRequestExecutorResult<TOutput = unknown> = {
-  output: TOutput;
+  output: TOutput; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
+  usage?: AgentCallUsage;
   [key: string]: unknown;
 };
 /**
@@ -604,6 +634,20 @@ type AgentRequestExecutorResult<TOutput = unknown> = {
 interface AgentRequestExecutorInfo {
   onChunk?: (chunk: string) => void;
   signal?: AbortSignal;
+  /**
+   * The `runAgent` run this call belongs to (`run_<n>`, matching trace
+   * events). Undefined off the runAgent path (bare `provideExecutors` /
+   * direct `TextLogic.execute`). Lets executor middleware (caching, rate
+   * limits, span parenting) correlate calls without side channels.
+   */
+  runId?: string;
+  /**
+   * The durable invoke id of the request making this call (e.g.
+   * `'0.(machine).asking'`) — stable across resume/replay, and it encodes the
+   * invoking state, so per-state middleware can key on it. Undefined when the
+   * call has no invoking actor.
+   */
+  requestId?: string;
 }
 /**
  * A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
@@ -648,13 +692,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;
 }
@@ -670,8 +716,6 @@ type AgentOutputMode = "structured" | "text";
  * as `'text'`.
  */
 declare function getAgentOutputMode(schema?: StandardSchemaV1): AgentOutputMode;
-/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
-declare function isStructuredOutputSchema(schema?: StandardSchemaV1): boolean;
 /** The unwrapped shape a {@link buildEnvelopeSchema} validate returns: the inner
  * `result` value plus, when opted in and present, the model's `reasoning`. */
 interface StructuredOutputEnvelope {
@@ -707,4 +751,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, resolveDecision as B, createTextLogic as C, parseStructuredEnvelope as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentEventToolNameResolver as H, PLAN_DONE_EVENT_TYPE as I, parseAgentEvent as K, PlanLogic as L, AgentPlanInput as M, AgentPlanOutput as N, AgentDecisionExecutor as O, DecisionAttempt as P, ResolveDecisionOptions as R, buildEnvelopeSchema as S, parseModelRef as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, TextLogic as _, AgentRequestExecutor as a, TextLogicExecutor as b, AgentRequestExecutors as c, AgentUsage as d, AgentUserInput as f, StructuredOutputEnvelope as g, BuiltinAgentActors as h, AgentOutputMode as i, AgentDecisionRequest as j, AgentDecisionExhaustedError as k, AgentRequestMode as l, AiSdkShapedTextResult as m, AgentModelMap as n, AgentRequestExecutorInfo as o, AiSdkShapedStreamResult as p, AgentModelRef as r, AgentRequestExecutorResult as s, AgentCallUsage as t, AgentTextRequest as u, TextLogicConfig as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, renderDecisionAttempts as z };