State and interaction

Three state lifetimes

• Node outputs and store-* values live in WorkflowContext for one workflow execution.
• memory-file-* reads and replaces complete UTF-8 files through configured file memories.
• memory-value-* reads and writes JSON values through configured key/value drivers.

Every node names an entry from config/memories.yaml. scope defaults to named; session scope requires the workflow call to provide a session ID and the selected driver to support it. Calls to POST /api/runs accept sessionId, webhook calls accept x-session-id, and channel instances use their instance ID. The fixed-file driver deliberately rejects session scope; the SQLite key-value driver supports both named and session scopes.

• Async run records, events, callbacks, and checkpoints live in the server run store and follow run-retention policy where applicable.

Values crossing a persistence boundary must be JSON-compatible. Use stable, namespaced keys and design writes to tolerate at-least-once execution.

Interaction input

interaction-input accepts one question or a group. Questions have stable IDs, a question or approval kind, prompt, optional choices, metadata, and optional tool-call details. If an interaction callback answers immediately, execution continues. Otherwise, a checkpoint is written and the run becomes suspended.

Every pending request is stored. Private requests are omitted from the default pending list, while broadcasted requests appear on the application WebSocket. Schedules default to public and broadcasted; channel requests default to private and non-broadcasted. Nested workflow and workflow-tool calls inherit these settings. Suspended runs embed the complete request in GET /api/runs/:id, and direct request lookup and resolution remain available by ID. Resolving restores the saved workflow/context and continues from the suspended node. Grouped responses are objects keyed by question ID.

Durable execution expectations

Queued async runs survive restart. A run interrupted while executing is requeued, so externally visible side effects can repeat. Callbacks retry, and schedules may perform one catch-up occurrence after downtime. Use idempotency keys at downstream boundaries whenever possible.