Runs
A run is one turn of one agent: everything the agent's process wrote while it ran that turn. Its
id is the agent id, a dot and the turn number, for example
6f1c2e0a-5d7b-4c1e-9a43-2b8f0e6d1a77.3. GET /v1/agents/{id}/turns/{n} names it in run.
The server stores each line of a run as it comes in (#591). You can attach to a run by its id at any time: while it runs, after it ended, and after the server restarted. You get the run from its first line, or from an offset, and then each new line until the run is over.
- Page.
/run?id=<run id>shows the run, one row per line, and follows it while it runs. Add&from=<offset>to start later. The row number is the line's offset. - CLI.
fleet attach <run id> [--from N]prints each line as JSON on stdout and returns when the run is over. If the stream drops (a server restart), it opens it again from the next offset, so no line prints twice. - API.
GET /v1/runs/{id}gives the run's state (runningordone) andnext, the offset after its last stored line.GET /v1/runs/{id}/events?from=Nis the stream as Server-Sent Events: alineevent per line (the event id is its offset), agapevent for offsets the server never had, and anendevent when the run is over.
An offset is the line's index in the turn's output as the node counts it. Offsets can skip a number (fleet's own control answers are not stored); a skip is not a gap. A gap is rare: the server stores each batch of lines before it acknowledges it to the node, so a restart loses nothing, but a failed disk write does.
Runs from before #591 have no stored lines: the page and fleet attach show an empty run. Their
conversation is still in the transcript.