Debug runs

Faimulus supports stepwise debug execution for asynchronous runs.

Start a debug run

Send debug: true with POST /api/runs/async (or webhook async routes where supported):

{
  "flowPath": "book-document/flow.yaml",
  "input": { "document": "hello" },
  "debug": true
}

The server returns 202 with run metadata and a status URL.

Pause and continue lifecycle

Debug runs transition between running and paused:

1. The run starts and executes until the next debug boundary.
2. The run enters paused.
3. The client calls POST /api/runs/:id/continue.
4. The run resumes and may pause again until terminal status.

Other terminal states remain success, failure, or cancelled.

Continue endpoint

POST /api/runs/:id/continue advances exactly one paused debug step. Calling it on non-paused runs returns an error.

Observability

Use these endpoints during debugging:

• GET /api/runs/:id for durable status and node state snapshots.
• GET /api/runs/:id/events for a WebSocket snapshot of the current run followed by live ordered events. Per-run streams do not replay missed events; reconnect and refresh the snapshot after a disconnect.
• GET /api/interaction-requests when a run is suspended waiting for user input.

Debug control is part of the server control plane and is not delegated to remote runners.