@statelyai/agent 2.0.0-alpha.39 → 2.0.0-alpha.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/evals.cjs +1 -1
  3. package/dist/evals.d.cts +1 -1
  4. package/dist/evals.d.mts +1 -1
  5. package/dist/evals.mjs +1 -1
  6. package/dist/index.cjs +17 -10
  7. package/dist/index.d.cts +28 -11
  8. package/dist/index.d.mts +28 -11
  9. package/dist/index.mjs +17 -10
  10. package/dist/machine-input-0YTPcnCm.mjs +27 -0
  11. package/dist/machine-input-DU3owLUr.cjs +32 -0
  12. package/dist/otel.d.cts +1 -1
  13. package/dist/otel.d.mts +1 -1
  14. package/dist/policy.cjs +1 -1
  15. package/dist/policy.d.cts +1 -1
  16. package/dist/policy.d.mts +1 -1
  17. package/dist/policy.mjs +1 -1
  18. package/dist/{run-agent-Dq0oSFRm.d.cts → run-agent-BO9RSb7i.d.cts} +16 -7
  19. package/dist/{run-agent-DHlq87G7.d.mts → run-agent-BxkeuAYR.d.mts} +16 -7
  20. package/dist/{run-agent-De3xVFGw.cjs → run-agent-COdR9FpM.cjs} +26 -27
  21. package/dist/{run-agent-BE7DOWD6.mjs → run-agent-D3gW9wfd.mjs} +27 -28
  22. package/dist/testing.cjs +2 -2
  23. package/dist/testing.d.cts +2 -2
  24. package/dist/testing.d.mts +2 -2
  25. package/dist/testing.mjs +2 -2
  26. package/dist/validate.cjs +1 -1
  27. package/dist/validate.d.cts +1 -1
  28. package/dist/validate.d.mts +1 -1
  29. package/dist/validate.mjs +1 -1
  30. package/dist/{verify-H3Pr2gNw.d.mts → verify-CIu4mqIZ.d.mts} +15 -1
  31. package/dist/{verify-BM0sGmsf.d.cts → verify-CTHlmBbh.d.cts} +15 -1
  32. package/dist/{verify-CWlg3j7B.mjs → verify-Cacz6XSk.mjs} +19 -3
  33. package/dist/{verify-Dek6gHCS.cjs → verify-D8UDqU4l.cjs} +19 -3
  34. package/docs/hosts.md +5 -3
  35. package/docs/strangler-fig.md +36 -29
  36. package/docs/verify.md +3 -2
  37. package/package.json +1 -1
@@ -369,9 +369,12 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
369
369
  * when the machine has no transition for `event`, when the loop never
370
370
  * applies it, when the machine settles still `active` after handling it,
371
371
  * or when `timeout` milliseconds pass while it is still working.
372
+ *
373
+ * `event` can be a function of `signal.reason`, so aborts with different
374
+ * reasons (a pause and a stop) send different events.
372
375
  */
373
376
  abortWith?: {
374
- event: EventFromLogic<TMachine>;
377
+ event: EventFromLogic<TMachine> | ((reason: unknown) => EventFromLogic<TMachine>);
375
378
  timeout?: number;
376
379
  };
377
380
  /** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
@@ -617,7 +620,8 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
617
620
  nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
618
621
  /**
619
622
  * Delivers a host event (a cancel, a user message, a host-owned timer) into
620
- * the run's mailbox, behind whatever already arrived. Asynchronous: `send`
623
+ * the run, behind earlier host sends and ahead of completions not yet handed
624
+ * out. Asynchronous: `send`
621
625
  * only enqueues; the machine moves when the host loop's next `nextEvent()`
622
626
  * hands the event out (a parked `nextEvent()` resolves with it) and the loop
623
627
  * calls `transition`. A host that needs the event applied before it returns
@@ -631,8 +635,9 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
631
635
  *
632
636
  * - Before `start`: queued; the first `nextEvent()` hands it out (after the
633
637
  * init event a host delivers itself). Returns `true`.
634
- * - While an effect, child or timer is in flight: queued in arrival order
635
- * with their completions. Returns `true`.
638
+ * - While an effect, child or timer is in flight: queued behind earlier
639
+ * host sends, and handed out before any completion the run holds, so
640
+ * actors that settle in microtasks cannot keep it waiting. Returns `true`.
636
641
  * - After the run stopped (cancelled, aborted, journal failure) or the
637
642
  * machine left `active` (done, error): dropped. Returns `false`.
638
643
  * - After `finish`: throws {@link AgentError} `runtime-finished`.
@@ -682,10 +687,13 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
682
687
  * A host that cannot block for the answer (a request handler, a durable
683
688
  * object) leaves this out, stores `result.persist()`, and calls
684
689
  * {@link runAgent} again later with `{ snapshot, event }`.
690
+ *
691
+ * `"inbox"`: each idle state waits for the next `inbox.send` (a resume
692
+ * after a pause), with no answer of its own. Needs `inbox`.
685
693
  */
686
- onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
694
+ onIdle?: ((snapshot: SnapshotFrom<TMachine>, options: {
687
695
  signal: AbortSignal | undefined;
688
- }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>;
696
+ }) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>) | "inbox";
689
697
  /**
690
698
  * A send handle for events pushed mid-run (a cancel, a user message), from
691
699
  * {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
@@ -695,7 +703,8 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
695
703
  * dropped). Without `onIdle`, the run returns at the first idle state
696
704
  * (an event that lands while that pass is finishing still resumes it), and
697
705
  * a `send` after `runAgent` returns gets `false`: a pause that waits for a
698
- * resume needs `onIdle` as well. One inbox serves one `runAgent` call.
706
+ * resume needs `onIdle` as well (`onIdle: "inbox"` when only the inbox
707
+ * answers). One inbox serves one `runAgent` call.
699
708
  */
700
709
  inbox?: AgentInbox<EventFromLogic<TMachine>>;
701
710
  }
@@ -2,6 +2,7 @@ const require_event_log = require("./event-log-dSOnXHuG.cjs");
2
2
  const require_decision = require("./decision-D8bcIGXQ.cjs");
3
3
  const require_act = require("./act-B0CVbmo4.cjs");
4
4
  const require_event_log_store = require("./event-log-store-Dey9ufA4.cjs");
5
+ const require_machine_input = require("./machine-input-DU3owLUr.cjs");
5
6
  let xstate = require("xstate");
6
7
  let xstate_durable = require("xstate/durable");
7
8
  //#region src/internal/stable-inspection.ts
@@ -1282,26 +1283,6 @@ function bindChildMachineForProvide(childMachine, executors, options, visited) {
1282
1283
  return rebindChildMachine(childMachine, ctxFor(childMachine), visited, ctxFor);
1283
1284
  }
1284
1285
  /**
1285
- * Validates `input` against the machine's registered input schema, returning
1286
- * the schema's output — so defaults are filled and transforms applied before
1287
- * the value reaches `createActor` or the replayable event log.
1288
- *
1289
- * Standard Schema only (no validation library is referenced), so this works for
1290
- * whatever the machine was declared with. Omitted input stays omitted rather
1291
- * than being validated as `{}`: "started with no input" keeps meaning what it
1292
- * has always meant, instead of newly failing schemas with required fields.
1293
- */
1294
- function resolveMachineInput(machine, input) {
1295
- if (input === void 0) return input;
1296
- const schema = require_event_log.getRegisteredAgentExecutionOptions(machine).schemas?.input;
1297
- if (!require_event_log.isStandardSchema(schema)) return input;
1298
- try {
1299
- return require_event_log.validateSchemaSync(schema, input);
1300
- } catch (error) {
1301
- throw new require_event_log.AgentError("invalid-machine-input", `createAgentRuntime: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1302
- }
1303
- }
1304
- /**
1305
1286
  * Recursively rebinds an invoked child machine's own agent sources with the
1306
1287
  * SAME host-backed wrappers the runtime applies to the top-level machine, so a
1307
1288
  * child's text/stream/decision requests inherit the runtime's executors and
@@ -1569,7 +1550,9 @@ async function waitForIdleAnswer(snapshot, onIdle, inbox, signal, aborted) {
1569
1550
  * ```
1570
1551
  */
1571
1552
  async function runAgent(machine, options = {}) {
1572
- const { onIdle, inbox, ...rest } = options;
1553
+ const { onIdle: idle, inbox, ...rest } = options;
1554
+ if (idle === "inbox" && inbox === void 0) throw new require_event_log.AgentError("inbox-required", "runAgent: `onIdle: \"inbox\"` needs an `inbox`.");
1555
+ const onIdle = idle === "inbox" ? () => new Promise(() => {}) : idle;
1573
1556
  const inboxState = inbox === void 0 ? void 0 : inboxStates.get(inbox);
1574
1557
  if (inbox !== void 0) {
1575
1558
  if (inboxState === void 0 || inboxState.claimed) throw new require_event_log.AgentError("inbox-in-use", "runAgent: `inbox` must come from createAgentInbox() and serves one runAgent call.");
@@ -2001,6 +1984,7 @@ function createAgentRuntime(machine, options = {}) {
2001
1984
  }
2002
1985
  const boundMachine = provided.provide({ actors: wrappedSources });
2003
1986
  const mailbox = [];
1987
+ const hostQueue = [];
2004
1988
  let wake;
2005
1989
  const fromMailbox = /* @__PURE__ */ new WeakSet();
2006
1990
  let stopReason;
@@ -2014,7 +1998,8 @@ function createAgentRuntime(machine, options = {}) {
2014
1998
  if (waiting) {
2015
1999
  wake = void 0;
2016
2000
  waiting(event);
2017
- } else mailbox.push(event);
2001
+ } else if (fromHost) hostQueue.push(event);
2002
+ else mailbox.push(event);
2018
2003
  };
2019
2004
  const inProcessTimers = options.timers === void 0 || options.timers === "in-process";
2020
2005
  const timerHandles = /* @__PURE__ */ new Map();
@@ -2089,11 +2074,25 @@ function createAgentRuntime(machine, options = {}) {
2089
2074
  let abortTimer;
2090
2075
  const onAbort = () => {
2091
2076
  const abortWith = options.abortWith;
2092
- if (abortWith === void 0 || runtime.send(abortWith.event) === false) {
2077
+ if (abortWith === void 0) {
2078
+ abortNow();
2079
+ return;
2080
+ }
2081
+ let event;
2082
+ try {
2083
+ event = typeof abortWith.event === "function" ? abortWith.event(options.signal?.reason) : abortWith.event;
2084
+ } catch (error) {
2085
+ stopRun({
2086
+ cause: "aborted",
2087
+ error
2088
+ });
2089
+ return;
2090
+ }
2091
+ if (runtime.send(event) === false) {
2093
2092
  abortNow();
2094
2093
  return;
2095
2094
  }
2096
- pendingAbort = abortWith.event;
2095
+ pendingAbort = event;
2097
2096
  if (abortWith.timeout !== void 0) abortTimer = setTimeout(() => {
2098
2097
  if (current?.status === "active") abortNow();
2099
2098
  }, abortWith.timeout);
@@ -2151,7 +2150,7 @@ function createAgentRuntime(machine, options = {}) {
2151
2150
  enqueueRootEvent: (_source, event) => enqueue(event),
2152
2151
  executeAction: (action, _metadata, runtime) => action.exec(runtime),
2153
2152
  waitForEvent: () => {
2154
- const queued = mailbox.shift();
2153
+ const queued = hostQueue.shift() ?? mailbox.shift();
2155
2154
  if (queued !== void 0) return queued;
2156
2155
  if (resultOwed) {
2157
2156
  resultOwed = false;
@@ -2224,7 +2223,7 @@ function createAgentRuntime(machine, options = {}) {
2224
2223
  resumedFromStore = true;
2225
2224
  }
2226
2225
  }
2227
- const resolvedInput = resolveMachineInput(machine, init.input);
2226
+ const resolvedInput = require_machine_input.resolveMachineInput(machine, init.input, "createAgentRuntime");
2228
2227
  const threadInit = resumeEvents?.[0]?.event;
2229
2228
  if (resumedFromStore && init.input !== void 0 && threadInit !== void 0 && Object.hasOwn(threadInit, "input")) {
2230
2229
  if (require_event_log.canonicalJson(threadInit.input) !== require_event_log.canonicalJson(resolvedInput)) throw new require_event_log.AgentError("thread-input-mismatch", `createAgentRuntime: thread '${threadId}' was started with different input. A thread that already has entries is resumed, not restarted; give a new run a new threadId.`);
@@ -2471,7 +2470,7 @@ function createAgentRuntime(machine, options = {}) {
2471
2470
  async nextEvent() {
2472
2471
  for (;;) {
2473
2472
  if (finished || stopReason !== void 0 || current?.status !== "active") return;
2474
- const event = await execution.waitForEvent();
2473
+ const event = hostQueue.shift() ?? await execution.waitForEvent();
2475
2474
  if (event === QUIESCENT || stopReason !== void 0) return;
2476
2475
  if (isStaleChildEvent(event)) continue;
2477
2476
  return event;
@@ -1,7 +1,8 @@
1
- import { C as AGENT_USAGE_EVENT_TYPE, F as getCallModelCalls, I as getCallUsage, K as getRegisteredAgentExecutionOptions, L as isTextLogic, P as getCallFinishReason, R as normalizeGeneratorResult, S as validateReplayEntries, T as ACT_ACTOR, U as responseMessagesOf, W as executorBoundLogics, Z as findNonSerializableContextPaths, _ as getSnapshotStateHash, c as agentCallSite, ct as validateSchemaSync, d as canonicalEventJson, dt as isPlainObject, f as createReplayEntry, ft as isRecord, g as getLogExecutionId, i as AgentMachineVersionMismatchError, it as resolveMachineVersion, lt as canonicalJson, p as foldLog, pt as AgentError, q as isUnboundPlaceholder, rt as isStandardSchema, s as agentCallOccurrence, u as assertJsonSerializable, v as getUsageFromEvents, w as restoreMachineSnapshot, x as replay, y as initEntry } from "./event-log-CEq_bVXQ.mjs";
1
+ import { C as AGENT_USAGE_EVENT_TYPE, F as getCallModelCalls, I as getCallUsage, K as getRegisteredAgentExecutionOptions, L as isTextLogic, P as getCallFinishReason, R as normalizeGeneratorResult, S as validateReplayEntries, T as ACT_ACTOR, U as responseMessagesOf, W as executorBoundLogics, Z as findNonSerializableContextPaths, _ as getSnapshotStateHash, c as agentCallSite, ct as validateSchemaSync, d as canonicalEventJson, dt as isPlainObject, f as createReplayEntry, ft as isRecord, g as getLogExecutionId, i as AgentMachineVersionMismatchError, it as resolveMachineVersion, lt as canonicalJson, p as foldLog, pt as AgentError, q as isUnboundPlaceholder, s as agentCallOccurrence, u as assertJsonSerializable, v as getUsageFromEvents, w as restoreMachineSnapshot, x as replay, y as initEntry } from "./event-log-CEq_bVXQ.mjs";
2
2
  import { _ as isEventPattern, a as createDecisionRequest, g as getHumanEventTypes, h as getAcceptedEvents, l as resolveAllowedEventTypes, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as resolveDecision } from "./decision-B41YBx5U.mjs";
3
3
  import { i as isActLogic, t as ACT_STATE_EXITED } from "./act-Bsz-hUfD.mjs";
4
4
  import { t as AgentEventLogConflictError } from "./event-log-store-DLAfNM34.mjs";
5
+ import { t as resolveMachineInput } from "./machine-input-0YTPcnCm.mjs";
5
6
  import { createAsyncLogic, deliverEvent, getNextTransitions, isMachineSnapshot, stopActor, transition } from "xstate";
6
7
  import { createDurable } from "xstate/durable";
7
8
  //#region src/internal/stable-inspection.ts
@@ -1282,26 +1283,6 @@ function bindChildMachineForProvide(childMachine, executors, options, visited) {
1282
1283
  return rebindChildMachine(childMachine, ctxFor(childMachine), visited, ctxFor);
1283
1284
  }
1284
1285
  /**
1285
- * Validates `input` against the machine's registered input schema, returning
1286
- * the schema's output — so defaults are filled and transforms applied before
1287
- * the value reaches `createActor` or the replayable event log.
1288
- *
1289
- * Standard Schema only (no validation library is referenced), so this works for
1290
- * whatever the machine was declared with. Omitted input stays omitted rather
1291
- * than being validated as `{}`: "started with no input" keeps meaning what it
1292
- * has always meant, instead of newly failing schemas with required fields.
1293
- */
1294
- function resolveMachineInput(machine, input) {
1295
- if (input === void 0) return input;
1296
- const schema = getRegisteredAgentExecutionOptions(machine).schemas?.input;
1297
- if (!isStandardSchema(schema)) return input;
1298
- try {
1299
- return validateSchemaSync(schema, input);
1300
- } catch (error) {
1301
- throw new AgentError("invalid-machine-input", `createAgentRuntime: machine input failed validation against the declared input schema: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
1302
- }
1303
- }
1304
- /**
1305
1286
  * Recursively rebinds an invoked child machine's own agent sources with the
1306
1287
  * SAME host-backed wrappers the runtime applies to the top-level machine, so a
1307
1288
  * child's text/stream/decision requests inherit the runtime's executors and
@@ -1569,7 +1550,9 @@ async function waitForIdleAnswer(snapshot, onIdle, inbox, signal, aborted) {
1569
1550
  * ```
1570
1551
  */
1571
1552
  async function runAgent(machine, options = {}) {
1572
- const { onIdle, inbox, ...rest } = options;
1553
+ const { onIdle: idle, inbox, ...rest } = options;
1554
+ if (idle === "inbox" && inbox === void 0) throw new AgentError("inbox-required", "runAgent: `onIdle: \"inbox\"` needs an `inbox`.");
1555
+ const onIdle = idle === "inbox" ? () => new Promise(() => {}) : idle;
1573
1556
  const inboxState = inbox === void 0 ? void 0 : inboxStates.get(inbox);
1574
1557
  if (inbox !== void 0) {
1575
1558
  if (inboxState === void 0 || inboxState.claimed) throw new AgentError("inbox-in-use", "runAgent: `inbox` must come from createAgentInbox() and serves one runAgent call.");
@@ -2001,6 +1984,7 @@ function createAgentRuntime(machine, options = {}) {
2001
1984
  }
2002
1985
  const boundMachine = provided.provide({ actors: wrappedSources });
2003
1986
  const mailbox = [];
1987
+ const hostQueue = [];
2004
1988
  let wake;
2005
1989
  const fromMailbox = /* @__PURE__ */ new WeakSet();
2006
1990
  let stopReason;
@@ -2014,7 +1998,8 @@ function createAgentRuntime(machine, options = {}) {
2014
1998
  if (waiting) {
2015
1999
  wake = void 0;
2016
2000
  waiting(event);
2017
- } else mailbox.push(event);
2001
+ } else if (fromHost) hostQueue.push(event);
2002
+ else mailbox.push(event);
2018
2003
  };
2019
2004
  const inProcessTimers = options.timers === void 0 || options.timers === "in-process";
2020
2005
  const timerHandles = /* @__PURE__ */ new Map();
@@ -2089,11 +2074,25 @@ function createAgentRuntime(machine, options = {}) {
2089
2074
  let abortTimer;
2090
2075
  const onAbort = () => {
2091
2076
  const abortWith = options.abortWith;
2092
- if (abortWith === void 0 || runtime.send(abortWith.event) === false) {
2077
+ if (abortWith === void 0) {
2078
+ abortNow();
2079
+ return;
2080
+ }
2081
+ let event;
2082
+ try {
2083
+ event = typeof abortWith.event === "function" ? abortWith.event(options.signal?.reason) : abortWith.event;
2084
+ } catch (error) {
2085
+ stopRun({
2086
+ cause: "aborted",
2087
+ error
2088
+ });
2089
+ return;
2090
+ }
2091
+ if (runtime.send(event) === false) {
2093
2092
  abortNow();
2094
2093
  return;
2095
2094
  }
2096
- pendingAbort = abortWith.event;
2095
+ pendingAbort = event;
2097
2096
  if (abortWith.timeout !== void 0) abortTimer = setTimeout(() => {
2098
2097
  if (current?.status === "active") abortNow();
2099
2098
  }, abortWith.timeout);
@@ -2151,7 +2150,7 @@ function createAgentRuntime(machine, options = {}) {
2151
2150
  enqueueRootEvent: (_source, event) => enqueue(event),
2152
2151
  executeAction: (action, _metadata, runtime) => action.exec(runtime),
2153
2152
  waitForEvent: () => {
2154
- const queued = mailbox.shift();
2153
+ const queued = hostQueue.shift() ?? mailbox.shift();
2155
2154
  if (queued !== void 0) return queued;
2156
2155
  if (resultOwed) {
2157
2156
  resultOwed = false;
@@ -2224,7 +2223,7 @@ function createAgentRuntime(machine, options = {}) {
2224
2223
  resumedFromStore = true;
2225
2224
  }
2226
2225
  }
2227
- const resolvedInput = resolveMachineInput(machine, init.input);
2226
+ const resolvedInput = resolveMachineInput(machine, init.input, "createAgentRuntime");
2228
2227
  const threadInit = resumeEvents?.[0]?.event;
2229
2228
  if (resumedFromStore && init.input !== void 0 && threadInit !== void 0 && Object.hasOwn(threadInit, "input")) {
2230
2229
  if (canonicalJson(threadInit.input) !== canonicalJson(resolvedInput)) throw new AgentError("thread-input-mismatch", `createAgentRuntime: thread '${threadId}' was started with different input. A thread that already has entries is resumed, not restarted; give a new run a new threadId.`);
@@ -2471,7 +2470,7 @@ function createAgentRuntime(machine, options = {}) {
2471
2470
  async nextEvent() {
2472
2471
  for (;;) {
2473
2472
  if (finished || stopReason !== void 0 || current?.status !== "active") return;
2474
- const event = await execution.waitForEvent();
2473
+ const event = hostQueue.shift() ?? await execution.waitForEvent();
2475
2474
  if (event === QUIESCENT || stopReason !== void 0) return;
2476
2475
  if (isStaleChildEvent(event)) continue;
2477
2476
  return event;
package/dist/testing.cjs CHANGED
@@ -3,9 +3,9 @@ const require_event_log = require("./event-log-dSOnXHuG.cjs");
3
3
  const require_decision = require("./decision-D8bcIGXQ.cjs");
4
4
  const require_act = require("./act-B0CVbmo4.cjs");
5
5
  const require_event_log_store = require("./event-log-store-Dey9ufA4.cjs");
6
- const require_run_agent = require("./run-agent-De3xVFGw.cjs");
6
+ const require_run_agent = require("./run-agent-COdR9FpM.cjs");
7
7
  const require_effects = require("./effects-DrWcUGgc.cjs");
8
- const require_verify = require("./verify-Dek6gHCS.cjs");
8
+ const require_verify = require("./verify-D8UDqU4l.cjs");
9
9
  const require_trajectory = require("./trajectory-CoZSv4wF.cjs");
10
10
  //#region src/equivalence.ts
11
11
  /**
@@ -1,7 +1,7 @@
1
1
  import { c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.cjs";
2
- import { C as simulateAgent, S as lintAgentMachine, _ as SimulationScript, a as AgentPathTerminal, b as canReach, c as CanReachOrdering, d as ExplorePathsOptions, f as ExploreSnapshot, g as SimulateAgentResult, h as SimulateAgentOptions, i as AgentPathReport, l as CanReachResult, m as LintAgentMachineOptions, n as AgentLintError, o as AgentUnknownStateError, p as ExploreStep, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as CanReachTarget, v as SimulationTrailEntry, w as textOutput, x as explorePaths, y as assertAgentMachine } from "./verify-BM0sGmsf.cjs";
2
+ import { C as simulateAgent, S as lintAgentMachine, _ as SimulationScript, a as AgentPathTerminal, b as canReach, c as CanReachOrdering, d as ExplorePathsOptions, f as ExploreSnapshot, g as SimulateAgentResult, h as SimulateAgentOptions, i as AgentPathReport, l as CanReachResult, m as LintAgentMachineOptions, n as AgentLintError, o as AgentUnknownStateError, p as ExploreStep, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as CanReachTarget, v as SimulationTrailEntry, w as textOutput, x as explorePaths, y as assertAgentMachine } from "./verify-CTHlmBbh.cjs";
3
3
  import { a as TrajectoryMatch, i as TrajectoryItem, n as TrajectoryEvent, o as TrajectoryMiss, r as TrajectoryEventEnvelope, s as matchesTrajectory, t as MatchTrajectoryOptions } from "./trajectory-BFjXaooB.cjs";
4
- import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-Dq0oSFRm.cjs";
4
+ import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-BO9RSb7i.cjs";
5
5
  import { n as AgentEventLogStore } from "./event-log-store-aFXK6yZX.cjs";
6
6
  import { A as RecordedToolCall, C as RecordableLanguageModel, D as RecordedError, E as RecordedEffect, F as createRecorder, I as sameModelCallShape, M as Recording, N as RecordingDivergenceError, O as RecordedModelCall, P as compareRecordings, S as RecordableDecisionModel, T as RecordedCall, _ as ModelAnswer, b as RecordCallOptions, f as CompareRecordingsOptions, g as EquivalenceReport, h as EffectDivergenceReason, j as Recorder, k as RecordedOutput, m as EffectDivergence, p as CreateRecorderOptions, t as MetaOfSnapshot, v as ModelCallMatch, w as RecordableModel, x as RecordClientOptions, y as NormalizeEffect } from "./utils-DAclF-kw.cjs";
7
7
  import { AnyActorLogic, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
@@ -1,7 +1,7 @@
1
1
  import { c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.mjs";
2
- import { C as simulateAgent, S as lintAgentMachine, _ as SimulationScript, a as AgentPathTerminal, b as canReach, c as CanReachOrdering, d as ExplorePathsOptions, f as ExploreSnapshot, g as SimulateAgentResult, h as SimulateAgentOptions, i as AgentPathReport, l as CanReachResult, m as LintAgentMachineOptions, n as AgentLintError, o as AgentUnknownStateError, p as ExploreStep, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as CanReachTarget, v as SimulationTrailEntry, w as textOutput, x as explorePaths, y as assertAgentMachine } from "./verify-H3Pr2gNw.mjs";
2
+ import { C as simulateAgent, S as lintAgentMachine, _ as SimulationScript, a as AgentPathTerminal, b as canReach, c as CanReachOrdering, d as ExplorePathsOptions, f as ExploreSnapshot, g as SimulateAgentResult, h as SimulateAgentOptions, i as AgentPathReport, l as CanReachResult, m as LintAgentMachineOptions, n as AgentLintError, o as AgentUnknownStateError, p as ExploreStep, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as CanReachTarget, v as SimulationTrailEntry, w as textOutput, x as explorePaths, y as assertAgentMachine } from "./verify-CIu4mqIZ.mjs";
3
3
  import { a as TrajectoryMatch, i as TrajectoryItem, n as TrajectoryEvent, o as TrajectoryMiss, r as TrajectoryEventEnvelope, s as matchesTrajectory, t as MatchTrajectoryOptions } from "./trajectory-BFjXaooB.mjs";
4
- import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-DHlq87G7.mjs";
4
+ import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-BxkeuAYR.mjs";
5
5
  import { n as AgentEventLogStore } from "./event-log-store-DYun526m.mjs";
6
6
  import { A as RecordedToolCall, C as RecordableLanguageModel, D as RecordedError, E as RecordedEffect, F as createRecorder, I as sameModelCallShape, M as Recording, N as RecordingDivergenceError, O as RecordedModelCall, P as compareRecordings, S as RecordableDecisionModel, T as RecordedCall, _ as ModelAnswer, b as RecordCallOptions, f as CompareRecordingsOptions, g as EquivalenceReport, h as EffectDivergenceReason, j as Recorder, k as RecordedOutput, m as EffectDivergence, p as CreateRecorderOptions, t as MetaOfSnapshot, v as ModelCallMatch, w as RecordableModel, x as RecordClientOptions, y as NormalizeEffect } from "./utils-B8k-YPYI.mjs";
7
7
  import { AnyActorLogic, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
package/dist/testing.mjs CHANGED
@@ -2,9 +2,9 @@ import { I as getCallUsage, L as isTextLogic, R as normalizeGeneratorResult, c a
2
2
  import { s as isDecisionLogic } from "./decision-B41YBx5U.mjs";
3
3
  import { i as isActLogic } from "./act-Bsz-hUfD.mjs";
4
4
  import { n as createInMemoryEventLogStore } from "./event-log-store-DLAfNM34.mjs";
5
- import { f as isStateMachineLogic, g as toJsonValue, l as createAgentRuntime, m as runToQuiescence } from "./run-agent-BE7DOWD6.mjs";
5
+ import { f as isStateMachineLogic, g as toJsonValue, l as createAgentRuntime, m as runToQuiescence } from "./run-agent-D3gW9wfd.mjs";
6
6
  import { n as mapEffects, t as isAsyncIterable } from "./effects-B9IvUPVh.mjs";
7
- import { a as explorePaths, c as simulateAgent, i as canReach, l as textOutput, n as AgentUnknownStateError, r as assertAgentMachine, s as lintAgentMachine, t as AgentLintError } from "./verify-CWlg3j7B.mjs";
7
+ import { a as explorePaths, c as simulateAgent, i as canReach, l as textOutput, n as AgentUnknownStateError, r as assertAgentMachine, s as lintAgentMachine, t as AgentLintError } from "./verify-Cacz6XSk.mjs";
8
8
  import { t as matchesTrajectory } from "./trajectory-BUXj_1Ue.mjs";
9
9
  //#region src/equivalence.ts
10
10
  /**
package/dist/validate.cjs CHANGED
@@ -24,7 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
24
24
  const require_event_log = require("./event-log-dSOnXHuG.cjs");
25
25
  const require_decision = require("./decision-D8bcIGXQ.cjs");
26
26
  const require_setup_agent = require("./setup-agent-Dv5VpuHe.cjs");
27
- const require_verify = require("./verify-Dek6gHCS.cjs");
27
+ const require_verify = require("./verify-D8UDqU4l.cjs");
28
28
  let ajv_dist_2020_js = require("ajv/dist/2020.js");
29
29
  ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
30
30
  //#region schemas/agent-workflow.json
@@ -1,4 +1,4 @@
1
- import { d as ExplorePathsOptions } from "./verify-BM0sGmsf.cjs";
1
+ import { d as ExplorePathsOptions } from "./verify-CTHlmBbh.cjs";
2
2
  import { _ as FromConfigOptions, f as AgentWorkflowConfig, y as SchemaCompiler } from "./setup-agent-Cv8Hk3mX.cjs";
3
3
  import { AnyActorLogic, AnyStateMachine } from "xstate";
4
4
  //#region src/validate/validate-config.d.ts
@@ -1,4 +1,4 @@
1
- import { d as ExplorePathsOptions } from "./verify-H3Pr2gNw.mjs";
1
+ import { d as ExplorePathsOptions } from "./verify-CIu4mqIZ.mjs";
2
2
  import { _ as FromConfigOptions, f as AgentWorkflowConfig, y as SchemaCompiler } from "./setup-agent-DgFAhaPJ.mjs";
3
3
  import { AnyActorLogic, AnyStateMachine } from "xstate";
4
4
  //#region src/validate/validate-config.d.ts
package/dist/validate.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  import { D as DECIDE_ACTOR, O as GENERATE_TEXT_ACTOR, T as ACT_ACTOR, k as STREAM_TEXT_ACTOR } from "./event-log-CEq_bVXQ.mjs";
2
2
  import { p as payloadNeedsFillModel } from "./decision-B41YBx5U.mjs";
3
3
  import { i as setupAgentFromConfig } from "./setup-agent-CLm6QVGy.mjs";
4
- import { a as explorePaths, s as lintAgentMachine } from "./verify-CWlg3j7B.mjs";
4
+ import { a as explorePaths, s as lintAgentMachine } from "./verify-Cacz6XSk.mjs";
5
5
  import Ajv2020 from "ajv/dist/2020.js";
6
6
  //#region schemas/agent-workflow.json
7
7
  var agent_workflow_default = {
@@ -169,6 +169,11 @@ interface SimulationTrailEntry {
169
169
  }
170
170
  /** Options for {@link simulateAgent}. */
171
171
  interface SimulateAgentOptions {
172
+ /**
173
+ * The machine input. A machine with a declared input schema validates it as
174
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
175
+ * the parsed value (defaults filled) seeds the search.
176
+ */
172
177
  input?: unknown;
173
178
  script: SimulationScript;
174
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -268,12 +273,21 @@ interface ExploreStep {
268
273
  interface CanReachOrdering {
269
274
  /** The trigger: an event type, or a step predicate. */
270
275
  after: string | ((step: ExploreStep) => boolean);
271
- /** Checked on every step after the first `after` step, not on that step itself. */
276
+ /**
277
+ * Checked on the first `after` step and every step after it. On the
278
+ * trigger's own step, `started`, `settled` and `state` are its effects;
279
+ * `event` is the trigger itself.
280
+ */
272
281
  reach: (step: ExploreStep) => boolean;
273
282
  }
274
283
  /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
275
284
  type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
276
285
  interface ExplorePathsOptions {
286
+ /**
287
+ * The machine input. A machine with a declared input schema validates it as
288
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
289
+ * the parsed value (defaults filled) seeds the search.
290
+ */
277
291
  input?: unknown;
278
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
279
293
  maxDepth?: number;
@@ -169,6 +169,11 @@ interface SimulationTrailEntry {
169
169
  }
170
170
  /** Options for {@link simulateAgent}. */
171
171
  interface SimulateAgentOptions {
172
+ /**
173
+ * The machine input. A machine with a declared input schema validates it as
174
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
175
+ * the parsed value (defaults filled) seeds the search.
176
+ */
172
177
  input?: unknown;
173
178
  script: SimulationScript;
174
179
  /** Max steps before returning `'exhausted'`. Default 100. */
@@ -268,12 +273,21 @@ interface ExploreStep {
268
273
  interface CanReachOrdering {
269
274
  /** The trigger: an event type, or a step predicate. */
270
275
  after: string | ((step: ExploreStep) => boolean);
271
- /** Checked on every step after the first `after` step, not on that step itself. */
276
+ /**
277
+ * Checked on the first `after` step and every step after it. On the
278
+ * trigger's own step, `started`, `settled` and `state` are its effects;
279
+ * `event` is the trigger itself.
280
+ */
272
281
  reach: (step: ExploreStep) => boolean;
273
282
  }
274
283
  /** What {@link canReach} looks for: a state id or path, a snapshot predicate, or an ordering. */
275
284
  type CanReachTarget = string | ((snapshot: ExploreSnapshot) => boolean) | CanReachOrdering;
276
285
  interface ExplorePathsOptions {
286
+ /**
287
+ * The machine input. A machine with a declared input schema validates it as
288
+ * a run does: input the schema rejects throws `invalid-machine-input`, and
289
+ * the parsed value (defaults filled) seeds the search.
290
+ */
277
291
  input?: unknown;
278
292
  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
279
293
  maxDepth?: number;
@@ -1,5 +1,6 @@
1
1
  import { $ as getJsonSchemaSync, C as AGENT_USAGE_EVENT_TYPE, K as getRegisteredAgentExecutionOptions, L as isTextLogic, W as executorBoundLogics, ft as isRecord, pt as AgentError } from "./event-log-CEq_bVXQ.mjs";
2
2
  import { _ as isEventPattern, g as getHumanEventTypes, h as getAcceptedEvents, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as resolveDecision } from "./decision-B41YBx5U.mjs";
3
+ import { t as resolveMachineInput } from "./machine-input-0YTPcnCm.mjs";
3
4
  import { getInitialMicrosteps, getMicrosteps, getNextTransitions, initialTransition, machineToJSON, transition } from "xstate";
4
5
  //#region src/steps.ts
5
6
  /**
@@ -578,6 +579,7 @@ function takeFromQueue(channel, src) {
578
579
  * ```
579
580
  */
580
581
  async function simulateAgent(machine, options) {
582
+ options = withMachineInput(machine, options, "simulateAgent");
581
583
  const maxSteps = options.maxSteps ?? 100;
582
584
  const script = {
583
585
  text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
@@ -1093,13 +1095,13 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1093
1095
  if (!logging) return next;
1094
1096
  const before = prev && logs.get(prev);
1095
1097
  const step = exploreStep(prev, next, timerDelivers.get(event) ?? event);
1096
- const after = before?.after ?? false;
1097
1098
  const trigger = ordering?.after;
1099
+ const after = (before?.after ?? false) || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step));
1098
1100
  logs.set(next, {
1099
1101
  step,
1100
1102
  prev: before,
1101
1103
  length: (before?.length ?? 0) + 1,
1102
- after: after || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step)),
1104
+ after,
1103
1105
  violated: (before?.violated ?? false) || after && ordering.reach(step)
1104
1106
  });
1105
1107
  return next;
@@ -2293,6 +2295,19 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2293
2295
  };
2294
2296
  }
2295
2297
  /**
2298
+ * Validates `options.input` against the machine's input schema, as a run
2299
+ * would, and seeds the search with the parsed value (defaults filled). Input
2300
+ * the machine would reject throws `invalid-machine-input` instead of giving a
2301
+ * proof over a start state no run can reach.
2302
+ */
2303
+ function withMachineInput(machine, options, caller) {
2304
+ if (options.input === void 0) return options;
2305
+ return {
2306
+ ...options,
2307
+ input: resolveMachineInput(machine, options.input, caller)
2308
+ };
2309
+ }
2310
+ /**
2296
2311
  * Enumerates a machine's decision and external-event branches to a bounded
2297
2312
  * depth, model-free, and reports which states are reached and how each path
2298
2313
  * terminates. At each decision request it forks one branch per candidate event
@@ -2329,7 +2344,7 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2329
2344
  * ```
2330
2345
  */
2331
2346
  async function explorePaths(machine, options = {}) {
2332
- return explore(machine, options).report;
2347
+ return explore(machine, withMachineInput(machine, options, "explorePaths")).report;
2333
2348
  }
2334
2349
  /** Thrown when a string reachability target is not a state in the machine. */
2335
2350
  var AgentUnknownStateError = class extends AgentError {
@@ -2378,6 +2393,7 @@ function resolveStateTarget(machine, target) {
2378
2393
  * ```
2379
2394
  */
2380
2395
  async function canReach(machine, target, options = {}) {
2396
+ options = withMachineInput(machine, options, "canReach");
2381
2397
  const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
2382
2398
  const ordering = typeof target === "object" ? target : void 0;
2383
2399
  const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0);
@@ -1,5 +1,6 @@
1
1
  const require_event_log = require("./event-log-dSOnXHuG.cjs");
2
2
  const require_decision = require("./decision-D8bcIGXQ.cjs");
3
+ const require_machine_input = require("./machine-input-DU3owLUr.cjs");
3
4
  let xstate = require("xstate");
4
5
  //#region src/steps.ts
5
6
  /**
@@ -578,6 +579,7 @@ function takeFromQueue(channel, src) {
578
579
  * ```
579
580
  */
580
581
  async function simulateAgent(machine, options) {
582
+ options = withMachineInput(machine, options, "simulateAgent");
581
583
  const maxSteps = options.maxSteps ?? 100;
582
584
  const script = {
583
585
  text: mapValues(options.script.text ?? {}, (arr) => [...arr]),
@@ -1093,13 +1095,13 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
1093
1095
  if (!logging) return next;
1094
1096
  const before = prev && logs.get(prev);
1095
1097
  const step = exploreStep(prev, next, timerDelivers.get(event) ?? event);
1096
- const after = before?.after ?? false;
1097
1098
  const trigger = ordering?.after;
1099
+ const after = (before?.after ?? false) || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step));
1098
1100
  logs.set(next, {
1099
1101
  step,
1100
1102
  prev: before,
1101
1103
  length: (before?.length ?? 0) + 1,
1102
- after: after || trigger !== void 0 && (typeof trigger === "string" ? step.event.type === trigger : trigger(step)),
1104
+ after,
1103
1105
  violated: (before?.violated ?? false) || after && ordering.reach(step)
1104
1106
  });
1105
1107
  return next;
@@ -2293,6 +2295,19 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2293
2295
  };
2294
2296
  }
2295
2297
  /**
2298
+ * Validates `options.input` against the machine's input schema, as a run
2299
+ * would, and seeds the search with the parsed value (defaults filled). Input
2300
+ * the machine would reject throws `invalid-machine-input` instead of giving a
2301
+ * proof over a start state no run can reach.
2302
+ */
2303
+ function withMachineInput(machine, options, caller) {
2304
+ if (options.input === void 0) return options;
2305
+ return {
2306
+ ...options,
2307
+ input: require_machine_input.resolveMachineInput(machine, options.input, caller)
2308
+ };
2309
+ }
2310
+ /**
2296
2311
  * Enumerates a machine's decision and external-event branches to a bounded
2297
2312
  * depth, model-free, and reports which states are reached and how each path
2298
2313
  * terminates. At each decision request it forks one branch per candidate event
@@ -2329,7 +2344,7 @@ function explore(machine, options, stopWhen, nesting = 0, deliverable, childRef,
2329
2344
  * ```
2330
2345
  */
2331
2346
  async function explorePaths(machine, options = {}) {
2332
- return explore(machine, options).report;
2347
+ return explore(machine, withMachineInput(machine, options, "explorePaths")).report;
2333
2348
  }
2334
2349
  /** Thrown when a string reachability target is not a state in the machine. */
2335
2350
  var AgentUnknownStateError = class extends require_event_log.AgentError {
@@ -2378,6 +2393,7 @@ function resolveStateTarget(machine, target) {
2378
2393
  * ```
2379
2394
  */
2380
2395
  async function canReach(machine, target, options = {}) {
2396
+ options = withMachineInput(machine, options, "canReach");
2381
2397
  const resolvedTarget = typeof target === "string" ? resolveStateTarget(machine, target) : void 0;
2382
2398
  const ordering = typeof target === "object" ? target : void 0;
2383
2399
  const { witness, report } = explore(machine, options, typeof target === "function" ? target : ordering ? () => false : (snapshot) => snapshot.nodes.some((node) => node.id === resolvedTarget), 0, void 0, void 0, resolvedTarget !== void 0 && hasTransientStates(machine.getStateNodeById(resolvedTarget)), void 0, false, ordering, resolvedTarget !== void 0);
package/docs/hosts.md CHANGED
@@ -309,7 +309,7 @@ Each operation is described in [The runtime loop](steps.md).
309
309
 
310
310
  ### Host events mid-run
311
311
 
312
- `runtime.send(event)` puts a host event in the run's mailbox, behind whatever already arrived. A `nextEvent()` parked on a pending request resolves with it; the loop applies it with `transition` like any other event.
312
+ `runtime.send(event)` queues a host event behind earlier host sends and ahead of completions the run holds but has not handed out. A `nextEvent()` parked on a pending request resolves with it; the loop applies it with `transition` like any other event.
313
313
 
314
314
  ```ts no-check
315
315
  const runtime = createAgentRuntime(machine, { executors });
@@ -325,7 +325,7 @@ for (let event; (event = await runtime.nextEvent());) {
325
325
  const result = await runtime.finish();
326
326
  ```
327
327
 
328
- - **Ordering.** One FIFO with request completions, child messages, and timers. A send during a pending invoke is handed out by the next `nextEvent()`; the invoke keeps running unless the transition leaves its state, which aborts its `signal`.
328
+ - **Ordering.** Host sends keep their own order and go ahead of request completions, child messages, and timers the run already holds, which keep theirs. A send during a pending invoke is handed out by the next `nextEvent()`; the invoke keeps running unless the transition leaves its state, which aborts its `signal`.
329
329
  - **Journal.** A sent event is a log entry, the same as `runAgent({ event })`. Replaying `result.events` lands on the same state.
330
330
  - **Unhandled.** A sent event the state has no transition for is reported as `result.ignored`.
331
331
  - **Before `start`.** Queued; the first `nextEvent()` hands it out. Returns `true`.
@@ -380,6 +380,8 @@ const result = await runAgent(machine, {
380
380
  - the loop never applies it;
381
381
  - the machine handled it but settles still `active` (an idle wait nothing will answer), immediately and without waiting for `timeout`;
382
382
  - `timeout` ms pass while the machine is still active and working.
383
+ - `event` is a function and it throws; the run's `error` is what it threw.
384
+ - **Per reason.** `event` can be a function of `signal.reason`, so a pause and a stop send different events: `abortWith: { event: (reason) => ({ type: reason === "pause" ? ("PAUSE" as const) : ("STOP" as const) }) }`. As with `onIdle`, an event built in a function needs `as const` for its `type`.
383
385
  - **Journal.** The abort event is a log entry; replay reaches the same final state.
384
386
 
385
387
  ### runAgent inbox
@@ -395,7 +397,7 @@ const result = await run;
395
397
 
396
398
  - **Same as `runtime.send`.** Each `inbox.send` goes to the run's mailbox and returns the same boolean. See [Host events mid-run](#host-events-mid-run).
397
399
  - **Before start.** Queued; delivered after the init event and after `runAgent`'s own `event`. Returns `true`.
398
- - **While idle.** An inbox event resumes the run, ahead of a pending `onIdle` answer; that answer is dropped. Without `onIdle`, `runAgent` returns at the first idle.
400
+ - **While idle.** An inbox event resumes the run, ahead of a pending `onIdle` answer; that answer is dropped. Without `onIdle`, `runAgent` returns at the first idle. With `onIdle: "inbox"`, an idle state waits for the next `inbox.send` (a resume after a pause) and has no answer of its own.
399
401
  - **Ignored.** An inbox event the state does not handle is reported as `result.ignored`. Unlike an ignored `onIdle` answer, it does not end the `onIdle` loop.
400
402
  - **After `runAgent` returns.** Returns `false`.
401
403
  - **One call.** An inbox serves one `runAgent` call; reusing it throws `AgentError` `inbox-in-use`.