Conversations, tasks & approvals
How a message becomes a task, the six states it passes through, and the three approval modes.
The model
A conversation is a thread bound to one agent and optionally to one working directory. A task is a single message inside it. Each task gets an id you can poll until it reaches a terminal state.
Task states
| State | Meaning |
|---|---|
| queued | Accepted, not yet written into the terminal |
| sent | Written into the running session |
| working | The agent is producing output |
| completed | Finished, with a parsed result |
| completed_with_raw | Finished, but only raw screen output could be captured |
| failed | Ended with an error; a failure reason is attached |
Poll GET /api/message/:id to follow a task. The response carries status, plus response, rawOutput, error, failureReason, modelId, duration and completedAt as they become available.
Approval modes
| Mode | Behaviour |
|---|---|
| safe | Runs routine commands; asks before anything risky |
| askAll | Asks for approval before every command |
| auto | Approves without asking |
The mode is stored globally and can be overridden per conversation. When a command needs approval, POST /api/message answers with status pending_approval plus an approval object; resolve it with POST /api/approvals/:id using approve, deny or always_approve. GET /api/approvals lists what is waiting.
Conversation lifecycle
| Operation | Endpoint |
|---|---|
| List / create | GET, POST /api/conversations |
| Read / update / delete | GET, PATCH, DELETE /api/conversations/:id |
| Make active | POST /api/conversations/:id/activate |
| Send a task | POST /api/message |
| Follow a task | GET /api/message/:id |
Creating a conversation accepts agentId, workdir, approvalMode and an optional firstMessage. Updating accepts title, archived, pinned, workdir, agentId, approvalMode, modelId and modelProviderId.
No manual session start on mobile