Skip to content

Runtime Orchestration

This page describes the Postgres-backed durable orchestration model used for agent execution.

Core Model

The runtime is centered on explicit durable state tables:

  • agent_runs – run lifecycle (queued, leased, waiting_on_child, sleeping, terminal states)
  • agent_run_steps – step checkpoints for model/tool/finalize transitions
  • tool_calls – durable tool-call execution state and idempotency tracking
  • scheduled_tasks – deferred execution (for example parent resume tasks, chat titles, embedding sync)
  • event_inbox / event_outbox – durable ingress and egress event channels

Execution Flow

  1. A run is enqueued into agent_runs (and an audit/replay event is appended).
  2. The claim worker leases runnable rows from agent_runs.
  3. Execution emits step checkpoints into agent_run_steps.
  4. Tool calls are tracked in tool_calls.
  5. Terminal transitions update agent_runs and append outbox events.
  6. Waiting parent runs, chat-title generation, and embedding sync are resumed via scheduled_tasks.

Event Log Position

The append-only event log is no longer the scheduler/queue for runtime work. It remains in use for agent-run audit/replay and stream catch-up, plus legacy historical rows.

Runtime orchestration authority is in the runtime tables above.

Runtime APIs

  • POST /api/v1/runtime-events/inbox (requires runtime-events:write)
  • GET /api/v1/runtime-events/stream (requires runtime-events:read)

The stream endpoint is workspace-scoped and publishes runtime bus events from outbox dispatch.