@statelyai/agent 1.1.6 → 2.0.0-alpha.5

package/dist/text-logic-1ZQkO3zr.d.cts

@@ -0,0 +1,682 @@
+import { b as StandardSchemaV1, c as AgentTools, f as ChosenEvent, i as AgentToolChoice, t as AgentMessage, u as AllowedEvents, v as InferOutput } from "./types-BHjeDdch.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;
+  toolName: string;
+  inputSchema?: StandardSchemaV1;
+}
+/** Registered event payload schemas, as attached to a machine by `setupAgent`/`createAgentSchemas`. */
+interface AgentSchemas {
+  events?: Record<string, 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 {
+  snapshot?: AnyMachineSnapshot;
+  events?: Record<string, StandardSchemaV1>;
+  schemas?: AgentSchemas;
+  actorSources?: 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;
+/**
+ * Runtime-validates a dynamically-built `{ type, ...payload }` event against a
+ * snapshot's currently-accepted events (via {@link getAcceptedEvents}) and,
+ * when one is registered, the event type's payload schema — returning the
+ * event typed as the machine's event union (recovered from the snapshot type)
+ * so it can be sent to `runAgent({ event })` / `actor.send(...)` without an
+ * `as never` cast. For generic, meta-driven hosts that assemble events from
+ * user input or a wire message.
+ *
+ * Throws a descriptive error when `event.type` is not currently accepted
+ * (listing the accepted types) or when its payload fails the registered schema.
+ * Pass event payload schemas via `options.events`/`options.schemas` (the same
+ * shape {@link getAcceptedEvents} takes) — the accepted TYPES always come from
+ * the live snapshot; the schemas only add payload validation.
+ *
+ * @example
+ * ```ts
+ * const event = parseAgentEvent(result.snapshot, rawEvent, { events: schemas.events });
+ * result = await runAgent(machine, { snapshot: result.snapshot, event, executors });
+ * ```
+ */
+declare function parseAgentEvent<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, event: {
+  type: string;
+} & Record<string, unknown>, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName">): EventFromSnapshot<TSnapshot>;
+declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName"> & {
+  eventTypes?: readonly string[];
+}): AgentEventDescriptor[];
+//#endregion
+//#region src/decision.d.ts
+/**
+ * Inline input for the `agent.decide` builtin actor — the zero-config
+ * counterpart to {@link createDecisionLogic}, invoked directly from a
+ * state's `invoke.input` (typed against the machine's own event schemas).
+ * See {@link AgentDecisionRequest} for the request shape this lowers to.
+ */
+interface AgentDecisionInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> {
+  model: TModel;
+  system?: string;
+  prompt?: string;
+  messages?: AgentMessage[];
+  allowedEvents?: AllowedEvents<TEvent>;
+  maxRetries?: number;
+  temperature?: number;
+  maxOutputTokens?: number;
+  topP?: number;
+  topK?: number;
+  seed?: number;
+  stopSequences?: string[];
+  metadata?: TMetadata;
+}
+/**
+ * Inline input for the `agent.plan` builtin actor — a multi-event decision.
+ * Where `agent.decide` picks exactly one currently-legal event, `agent.plan`
+ * applies an ordered sequence of them: each step re-reads the live snapshot,
+ * asks the `decide` executor for one legal event (same validation and
+ * `rejected-by-guard` retry loop as a decision), sends it to the machine,
+ * and repeats until a `stopOn` event is chosen, `maxSteps` is reached, no
+ * legal candidate remains, or an applied event exits the invoking state
+ * (which cancels the invoke — the machine simply moves on).
+ *
+ * Requires a snapshot-aware host: {@link runAgent}, or the step path (where an
+ * `agent.plan` invoke re-surfaces as a `kind: 'plan'` request that
+ * `resolveAgentRequests` drives one step per call).
+ */
+interface AgentPlanInput<TEvent extends string = string, TMetadata = Record<string, unknown>, TModel extends string = string> extends AgentDecisionInput<TEvent, TMetadata, TModel> {
+  /** Maximum events applied in one plan. Default 8. */
+  maxSteps?: number;
+  /**
+   * Machine events that end the plan once chosen: the event is still
+   * validated and sent, then the loop stops. Usually unnecessary — every
+   * plan step already offers the built-in {@link PLAN_DONE_EVENT_TYPE}
+   * "done" option, which ends the plan without touching the machine.
+   * Declare `stopOn` only for "send this real event AND stop" semantics.
+   */
+  stopOn?: readonly TEvent[];
+}
+/**
+ * Reserved event type the `agent.plan` builtin adds to every step's
+ * candidates as the explicit "no further action needed" move. Choosing it
+ * ends the plan (`stopped: 'done'`); it is never sent to the machine, so
+ * machines need no no-op sentinel event of their own.
+ */
+declare const PLAN_DONE_EVENT_TYPE: "agent.plan.done";
+/** What an `agent.plan` invoke resolves with (its `onDone` output). */
+interface AgentPlanOutput {
+  /** The events applied, in order (possibly empty). */
+  steps: ChosenEvent[];
+  /** Why the loop ended. */
+  stopped: "done" | "stop-event" | "max-steps" | "no-legal-events";
+}
+/**
+ * The in-progress state of a plan, held in the `agent.plan` invoke child's own
+ * `createLogic` snapshot `context`. Because a `createLogic` snapshot serializes
+ * (and restores) by identity, this lands at
+ * `children.<planId>.snapshot.context` in a machine's persisted snapshot for
+ * free — so a step-path host that persists after every event resumes a plan
+ * mid-flight without a bespoke carrier.
+ */
+interface PlanLedgerContext {
+  /** The events applied so far in this plan, in order (the trail). */
+  applied: ChosenEvent[];
+  /** How many more events the plan may apply (`maxSteps - applied.length`). */
+  stepsRemaining: number;
+  /** Set once the plan terminates; `null` while in flight. */
+  stopped: AgentPlanOutput["stopped"] | null;
+}
+/**
+ * The two ledger events that drive a {@link PlanLedgerContext} forward:
+ * `plan.applied` appends one event to the trail and decrements the budget;
+ * `plan.ended` records the stop reason and completes the ledger (its snapshot
+ * goes `done` with the {@link AgentPlanOutput}).
+ */
+type PlanLedgerEvent = {
+  type: "plan.applied";
+  event: ChosenEvent;
+} | {
+  type: "plan.ended";
+  stopped: AgentPlanOutput["stopped"];
+};
+/**
+ * Actor logic for the `agent.plan` builtin: a stateful, transition-based
+ * ledger. Its snapshot `context` ({@link PlanLedgerContext}) IS the plan's
+ * in-progress state — the applied trail plus remaining budget — advanced one
+ * {@link PlanLedgerEvent} at a time. On the step path the invoke child runs this
+ * logic directly (so its context persists at `children.<id>.snapshot.context`);
+ * runAgent swaps in an async implementation that drives the SAME ledger via the
+ * shared {@link initialPlanLedger}/{@link advancePlanLedger} drivers.
+ */
+interface PlanLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<AgentPlanInput>> extends LogicActorLogic<PlanLedgerContext, AgentPlanOutput, PlanLedgerEvent, InferOutput<TInputSchema>> {
+  readonly kind: "statelyai.planLogic";
+  readonly maxRetries: number;
+  /** Builds the per-step base {@link AgentDecisionRequest} (id/events filled in per step). */
+  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
+  /** @internal Resolves declared `allowedEvents` (undefined = all currently legal). */
+  allowedEventTypes(input: InferOutput<TInputSchema>): readonly string[] | undefined;
+}
+/**
+ * Config for {@link createDecisionLogic}: how to build an
+ * {@link AgentDecisionRequest} from typed input. Each field mirrors
+ * {@link TextLogicConfig} (static value or a `({ input }) => value`
+ * resolver), plus `allowedEvents` to narrow the candidate event set (see
+ * {@link AllowedEvents}) and `maxRetries` for {@link resolveDecision}.
+ */
+interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TEvent extends string = string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TModel extends string = string> {
+  schemas?: {
+    input: TInputSchema;
+  };
+  model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
+  system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
+  prompt?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
+  messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
+  allowedEvents?: AllowedEvents<TEvent, InferOutput<TInputSchema>>;
+  maxRetries?: number;
+  temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  topP?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  topK?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  seed?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  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`.
+ */
+interface AgentDecisionRequest {
+  kind: "decision";
+  /** Durable invoke id. */
+  id: string;
+  model: string;
+  system?: string;
+  prompt?: string;
+  messages?: AgentMessage[];
+  /** Candidate events: declared `allowedEvents` ∩ snapshot-legal events. */
+  events: AgentEventDescriptor[];
+  /**
+   * Prior failed attempts for THIS decision. Empty on the first attempt.
+   * Adapters render these into the provider request so retries converge.
+   * Core never rewrites prompts/messages — attempts are data on the request.
+   */
+  attempts: DecisionAttempt[];
+  temperature?: number;
+  maxOutputTokens?: number;
+  topP?: number;
+  topK?: number;
+  seed?: number;
+  stopSequences?: string[];
+  metadata?: Record<string, unknown>;
+  /**
+   * Abort signal for the underlying model call, threaded through by
+   * {@link resolveDecision} from its `options.signal` so a `decide` executor
+   * can cancel the in-flight request (symmetric with the text executors'
+   * `info.signal`). Runtime-only — never serialized into a provider request.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * A single failed decision attempt, recorded by {@link resolveDecision} and
+ * fed back to the executor on the next attempt via
+ * `request.attempts`. `failure` names which of the three checks rejected the
+ * choice: `'unknown-event'` (not among the candidate `events`),
+ * `'invalid-payload'` (failed the event's schema), or `'rejected-by-guard'`
+ * (failed the `canTake` check — type/payload were legal, but the machine's
+ * guard rejected it at apply time).
+ */
+interface DecisionAttempt {
+  event?: ChosenEvent;
+  failure: "unknown-event" | "invalid-payload" | "rejected-by-guard";
+  reason: string;
+}
+/**
+ * Thrown by {@link resolveDecision} when every attempt (up to
+ * `maxRetries + 1` of them) fails one of the three checks recorded in
+ * {@link DecisionAttempt.failure}. Carries the full `attempts` list for
+ * diagnostics; a machine typically routes this via the decision invoke's
+ * `onError`.
+ */
+declare class DecisionExhaustedError extends Error {
+  attempts: DecisionAttempt[];
+  constructor(attempts: DecisionAttempt[]);
+}
+/**
+ * Renders a decision request's prior failed `attempts` into feedback messages
+ * a host appends to the model call so retries converge — the transport-agnostic
+ * "your last choice failed because X, choose again from Y" logic every adapter
+ * and raw-SDK host repeats. Returns one `user`-role {@link AgentMessage} per
+ * attempt (empty when there are none); adapters map each onto their wire
+ * message shape (`attempt.content` is always a string). Core never rewrites the
+ * request itself — this only turns the recorded attempts into messages.
+ *
+ * @example
+ * ```ts
+ * const messages = [...baseMessages, ...renderDecisionAttempts(request)];
+ * ```
+ */
+declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "events" | "attempts">): AgentMessage[];
+/**
+ * Host implementation of "make the model choose one of `request.events`."
+ * Third executor slot on {@link AgentRequestExecutors}, symmetric with
+ * `generateText`/`streamText` — how the model is coerced into choosing
+ * (tool-per-event + forced tool choice, structured output, …) is entirely
+ * 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`.
+ */
+type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
+  event: ChosenEvent;
+  reason?: string;
+  [key: string]: unknown;
+}>;
+/**
+ * Options for {@link resolveDecision}. The `TEvent` parameter (the machine's
+ * event union, defaulting to the loose {@link ChosenEvent}) types both
+ * `canTake`'s argument and {@link resolveDecision}'s return — pass it (or let
+ * it infer from `canTake`) to get a machine-typed chosen event out without a
+ * downstream cast.
+ */
+interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
+  /** Retries after a failed attempt. Default `2`, so up to 3 attempts total. */
+  maxRetries?: number;
+  /** Checked before each attempt; aborting rejects the pending decision. */
+  signal?: AbortSignal;
+  /**
+   * Guard-legality check (mode 3), typically `(e) => snapshot.can(e)`. A
+   * type-and-payload-valid event that this rejects records a
+   * `'rejected-by-guard'` attempt and retries. Omit to skip guard checking
+   * (type + payload validation only — e.g. under bare `createActor`, where
+   * no snapshot is reachable). Typing its argument as the machine's event
+   * union (e.g. `(e: GameEvent) => snapshot.can(e)`) makes
+   * {@link resolveDecision} return that union.
+   */
+  canTake?: (event: TEvent) => boolean;
+}
+/**
+ * Validation + retry core for decisions. No provider mechanics — the
+ * `executor` is responsible for making the model choose an event; this
+ * function only validates the choice and retries on failure, up to
+ * `options.maxRetries` (default 2, i.e. up to 3 attempts total).
+ *
+ * Each attempt is checked in order and can fail one of three ways (recorded
+ * as a {@link DecisionAttempt}): `'unknown-event'` (the chosen `type` is not
+ * among `request.events`), `'invalid-payload'` (the payload fails that
+ * event's schema), or `'rejected-by-guard'` (passes both checks but
+ * `options.canTake` returns `false` — a type/payload-legal event the
+ * machine's guard rejects right now; omit `canTake` to skip this check).
+ * Every prior failed attempt for this call is fed back to the executor on
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const event = await resolveDecision(request, decide, {
+ *   canTake: (e) => snapshot.can(e),
+ * });
+ * ```
+ */
+declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executor: AgentDecisionExecutor, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
+//#endregion
+//#region src/text-logic.d.ts
+declare const USER_INPUT_ACTOR: "agent.userInput";
+declare const GENERATE_TEXT_ACTOR: "agent.generateText";
+declare const STREAM_TEXT_ACTOR: "agent.streamText";
+declare const DECIDE_ACTOR: "agent.decide";
+declare const PLAN_ACTOR: "agent.plan";
+/** Whether a text request should be resolved with `generateText` (one-shot) or `streamText` (chunked, via `onChunk`). */
+type AgentRequestMode = "generate" | "stream";
+/** A `setupAgent({ models })` model registry, mapping short model refs to provider-specific model values. */
+type AgentModelMap = Record<string, unknown>;
+/**
+ * A model reference: any string is legal, but a registered `models` map's keys
+ * autocomplete. Refs are opaque routing keys — the host/executor (or the AI SDK
+ * adapter's models map / `resolveModel`) resolves them to a real model.
+ */
+type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+/**
+ * Portable, provider-agnostic input a text request passes to a host
+ * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
+ * Built by {@link TextLogic.request} / `DecisionLogic.request` from a
+ * `TextLogicConfig`/`DecisionLogicConfig`; adapters (e.g.
+ * `createAiSdkExecutors`) map this shape onto their provider's call
+ * settings.
+ */
+interface AgentTextRequest<TMetadata = Record<string, unknown>> {
+  /**
+   * The registered name of the request that produced this call — the
+   * `setupAgent({ requests })` key (also set by `setupAgent.fromConfig`), or
+   * `TextLogicConfig.name` for standalone `createTextLogic` actors. Hosts and
+   * test mocks can route on it instead of sniffing `system`/`prompt` text.
+   * Absent for ad-hoc `agent.generateText`/`agent.streamText` invokes unless
+   * the caller sets it on the inline input.
+   */
+  name?: string;
+  model: string;
+  system?: string;
+  prompt?: string;
+  messages?: AgentMessage[];
+  /** Host/model tools that are always available to this text call. */
+  tools?: AgentTools;
+  toolChoice?: AgentToolChoice;
+  outputSchema?: StandardSchemaV1;
+  /**
+   * Opt-in reasoning for a structured-output request: when `true`, adapters add
+   * an optional string `reasoning` property (listed BEFORE `result`) to the
+   * structured-output envelope schema, nudging the model to reason before
+   * committing to the result. The reasoning is surfaced on the executor's raw
+   * result (never in machine context/output). Ignored for text-mode requests.
+   */
+  reasoning?: boolean;
+  temperature?: number;
+  /**
+   * Maximum number of output tokens to generate. Named `maxOutputTokens` (not
+   * `maxTokens`) so an `AgentTextRequest` is spread-compatible with the Vercel
+   * AI SDK's `generateText`/`streamText` options.
+   */
+  maxOutputTokens?: number;
+  topP?: number;
+  topK?: number;
+  seed?: number;
+  stopSequences?: string[];
+  /**
+   * Host-owned per-call options. Use this for provider/runtime details such
+   * as Cloudflare bindings, tracing IDs, SDK provider options, or transport
+   * hints. The machine carries it; the host decides what it means — e.g.
+   * the AI SDK adapter (`createAiSdkExecutors`) reads `metadata.maxSteps` to
+   * bound its multi-step tool-call loop for that request.
+   */
+  metadata?: TMetadata;
+}
+/** Inline input for the `agent.userInput` builtin actor — a human-input request (CLI prompt, form, chat reply, …). See {@link RunAgentOptions.userInput}. */
+interface AgentUserInput<TMetadata = Record<string, unknown>> {
+  prompt?: string;
+  schema?: StandardSchemaV1;
+  metadata?: TMetadata;
+}
+/** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
+type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
+  [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
+  [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
+  [USER_INPUT_ACTOR]: AsyncActorLogic<unknown, AgentUserInput>;
+  [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
+  [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
+};
+/**
+ * Validates a raw model/executor output against `schema`, returning the
+ * parsed value. Thin wrapper over {@link validateSchemaSync} for parsing a
+ * text request's structured output outside of `TextLogic.execute`/
+ * `executeAgentRequest` (e.g. a custom host loop).
+ */
+declare function parseOutput<TSchema extends StandardSchemaV1>(schema: TSchema, output: unknown): InferOutput<TSchema>;
+/** A TextLogicConfig/DecisionLogicConfig field value: either static, or a `({ input }) => value` resolver. @internal */
+type ResolveTextLogicValue<TValue, TInput> = TValue | ((args: {
+  input: TInput;
+}) => TValue);
+/**
+ * Config for {@link createTextLogic}: how to build an
+ * {@link AgentTextRequest} from typed input, plus the input/output schemas
+ * 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> {
+  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;
+  };
+  model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
+  system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
+  prompt?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
+  messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
+  tools?: ResolveTextLogicValue<AgentTools | undefined, InferOutput<TInputSchema>>;
+  toolChoice?: ResolveTextLogicValue<AgentToolChoice | undefined, InferOutput<TInputSchema>>;
+  /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.reasoning}). */
+  reasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
+  temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  topP?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  topK?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  seed?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
+  stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
+  metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
+}
+/** Arguments passed to a {@link TextLogicExecutor}: the typed input, the lowered {@link AgentTextRequest}, and the actor's own `signal`/`system`/`self`/`emit`. */
+interface TextLogicExecuteArgs<TInput, TMetadata = Record<string, unknown>> {
+  input: TInput;
+  request: AgentTextRequest<TMetadata>;
+  signal: AbortSignal;
+  system: unknown;
+  self: unknown;
+  emit: (emitted: EventObject) => void;
+}
+/** Host implementation bound to a specific {@link TextLogic} via `withExecutor`/`createTextLogic`'s second argument — resolves one text request to an `{ output }` envelope typed from the logic's output schema (`{ output: T }`). Passthrough fields (usage, raw, …) are allowed alongside `output`. */
+type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = unknown> = (args: TextLogicExecuteArgs<InferOutput<TInputSchema>, TMetadata>) => PromiseLike<AgentRequestExecutorResult<InferOutput<TOutputSchema>>> | AgentRequestExecutorResult<InferOutput<TOutputSchema>>;
+/**
+ * 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
+ * bind an executor later with `withExecutor`. The `agent.generateText`/
+ * `agent.streamText` builtins and `setupAgent({ requests })` entries are
+ * both `TextLogic` under the hood.
+ */
+interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata = Record<string, unknown>> extends AsyncActorLogic<InferOutput<TOutputSchema>, InferOutput<TInputSchema>> {
+  readonly kind: "statelyai.textLogic";
+  readonly mode: AgentRequestMode;
+  readonly schemas: {
+    readonly input: TInputSchema;
+    readonly output: TOutputSchema;
+  };
+  request(input: InferOutput<TInputSchema>): AgentTextRequest<TMetadata>;
+  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
+ * `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`/
+ * `streamText` options.
+ *
+ * @example
+ * ```ts
+ * export const tellJoke = createTextLogic({
+ *   mode: 'stream',
+ *   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
+ *   model: 'openai/gpt-5.4-mini',
+ *   system: 'You tell short, punchy jokes.',
+ *   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
+ * });
+ * ```
+ */
+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>;
+/**
+ * Binds a child machine's {@link TextLogic} to a raw
+ * {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
+ * implement). Encapsulates the `withExecutor` idiom child agents repeat:
+ * default the request's `tools` to `{}`, forward the actor `signal`, call the
+ * executor, and return its `{ output }` envelope. Use this to share ONE
+ * executor across a parent and its nested children.
+ *
+ * @example
+ * ```ts
+ * childMachine.provide({
+ *   actorSources: {
+ *     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
+ *   },
+ * });
+ * ```
+ */
+declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+/**
+ * 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}
+ * unwraps `output`; a non-envelope return is a runtime error.
+ */
+type AgentRequestExecutorResult<TOutput = unknown> = {
+  output: TOutput;
+  [key: string]: unknown;
+};
+/**
+ * Optional second argument passed to executors by `runAgent`. The step path
+ * (`executeAgentRequest`) never passes this — chunk streaming only exists on
+ * the live path, where `onChunk` (§3.1) needs a way to reach the executor.
+ */
+interface AgentRequestExecutorInfo {
+  onChunk?: (chunk: string) => void;
+  signal?: AbortSignal;
+}
+/**
+ * A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
+ * string or a promise of one) instead of the `{ output }`
+ * {@link AgentRequestExecutorResult} envelope. Admitted directly as an executor
+ * return type so `ai`'s `generateText` passes to `runAgent`/executors without a
+ * cast — {@link normalizeGeneratorResult} unwraps `text` at runtime (text-only;
+ * structured output is best-effort JSON parsing against the request's
+ * `outputSchema`). Extra fields (`content`, `usage`, …) are ignored.
+ */
+type AiSdkShapedTextResult = {
+  text: string | PromiseLike<string>;
+  [key: string]: unknown;
+};
+/**
+ * A raw Vercel AI SDK `streamText` result shape: exposes a `textStream` async
+ * iterable of string chunks (and, optionally, a `text` promise for the final
+ * text) instead of the `{ output }` {@link AgentRequestExecutorResult} envelope.
+ * Admitted directly as an executor return type so `ai`'s `streamText` passes to
+ * `runAgent`/executors without a cast — {@link normalizeGeneratorResult}
+ * iterates `textStream`, forwarding chunks, then resolves the final text
+ * (text-only; structured output is best-effort). Extra fields are ignored.
+ */
+type AiSdkShapedStreamResult = {
+  textStream: AsyncIterable<string>;
+  text?: PromiseLike<string>;
+  [key: string]: unknown;
+};
+/**
+ * Host implementation of one text call (`generateText` or `streamText`) —
+ * resolves a lowered {@link AgentTextRequest} to an `{ output }` envelope (see
+ * {@link AgentRequestExecutorResult}), unwrapped by
+ * {@link normalizeGeneratorResult}. The return type is widened to also admit the
+ * raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
+ * {@link AiSdkShapedStreamResult}) so `ai`'s own `generateText`/`streamText`
+ * pass through without a cast; `normalizeGeneratorResult` checks for `{ output }`
+ * first, then falls back to those shapes at runtime.
+ */
+type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentTextRequest & {
+  tools: AgentTools;
+}, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
+/**
+ * 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`).
+ */
+interface AgentRequestExecutors<TGenerateResult extends AgentRequestExecutorResult = AgentRequestExecutorResult, TStreamResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> {
+  generateText: AgentRequestExecutor<TGenerateResult>;
+  streamText?: AgentRequestExecutor<TStreamResult>;
+  decide?: AgentDecisionExecutor;
+}
+/** Whether a text request's output is a validated structured object (`'structured'`) or plain text (`'text'`) — derived from the output schema's JSON Schema `type`. */
+type AgentOutputMode = "structured" | "text";
+/**
+ * Classifies a text request's output schema as `'structured'` (its JSON
+ * Schema is `type: 'object'`, `type: 'array'`, or a top-level union/
+ * composition — `anyOf`/`oneOf`/`allOf`, which a bare `z.union`/
+ * `z.discriminatedUnion` emits with no top-level `type`) or `'text'`
+ * (anything else, including no schema). Reads the schema's
+ * `~standard.jsonSchema.input()` extension — schemas without it are treated
+ * 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 {
+  result: unknown;
+  reasoning?: string;
+}
+/**
+ * Builds the uniform structured-output envelope schema every structured request
+ * is sent to the provider as: a root object `{ result: <inner> }`, plus — when
+ * `options.reasoning` is `true` — an optional string `reasoning` property listed
+ * BEFORE `result` (property order nudges the model to reason first). This is THE
+ * wire contract for structured output: a root object is universally accepted as
+ * a provider response schema, unlike a bare union/array root that many providers
+ * reject.
+ *
+ * The returned {@link StandardSchemaV1} validates the `{ reasoning?, result }`
+ * envelope (unwrapping `result` through the original schema, capturing a string
+ * `reasoning` when present) and exposes the enveloped JSON Schema. Adapters read
+ * `.result` off the provider output before the machine validates it — so this is
+ * transparent: user-facing output types stay the declared (un-enveloped) schema,
+ * and `reasoning` is surfaced only on the raw executor result, never in machine
+ * context/output.
+ */
+declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
+  reasoning?: boolean;
+}): StandardSchemaV1<StructuredOutputEnvelope>;
+//#endregion
+export { AgentPlanInput as A, AgentEventDescriptor as B, createTextLogic as C, AgentDecisionExecutor as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentRequestOptions as H, PLAN_DONE_EVENT_TYPE as I, matchesEventPattern as K, ResolveDecisionOptions as L, DecisionAttempt as M, DecisionExhaustedError as N, AgentDecisionInput as O, DecisionLogic as P, renderDecisionAttempts as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentRequestSource as U, AgentEventToolNameResolver as V, EVENT_TOOL_PREFIX as W, 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, AgentPlanOutput as j, AgentDecisionRequest as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, parseAgentEvent 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, resolveDecision as z };