# Sessions

> A session is one run of an agent's work, with a status, a headline, its progress and any open ask, which its messages belong to.

A **session** is one run of work: a build, a migration, an agent's task. It has a title, a headline of what it is
doing now, its progress and the ask it is waiting on, if any, and the messages and asks sent in it belong to it.

## Start, update, end

```sh
export KABU_SESSION=$(kabu session start --title "Migrate billing" --external-id run-77 | jq -r .id)
kabu session update --headline "Copying tables" --progress 2/5 --progress-label tables
kabu session end --outcome success --summary "All 5 tables copied"
```

Report progress only when it is measurable (items done of a known total) or for known steps; set `--progress-label` to
what is counted; never estimate a percentage; otherwise send only a `--headline`. The app shows progress exactly as
sent, never converted to a percentage: a count reads "2 of 5 tables" with a bar, steps read "Step 3 of 8 · " and the
label of the step marked `doing`, and with no progress there is no bar.

Over HTTP, the same three calls:

| Call | Body |
|---|---|
| `POST /v2/sessions` | `title`, and optionally `project`, `agent`, `external_id`, `to` and `live` |
| `PATCH /v2/sessions/{session_id}` | `status` (`running` or `idle`), `headline`, `progress` (`value`, `total`, `label`, `steps`) |
| `POST /v2/sessions/{session_id}/end` | `outcome` (`success`, `failure` or `cancelled`), `summary`, `dismiss_after` |

Starting is get-or-create on the project, the agent and your `external_id`: a job that restarts and starts its session
again gets the same one back.

## Messages in a session

A message with `session` set belongs to it (`kabu` sets it from `KABU_SESSION`). While an ask of the session is
pending, the session's status is `waiting`.

Ending a session cancels its open asks, and a session that has ended takes no new messages: sending to it is `409`
[`session_ended`](/docs/errors/session_ended). Start a new one instead.

## Statuses

| Status | Means |
|---|---|
| `running` | Work is going on |
| `waiting` | An ask of the session is waiting for an answer |
| `idle` | Started, nothing happening now |
| `ended` | Finished, with its `outcome` |