Enrai Task Queue

Purpose

The backend exposes a queue so external systems, scripts, or future UI flows can submit Enrai jobs without colliding with an already running turn.

Queue modal

This screenshot should make the queue feel real: one running task, at least one completed task, and a visible rollout action.

Drop replacement PNG here

Replace documentation/public/images/editor-task-queue.png. Keep the queue tab selected and leave the webhook block visible.

• Configuration modal open on the Queue or Completed tab
• A running task with live activity or output
• A completed task with an open-rollout action visible
• The compact webhook block visible somewhere in the modal

documentation/public/images/editor-task-queue.png

Enqueue endpoint

POST /api/enrai/tasks

Behavior

• If rollout or resume_path is provided, Enrai resumes that rollout and continues the thread.
• If no rollout is provided, Enrai starts a fresh Enrai session for the task.
• Tasks are executed one at a time.
• When a task finishes as completed, failed, or interrupted, Enrai can notify another system with a POST callback.
• Queue state is available from:
  • GET /api/enrai/tasks
  • SSE event task_queue
  • DELETE /api/enrai/tasks/:id for queued task cancellation

Completion notifications

Enrai can send an outbound POST when a queued task reaches a terminal state.

You can configure this in two ways:

• globally in the editor Preferences as Task callback URL
• per request with callback_url in POST /api/enrai/tasks

Accepted terminal states:

• completed
• failed
• interrupted

Example callback payload:

{
  "event": "task.completed",
  "timestamp": "2026-03-19T18:42:10.000Z",
  "task": {
    "id": "task-7",
    "status": "completed",
    "summary": "Add a health endpoint",
    "resume_path": "/Users/you/.codex/sessions/.../rollout-....jsonl",
    "workdir": "/workspace/demo"
  }
}

cURL examples

Continue an existing rollout:

curl -X POST http://localhost:3001/api/enrai/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Continue the auth refactor and run tests",
    "rollout": "rollout-2026-03-18T20-28-17-019d03b5-2ac6-77a3-91d9-97c1c18d5f2d.jsonl"
  }'

Create a brand new session:

curl -X POST http://localhost:3001/api/enrai/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Create a healthcheck endpoint in the current project",
    "workdir": "./backend/projects/demo",
    "callback_url": "https://automation.example.com/enrai/task-finished"
  }'

List queue state:

curl http://localhost:3001/api/enrai/tasks

Cancel a queued task:

curl -X DELETE http://localhost:3001/api/enrai/tasks/task-3

Example payload

{
  "text": "Add a health endpoint and run tests",
  "rollout": "rollout-2026-03-18T20-28-17-019d03b5-2ac6-77a3-91d9-97c1c18d5f2d.jsonl",
  "workdir": "./backend/projects/demo",
  "callback_url": "https://automation.example.com/enrai/task-finished",
  "instructions": "Keep the change small and avoid unrelated refactors.",
  "manifest": {
    "goal": "safe-change",
    "testing": "required"
  }
}

Prompt model

The manifest field is an Enrai-specific convention. It is serialized into the prompt for the queued task. It is useful for per-task behavior shaping without mutating global config.

Official behavior is generally controlled through:

• AGENTS.md in the repository
• model_instructions_file in ~/.codex/config.toml
• runtime developer instructions injected by the harness