# Runs and turns

Understand durable runs, individual turns, sandboxes, and cancellation.

A run is the durable agent context. A turn is one accepted unit of work inside
that run.

## Ownership

| Object     | Owns                                                         |
| ---------- | ------------------------------------------------------------ |
| Deployment | Immutable agent and sandbox configuration                    |
| Run        | Pi session, workspace, active sandbox, and pinned deployment |
| Turn       | One input, its execution state, output, and error            |
| Sandbox    | Replaceable compute for the run                              |

## Turn states

| Status        | Meaning                                      |
| ------------- | -------------------------------------------- |
| `queued`      | Accepted and waiting to start                |
| `in_progress` | Provider or tool execution is active         |
| `cancelling`  | Cancellation is accepted and is settling     |
| `completed`   | Work and required durability steps completed |
| `failed`      | Execution or required durability work failed |
| `cancelled`   | The turn was intentionally cancelled         |
| `incomplete`  | Execution stopped without a complete result  |

## Run and turn states can differ

The run state reports whether the durable context can accept work. The turn
status reports the selected unit of work.

For example, a cancelled turn can leave its run `idle`. The client can then
submit a new turn to the same run. A run can stay `busy` after one queued turn
is cancelled because another turn is still active.

## Cancellation

Cancel current work:

```http
POST /api/v1/runs/{runId}/cancel
```

Cancel a selected active or queued turn:

```json
{
  "turn_id": "turn_01J..."
}
```

Cancellation:

* requests an abort for active provider and tool work;
* removes a selected queued turn;
* settles the turn lifecycle;
* stops active sandbox compute through run cleanup when required.

## Deletion

Deletion is cleanup for an idle run. Do not use deletion as a substitute for
cancellation of active work.