Concepts

Watch and steer live

Follow a run as it works, send it the next instruction, stop it, or take over its desktop. Every surface reads the same event stream.

View .md

A run is not a black box you wait on. While it works you can read its events as they happen, send it follow-ups, cancel it, and in the console watch or drive the computer it is using. The API, the console and the CLI read the same stream and write the same session.

04The turn ends; the queued one goes in

Scene. The live stream, and what a follow-up sent mid-turn gets: refused with 409 for an API key, queued for the console and the CLI.

The event stream

GET /o/{org}/sessions/{session}/events is a server-sent event stream. Each frame is an event: line, an id: and a JSON data: line.

Event	When
`status`	Before the sandbox starts, and on every status change. Data: `{status}`.
`message`, `thinking`	The agent's own text and reasoning.
`tool_use`, `tool_result`	A tool call and its outcome, linked by `call_id`.
`result`	The turn's final answer.
`error`	A harness error. An `error` with no `type` (`{code, message}`, code `NOT_FOUND` or `STREAM_ERROR`) ends the stream early.
`done`	The last frame. Data: `{status, output, result}`.

The stream closes after done. If your connection drops, reconnect with the Last-Event-ID header (or ?cursor=) set to the last id you saw, and the stream resumes after it. Comment lines (: keepalive) hold idle connections open.

A session that has already finished sends only status and done, never its history. Read past events from GET …/messages.

curl -N https://api.prix.dev/o/$ORG/sessions/$SESSION/events \
  -H "Authorization: Bearer $RUSH_API_KEY" -H "Last-Event-ID: $LAST_ID"

Follow-ups

A follow-up is the next instruction in the same session: POST …/messages with {"input": "…"}, the same text or file blocks a run takes. It answers 202 with the session, status running, and wakes a parked sandbox where it left off.

How a follow-up sent mid-turn behaves depends on who sends it:

An API key must wait for the turn to end. While a turn is running the follow-up is refused with 409 TURN_ACTIVE. Wait for done, or for status to leave running, then send it.
The console or the CLI queue a text-only message sent mid-turn, up to 20, and deliver them in order when the turn ends. One more answers 429 QUEUE_FULL. A message with files waits for the turn to end.

A follow-up to a closed session is 409 TASK_TERMINAL.

Cancel

POST …/cancel, with no body, ends the run and releases its sandbox. It answers 202 with the session: status cancelled, or cancelling while the sandbox is still being released. A run that has already finished answers 409 RUN_STATE_CONFLICT.

Browser and computer

A run's sandbox has a desktop and a browser the agent uses. From the run's page in the console, the run's owner or an org admin can:

Watch the display, read-only. Any number of people can watch at once.
Take control of mouse and keyboard.
Open a terminal in the sandbox.

For anyone else in the org, a run's live surfaces answer 404, as if the run did not exist. A run with no desktop to show answers 409 VISUAL_UNAVAILABLE.

The control lease

05Control goes back to the agent

Scene. Taking control of a run's browser: one holder at a time, on a five-minute lease. Only the run's owner or an org admin can take it.

Only one person drives a desktop at a time. Taking control grants a control lease for 5 minutes, which the holder can renew while they work, up to 15 minutes ahead. While someone holds it, another request to take control answers 409 CONTROL_HELD with the holder's name and when their lease expires.

The holder releases it when done, and a run owner or org admin can release anyone's lease. When the run ends (completed, failed or cancelled) the lease ends with it.

Steer a run as a team walks through handing a run between people.