@statelyai/agent 2.0.0-alpha.21 → 2.0.0-alpha.22

package/dist/machines.d.cts

@@ -1,6 +1,46 @@
 import { c as AgentTools, v as StandardSchemaV1 } from "./types-DSdj2tGs.cjs";
-import { AnyStateMachine } from "xstate";
+import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
 
+//#region src/machines/internal.d.ts
+/**
+ * The machine type a preset factory returns: its context, event union, input
+ * and output are all concrete, so callers get typed `runAgent` input and
+ * output instead of `AnyStateMachine`. The remaining slots (children, state
+ * value/tags/config, source maps) are left permissive — a preset builds its
+ * states dynamically, so there is no literal state schema to infer.
+ *
+ * @internal
+ */
+type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
+/** 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 the request's typed `maxSteps`). */
+  maxSteps?: 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/tool-loop.d.ts
 /** Config for {@link createToolLoopMachine}. */
 interface CreateToolLoopMachineConfig {
@@ -24,6 +64,16 @@ type ToolLoopContext = {
   prompt: string;
   result: unknown;
 };
+/** Machine input of a {@link createToolLoopMachine} machine. */
+type ToolLoopInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createToolLoopMachine} machine. */
+type ToolLoopOutput = {
+  result: unknown;
+};
+/** The machine {@link createToolLoopMachine} returns. */
+type ToolLoopMachine = PresetMachine<ToolLoopContext, ToolLoopInput, ToolLoopOutput>;
 /**
  * The single-state tool loop: one text request carries the `tools`, and the
  * host runs the tool loop inside it (`maxSteps` bounds it). Selecting and
@@ -46,7 +96,7 @@ type ToolLoopContext = {
  * // Snapshots and log entries carry machine.version ("1") automatically.
  * ```
  */
-declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): AnyStateMachine;
+declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): ToolLoopMachine;
 //#endregion
 //#region src/machines/sequential.d.ts
 /** Arguments a {@link SequentialStep}'s `prompt` receives. */
@@ -88,6 +138,17 @@ type SequentialContext = {
   results: Record<string, unknown>;
   previous: unknown;
 };
+/** Machine input of a {@link createSequentialMachine} machine. */
+type SequentialInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createSequentialMachine} machine. */
+type SequentialOutput = {
+  results: Record<string, unknown>;
+  output: unknown;
+};
+/** The machine {@link createSequentialMachine} returns. */
+type SequentialMachine = PresetMachine<SequentialContext, SequentialInput, SequentialOutput>;
 /**
  * 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
@@ -106,56 +167,41 @@ type SequentialContext = {
  * });
  * ```
  */
-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 the request's typed `maxSteps`). */
-  maxSteps?: 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;
+declare function createSequentialMachine(config: CreateSequentialMachineConfig): SequentialMachine;
 //#endregion
 //#region src/machines/router.d.ts
 /** Config for {@link createRouterMachine}. */
-interface CreateRouterMachineConfig {
+interface CreateRouterMachineConfig<TRoutes extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** 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>;
+  routes: TRoutes;
   /** Route taken when the routing decision errors. Without it, a failed decision ends the run. */
-  fallback?: string;
+  fallback?: keyof TRoutes & string;
 }
 /** Context of a {@link createRouterMachine} machine. */
-type RouterContext = {
+type RouterContext<TRoute extends string = string> = {
   prompt: string;
-  route: string | null;
+  route: TRoute | null;
   result: unknown;
 };
+/** Machine input of a {@link createRouterMachine} machine. */
+type RouterInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createRouterMachine} machine. */
+type RouterOutput<TRoute extends string = string> = {
+  route: TRoute | null;
+  result: unknown;
+};
+/** The events a {@link createRouterMachine} machine accepts: one per declared route. */
+type RouterEvent<TRoute extends string = string> = {
+  type: `ROUTE_${TRoute}`;
+};
+/** The machine {@link createRouterMachine} returns. */
+type RouterMachine<TRoute extends string = string> = PresetMachine<RouterContext<TRoute>, RouterInput, RouterOutput<TRoute>, RouterEvent<TRoute>>;
 /** The event a route decision chooses: `ROUTE_<name>`. */
 declare function routeEventType(route: string): string;
 /**
@@ -177,7 +223,7 @@ declare function routeEventType(route: string): string;
  * });
  * ```
  */
-declare function createRouterMachine(config: CreateRouterMachineConfig): AnyStateMachine;
+declare function createRouterMachine<const TRoutes extends Record<string, PresetEntry>>(config: CreateRouterMachineConfig<TRoutes>): RouterMachine<keyof TRoutes & string>;
 //#endregion
 //#region src/machines/parallel.d.ts
 /** Config for {@link createParallelMachine}. */
@@ -192,6 +238,16 @@ type ParallelContext = {
   prompt: string;
   results: Record<string, unknown>;
 };
+/** Machine input of a {@link createParallelMachine} machine. */
+type ParallelInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createParallelMachine} machine. */
+type ParallelOutput = {
+  results: Record<string, unknown>;
+};
+/** The machine {@link createParallelMachine} returns. */
+type ParallelMachine = PresetMachine<ParallelContext, ParallelInput, ParallelOutput>;
 /**
  * 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
@@ -213,7 +269,7 @@ type ParallelContext = {
  * });
  * ```
  */
-declare function createParallelMachine(config: CreateParallelMachineConfig): AnyStateMachine;
+declare function createParallelMachine(config: CreateParallelMachineConfig): ParallelMachine;
 //#endregion
 //#region src/machines/loop.d.ts
 /** The accumulated state a {@link CreateLoopMachineConfig.until} predicate reads. */
@@ -247,6 +303,18 @@ type LoopContext = {
   results: unknown[];
   last: unknown;
 };
+/** Machine input of a {@link createLoopMachine} machine. */
+type LoopInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createLoopMachine} machine. */
+type LoopOutput = {
+  iterations: number;
+  results: unknown[];
+  last: unknown;
+};
+/** The machine {@link createLoopMachine} returns. */
+type LoopMachine = PresetMachine<LoopContext, LoopInput, LoopOutput>;
 /**
  * A bounded repeat: run the body, check `until` over the accumulated state,
  * and either stop or go again. `maxTurns` is a guard, so the loop cannot
@@ -263,27 +331,44 @@ type LoopContext = {
  * });
  * ```
  */
-declare function createLoopMachine(config: CreateLoopMachineConfig): AnyStateMachine;
+declare function createLoopMachine(config: CreateLoopMachineConfig): LoopMachine;
 //#endregion
 //#region src/machines/supervisor.d.ts
 /** Config for {@link createSupervisorMachine}. */
-interface CreateSupervisorMachineConfig {
+interface CreateSupervisorMachineConfig<TWorkers extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** 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>;
+  workers: TWorkers;
   /** Hard upper bound on delegations, enforced by a guard. Default 6. */
   maxTurns?: number;
 }
 /** Context of a {@link createSupervisorMachine} machine. */
-type SupervisorContext = {
+type SupervisorContext<TWorker extends string = string> = {
   task: string;
   results: Record<string, unknown>;
   turns: number;
-  worker: string | null;
+  worker: TWorker | null;
+};
+/** Machine input of a {@link createSupervisorMachine} machine. */
+type SupervisorInput = {
+  task: string;
 };
+/** Machine output of a {@link createSupervisorMachine} machine. */
+type SupervisorOutput = {
+  results: Record<string, unknown>;
+  turns: number;
+};
+/** The events a {@link createSupervisorMachine} machine accepts: one per worker, plus `FINISH`. */
+type SupervisorEvent<TWorker extends string = string> = {
+  type: `DELEGATE_${TWorker}`;
+} | {
+  type: typeof FINISH_EVENT_TYPE;
+};
+/** The machine {@link createSupervisorMachine} returns. */
+type SupervisorMachine<TWorker extends string = string> = PresetMachine<SupervisorContext<TWorker>, SupervisorInput, SupervisorOutput, SupervisorEvent<TWorker>>;
 /** 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. */
@@ -314,24 +399,36 @@ declare const FINISH_EVENT_TYPE = "FINISH";
  * });
  * ```
  */
-declare function createSupervisorMachine(config: CreateSupervisorMachineConfig): AnyStateMachine;
+declare function createSupervisorMachine<const TWorkers extends Record<string, PresetEntry>>(config: CreateSupervisorMachineConfig<TWorkers>): SupervisorMachine<keyof TWorkers & string>;
 //#endregion
 //#region src/machines/handoff.d.ts
 /** Config for {@link createHandoffMachine}. */
-interface CreateHandoffMachineConfig {
+interface CreateHandoffMachineConfig<TAgents extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** The peer agents, keyed by name. Each is an inline request or a child machine. */
-  agents: Record<string, PresetEntry>;
+  agents: TAgents;
   /** Which agent holds the mic at the start of a run. */
-  defaultActiveAgent: string;
+  defaultActiveAgent: keyof TAgents & string;
   /** Default model ref for request agents that declare none. */
   model?: string;
 }
 /** Context of a {@link createHandoffMachine} machine. */
-type HandoffContext = {
+type HandoffContext<TAgent extends string = string> = {
   message: string;
-  activeAgent: string;
+  activeAgent: TAgent;
   reply: unknown;
 };
+/** Machine input of a {@link createHandoffMachine} machine. */
+type HandoffInput<TAgent extends string = string> = {
+  message: string;
+  activeAgent?: TAgent;
+};
+/** The events a {@link createHandoffMachine} machine accepts: one per peer agent. */
+type HandoffEvent<TAgent extends string = string> = {
+  type: `transfer_to_${TAgent}`;
+  message?: string;
+};
+/** The machine {@link createHandoffMachine} returns. There is no final state, so it has no output. */
+type HandoffMachine<TAgent extends string = string> = PresetMachine<HandoffContext<TAgent>, HandoffInput<TAgent>, undefined, HandoffEvent<TAgent>>;
 /** The event that hands the mic to a peer: `transfer_to_<name>`. */
 declare function transferEventType(agent: string): string;
 /**
@@ -364,6 +461,6 @@ declare function transferEventType(agent: string): string;
  * });
  * ```
  */
-declare function createHandoffMachine(config: CreateHandoffMachineConfig): AnyStateMachine;
+declare function createHandoffMachine<const TAgents extends Record<string, PresetEntry>>(config: CreateHandoffMachineConfig<TAgents>): HandoffMachine<keyof TAgents & string>;
 //#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 };
+export { type CreateHandoffMachineConfig, type CreateLoopMachineConfig, type CreateParallelMachineConfig, type CreateRouterMachineConfig, type CreateSequentialMachineConfig, type CreateSupervisorMachineConfig, type CreateToolLoopMachineConfig, FINISH_EVENT_TYPE, type HandoffContext, type HandoffEvent, type HandoffInput, type HandoffMachine, type LoopContext, type LoopInput, type LoopMachine, type LoopOutput, type LoopState, type ParallelContext, type ParallelInput, type ParallelMachine, type ParallelOutput, type PresetEntry, type PresetMachine, type PresetMachineEntry, type PresetRequestEntry, type RouterContext, type RouterEvent, type RouterInput, type RouterMachine, type RouterOutput, type SequentialContext, type SequentialInput, type SequentialMachine, type SequentialOutput, type SequentialPromptArgs, type SequentialStep, type SupervisorContext, type SupervisorEvent, type SupervisorInput, type SupervisorMachine, type SupervisorOutput, type ToolLoopContext, type ToolLoopInput, type ToolLoopMachine, type ToolLoopOutput, createHandoffMachine, createLoopMachine, createParallelMachine, createRouterMachine, createSequentialMachine, createSupervisorMachine, createToolLoopMachine, delegateEventType, routeEventType, transferEventType };

package/dist/machines.d.mts

@@ -1,6 +1,46 @@
 import { c as AgentTools, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
-import { AnyStateMachine } from "xstate";
+import { AnyActorRef, AnyStateMachine, EventObject, MachineContext, MetaObject, StateMachine, StateSchema, StateValue } from "xstate";
 
+//#region src/machines/internal.d.ts
+/**
+ * The machine type a preset factory returns: its context, event union, input
+ * and output are all concrete, so callers get typed `runAgent` input and
+ * output instead of `AnyStateMachine`. The remaining slots (children, state
+ * value/tags/config, source maps) are left permissive — a preset builds its
+ * states dynamically, so there is no literal state schema to infer.
+ *
+ * @internal
+ */
+type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
+/** 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 the request's typed `maxSteps`). */
+  maxSteps?: 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/tool-loop.d.ts
 /** Config for {@link createToolLoopMachine}. */
 interface CreateToolLoopMachineConfig {
@@ -24,6 +64,16 @@ type ToolLoopContext = {
   prompt: string;
   result: unknown;
 };
+/** Machine input of a {@link createToolLoopMachine} machine. */
+type ToolLoopInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createToolLoopMachine} machine. */
+type ToolLoopOutput = {
+  result: unknown;
+};
+/** The machine {@link createToolLoopMachine} returns. */
+type ToolLoopMachine = PresetMachine<ToolLoopContext, ToolLoopInput, ToolLoopOutput>;
 /**
  * The single-state tool loop: one text request carries the `tools`, and the
  * host runs the tool loop inside it (`maxSteps` bounds it). Selecting and
@@ -46,7 +96,7 @@ type ToolLoopContext = {
  * // Snapshots and log entries carry machine.version ("1") automatically.
  * ```
  */
-declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): AnyStateMachine;
+declare function createToolLoopMachine(config: CreateToolLoopMachineConfig): ToolLoopMachine;
 //#endregion
 //#region src/machines/sequential.d.ts
 /** Arguments a {@link SequentialStep}'s `prompt` receives. */
@@ -88,6 +138,17 @@ type SequentialContext = {
   results: Record<string, unknown>;
   previous: unknown;
 };
+/** Machine input of a {@link createSequentialMachine} machine. */
+type SequentialInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createSequentialMachine} machine. */
+type SequentialOutput = {
+  results: Record<string, unknown>;
+  output: unknown;
+};
+/** The machine {@link createSequentialMachine} returns. */
+type SequentialMachine = PresetMachine<SequentialContext, SequentialInput, SequentialOutput>;
 /**
  * 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
@@ -106,56 +167,41 @@ type SequentialContext = {
  * });
  * ```
  */
-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 the request's typed `maxSteps`). */
-  maxSteps?: 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;
+declare function createSequentialMachine(config: CreateSequentialMachineConfig): SequentialMachine;
 //#endregion
 //#region src/machines/router.d.ts
 /** Config for {@link createRouterMachine}. */
-interface CreateRouterMachineConfig {
+interface CreateRouterMachineConfig<TRoutes extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** 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>;
+  routes: TRoutes;
   /** Route taken when the routing decision errors. Without it, a failed decision ends the run. */
-  fallback?: string;
+  fallback?: keyof TRoutes & string;
 }
 /** Context of a {@link createRouterMachine} machine. */
-type RouterContext = {
+type RouterContext<TRoute extends string = string> = {
   prompt: string;
-  route: string | null;
+  route: TRoute | null;
   result: unknown;
 };
+/** Machine input of a {@link createRouterMachine} machine. */
+type RouterInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createRouterMachine} machine. */
+type RouterOutput<TRoute extends string = string> = {
+  route: TRoute | null;
+  result: unknown;
+};
+/** The events a {@link createRouterMachine} machine accepts: one per declared route. */
+type RouterEvent<TRoute extends string = string> = {
+  type: `ROUTE_${TRoute}`;
+};
+/** The machine {@link createRouterMachine} returns. */
+type RouterMachine<TRoute extends string = string> = PresetMachine<RouterContext<TRoute>, RouterInput, RouterOutput<TRoute>, RouterEvent<TRoute>>;
 /** The event a route decision chooses: `ROUTE_<name>`. */
 declare function routeEventType(route: string): string;
 /**
@@ -177,7 +223,7 @@ declare function routeEventType(route: string): string;
  * });
  * ```
  */
-declare function createRouterMachine(config: CreateRouterMachineConfig): AnyStateMachine;
+declare function createRouterMachine<const TRoutes extends Record<string, PresetEntry>>(config: CreateRouterMachineConfig<TRoutes>): RouterMachine<keyof TRoutes & string>;
 //#endregion
 //#region src/machines/parallel.d.ts
 /** Config for {@link createParallelMachine}. */
@@ -192,6 +238,16 @@ type ParallelContext = {
   prompt: string;
   results: Record<string, unknown>;
 };
+/** Machine input of a {@link createParallelMachine} machine. */
+type ParallelInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createParallelMachine} machine. */
+type ParallelOutput = {
+  results: Record<string, unknown>;
+};
+/** The machine {@link createParallelMachine} returns. */
+type ParallelMachine = PresetMachine<ParallelContext, ParallelInput, ParallelOutput>;
 /**
  * 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
@@ -213,7 +269,7 @@ type ParallelContext = {
  * });
  * ```
  */
-declare function createParallelMachine(config: CreateParallelMachineConfig): AnyStateMachine;
+declare function createParallelMachine(config: CreateParallelMachineConfig): ParallelMachine;
 //#endregion
 //#region src/machines/loop.d.ts
 /** The accumulated state a {@link CreateLoopMachineConfig.until} predicate reads. */
@@ -247,6 +303,18 @@ type LoopContext = {
   results: unknown[];
   last: unknown;
 };
+/** Machine input of a {@link createLoopMachine} machine. */
+type LoopInput = {
+  prompt: string;
+};
+/** Machine output of a {@link createLoopMachine} machine. */
+type LoopOutput = {
+  iterations: number;
+  results: unknown[];
+  last: unknown;
+};
+/** The machine {@link createLoopMachine} returns. */
+type LoopMachine = PresetMachine<LoopContext, LoopInput, LoopOutput>;
 /**
  * A bounded repeat: run the body, check `until` over the accumulated state,
  * and either stop or go again. `maxTurns` is a guard, so the loop cannot
@@ -263,27 +331,44 @@ type LoopContext = {
  * });
  * ```
  */
-declare function createLoopMachine(config: CreateLoopMachineConfig): AnyStateMachine;
+declare function createLoopMachine(config: CreateLoopMachineConfig): LoopMachine;
 //#endregion
 //#region src/machines/supervisor.d.ts
 /** Config for {@link createSupervisorMachine}. */
-interface CreateSupervisorMachineConfig {
+interface CreateSupervisorMachineConfig<TWorkers extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** 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>;
+  workers: TWorkers;
   /** Hard upper bound on delegations, enforced by a guard. Default 6. */
   maxTurns?: number;
 }
 /** Context of a {@link createSupervisorMachine} machine. */
-type SupervisorContext = {
+type SupervisorContext<TWorker extends string = string> = {
   task: string;
   results: Record<string, unknown>;
   turns: number;
-  worker: string | null;
+  worker: TWorker | null;
+};
+/** Machine input of a {@link createSupervisorMachine} machine. */
+type SupervisorInput = {
+  task: string;
 };
+/** Machine output of a {@link createSupervisorMachine} machine. */
+type SupervisorOutput = {
+  results: Record<string, unknown>;
+  turns: number;
+};
+/** The events a {@link createSupervisorMachine} machine accepts: one per worker, plus `FINISH`. */
+type SupervisorEvent<TWorker extends string = string> = {
+  type: `DELEGATE_${TWorker}`;
+} | {
+  type: typeof FINISH_EVENT_TYPE;
+};
+/** The machine {@link createSupervisorMachine} returns. */
+type SupervisorMachine<TWorker extends string = string> = PresetMachine<SupervisorContext<TWorker>, SupervisorInput, SupervisorOutput, SupervisorEvent<TWorker>>;
 /** 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. */
@@ -314,24 +399,36 @@ declare const FINISH_EVENT_TYPE = "FINISH";
  * });
  * ```
  */
-declare function createSupervisorMachine(config: CreateSupervisorMachineConfig): AnyStateMachine;
+declare function createSupervisorMachine<const TWorkers extends Record<string, PresetEntry>>(config: CreateSupervisorMachineConfig<TWorkers>): SupervisorMachine<keyof TWorkers & string>;
 //#endregion
 //#region src/machines/handoff.d.ts
 /** Config for {@link createHandoffMachine}. */
-interface CreateHandoffMachineConfig {
+interface CreateHandoffMachineConfig<TAgents extends Record<string, PresetEntry> = Record<string, PresetEntry>> {
   /** The peer agents, keyed by name. Each is an inline request or a child machine. */
-  agents: Record<string, PresetEntry>;
+  agents: TAgents;
   /** Which agent holds the mic at the start of a run. */
-  defaultActiveAgent: string;
+  defaultActiveAgent: keyof TAgents & string;
   /** Default model ref for request agents that declare none. */
   model?: string;
 }
 /** Context of a {@link createHandoffMachine} machine. */
-type HandoffContext = {
+type HandoffContext<TAgent extends string = string> = {
   message: string;
-  activeAgent: string;
+  activeAgent: TAgent;
   reply: unknown;
 };
+/** Machine input of a {@link createHandoffMachine} machine. */
+type HandoffInput<TAgent extends string = string> = {
+  message: string;
+  activeAgent?: TAgent;
+};
+/** The events a {@link createHandoffMachine} machine accepts: one per peer agent. */
+type HandoffEvent<TAgent extends string = string> = {
+  type: `transfer_to_${TAgent}`;
+  message?: string;
+};
+/** The machine {@link createHandoffMachine} returns. There is no final state, so it has no output. */
+type HandoffMachine<TAgent extends string = string> = PresetMachine<HandoffContext<TAgent>, HandoffInput<TAgent>, undefined, HandoffEvent<TAgent>>;
 /** The event that hands the mic to a peer: `transfer_to_<name>`. */
 declare function transferEventType(agent: string): string;
 /**
@@ -364,6 +461,6 @@ declare function transferEventType(agent: string): string;
  * });
  * ```
  */
-declare function createHandoffMachine(config: CreateHandoffMachineConfig): AnyStateMachine;
+declare function createHandoffMachine<const TAgents extends Record<string, PresetEntry>>(config: CreateHandoffMachineConfig<TAgents>): HandoffMachine<keyof TAgents & string>;
 //#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 };
+export { type CreateHandoffMachineConfig, type CreateLoopMachineConfig, type CreateParallelMachineConfig, type CreateRouterMachineConfig, type CreateSequentialMachineConfig, type CreateSupervisorMachineConfig, type CreateToolLoopMachineConfig, FINISH_EVENT_TYPE, type HandoffContext, type HandoffEvent, type HandoffInput, type HandoffMachine, type LoopContext, type LoopInput, type LoopMachine, type LoopOutput, type LoopState, type ParallelContext, type ParallelInput, type ParallelMachine, type ParallelOutput, type PresetEntry, type PresetMachine, type PresetMachineEntry, type PresetRequestEntry, type RouterContext, type RouterEvent, type RouterInput, type RouterMachine, type RouterOutput, type SequentialContext, type SequentialInput, type SequentialMachine, type SequentialOutput, type SequentialPromptArgs, type SequentialStep, type SupervisorContext, type SupervisorEvent, type SupervisorInput, type SupervisorMachine, type SupervisorOutput, type ToolLoopContext, type ToolLoopInput, type ToolLoopMachine, type ToolLoopOutput, createHandoffMachine, createLoopMachine, createParallelMachine, createRouterMachine, createSequentialMachine, createSupervisorMachine, createToolLoopMachine, delegateEventType, routeEventType, transferEventType };

package/dist/machines.mjs

@@ -1,4 +1,4 @@
-import { r as setupAgent } from "./setup-agent-DqqdcdNh.mjs";
+import { r as setupAgent } from "./setup-agent-nSFYrNTP.mjs";
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";

package/dist/otel.d.cts

@@ -1,4 +1,4 @@
-import { d as AgentTraceEvent } from "./run-agent-Do094mGu.cjs";
+import { d as AgentTraceEvent } from "./run-agent-Zbkx7XP8.cjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts

package/dist/otel.d.mts

@@ -1,4 +1,4 @@
-import { d as AgentTraceEvent } from "./run-agent-DBNI8ETM.mjs";
+import { d as AgentTraceEvent } from "./run-agent-0fpEZ1wJ.mjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts