Manual contents

Conversation states

This page lists the status values a conversation takes, what exists in each one, and which operations are legal. Read About conversations for what a conversation is.

Transitions

pending ---> running <---> idle
| | |
| v |
+--------> failed <-------+
any non-terminal state ---> terminated

idle returns to running when a follow-up prompt arrives. Each non-terminal state moves to terminated through POST /api/conversations/:id/terminate.

The states

Status What exists What you can do Terminal
pending The conversation row, and its resolved set of environment variables. No sandbox yet. Terminate it. No
running A sandbox, and a turn in flight. Interrupt the turn, stream events, terminate it. No
idle A sandbox, and no turn in flight. The sandbox can be live or suspended. Send a follow-up prompt, stream events, terminate it. No
failed The transcript and the log events. Managoat can have destroyed the sandbox already. Read the transcript. Launch a new conversation. Yes
terminated The transcript and the log events. Read the transcript. Yes

The sandbox is not the status

A conversation's status describes the run. It does not tell you whether a machine has power right now.

An idle conversation can have a live sandbox, a suspended one, or none at all. Which one depends on how long it has been idle, and on what the provider supports.

Sandbox event Trigger Effect on status Agent memory
Suspend Idle for SANDBOX_IDLE_TIMEOUT_MINUTES, 60 by default. None. It stays idle. Kept. The disk survives.
Wake The next prompt. idle to running. Kept.
Wake without a prompt POST /api/conversations/{id}/wake, or managoat conv wake <id>. None. It stays idle. Kept.
Destroy on ceiling It ran for SANDBOX_MAX_LIFETIME_HOURS. Off by default, so this never happens unless you set it. None. It stays resumable. Lost.
Destroy on idle It went idle on a provider with no :suspend capability. None. Lost.

Wake a conversation ahead of its next prompt when that prompt should not wait for the sandbox: open it in an app, then send. The response is awake when the sandbox was already up and waking when the request started it. The wake runs after the response, so a wake that fails shows up on the event stream as a wake stage in the failed state. A sandbox that is gone is replaced, as a prompt would replace it, and a woken conversation is suspended again after the same idle period.

Poll GET /api/sandboxes/{id} for status: "ready" and transition: null. A Sprites wake keeps transition: "resuming" until a no-op exec succeeds. Its probe retries transient failures for up to 60 seconds, plus any synchronous provider startup overrun. A failed or interrupted wake remains unreadable; retry the wake. Background wakes allow two minutes for the machine owner, including provider lookup and startup, while the HTTP response stays immediate. If that caller times out, the owner may still finish, so check the sandbox before retrying.

You set the idle timeout and max-lifetime ceiling for each instance. A 0 turns either one off, and the ceiling starts off. Read the configuration reference.

Warnings

Do not expect to resume a conversation in failed or terminated. Launch a new one.

An interrupt applies to the turn in flight, and not to the conversation. The conversation returns to idle and stays usable.

Do not terminate a conversation you want back. Termination destroys the sandbox, and the memory the agent works from goes with it. The transcript stays.

A sandbox that a configured ceiling reclaims leaves the conversation resumable, and leaves the agent without its earlier context. State what matters again on the next turn.

Where to go next