Stately

Debugging

Use the XState inspection protocol for framework behavior and Agent traces for request behavior.

const result = await runToQuiescence(
  createAgentRuntime(machine, {
    executors,
    inspect: (event) => inspector.next(event),
    onTrace: (event) => logger.write(serializeTraceEvent(event)),
  }),
  { input },
);

inspect is the raw XState stream. onTrace adds Agent request start/end/error, chunks, usage, emitted events, transitions, and the terminal run result.

Common errors:

ErrorMeaning
AgentInvalidEventPayloadErrorA payload passed to parseAgentEvent was not { type, ... }, used a reserved @agent.* type, or failed the machine's event schema.
AgentDecisionExhaustedErrorEvery proposed decision was unknown, invalid, or guard-rejected.
AgentMaxModelCallsExceededErrorThe run exceeded its configured model-call budget.
XState version errorThe persisted snapshot version needs the machine's native migrate function.

An event the active state has no transition for is not an error: the run settles normally and the event comes back as result.ignored. Its machine.transition trace event carries ignored: true.

lintAgentMachine reports only Agent-specific mistakes: decisions with no candidate events, decisions that list an event only a person sends, direct object request sources that a host cannot bind, and invokes with no error path. General state-machine lint belongs in XState tooling.