@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/machines.d.mts

@@ -0,0 +1,372 @@
+import { _ as StandardSchemaV1, c as AgentTools } from "./types-_FXoFBGO.mjs";
+import { AnyStateMachine } from "xstate";
+
+//#region src/machines/tool-loop.d.ts
+/** Config for {@link createToolLoopMachine}. */
+interface CreateToolLoopMachineConfig {
+  /** Model ref, or an alias from the host's `models` registry. */
+  model: string;
+  /** System prompt. */
+  instructions?: string;
+  /** Tools the host runs inside the one request. */
+  tools?: AgentTools;
+  /** Structured output schema. Omitted means the output is plain text. */
+  outputSchema?: StandardSchemaV1;
+  /** Bounds the host-side tool loop — lowered to `metadata.maxSteps`. */
+  maxTurns?: number;
+  /**
+   * Tool names the host should gate before executing. Lowered to
+   * `metadata.interruptOn`, which only a host that implements gating reads —
+   * the preset itself stays a single state and never pauses. For a real
+   * approval gate as machine states, eject to `examples/review-tool-calls`.
+   */
+  interruptOn?: readonly string[];
+}
+/** Context of a {@link createToolLoopMachine} machine. */
+type ToolLoopContext = {
+  prompt: string;
+  result: unknown;
+};
+/**
+ * The single-state tool loop: one text request carries the `tools`, and the
+ * host runs the tool loop inside it (`maxTurns` bounds it). Selecting and
+ * executing tools is the model + host's business, not machine states.
+ *
+ * States: `answering` → `done`.
+ *
+ * ```ts
+ * const machine = createToolLoopMachine({
+ *   model: "quick",
+ *   instructions: "Answer using the tools.",
+ *   tools: { calculate },
+ *   maxTurns: 5,
+ * });
+ *
+ * const result = await runAgent(machine, {
+ *   input: { prompt: "What is 42 * 17?" },
+ *   executors,
+ * });
+ * // Snapshots and log entries carry machine.version ("1") automatically.
+ * ```
+ */
+declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/sequential.d.ts
+/** Arguments a {@link SequentialStep}'s `prompt` receives. */
+interface SequentialPromptArgs {
+  /** The machine's `input.prompt`. */
+  prompt: string;
+  /** Every completed step's output, keyed by step name. */
+  results: Record<string, unknown>;
+  /** The previous step's output (`null` for the first step). */
+  previous: unknown;
+}
+/** One step of a {@link createSequentialMachine} chain. */
+interface SequentialStep {
+  /** Step name. Becomes the state name and the `results` key. */
+  name: string;
+  /** System prompt for this step. */
+  instructions?: string;
+  /** Builds this step's prompt. Defaults to the previous step's output (the machine's `prompt` for the first step). */
+  prompt?: (args: SequentialPromptArgs) => string;
+  /** Structured output schema for this step. */
+  outputSchema?: StandardSchemaV1;
+  /** Model ref for this step. Falls back to the factory's `model`. */
+  model?: string;
+  /** Tools the host runs inside this step's request. */
+  tools?: AgentTools;
+  /** Bounds this step's host-side tool loop (`metadata.maxSteps`). */
+  maxTurns?: number;
+}
+/** Config for {@link createSequentialMachine}. */
+interface CreateSequentialMachineConfig {
+  /** Default model ref for every step. */
+  model: string;
+  /** The chain, run in array order. */
+  steps: readonly SequentialStep[];
+}
+/** Context of a {@link createSequentialMachine} machine. */
+type SequentialContext = {
+  prompt: string;
+  results: Record<string, unknown>;
+  previous: unknown;
+};
+/**
+ * A prompt chain: each step is one state, and each step's output feeds the
+ * next. The default prompt for a step is the previous step's output, so a
+ * chain needs no `prompt` functions at all.
+ *
+ * States: one per step, in order → `done`.
+ *
+ * ```ts
+ * const machine = createSequentialMachine({
+ *   model: "quick",
+ *   steps: [
+ *     { name: "outline", instructions: "Outline the post." },
+ *     { name: "draft", instructions: "Write the post from the outline." },
+ *     { name: "polish", instructions: "Tighten the prose." },
+ *   ],
+ * });
+ * ```
+ */
+declare function createSequentialMachine(config: CreateSequentialMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/internal.d.ts
+/** One delegated unit of work, lowered to an inline text request. */
+interface PresetRequestEntry {
+  /** What this entry is for. Shown to the routing/supervising model. */
+  description?: string;
+  /** System prompt for this entry's model call. */
+  instructions?: string;
+  /** Model ref (or `models` alias). Falls back to the factory's `model`. */
+  model?: string;
+  /** Structured output schema. Omitted means plain text. */
+  outputSchema?: StandardSchemaV1;
+  /** Tools the host runs inside this one request. */
+  tools?: AgentTools;
+  /** Bounds the host-side tool loop (lowered to `metadata.maxSteps`). */
+  maxTurns?: number;
+}
+/** One delegated unit of work, lowered to an invoked child machine. */
+interface PresetMachineEntry {
+  /** What this entry is for. Shown to the routing/supervising model. */
+  description?: string;
+  /** The child machine to invoke. Registered as an actor source, so `runAgent` binds its executors. */
+  machine: AnyStateMachine;
+  /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
+  input?: (args: {
+    prompt: string;
+  }) => unknown;
+}
+/** A route/branch/worker/agent entry: an inline request, or a child machine. */
+type PresetEntry = PresetRequestEntry | PresetMachineEntry;
+//#endregion
+//#region src/machines/router.d.ts
+/** Config for {@link createRouterMachine}. */
+interface CreateRouterMachineConfig {
+  /** Model ref for the routing decision, and the default for request routes. */
+  model: string;
+  /** System prompt for the routing decision. */
+  instructions?: string;
+  /** The legal destinations, keyed by route name. Each is an inline request or a child machine. */
+  routes: Record<string, PresetEntry>;
+  /** Route taken when the routing decision errors. Without it, a failed decision ends the run. */
+  fallback?: string;
+}
+/** Context of a {@link createRouterMachine} machine. */
+type RouterContext = {
+  prompt: string;
+  route: string | null;
+  result: unknown;
+};
+/** The event a route decision chooses: `ROUTE_<name>`. */
+declare function routeEventType(route: string): string;
+/**
+ * One `agent.decide` picks exactly one declared route, then the machine runs
+ * it. Only the declared routes have events and transitions, so a model naming
+ * anything else is rejected before any work happens — illegal routes are
+ * impossible, not discouraged.
+ *
+ * States: `routing` → one state per route → `done`.
+ *
+ * ```ts
+ * const machine = createRouterMachine({
+ *   model: "quick",
+ *   routes: {
+ *     billing: { description: "Payments and invoices", instructions: "Answer the billing question." },
+ *     technical: { description: "Bugs and outages", machine: technicalMachine },
+ *   },
+ *   fallback: "technical",
+ * });
+ * ```
+ */
+declare function createRouterMachine(config: CreateRouterMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/parallel.d.ts
+/** Config for {@link createParallelMachine}. */
+interface CreateParallelMachineConfig {
+  /** Default model ref for request branches. */
+  model: string;
+  /** The branches, run concurrently. Each is an inline request or a child machine. */
+  branches: Record<string, PresetEntry>;
+}
+/** Context of a {@link createParallelMachine} machine. */
+type ParallelContext = {
+  prompt: string;
+  results: Record<string, unknown>;
+};
+/**
+ * Static fan-out: every branch runs concurrently as its own region of one
+ * parallel state, and the run joins when all of them finish. Results are keyed
+ * by branch name.
+ *
+ * Branch count is fixed at author time. For an N decided at run time (a planner
+ * choosing subtopics), eject to `examples/fan-out`, which spawns branches
+ * dynamically.
+ *
+ * States: `running` (one region per branch) → `done`.
+ *
+ * ```ts
+ * const machine = createParallelMachine({
+ *   model: "quick",
+ *   branches: {
+ *     security: { instructions: "Review for security issues." },
+ *     performance: { instructions: "Review for performance issues." },
+ *   },
+ * });
+ * ```
+ */
+declare function createParallelMachine(config: CreateParallelMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/loop.d.ts
+/** The accumulated state a {@link CreateLoopMachineConfig.until} predicate reads. */
+interface LoopState {
+  /** The machine's `input.prompt`. */
+  prompt: string;
+  /** Completed iterations. */
+  iterations: number;
+  /** Every iteration's output, in order. */
+  results: unknown[];
+  /** The latest iteration's output. */
+  last: unknown;
+}
+/** Config for {@link createLoopMachine}. */
+interface CreateLoopMachineConfig {
+  /** Default model ref for a request body. */
+  model: string;
+  /** The repeated unit of work: an inline request or a child machine. */
+  body: PresetEntry & {
+    /** Builds each iteration's prompt. Defaults to the machine's `prompt`. */prompt?: (state: LoopState) => string;
+  };
+  /** Stop condition, checked after each iteration. */
+  until: (state: LoopState) => boolean;
+  /** Hard upper bound on iterations, enforced by a guard. */
+  maxIterations: number;
+}
+/** Context of a {@link createLoopMachine} machine. */
+type LoopContext = {
+  prompt: string;
+  iterations: number;
+  results: unknown[];
+  last: unknown;
+};
+/**
+ * A bounded repeat: run the body, check `until` over the accumulated state,
+ * and either stop or go again. `maxIterations` is a guard, so the loop cannot
+ * run away even if `until` never returns `true`.
+ *
+ * States: `running` → `checking` → (`running` | `done`).
+ *
+ * ```ts
+ * const machine = createLoopMachine({
+ *   model: "quick",
+ *   body: { instructions: "Improve the draft. Return only the draft." },
+ *   until: ({ last }) => String(last).length > 500,
+ *   maxIterations: 4,
+ * });
+ * ```
+ */
+declare function createLoopMachine(config: CreateLoopMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/supervisor.d.ts
+/** Config for {@link createSupervisorMachine}. */
+interface CreateSupervisorMachineConfig {
+  /** Model ref for the supervising decision, and the default for request workers. */
+  model: string;
+  /** System prompt for the supervising decision. */
+  instructions?: string;
+  /** The workers the supervisor may delegate to, keyed by name. */
+  workers: Record<string, PresetEntry>;
+  /** Hard upper bound on delegations, enforced by a guard. Default 6. */
+  maxTurns?: number;
+}
+/** Context of a {@link createSupervisorMachine} machine. */
+type SupervisorContext = {
+  task: string;
+  results: Record<string, unknown>;
+  turns: number;
+  worker: string | null;
+};
+/** The event a supervising decision chooses to delegate to a worker: `DELEGATE_<name>`. */
+declare function delegateEventType(worker: string): string;
+/** The event a supervising decision chooses to stop. */
+declare const FINISH_EVENT_TYPE = "FINISH";
+/**
+ * A supervisor delegating to typed workers: each turn, one `agent.decide`
+ * picks a worker or `FINISH`. Worker results accumulate in context and are fed
+ * back into the next decision.
+ *
+ * Control always returns to the supervisor after a worker finishes — that is
+ * what separates this from {@link createHandoffMachine}, where control
+ * transfers and does not come back.
+ *
+ * `maxTurns` bounds the delegations twice over: a spent budget removes every
+ * `DELEGATE_*` from the decision's candidate events, and a guard on each
+ * delegate transition rejects one anyway. `FINISH` is all that is left.
+ *
+ * States: `supervising` → one state per worker → `supervising` → … → `done`.
+ *
+ * ```ts
+ * const machine = createSupervisorMachine({
+ *   model: "quick",
+ *   workers: {
+ *     researcher: { description: "Facts and background", instructions: "Research it." },
+ *     writer: { description: "Prose and summaries", instructions: "Write it up." },
+ *   },
+ *   maxTurns: 4,
+ * });
+ * ```
+ */
+declare function createSupervisorMachine(config: CreateSupervisorMachineConfig): AnyStateMachine;
+//#endregion
+//#region src/machines/handoff.d.ts
+/** Config for {@link createHandoffMachine}. */
+interface CreateHandoffMachineConfig {
+  /** The peer agents, keyed by name. Each is an inline request or a child machine. */
+  agents: Record<string, PresetEntry>;
+  /** Which agent holds the mic at the start of a run. */
+  defaultActiveAgent: string;
+  /** Default model ref for request agents that declare none. */
+  model?: string;
+}
+/** Context of a {@link createHandoffMachine} machine. */
+type HandoffContext = {
+  message: string;
+  activeAgent: string;
+  reply: unknown;
+};
+/** The event that hands the mic to a peer: `transfer_to_<name>`. */
+declare function transferEventType(agent: string): string;
+/**
+ * Peer handoff (the swarm shape): `context.activeAgent` holds the mic, runs one
+ * turn, then the machine settles idle in `waiting`. A `transfer_to_<name>`
+ * event moves the mic to a peer and re-routes.
+ *
+ * Control TRANSFERS and does not return — the opposite of
+ * {@link createSupervisorMachine}, where every worker hands control back.
+ *
+ * There is no final state: a conversation ends when the host stops resuming it.
+ * Persist the idle snapshot between turns; `activeAgent` round-trips with it.
+ *
+ * States: `routing` → one turn state per agent → `waiting` → `routing` → …
+ *
+ * ```ts
+ * const machine = createHandoffMachine({
+ *   model: "quick",
+ *   defaultActiveAgent: "travel",
+ *   agents: {
+ *     travel: { description: "Destinations and itineraries", instructions: "You are a travel concierge." },
+ *     food: { description: "Restaurants and dishes", instructions: "You are a food concierge." },
+ *   },
+ * });
+ *
+ * const next = await runAgent(machine, {
+ *   snapshot,
+ *   event: { type: "transfer_to_food", message: "What should I eat there?" },
+ *   executors,
+ * });
+ * ```
+ */
+declare function createHandoffMachine(config: CreateHandoffMachineConfig): AnyStateMachine;
+//#endregion
+export { type CreateHandoffMachineConfig, type CreateLoopMachineConfig, type CreateParallelMachineConfig, type CreateRouterMachineConfig, type CreateSequentialMachineConfig, type CreateSupervisorMachineConfig, type CreateToolLoopMachineConfig, FINISH_EVENT_TYPE, type HandoffContext, type LoopContext, type LoopState, type ParallelContext, type PresetEntry, type PresetMachineEntry, type PresetRequestEntry, type RouterContext, type SequentialContext, type SequentialPromptArgs, type SequentialStep, type SupervisorContext, type ToolLoopContext, createHandoffMachine, createLoopMachine, createParallelMachine, createRouterMachine, createSequentialMachine, createSupervisorMachine, createToolLoopMachine, delegateEventType, routeEventType, transferEventType };