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

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { A as getJsonSchema, B as userMessage, D as assistantMessage, F as getStatePath, H as AgentError, I as isStandardSchema, M as getMachineStructuralHash, N as getMessageText, P as getStateMeta, R as systemMessage, U as AgentTruncatedError, a as bindRequestExecutor, b as getAgentExecutionOptions, d as getCallUsage, f as isTextLogic, g as providerOutputSchema, h as parseProviderOutput, j as getJsonSchemaSync, l as getAgentOutputMode, m as parseOutput, s as createTextLogic, u as getCallFinishReason, y as executorBoundLogics, z as toolMessage } from "./text-logic-Bl_ZRxDi.mjs";
-import { a as isDecisionLogic, c as AgentInvalidEventPayloadError, i as createDecisionRequest, l as getAcceptedEvents, o as renderDecisionAttempts, r as createDecisionLogic, s as resolveDecision, t as AgentDecisionExhaustedError, u as parseAgentEvent } from "./decision-DzSv1NpD.mjs";
+import { A as getMessageText, B as AgentTruncatedError, D as getJsonSchema, F as systemMessage, I as toolMessage, L as userMessage, M as getStatePath, N as isStandardSchema, O as getJsonSchemaSync, a as bindRequestExecutor, c as getAgentOutputMode, d as isTextLogic, h as providerOutputSchema, j as getStateMeta, k as getMachineStructuralHash, l as getCallFinishReason, m as parseProviderOutput, p as parseOutput, s as createTextLogic, u as getCallUsage, v as executorBoundLogics, w as assistantMessage, y as getAgentExecutionOptions, z as AgentError } from "./text-logic-CIqHAmBi.mjs";
+import { a as isDecisionLogic, c as AgentInvalidEventPayloadError, i as createDecisionRequest, l as getAcceptedEvents, o as renderDecisionAttempts, r as createDecisionLogic, s as resolveDecision, t as AgentDecisionExhaustedError, u as parseAgentEvent } from "./decision-RQ0iv0oZ.mjs";
 import { t as AGENT_USAGE_EVENT_TYPE } from "./usage-BdEjFuIi.mjs";
-import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-CFW-jPI8.mjs";
-import { _ as rejectAgentStep, a as bindDecisionForProvide, c as inspectTransitions, d as runAgent, f as serializeTraceEvent, g as initialAgentStep, i as bindChildMachineForProvide, l as isAgentIdle, m as executeAgentRequest, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as traceTransitions, r as AgentSnapshotDivergedError, s as getConfiguredInvokeSrcs, t as AGENT_TRACE_SCHEMA_VERSION, u as isStateMachineLogic, v as resolveAgentStep, y as transitionAgentStep } from "./run-agent-DvDQd4If.mjs";
-import { o as AgentMachineVersionMismatchError, t as AgentEventLogConflictError } from "./event-log-store-Ba2fsc4E.mjs";
+import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-BuanDXeh.mjs";
+import { o as AgentMachineVersionMismatchError, t as AgentEventLogConflictError } from "./event-log-store-2pAFiWuc.mjs";
+import { a as bindDecisionForProvide, c as getConfiguredInvokeSrcs, d as isStateMachineLogic, f as runToQuiescence, i as bindChildMachineForProvide, l as inspectTransitions, m as traceTransitions, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as serializeTraceEvent, r as AgentSnapshotDivergedError, s as createAgentRuntime, t as AGENT_TRACE_SCHEMA_VERSION, u as isAgentIdle } from "./run-agent-xNTxpt82.mjs";
 //#region src/messages.ts
 const KNOWN_PART_TYPES = new Set([
 	"text",
@@ -256,189 +256,12 @@ function eventFromInteraction(snapshot, choice) {
 	return parseAgentEvent(snapshot, event);
 }
 //#endregion
-//#region src/agent-run.ts
-/**
-* Wraps {@link runAgent} in a canonical run-stream handle: the run's trace
-* events as a pull-based {@link AgentRun.events} async iterator, alongside the
-* unchanged {@link AgentRun.result} promise.
-*
-* Semantics:
-*
-* 1. **Starts immediately.** The underlying `runAgent` is invoked on this call,
-*    not on the first `events` iteration — work is already in flight when
-*    `createAgentRun` returns.
-* 2. **Buffer, don't stall.** Events are queued in an unbounded in-memory
-*    buffer as the run emits them; a slow or absent consumer never applies
-*    backpressure to the run. Once `run.end` is delivered, the iterator
-*    completes.
-* 3. **Composes `onTrace`.** If `options.onTrace` is passed, it still fires for
-*    every event — the wrapper adds queue delivery, it does not replace the
-*    caller's sink.
-* 4. **`result` mirrors `runAgent`.** Same resolution and rejection behavior
-*    (see {@link AgentRun.result}). A no-op rejection handler is attached
-*    internally so a caller who reads only `events` never trips an unhandled
-*    rejection on a bind-time throw; the returned promise still rejects for a
-*    caller who awaits it.
-* 5. **Resume is identical.** Options pass straight through, so starting from a
-*    persisted `snapshot` (+ resume `event`) streams that run's events from its
-*    own `run.start`, exactly as `runAgent` would run it.
-* 6. **Early termination does not cancel the run.** Breaking out of a
-*    `for await` (or calling `events.return()`) stops delivery, but the run
-*    keeps going and `result` still settles. Cancelling the run itself is
-*    future work — pass `options.signal` to abort it.
-* 7. **`events` is single-consumer.** See {@link AgentRun.events}.
-*/
-function createAgentRun(machine, options) {
-	const buffer = [];
-	const resolvers = [];
-	let closed = false;
-	let stopped = false;
-	const push = (event) => {
-		if (closed || stopped) return;
-		const resolve = resolvers.shift();
-		if (resolve) resolve({
-			value: event,
-			done: false
-		});
-		else buffer.push(event);
-	};
-	const drain = () => {
-		while (resolvers.length > 0) resolvers.shift()({
-			value: void 0,
-			done: true
-		});
-	};
-	const close = () => {
-		if (closed) return;
-		closed = true;
-		drain();
-	};
-	const userOnTrace = options.onTrace;
-	const result = runAgent(machine, {
-		...options,
-		onTrace: (event) => {
-			push(event);
-			userOnTrace?.(event);
-			if (event.type === "run.end") close();
-		}
-	});
-	result.then(close, close);
-	return {
-		events: {
-			next() {
-				if (buffer.length > 0) return Promise.resolve({
-					value: buffer.shift(),
-					done: false
-				});
-				if (closed || stopped) return Promise.resolve({
-					value: void 0,
-					done: true
-				});
-				return new Promise((resolve) => {
-					resolvers.push(resolve);
-				});
-			},
-			return() {
-				stopped = true;
-				buffer.length = 0;
-				drain();
-				return Promise.resolve({
-					value: void 0,
-					done: true
-				});
-			},
-			[Symbol.asyncIterator]() {
-				return this;
-			}
-		},
-		result
-	};
-}
-function requestIdentity(request) {
-	const candidate = request;
-	const id = candidate.id ?? candidate.name ?? "agent.request";
-	return {
-		name: candidate.kind === "text" ? candidate.input?.name ?? id : candidate.name ?? id,
-		id
-	};
-}
-/**
-* Streams one {@link runAgent} call as agent-level events. The machine remains
-* the single artifact; this function only projects its requests, chunks,
-* transitions, emitted events, and terminal result into an async iterable.
-*/
-async function* runAgentStream(machine, options) {
-	const run = createAgentRun(machine, options);
-	for await (const event of run.events) switch (event.type) {
-		case "request.start":
-			yield {
-				kind: "request",
-				phase: "start",
-				...requestIdentity(event.request),
-				request: event.request
-			};
-			break;
-		case "request.end":
-			yield {
-				kind: "request",
-				phase: "end",
-				...requestIdentity(event.request),
-				request: event.request,
-				output: event.output,
-				raw: event.raw
-			};
-			break;
-		case "request.error":
-			yield {
-				kind: "request",
-				phase: "error",
-				...requestIdentity(event.request),
-				request: event.request,
-				error: event.error
-			};
-			break;
-		case "stream.chunk":
-			yield {
-				kind: "chunk",
-				...requestIdentity(event.request),
-				delta: event.chunk
-			};
-			break;
-		case "machine.transition":
-			yield {
-				kind: "transition",
-				value: event.snapshot.value,
-				event: event.event
-			};
-			break;
-		case "emit":
-			yield {
-				kind: "emit",
-				event: event.event
-			};
-			break;
-	}
-	const result = await run.result;
-	if (result.status === "done") yield {
-		kind: "done",
-		result
-	};
-	else if (result.status === "idle") yield {
-		kind: "idle",
-		result
-	};
-	else yield {
-		kind: "error",
-		result
-	};
-}
-//#endregion
 //#region src/provide-executors.ts
 /**
 * Binds a machine's agent actor sources to a set of host `executors` in one
 * call, returning a `machine.provide(...)`-ed copy ready for a plain
-* `createActor(...)` — the uncontrolled-mode counterpart to {@link runAgent}.
-* No run loop, no idle settling: the returned machine drives itself, so
+* `createActor(...)` — the uncontrolled-mode counterpart to {@link createAgentRuntime}.
+* No run loop, no settling: the returned machine drives itself, so
 *
 * ```ts
 * const actor = createActor(provideExecutors(machine, { generateText, decide }), { input });
@@ -453,10 +276,10 @@ async function* runAgentStream(machine, options) {
 * - `mode: 'stream'` text source → `executors.streamText`
 * - decision / `agent.decide` source → `executors.decide` (snapshot-driven
 *   candidate events, guard `canTake`, and auto-delivery of the chosen event,
-*   mirroring `runAgent` but without its model-call counting)
+*   mirroring `createAgentRuntime` but without its model-call counting)
 *
 * Pass `options.onTrace` to observe request-level trace events (identical in
-* shape to `runAgent`'s); pair it with {@link traceTransitions} on the actor's
+* shape to `createAgentRuntime`'s); pair it with {@link traceTransitions} on the actor's
 * `inspect` to also capture `machine.transition` events in the same stream.
 *
 * A source that already carries its own executor (`.withExecutor(...)`) is left
@@ -467,7 +290,7 @@ async function* runAgentStream(machine, options) {
 * Throws at bind time if a source needs an executor kind that `executors` does
 * not provide.
 *
-* Executor inheritance is RECURSIVE, exactly as in `runAgent`: a string-keyed
+* Executor inheritance is RECURSIVE, exactly as in `createAgentRuntime`: a string-keyed
 * invoked child machine is rebound too, so its own text/decision requests — at
 * any depth — reach the same host executors. A direct-object invoke `src`
 * cannot be swapped via `.provide`, so nothing under one inherits; bind those
@@ -523,7 +346,7 @@ function executorRequirementOf(logic) {
 /**
 * Walks an invoked child machine's own invoked sources (recursively, at any
 * depth) and throws the same missing-executor error `provideExecutors` throws
-* for the top-level machine — before any actor starts. Mirrors runAgent's
+* for the top-level machine — before any actor starts. Mirrors the runtime's
 * `assertBindable` for the uncontrolled path. Cycle-safe via `visited`.
 */
 function assertChildBindable(childMachine, executors, path, visited) {
@@ -546,4 +369,4 @@ function missingExecutorError(src, kind, executor) {
 	return /* @__PURE__ */ new Error(`provideExecutors: actor source '${src}' is a ${kind} source but no '${executor}' executor was provided. Add it to the executors object, or bind the source with its own executor (logic.withExecutor(...)) before calling provideExecutors.`);
 }
 //#endregion
-export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, executeAgentRequest, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, initialAgentStep, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, rejectAgentStep, renderDecisionAttempts, resolveAgentStep, resolveDecision, runAgent, runAgentStream, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, transitionAgentStep, userMessage };
+export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, renderDecisionAttempts, resolveDecision, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };

package/dist/log.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log_store = require("./event-log-store-DQmImLYk.cjs");
+const require_event_log_store = require("./event-log-store-C-COhIXP.cjs");
 //#region src/event-log-store-conformance.ts
 /**
 * The runner-agnostic conformance suite for {@link AgentEventLogStore}

package/dist/log.d.cts

@@ -1,4 +1,4 @@
-import { A as validateReplayEntries, C as forkEventLog, D as initEntry, E as getUsageFromEvents, O as rebindActorSession, S as createReplayEntry, T as getSnapshotStateHash, _ as ReplayOptions, a as AGENT_INIT_EVENT_TYPE, b as assertAgentLogEntry, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as NonSerializableAgentEventError, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, k as replay, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayResult, w as getLogExecutionId, x as assertJsonSerializable, y as agentCallOccurrence } from "./event-log-store-DvOcs10J.cjs";
+import { A as validateReplayEntries, C as forkEventLog, D as initEntry, E as getUsageFromEvents, O as rebindActorSession, S as createReplayEntry, T as getSnapshotStateHash, _ as ReplayOptions, a as AGENT_INIT_EVENT_TYPE, b as assertAgentLogEntry, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as NonSerializableAgentEventError, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, k as replay, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayResult, w as getLogExecutionId, x as assertJsonSerializable, y as agentCallOccurrence } from "./event-log-store-2xzFmgr2.cjs";
 
 //#region src/event-log-store-conformance.d.ts
 /** Produces a fresh, empty store for one case. */

package/dist/log.d.mts

@@ -1,4 +1,4 @@
-import { A as validateReplayEntries, C as forkEventLog, D as initEntry, E as getUsageFromEvents, O as rebindActorSession, S as createReplayEntry, T as getSnapshotStateHash, _ as ReplayOptions, a as AGENT_INIT_EVENT_TYPE, b as assertAgentLogEntry, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as NonSerializableAgentEventError, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, k as replay, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayResult, w as getLogExecutionId, x as assertJsonSerializable, y as agentCallOccurrence } from "./event-log-store-DxyVgnas.mjs";
+import { A as validateReplayEntries, C as forkEventLog, D as initEntry, E as getUsageFromEvents, O as rebindActorSession, S as createReplayEntry, T as getSnapshotStateHash, _ as ReplayOptions, a as AGENT_INIT_EVENT_TYPE, b as assertAgentLogEntry, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as NonSerializableAgentEventError, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, k as replay, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayResult, w as getLogExecutionId, x as assertJsonSerializable, y as agentCallOccurrence } from "./event-log-store-BIPOz-di.mjs";
 
 //#region src/event-log-store-conformance.d.ts
 /** Produces a fresh, empty store for one case. */

package/dist/log.mjs

@@ -1,4 +1,4 @@
-import { _ as getUsageFromEvents, a as AgentEventLogError, b as replay, c as NonSerializableAgentEventError, d as assertJsonSerializable, g as getSnapshotStateHash, h as getLogExecutionId, i as AGENT_INIT_EVENT_TYPE, l as agentCallOccurrence, m as forkEventLog, n as createInMemoryEventLogStore, o as AgentMachineVersionMismatchError, p as createReplayEntry, r as AGENT_EVENT_SCHEMA_VERSION, s as AgentReplayDivergenceError, t as AgentEventLogConflictError, u as assertAgentLogEntry, v as initEntry, x as validateReplayEntries, y as rebindActorSession } from "./event-log-store-Ba2fsc4E.mjs";
+import { _ as getUsageFromEvents, a as AgentEventLogError, b as replay, c as NonSerializableAgentEventError, d as assertJsonSerializable, g as getSnapshotStateHash, h as getLogExecutionId, i as AGENT_INIT_EVENT_TYPE, l as agentCallOccurrence, m as forkEventLog, n as createInMemoryEventLogStore, o as AgentMachineVersionMismatchError, p as createReplayEntry, r as AGENT_EVENT_SCHEMA_VERSION, s as AgentReplayDivergenceError, t as AgentEventLogConflictError, u as assertAgentLogEntry, v as initEntry, x as validateReplayEntries, y as rebindActorSession } from "./event-log-store-2pAFiWuc.mjs";
 //#region src/event-log-store-conformance.ts
 /**
 * The runner-agnostic conformance suite for {@link AgentEventLogStore}

package/dist/machines.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_setup_agent = require("./setup-agent-CPf7MxnG.cjs");
+const require_setup_agent = require("./setup-agent-DV4cTou-.cjs");
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";
@@ -149,9 +149,8 @@ const outputSchema$5 = objectSchema({ result: jsonAny }, ["result"]);
 *   maxSteps: 5,
 * });
 *
-* const result = await runAgent(machine, {
+* const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
 *   input: { prompt: "What is 42 * 17?" },
-*   executors,
 * });
 * // Snapshots and log entries carry machine.version ("1") automatically.
 * ```
@@ -718,10 +717,9 @@ function transferEventType(agent) {
 *   },
 * });
 *
-* const next = await runAgent(machine, {
+* const next = await runToQuiescence(createAgentRuntime(machine, { executors }), {
 *   snapshot,
 *   event: { type: "transfer_to_food", message: "What should I eat there?" },
-*   executors,
 * });
 * ```
 */
@@ -734,8 +732,7 @@ function createHandoffMachine(config) {
 		context: contextSchema,
 		input: inputSchema,
 		events: Object.fromEntries(names.map((name) => [transferEventType(name), transferPayload])),
-		actors: machineActors(agents),
-		isIdle: (snapshot) => snapshot.matches("waiting")
+		actors: machineActors(agents)
 	});
 	const turnState = (name) => `${name}Turn`;
 	const states = {

package/dist/machines.d.cts

@@ -1,10 +1,10 @@
-import { _ as StandardSchemaV1, s as AgentTools } from "./types-B1Qs2q3q.cjs";
+import { _ as StandardSchemaV1, s as AgentTools } from "./types-hR5f5YXa.cjs";
 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
+ * and output are all concrete, so callers get typed run 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.
@@ -31,7 +31,7 @@ interface PresetRequestEntry {
 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. */
+  /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
   machine: AnyStateMachine;
   /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
   input?: (args: {
@@ -89,9 +89,8 @@ type ToolLoopMachine = PresetMachine<ToolLoopContext, ToolLoopInput, ToolLoopOut
  *   maxSteps: 5,
  * });
  *
- * const result = await runAgent(machine, {
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
  *   input: { prompt: "What is 42 * 17?" },
- *   executors,
  * });
  * // Snapshots and log entries carry machine.version ("1") automatically.
  * ```
@@ -454,10 +453,9 @@ declare function transferEventType(agent: string): string;
  *   },
  * });
  *
- * const next = await runAgent(machine, {
+ * const next = await runToQuiescence(createAgentRuntime(machine, { executors }), {
  *   snapshot,
  *   event: { type: "transfer_to_food", message: "What should I eat there?" },
- *   executors,
  * });
  * ```
  */

package/dist/machines.d.mts

@@ -1,10 +1,10 @@
-import { _ as StandardSchemaV1, s as AgentTools } from "./types-tA3SdczG.mjs";
+import { _ as StandardSchemaV1, s as AgentTools } from "./types-BgNbNKnJ.mjs";
 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
+ * and output are all concrete, so callers get typed run 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.
@@ -31,7 +31,7 @@ interface PresetRequestEntry {
 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. */
+  /** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
   machine: AnyStateMachine;
   /** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
   input?: (args: {
@@ -89,9 +89,8 @@ type ToolLoopMachine = PresetMachine<ToolLoopContext, ToolLoopInput, ToolLoopOut
  *   maxSteps: 5,
  * });
  *
- * const result = await runAgent(machine, {
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
  *   input: { prompt: "What is 42 * 17?" },
- *   executors,
  * });
  * // Snapshots and log entries carry machine.version ("1") automatically.
  * ```
@@ -454,10 +453,9 @@ declare function transferEventType(agent: string): string;
  *   },
  * });
  *
- * const next = await runAgent(machine, {
+ * const next = await runToQuiescence(createAgentRuntime(machine, { executors }), {
  *   snapshot,
  *   event: { type: "transfer_to_food", message: "What should I eat there?" },
- *   executors,
  * });
  * ```
  */

package/dist/machines.mjs

@@ -1,4 +1,4 @@
-import { r as setupAgent } from "./setup-agent-CFW-jPI8.mjs";
+import { r as setupAgent } from "./setup-agent-BuanDXeh.mjs";
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";
@@ -148,9 +148,8 @@ const outputSchema$5 = objectSchema({ result: jsonAny }, ["result"]);
 *   maxSteps: 5,
 * });
 *
-* const result = await runAgent(machine, {
+* const result = await runToQuiescence(createAgentRuntime(machine, { executors }), {
 *   input: { prompt: "What is 42 * 17?" },
-*   executors,
 * });
 * // Snapshots and log entries carry machine.version ("1") automatically.
 * ```
@@ -717,10 +716,9 @@ function transferEventType(agent) {
 *   },
 * });
 *
-* const next = await runAgent(machine, {
+* const next = await runToQuiescence(createAgentRuntime(machine, { executors }), {
 *   snapshot,
 *   event: { type: "transfer_to_food", message: "What should I eat there?" },
-*   executors,
 * });
 * ```
 */
@@ -733,8 +731,7 @@ function createHandoffMachine(config) {
 		context: contextSchema,
 		input: inputSchema,
 		events: Object.fromEntries(names.map((name) => [transferEventType(name), transferPayload])),
-		actors: machineActors(agents),
-		isIdle: (snapshot) => snapshot.matches("waiting")
+		actors: machineActors(agents)
 	});
 	const turnState = (name) => `${name}Turn`;
 	const states = {

package/dist/openai.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_text_logic = require("./text-logic-C8xyr6Ag.cjs");
-const require_decision = require("./decision-CM9CYZ6t.cjs");
+const require_text_logic = require("./text-logic-f5F5sCdc.cjs");
+const require_decision = require("./decision-CmM8-HHz.cjs");
 //#region src/openai/index.ts
 /** Thrown for a message part Chat Completions cannot carry — dropping it would
 * silently change what the model sees. */
@@ -286,7 +286,7 @@ function toToolContent(output) {
 *   client: new OpenAI(),
 *   resolveModel: () => 'gpt-5.4-mini',
 * });
-* const result = await runAgent(machine, { input, executors });
+* const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
 * ```
 */
 function createOpenAiExecutors(options) {

package/dist/openai.d.cts

@@ -1,5 +1,5 @@
-import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
-import { M as AgentDecisionRequest, U as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BFEOxyxv.cjs";
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-hR5f5YXa.cjs";
+import { M as AgentDecisionRequest, U as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-IjfYy9DP.cjs";
 import OpenAI from "openai";
 import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
 
@@ -107,7 +107,7 @@ type CreateOpenAiExecutorsOptions = {
  * Raw result shape from {@link OpenAiExecutors.generateText} — `result` (the
  * validated structured object for structured-output requests, or the model's
  * text otherwise) plus the call metadata. Core reads `result` and `usage`;
- * everything else flows verbatim to `runAgent`'s `onResult(request, { raw })`.
+ * everything else flows verbatim to `createAgentRuntime`'s `onResult(request, { raw })`.
  */
 type OpenAiGenerateResult = {
   result: unknown;
@@ -115,7 +115,7 @@ type OpenAiGenerateResult = {
    * `includeReasoning` and the model produced it. Never enters machine
    * context/output. */
   reasoning?: string;
-  /** The call's token usage, on the flat field names `runAgent` folds into the
+  /** The call's token usage, on the flat field names the runtime folds into the
    * run result's aggregated `AgentUsage`. Absent when OpenAI reported none. */
   usage?: AgentCallUsage; /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
   finishReason: AgentFinishReason; /** The untouched OpenAI response. */
@@ -169,7 +169,7 @@ declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: Agen
  *   client: new OpenAI(),
  *   resolveModel: () => 'gpt-5.4-mini',
  * });
- * const result = await runAgent(machine, { input, executors });
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */
 declare function createOpenAiExecutors(options: CreateOpenAiExecutorsOptions): OpenAiExecutors;

package/dist/openai.d.mts

@@ -1,5 +1,5 @@
-import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-tA3SdczG.mjs";
-import { M as AgentDecisionRequest, U as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-hZSiRUo1.mjs";
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-BgNbNKnJ.mjs";
+import { M as AgentDecisionRequest, U as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-D-czVPYp.mjs";
 import OpenAI from "openai";
 import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
 
@@ -107,7 +107,7 @@ type CreateOpenAiExecutorsOptions = {
  * Raw result shape from {@link OpenAiExecutors.generateText} — `result` (the
  * validated structured object for structured-output requests, or the model's
  * text otherwise) plus the call metadata. Core reads `result` and `usage`;
- * everything else flows verbatim to `runAgent`'s `onResult(request, { raw })`.
+ * everything else flows verbatim to `createAgentRuntime`'s `onResult(request, { raw })`.
  */
 type OpenAiGenerateResult = {
   result: unknown;
@@ -115,7 +115,7 @@ type OpenAiGenerateResult = {
    * `includeReasoning` and the model produced it. Never enters machine
    * context/output. */
   reasoning?: string;
-  /** The call's token usage, on the flat field names `runAgent` folds into the
+  /** The call's token usage, on the flat field names the runtime folds into the
    * run result's aggregated `AgentUsage`. Absent when OpenAI reported none. */
   usage?: AgentCallUsage; /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
   finishReason: AgentFinishReason; /** The untouched OpenAI response. */
@@ -169,7 +169,7 @@ declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: Agen
  *   client: new OpenAI(),
  *   resolveModel: () => 'gpt-5.4-mini',
  * });
- * const result = await runAgent(machine, { input, executors });
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
  * ```
  */
 declare function createOpenAiExecutors(options: CreateOpenAiExecutorsOptions): OpenAiExecutors;

package/dist/openai.mjs

@@ -1,5 +1,5 @@
-import { A as getJsonSchema, I as isStandardSchema, U as AgentTruncatedError, g as providerOutputSchema, h as parseProviderOutput, j as getJsonSchemaSync, l as getAgentOutputMode, t as AGENT_USAGE_TOKEN_FIELDS } from "./text-logic-Bl_ZRxDi.mjs";
-import { o as renderDecisionAttempts } from "./decision-DzSv1NpD.mjs";
+import { B as AgentTruncatedError, D as getJsonSchema, N as isStandardSchema, O as getJsonSchemaSync, c as getAgentOutputMode, h as providerOutputSchema, m as parseProviderOutput, t as AGENT_USAGE_TOKEN_FIELDS } from "./text-logic-CIqHAmBi.mjs";
+import { o as renderDecisionAttempts } from "./decision-RQ0iv0oZ.mjs";
 //#region src/openai/index.ts
 /** Thrown for a message part Chat Completions cannot carry — dropping it would
 * silently change what the model sees. */
@@ -285,7 +285,7 @@ function toToolContent(output) {
 *   client: new OpenAI(),
 *   resolveModel: () => 'gpt-5.4-mini',
 * });
-* const result = await runAgent(machine, { input, executors });
+* const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
 * ```
 */
 function createOpenAiExecutors(options) {

package/dist/otel.cjs

@@ -71,7 +71,7 @@ function toException(error) {
 * GenAI spans: one `invoke_agent` span per run, one child span per model call,
 * transitions and emissions as span events.
 *
-* Works on both paths. On the controlled path (`runAgent`) the run span opens
+* Works on both paths. On the controlled path (`createAgentRuntime`) the run span opens
 * on `run.start` and closes on `run.end`. On the uncontrolled path
 * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
 * run span opens lazily on the first event of a `runId` and stays open until
@@ -84,7 +84,7 @@ function toException(error) {
 *
 * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
 * try {
-*   await runAgent(machine, { input, executors, onTrace });
+*   await runToQuiescence(createAgentRuntime(machine, { executors, onTrace }), { input });
 * } finally {
 *   onTrace.dispose();
 * }

package/dist/otel.d.cts

@@ -1,4 +1,4 @@
-import { o as AgentTraceEvent } from "./run-agent-BOfoJg5B.cjs";
+import { h as AgentTraceEvent } from "./run-agent-ByO-Bxyd.cjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts
@@ -43,7 +43,7 @@ type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
  * GenAI spans: one `invoke_agent` span per run, one child span per model call,
  * transitions and emissions as span events.
  *
- * Works on both paths. On the controlled path (`runAgent`) the run span opens
+ * Works on both paths. On the controlled path (`createAgentRuntime`) the run span opens
  * on `run.start` and closes on `run.end`. On the uncontrolled path
  * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
  * run span opens lazily on the first event of a `runId` and stays open until
@@ -56,7 +56,7 @@ type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
  *
  * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
  * try {
- *   await runAgent(machine, { input, executors, onTrace });
+ *   await runToQuiescence(createAgentRuntime(machine, { executors, onTrace }), { input });
  * } finally {
  *   onTrace.dispose();
  * }

package/dist/otel.d.mts

@@ -1,4 +1,4 @@
-import { o as AgentTraceEvent } from "./run-agent-CG343kFs.mjs";
+import { h as AgentTraceEvent } from "./run-agent-COXXc0RW.mjs";
 import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
 
 //#region src/otel/index.d.ts
@@ -43,7 +43,7 @@ type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
  * GenAI spans: one `invoke_agent` span per run, one child span per model call,
  * transitions and emissions as span events.
  *
- * Works on both paths. On the controlled path (`runAgent`) the run span opens
+ * Works on both paths. On the controlled path (`createAgentRuntime`) the run span opens
  * on `run.start` and closes on `run.end`. On the uncontrolled path
  * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
  * run span opens lazily on the first event of a `runId` and stays open until
@@ -56,7 +56,7 @@ type OtelTraceHandler = ((event: AgentTraceEvent) => void) & {
  *
  * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
  * try {
- *   await runAgent(machine, { input, executors, onTrace });
+ *   await runToQuiescence(createAgentRuntime(machine, { executors, onTrace }), { input });
  * } finally {
  *   onTrace.dispose();
  * }

package/dist/otel.mjs

@@ -69,7 +69,7 @@ function toException(error) {
 * GenAI spans: one `invoke_agent` span per run, one child span per model call,
 * transitions and emissions as span events.
 *
-* Works on both paths. On the controlled path (`runAgent`) the run span opens
+* Works on both paths. On the controlled path (`createAgentRuntime`) the run span opens
 * on `run.start` and closes on `run.end`. On the uncontrolled path
 * (`provideExecutors` + `traceTransitions`) there is no run boundary, so the
 * run span opens lazily on the first event of a `runId` and stays open until
@@ -82,7 +82,7 @@ function toException(error) {
 *
 * const onTrace = createOtelTraceHandler({ tracer: trace.getTracer('my-app') });
 * try {
-*   await runAgent(machine, { input, executors, onTrace });
+*   await runToQuiescence(createAgentRuntime(machine, { executors, onTrace }), { input });
 * } finally {
 *   onTrace.dispose();
 * }