@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.30

package/dist/{setup-agent-BuanDXeh.mjs → setup-agent-7rV_cujV.mjs}

@@ -1,7 +1,6 @@
-import { C as setAgentExecutionOptions, R as validateSchemaSync, S as missingActor, n as DECIDE_ACTOR, o as builtinTextActors, s as createTextLogic, y as getAgentExecutionOptions } from "./text-logic-CIqHAmBi.mjs";
-import { n as createDecideActor } from "./decision-RQ0iv0oZ.mjs";
-import { t as AGENT_USAGE_EVENT_TYPE } from "./usage-BdEjFuIi.mjs";
-import { createMachineFromConfig, setup } from "xstate";
+import { A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, G as missingActor, H as getAgentExecutionOptions, K as setAgentExecutionOptions, T as DECIDE_ACTOR, k as builtinTextActors, ot as validateSchemaSync } from "./event-log-DJCMHek_.mjs";
+import { r as createDecideActor } from "./decision-BHkvuImD.mjs";
+import { machineFromJSON, setup } from "xstate";
 //#region src/workflow-config.ts
 /**
 * The machines-as-data lowering: `setupAgent(...).fromConfig(config, options)`.
@@ -285,7 +284,8 @@ function setupAgentFromConfig(config, options) {
 		syntheticGuards: {},
 		transitionTargets: {}
 	};
-	const machine = createMachineFromConfig(translateWorkflowConfig(config, translation), {
+	const json = translateWorkflowConfig(config, translation);
+	const machine = machineFromJSON(json, {
 		guards: Object.fromEntries(Object.entries({
 			...translation.guards,
 			...translation.syntheticGuards
@@ -314,7 +314,12 @@ const emptyEventSchema = { "~standard": {
 	vendor: "statelyai-agent",
 	validate(value) {
 		return value !== null && typeof value === "object" && Object.keys(value).length === 0 ? { value: {} } : { issues: [{ message: "Expected an empty event payload" }] };
-	}
+	},
+	jsonSchema: { input: () => ({
+		type: "object",
+		properties: {},
+		additionalProperties: false
+	}) }
 } };
 const USAGE_TOKEN_FIELDS = [
 	"inputTokens",
@@ -451,7 +456,7 @@ function setupAgent(config) {
 	const schemas = normalizeAgentSchemas(config);
 	const requestActors = createRequestActors(config.requests ?? {});
 	const actors = createAgentActors(config.actors, requestActors);
-	const base = setup({
+	const setupConfig = {
 		schemas: {
 			context: schemas.context,
 			events: schemas.events,
@@ -465,7 +470,8 @@ function setupAgent(config) {
 		actions: config.actions,
 		guards: config.guards,
 		delays: config.delays
-	});
+	};
+	const base = setup(setupConfig);
 	const createBaseMachine = base.createMachine.bind(base);
 	const models = config.models ?? {};
 	const machineOptions = {
@@ -603,4 +609,4 @@ function createAgentActors(actors, requestActors) {
 	};
 }
 //#endregion
-export { getAgentSchemas as n, setupAgent as r, createAgentSchemas as t };
+export { setupAgentFromConfig as i, getAgentSchemas as n, setupAgent as r, createAgentSchemas as t };

package/dist/setup-agent-CGELn1qZ.d.mts

@@ -0,0 +1,577 @@
+import { _ as StandardSchemaV1, d as EventUnion, g as NormalizedEventSchemas, h as InferOutput, i as AgentToolChoice, m as InferInput, s as AgentTools, t as AgentEventSchemaInputMap, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.mjs";
+import { J as AgentSchemas, Y as EventFromSnapshot, _ as TextLogic, a as AgentModelRef, d as AgentRequestMode, h as BuiltinAgentActors, i as AgentModelMap, v as TextLogicConfig } from "./text-logic-BRYOPWvY.mjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BkM3z02Y.mjs";
+import { AnyActorLogic, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EventObject, MachineContext, MetaObject, NonReducibleUnknown, SetupReturnFromConfig, SetupStateSchema } from "xstate";
+//#region src/interaction.d.ts
+interface AgentInteractionEvent<TType extends string = string> {
+  type: TType;
+  label: string;
+  style?: string;
+  /** Optional fixed fields merged into the event when this choice is selected. */
+  event?: Record<string, unknown>;
+}
+/** One payload choice {@link getInteraction} resolved: a label and the full event it sends. */
+interface AgentInteractionChoice<TEvent extends EventObject = EventObject> {
+  label: string;
+  event: TEvent;
+  style?: string;
+}
+interface AgentInteraction<TEvent extends EventObject = EventObject> {
+  label: string;
+  events: AgentInteractionEvent<TEvent["type"]>[];
+  /**
+   * Payload choices from `choices`, each a full event the snapshot accepts
+   * right now. Present when the state declares `choices`.
+   */
+  choices?: AgentInteractionChoice<TEvent>[];
+  /** Event type used for a free-text response. */
+  textEvent?: TEvent["type"];
+  /** The `textEvent` field the text fills, when it is not `text`. */
+  textField?: string;
+}
+/** One payload choice as authored in `meta.interaction.choices`, inline or in a context array. */
+interface AgentInteractionChoiceMeta<TEvent extends string = string> {
+  /** Button text. `{path.to.field}` interpolates from the context. */
+  label: string;
+  /** The full event the choice sends. */
+  event: {
+    type: TEvent;
+    [key: string]: unknown;
+  };
+  style?: string;
+}
+/**
+ * One choice as authored in `meta.interaction.events`: a bare label, or a
+ * descriptor carrying a `style` and the fixed `event` fields merged in when the
+ * choice is selected.
+ */
+type AgentInteractionEventMeta = string | {
+  label?: string;
+  style?: string;
+  event?: Record<string, unknown>;
+};
+/**
+ * The `interaction` descriptor {@link getInteraction} reads off a state's meta.
+ * `TEvent` is the machine's event-type union, so a choice or `textEvent` that
+ * names an event the machine never declared is a compile error.
+ */
+interface AgentInteractionDescriptor<TEvent extends string = string> {
+  /** Label text, or a function of the machine context. `{path.to.field}` interpolates. */
+  label?: string | ((args: {
+    context: any;
+  }) => string);
+  events?: { [K in TEvent]?: AgentInteractionEventMeta; };
+  /**
+   * Payload choices: one button per full event, such as one per seat or per
+   * amount. A string is a context path to an array of the same shape,
+   * computed at runtime.
+   */
+  choices?: AgentInteractionChoiceMeta<TEvent>[] | string;
+  /**
+   * The free-text event. A bare type puts the text in a `text` field;
+   * `{ type, field }` names the field.
+   */
+  textEvent?: TEvent | {
+    type: TEvent;
+    field: string;
+  };
+}
+/**
+ * The state-meta shape the interaction protocol reads. `setupAgent` types
+ * every state's `meta` as this by default, with `TEvent` narrowed to the
+ * machine's declared events; see {@link interactionMetaSchema} for the runtime
+ * schema when a machine declares its own `meta` schema.
+ */
+interface AgentInteractionMeta<TEvent extends string = string> {
+  interaction?: AgentInteractionDescriptor<TEvent>;
+}
+/**
+ * A {@link StandardSchemaV1} for the state metadata {@link getInteraction}
+ * reads: an object whose optional `interaction` declares a `label` (a string
+ * with `{context.path}` interpolation, or a function of the context), an
+ * `events` map of choices, payload `choices` (an array, or a context path to
+ * one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
+ * the default `meta` type `setupAgent` gives a machine; pass it to
+ * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
+ * schema pack by hand.
+ */
+declare const interactionMetaSchema: StandardSchemaV1<AgentInteractionMeta>;
+/** Options for {@link getInteraction}. */
+interface GetInteractionOptions {
+  /**
+   * Keep label whitespace exactly as authored. Off by default: labels collapse
+   * runs of whitespace to single spaces and trim, so a multi-line template
+   * literal renders as one line and interpolated context cannot smuggle in
+   * layout. Turn it on when the label is deliberately multi-line (a rendered
+   * diff, a preformatted block).
+   */
+  preserveWhitespace?: boolean;
+}
+/** Reads the active state's interaction metadata and filters it through the
+ * events XState currently accepts. Returns `undefined` when none is declared. */
+declare function getInteraction<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, options?: GetInteractionOptions): AgentInteraction<EventFromSnapshot<TSnapshot>> | undefined;
+/**
+ * Converts a rendered interaction answer back into a schema-validated machine
+ * event:
+ *
+ * - `{ type, ...fields }` — an `events` choice; fixed fields declared in
+ *   metadata win over user fields.
+ * - `{ text }` — free text, placed in the `textEvent` field.
+ * - `{ choice }` — a payload choice, by its index in `getInteraction(snapshot).choices`
+ *   or by its label. A label that several choices share throws; pass the index.
+ */
+declare function eventFromInteraction<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, choice: ({
+  type: string;
+} & Record<string, unknown>) | {
+  text: string;
+} | {
+  choice: number | string;
+}): EventFromSnapshot<TSnapshot>;
+//#endregion
+//#region src/workflow-config.d.ts
+type JsonSchemaObject = {
+  type?: string | string[];
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  items?: JsonSchemaObject;
+  enum?: unknown[];
+  const?: unknown;
+  additionalProperties?: unknown;
+  [key: string]: unknown;
+};
+/**
+ * Compiles a JSON Schema object (from an `AgentWorkflowConfig`) into a
+ * runtime `StandardSchemaV1` validator. `setupAgent.fromConfig(...)` calls
+ * this once per schema in the config (context/events/input/output/meta,
+ * request input/output) — bring your own engine (Ajv, @cfworker/json-schema,
+ * a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no
+ * JSON Schema engine.
+ */
+type SchemaCompiler = (jsonSchema: Record<string, unknown>, name: string) => StandardSchemaV1;
+/**
+ * Serializable JSON/YAML machine definition — the config a database, visual
+ * editor, or LLM could produce and hand to `setupAgent.fromConfig(config, {
+ * compileSchema })` to get back the same kind of `AnyStateMachine`
+ * TypeScript `setupAgent(...)` authoring would build. JS/TS authoring should
+ * use `setupAgent(...)` directly instead of this JSON form. Any `unknown`-
+ * typed field here (`model`, `guard`, action `params`, …) accepts either a
+ * literal JSON value or a `"{{ path.to.value }}"` template-expression string
+ * resolved against `{ context, event, input, output }` at machine-build/
+ * transition time — see the sibling `evaluateWorkflowConfigValue` lowering.
+ */
+interface AgentWorkflowConfig {
+  /** JSON Schema reference (`"$schema"`) editors attach to a config file. Ignored by the lowering. */
+  $schema?: string;
+  key?: string;
+  id?: string;
+  version?: string;
+  description?: string;
+  schemas?: {
+    input?: JsonSchemaObject;
+    context?: JsonSchemaObject;
+    events?: Record<string, JsonSchemaObject>;
+    emitted?: Record<string, JsonSchemaObject>;
+    output?: JsonSchemaObject;
+    meta?: JsonSchemaObject;
+  };
+  context?: Record<string, unknown>;
+  requests?: Record<string, AgentWorkflowRequestConfig>;
+  actors?: Record<string, AgentWorkflowActorConfig>;
+  initial: string;
+  states: Record<string, AgentWorkflowStateConfig>;
+  meta?: Record<string, unknown>;
+}
+/** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
+interface AgentWorkflowRequestConfig {
+  mode?: AgentRequestMode;
+  description?: string;
+  model: unknown;
+  system?: unknown;
+  prompt?: unknown;
+  messages?: unknown;
+  input: JsonSchemaObject;
+  output: JsonSchemaObject;
+  tools?: AgentTools;
+  toolChoice?: AgentToolChoice | unknown;
+  /** Opt into the provider output's `reasoning` field (see `AgentTextRequest.includeReasoning`). */
+  includeReasoning?: boolean;
+  temperature?: unknown;
+  maxOutputTokens?: unknown;
+  topP?: unknown;
+  topK?: unknown;
+  seed?: unknown;
+  stopSequences?: unknown;
+  metadata?: unknown;
+}
+/** An `actors` entry in {@link AgentWorkflowConfig} — declares a placeholder actor source (by key) with no host execution wired from JSON; provide it via `machine.provide({ actors })` after `setupAgent.fromConfig(...)`. */
+interface AgentWorkflowActorConfig {
+  input?: JsonSchemaObject;
+  output?: JsonSchemaObject;
+  description?: string;
+}
+/** A `states` entry in {@link AgentWorkflowConfig} — the JSON equivalent of an XState state node config. */
+interface AgentWorkflowStateConfig {
+  description?: string;
+  type?: "parallel" | "history" | "final" | "choice";
+  initial?: string;
+  states?: Record<string, AgentWorkflowStateConfig>;
+  choice?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  invoke?: AgentWorkflowInvokeConfig | AgentWorkflowInvokeConfig[];
+  on?: Record<string, AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[]>;
+  always?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  onDone?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  after?: Record<string, AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[]>;
+  entry?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  exit?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  tags?: string[];
+  output?: unknown;
+  meta?: Record<string, unknown>;
+}
+/**
+ * An `invoke` entry in {@link AgentWorkflowStateConfig}. For `src:
+ * 'agent.decide'`, the chosen event is delivered automatically and handled by
+ * the state's `on` transitions — a decision has no output of its own, so an
+ * `onDone` there is always a config error and is rejected at
+ * `setupAgent.fromConfig(...)` time. `onError` handles retries-exhausted.
+ */
+interface AgentWorkflowInvokeConfig {
+  id?: string;
+  src: string;
+  input?: unknown;
+  onDone?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  onError?: AgentWorkflowTransitionConfig | AgentWorkflowTransitionConfig[];
+  meta?: Record<string, unknown>;
+}
+/**
+ * A transition target in {@link AgentWorkflowConfig}
+ * (`on`/`always`/`onDone`/`after`/invoke `onDone`/`onError`) — the JSON
+ * equivalent of an XState transition config. A string `guard` containing
+ * `{{ ... }}` is a template expression evaluated as truthy/falsy; any other
+ * string is a named guard reference resolved against the `guards` passed to
+ * `setupAgent.fromConfig(config, { guards })` (unresolvable references throw
+ * at build time).
+ */
+interface AgentWorkflowTransitionConfig {
+  target?: string | string[];
+  guard?: unknown;
+  assign?: Record<string, unknown>;
+  actions?: AgentWorkflowActionConfig | AgentWorkflowActionConfig[];
+  description?: string;
+  reenter?: boolean;
+  meta?: Record<string, unknown>;
+}
+/** An `entry`/`exit`/transition `actions` entry in {@link AgentWorkflowConfig} — a bare context `assign`, an `emit`, or a named action `type` (with template-expression `params`) resolved against the `actions` passed to `setupAgent.fromConfig(config, { actions })`. */
+interface AgentWorkflowActionConfig {
+  type?: string;
+  params?: unknown;
+  assign?: Record<string, unknown>;
+  emit?: unknown;
+  [key: string]: unknown;
+}
+/**
+ * What `setupAgent.fromConfig(...)` returns: the built machine plus the
+ * schema pack compiled from the config's `schemas` (with `compileSchema`).
+ * The pack is what hosts need for the runtime work the machine's types can't
+ * do for a JSON-authored agent — e.g. validating an inbound raw event:
+ *
+ * @example
+ * ```ts
+ * const { machine, schemas } = setupAgent.fromConfig(config, { compileSchema });
+ * const event = parseAgentEvent(snapshot, raw, { events: schemas.events });
+ * ```
+ */
+interface FromConfigResult {
+  machine: AnyStateMachine;
+  /** Compiled `context`/`events`/`input`/`output`/`meta`/`emitted` schemas — the same pack `createAgentRuntime` executes this machine with. */
+  schemas: AgentSchemaPack<StandardSchemaV1<Record<string, unknown>>, Record<string, StandardSchemaV1>, StandardSchemaV1, StandardSchemaV1, StandardSchemaV1<MetaObject>>;
+}
+/** Options for `setupAgent.fromConfig(...)`. */
+interface FromConfigOptions {
+  /**
+   * Compile a JSON Schema from the config into a runtime validator. Bring
+   * your own engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema
+   * pipeline, ...). Core intentionally ships no JSON Schema engine.
+   */
+  compileSchema: SchemaCompiler;
+  /**
+   * Host guard implementations for named guard references in the config
+   * (`guard: "isFromHuman"`). Each is called with `{ context, event }` and
+   * returns a boolean. A named guard reference with no implementation here is
+   * a build-time error — a guard is never silently dropped.
+   */
+  guards?: Record<string, (args: {
+    context: any;
+    event: any;
+  }) => boolean>;
+  /**
+   * Host action implementations for named action types in the config
+   * (`{ type: "notify", params: ... }`). Each is called with the
+   * template-resolved `params` as its only argument — pull context/event data
+   * into `params` via `{{ ... }}` templates. A named action type with no
+   * implementation here is a build-time error.
+   */
+  actions?: Record<string, (params: any) => unknown>;
+}
+//#endregion
+//#region src/setup-agent.d.ts
+type Constrain<T, TConstraint> = T extends TConstraint ? T : TConstraint;
+type ContextOf<TContextSchema extends StandardSchemaV1> = Constrain<InferOutput<TContextSchema>, MachineContext>;
+type EventsOf<TEventSchemas extends AgentEventSchemaInputMap> = Constrain<EventUnion<TEventSchemas>, EventObject>;
+/**
+ * The first argument a guard or delay source receives. `context` and `event`
+ * come from the agent's own schemas, so an inline source is contextually typed
+ * and an annotated one stays assignable. XState's remaining fields (`self`,
+ * `parent`, `value`, `children`, `stateNode`) are deliberately not modeled:
+ * `setupAgent` only forwards these sources to `setup()`, which types them for
+ * real where the machine is built.
+ */
+type AgentSourceArgs<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = {
+  context: ContextOf<TContextSchema>;
+  event: EventsOf<TEventSchemas>;
+};
+/** Guard sources for `setupAgent({ guards })`, typed against the agent's own context and events. */
+type AgentGuardSources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, (args: AgentSourceArgs<TContextSchema, TEventSchemas>, ...params: any[]) => boolean>;
+/** Delay sources for `setupAgent({ delays })`, typed the same way as {@link AgentGuardSources}. */
+type AgentDelaySources<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap> = Record<string, number | ((args: AgentSourceArgs<TContextSchema, TEventSchemas>) => number)>;
+type SetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic; }> = { [K in keyof TActors]: TActors[K] extends AsyncActorLogic<infer TOutput, infer TInput> ? AsyncActorLogic<TOutput, TInput> : TActors[K]; };
+type AgentSetupActors<TActors extends { [K in keyof TActors]: AnyActorLogic; }, TEvent extends string = string, TModel extends string = string> = TActors & BuiltinAgentActors<TEvent, TModel>;
+/**
+ * The default `meta` type of an agent machine: the interaction descriptor
+ * `getInteraction` reads, keyed by the machine's own event types (the
+ * reserved `@agent.*` events excluded). A machine that declares `meta`
+ * replaces this default.
+ */
+type AgentDefaultMeta<TEventSchemas extends AgentEventSchemaInputMap> = AgentInteractionMeta<Exclude<keyof TEventSchemas & string, typeof AGENT_USAGE_EVENT_TYPE>>;
+/**
+ * A machine's full schema set — context, event payloads, machine input/
+ * output, and state/transition meta — as returned by {@link createAgentSchemas}
+ * and retained on `setupAgent(...)`'s `result.schemas` for runtime
+ * validation (e.g. by `getAcceptedEvents` to attach event payload schemas). Unlike
+ * `AgentSchemaConfig` (the input to `createAgentSchemas`), every field here
+ * is required — `events`/`input`/`output`/`meta` default to empty/unknown
+ * schemas when not supplied.
+ */
+interface AgentSchemaPack<TContextSchema extends StandardSchemaV1<Record<string, unknown>> = StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap = AgentEventSchemaInputMap, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<AgentDefaultMeta<TEventSchemas>>, TEmittedSchemas extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> {
+  context: TContextSchema;
+  events: NormalizedEventSchemas<TEventSchemas>;
+  input: TInputSchema;
+  output: TOutputSchema;
+  meta: TMetaSchema;
+  /** Schemas for events the machine emits (`enq.emit(...)`), keyed by event type — they type `enq.emit` in the machine and the `on` handlers of {@link createAgentRuntime}. Optional: omitted means emitted events stay untyped. */
+  emitted?: TEmittedSchemas;
+}
+type AgentSchemaConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TEmittedSchemas extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
+  context: TContextSchema;
+  events?: TEventSchemas;
+  input?: TInputSchema;
+  output?: TOutputSchema;
+  meta?: TMetaSchema;
+  emitted?: TEmittedSchemas;
+};
+/**
+ * The payload of the reserved `'@agent.usage'` event — {@link AgentUsageEvent}
+ * without its `type`. It is what a machine's `'@agent.usage'` handler receives
+ * alongside `type`, since event schemas describe payloads only.
+ */
+type AgentUsageEventPayload = Omit<AgentUsageEvent, "type">;
+/**
+ * An authored event schema map with the reserved `'@agent.usage'` entry added —
+ * every agent machine's event union includes it, so `on: { '@agent.usage': … }`
+ * is typed (and autocompletes) without the machine declaring anything.
+ * Idempotent: re-applying it to an already-registered map is a no-op.
+ */
+type WithAgentEvents<T extends AgentEventSchemaInputMap> = Omit<T, typeof AGENT_USAGE_EVENT_TYPE> & {
+  [AGENT_USAGE_EVENT_TYPE]: StandardSchemaV1<AgentUsageEventPayload>;
+};
+/** @deprecated Use {@link WithAgentEvents}. */
+type WithAgentUsageEvent<T extends AgentEventSchemaInputMap> = WithAgentEvents<T>;
+/**
+ * Builds a machine's {@link AgentSchemaPack} from a partial schema
+ * declaration — only `context` is required; `events`/`input`/`output`/`meta`
+ * default to empty/unknown schemas when omitted. Pass the result as
+ * `setupAgent({ schemas })`'s `schemas` (or spread the individual fields
+ * directly into `setupAgent({ context, events, ... })` — both forms are
+ * accepted).
+ */
+declare function createAgentSchemas<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<AgentDefaultMeta<TEventSchemas>>, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}>(schemas: AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>): AgentSchemaPack<TContextSchema, WithAgentUsageEvent<TEventSchemas>, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
+type AgentRequestSchemaMap = Record<string, {
+  input?: StandardSchemaV1;
+  output?: StandardSchemaV1;
+}>;
+type ResolvedRequestSchema<TSchema, TFallback> = [NonNullable<TSchema>] extends [never] ? TFallback : [NonNullable<TSchema>] extends [StandardSchemaV1] ? NonNullable<TSchema> : TFallback;
+type RequestInputSchema<TSchemas extends {
+  input?: StandardSchemaV1;
+}> = ResolvedRequestSchema<TSchemas["input"], StandardSchemaV1<undefined>>;
+type RequestOutputSchema<TSchemas extends {
+  output?: StandardSchemaV1;
+}> = ResolvedRequestSchema<TSchemas["output"], StandardSchemaV1<string>>;
+type AgentRequestInput<TRequestSchemas extends AgentRequestSchemaMap, TModel extends string = string> = { [K in keyof TRequestSchemas]: Omit<TextLogicConfig<RequestInputSchema<TRequestSchemas[K]>, RequestOutputSchema<TRequestSchemas[K]>, Record<string, unknown>, TModel>, "schemas"> & {
+  schemas: TRequestSchemas[K];
+}; };
+type RequestActors<TRequestSchemas extends AgentRequestSchemaMap> = { [K in keyof TRequestSchemas]: TextLogic<RequestInputSchema<TRequestSchemas[K]>, RequestOutputSchema<TRequestSchemas[K]>>; };
+type AgentAllActors<TActors extends { [K in keyof TActors]: AnyActorLogic; }, TRequestSchemas extends AgentRequestSchemaMap> = TActors & RequestActors<TRequestSchemas>;
+type AgentSetupEventsSchema<TEventSchemas extends AgentEventSchemaInputMap> = {
+  events: NormalizedEventSchemas<WithAgentUsageEvent<TEventSchemas>>;
+};
+type AgentSetupEmittedSchema<TEmittedSchemas extends Record<string, StandardSchemaV1>> = [keyof TEmittedSchemas] extends [never] ? {} : {
+  emitted: TEmittedSchemas;
+};
+/**
+ * The input schema as handed to xstate's `setup(...)`, with the machine's input
+ * type branded by the schema it came from.
+ *
+ * XState resolves `schemas.input` to a single type used both by
+ * `createActor`'s `input` option and by the `context: ({ input })` factory —
+ * and it never validates, so a schema default reads as a required field at the
+ * call site while being absent at runtime. The runtime validates the input
+ * (filling defaults) and reads this brand back through `AgentInputFrom` to
+ * accept the schema's looser *input* side, while the factory keeps seeing the
+ * validated *output* side.
+ *
+ * Only object-shaped input is branded: with no declared input schema the
+ * resolved type is xstate's `NonReducibleUnknown` (a union including `null`),
+ * and intersecting a brand into that collapses members to `never`.
+ */
+type BrandedInputSchema<TInputSchema extends StandardSchemaV1> = InferOutput<TInputSchema> extends Record<string, unknown> ? StandardSchemaV1<InferInput<TInputSchema>, InferOutput<TInputSchema> & WithAgentInputSchema<TInputSchema>> : TInputSchema;
+type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic; }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = {
+  schemas: {
+    context: TContextSchema;
+    input: BrandedInputSchema<TInputSchema>;
+    output: TOutputSchema;
+    meta: TMetaSchema;
+  } & AgentSetupEventsSchema<TEventSchemas> & AgentSetupEmittedSchema<TEmittedSchemas>;
+  states?: TStateSchemas;
+  actors: SetupActors<AgentSetupActors<AgentAllActors<TActors, TRequestSchemas>, Exclude<keyof TEventSchemas & string, typeof AGENT_USAGE_EVENT_TYPE>, AgentModelRef<TModels>>>;
+  actions?: NonNullable<AnySetupConfig["actions"]>;
+  guards?: NonNullable<AnySetupConfig["guards"]>;
+  delays?: NonNullable<AnySetupConfig["delays"]>;
+};
+type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic; }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = ({
+  schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
+} | AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>) & {
+  models?: TModels;
+  actors?: TActors;
+  /**
+   * Per-state schemas, mirroring xstate's `setup({ states })`: narrow
+   * `context` inside a state (invoke `input`, transition fns, final `output`)
+   * — e.g. mark a field non-null in states only reachable after it is set.
+   * Use xstate's native `{ schemas: { context } }` form with a complete
+   * context schema.
+   */
+  states?: TStateSchemas;
+  requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
+  actions?: NonNullable<AnySetupConfig["actions"]>;
+  guards?: AgentGuardSources<TContextSchema, TEventSchemas>;
+  delays?: AgentDelaySources<TContextSchema, TEventSchemas>;
+};
+type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic; }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>>;
+/**
+ * The object returned by {@link setupAgent}: an xstate `setup(...)` result
+ * (`createMachine`, `assign`, …) extended with `schemas` (the resolved
+ * {@link AgentSchemaPack}), `models`, and `requests` (the built request
+ * actors). Machines created here are registered so
+ * `createAgentRuntime` can resolve their schemas/actors
+ * without re-passing them each call.
+ */
+type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic; }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
+  /**
+   * Creates the agent machine — XState's own `createMachine`, plus: the
+   * machine is registered so {@link createAgentRuntime} can resolve
+   * its schemas/actors without re-passing them, and a single final state's
+   * `output` is copied to the machine root when the root declares none.
+   */
+  createMachine: SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>["createMachine"];
+  /** The retained schema pack ({@link AgentSchemaPack}) for host-side validation and tooling. Its `events` include the reserved `'@agent.usage'` entry setupAgent registers by default. */
+  schemas: AgentSchemaPack<TContextSchema, WithAgentUsageEvent<TEventSchemas>, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
+  /** The `models` registry passed to `setupAgent(...)`, if any (used to type-narrow `AgentModelRef`). */
+  readonly models: TModels;
+  /** The {@link TextLogic} actors built from `setupAgent({ requests })`, keyed the same way. */
+  readonly requests: RequestActors<TRequestSchemas>;
+};
+/**
+ * Schema-first `setup(...)` for agent machines — the standard entry point
+ * for authoring a machine (the blueprint) that this library then runs (via
+ * {@link createAgentRuntime}) against host-supplied model/decision
+ * executors. Context, events, machine input, machine output, and
+ * state/transition meta are all standard schemas — no `{} as Type` casts —
+ * and are retained on `result.schemas` for runtime validation. Also
+ * registers the `agent.generateText`/`agent.streamText`/
+ * `agent.decide` builtin actors and lowers `requests`/`actors` into the
+ * machine's actor sources. The result is the xstate `setup(...)` object with
+ * a wrapped `result.createMachine(...)` plus `result.schemas`/`models`/
+ * `requests` attached. Also has a
+ * `setupAgent.fromConfig(...)` namespace member for building a machine from
+ * a serializable {@link AgentWorkflowConfig} instead of this TS API.
+ *
+ * @example
+ * ```ts
+ * const schemas = createAgentSchemas({
+ *   context: z.object({ topic: z.string(), joke: z.string().nullable() }),
+ *   input: z.object({ topic: z.string() }),
+ *   output: z.object({ joke: z.string() }),
+ * });
+ *
+ * const agent = setupAgent({
+ *   schemas,
+ *   actors: { tellJoke },
+ * });
+ *
+ * const jokeMachine = agent.createMachine({
+ *   context: ({ input }) => ({ topic: input.topic, joke: null }),
+ *   initial: 'telling',
+ *   states: {
+ *     telling: {
+ *       invoke: {
+ *         id: 'joke',
+ *         src: 'tellJoke',
+ *         input: ({ context }) => ({ topic: context.topic }),
+ *         onDone: ({ output }) => ({ target: 'done', context: { joke: output } }),
+ *       },
+ *     },
+ *     done: { type: 'final', output: ({ context }) => ({ joke: context.joke ?? '' }) },
+ *   },
+ * });
+ * ```
+ */
+declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends AgentEventSchemaInputMap, TActors extends { [K in keyof TActors]: AnyActorLogic; }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<AgentDefaultMeta<TEventSchemas>>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
+declare namespace setupAgent {
+  /**
+   * Builds a state machine from a serializable {@link AgentWorkflowConfig}
+   * (JSON/YAML) instead of the TypeScript `setupAgent(...)` API — the same
+   * kind of machine a database, visual editor, or LLM could produce and hand
+   * back. Requires a `compileSchema` (see {@link FromConfigOptions}) since
+   * the library bundles no JSON Schema engine itself; bring Ajv,
+   * @cfworker/json-schema, or another compiler that returns Standard Schema.
+   *
+   * Returns the built `machine` plus the compiled `schemas` pack (context,
+   * events, input, output, meta, emitted) — a JSON-authored agent has no
+   * TypeScript types, so hosts need the runtime schemas for things like
+   * validating an inbound raw event with `parseAgentEvent`.
+   *
+   * @example
+   * ```ts
+   * const { machine, schemas } = setupAgent.fromConfig(workflowConfig, {
+   *   compileSchema,
+   * });
+   * const result = await runToQuiescence(
+   *   createAgentRuntime(machine, { executors: { generateText, decide } }),
+   *   { input: { ticket } },
+   * );
+   * const event = parseAgentEvent(result.snapshot, raw, { events: schemas.events });
+   * ```
+   */
+  function fromConfig(config: AgentWorkflowConfig, options: FromConfigOptions): FromConfigResult;
+}
+/**
+ * The schema pack a machine was built with — `setupAgent(...).createMachine`
+ * and `setupAgent.fromConfig(...)` both register one, so hosts can read a
+ * machine's input/event schemas at runtime without knowing how it was
+ * authored. Returns `undefined` for machines not built by either (a plain
+ * xstate `createMachine`/`setup` machine).
+ *
+ * Registration also travels through `machine.provide(...)`: the pack is keyed
+ * on the machine's root `config`, which `.provide` shares by reference.
+ */
+declare function getAgentSchemas(machine: AnyStateMachine): AgentSchemas | undefined;
+//#endregion
+export { AgentInteractionEventMeta as C, getInteraction as D, eventFromInteraction as E, interactionMetaSchema as O, AgentInteractionEvent as S, GetInteractionOptions as T, FromConfigResult as _, WithAgentUsageEvent as a, AgentInteractionChoice as b, setupAgent as c, AgentWorkflowConfig as d, AgentWorkflowInvokeConfig as f, FromConfigOptions as g, AgentWorkflowTransitionConfig as h, WithAgentEvents as i, AgentWorkflowActionConfig as l, AgentWorkflowStateConfig as m, AgentSchemaPack as n, createAgentSchemas as o, AgentWorkflowRequestConfig as p, AgentUsageEventPayload as r, getAgentSchemas as s, AgentDefaultMeta as t, AgentWorkflowActorConfig as u, SchemaCompiler as v, AgentInteractionMeta as w, AgentInteractionDescriptor as x, AgentInteraction as y };