plyngent/doc/turns-and-rounds.md

# Turns and Rounds

Two nested units of work carry most of the loop's state. A **round** is one
request→response exchange with the provider plus the tool calls it asked for; a
**turn** is everything between a user message and the explicit stop that ends it.
A session is a stored sequence of turns.

```
turn ─┬─ round ─┬─ request  (hosted tools, history, system prompt)
      │         ├─ response (one assistant message)
      │         └─ tool batch (0..n calls, executed before the next round)
      ├─ round …
      └─ explicit stop (a round with no tool calls)
```

## Round — one model round trip

A round is one completion request and the single assistant message it produced,
followed by the tool calls that message asked for (one batch). The next round
starts only after that batch has reported results.

- **Identity.** One `UsageEvent` per round: `ChatAgent` counts them into
  `last_turn_rounds` (`agent/chat.py`). `AssistantMessageEvent` carries the
  response, `ToolCallEvent`/`ToolResultEvent` the batch. The transcript's
  `rounds=N` label counts the rounds that asked for tools (every round but the
  final one), so `/history` and `last_turn_rounds` can differ by that stop round.
- **Ends.** In one of four ways: with tool calls (the loop continues), with no
  tool calls (natural stop → the turn ends), at the output limit
  (`TruncatedEvent`, `finish_reason=length`: answer and thinking stay, that
  round's tool calls are dropped and a notice is appended; up to
  `max_truncation_continues` more rounds of the same turn carry on from there),
  or in an error (a retry re-runs the round).
- **Bounds.** `max_rounds` per turn (default `DEFAULT_MAX_ROUNDS = 32`,
  `agent/loop.py`). Reaching the allowance yields `MaxRoundsEvent(rounds,
  continued=False)` — `rounds` is the allowance that ran out — unless the
  `on_limit` hook answers yes (CLI: `y`/`n`/`yyy` prompt in `cli/limits.py`):
  then the event says `continued=True` and another `max_rounds` are granted.
- **Parallelism.** Calls of one round run concurrently (`parallel_tools`), but
  calls naming the same file serialize through per-file write locks, and the
  soft confirm for a round is decided once, before the batch runs
  (`ToolRegistry.prepare_batch_confirm`).
- **Round-scoped work.** Request assembly, context reduction / tool-result
  truncation over `max_context_tokens`, provider-tool (hosted search) blocks,
  and the usage sample are all per round.
- **Not durable on its own.** Only committed prefixes are persisted as they
  happen — a complete tool batch with its results, plus trailing developer
  notices. A final text answer is committed at turn end, so a turn that dies
  mid-round leaves its side effects in history but not a half-written answer.

## Turn — one user message to the explicit stop

A turn begins when the user message is appended (`ChatAgent.run`, which also
persists the message immediately) and ends at the explicit stop.

- **Explicit stop.** The first round whose assistant message has no tool calls.
  A turn also ends at a boundary: `max_rounds` without continuing,
  truncation-continues exhausted (left for `/retry`), cancellation (Ctrl+C), or
  an unrecovered error — the tail is rolled back to the committed prefix and the
  user message stays so `/retry` can continue.
- **Rounds per turn.** Zero (a failure before the first response) to many.
  `retry` continues the *same* turn — it reuses the user message instead of
  appending a new one — so retries never create another turn.
- **Turn-scoped state** (reset at the start of the next turn):
  - read-before-edit: line-numbered `read_file` authorizes `edit_lineno` for that
    path (mtime-checked) for this turn only (`reset_lineno_tracker`);
  - `yyy` limit auto-continue: cleared before and after
    `run_turn_with_retries`, so a retry of the same turn keeps it and the next
    user turn prompts again;
  - `/yolo once`: expires when the turn finishes (`expire_yolo_once`), so it
    covers exactly one turn;
  - todo nagging: `todo_stack.begin_turn()` clears the "touched" flag; any
    `todo_*` tool sets it again, and `needs_review()` at the stop decides whether
    a stack untouched this turn gets the review reminder;
  - usage totals: `last_turn_usage` and `last_turn_rounds` sum the turn's rounds
    (`last_request_usage` keeps the last round's sample).
- **Not turn-scoped.** Session identity and stored rows, the todo stack's
  contents, soft-confirm trust (path grants, access/skill grants, `TRUSTABLE`
  tool grants), and directive-reminder bands outlive the turn.

## Session

A session is the stored sequence of turns; the transcript groups rows by turn,
and `/history N` addresses a turn by number. Compaction rewrites the history sent
in one request and never moves a turn boundary. A side turn (`run_aside`) is a
turn whose history is forked and never written back.

## Where it lives

| unit | begins | ends | counters / records |
| --- | --- | --- | --- |
| round | provider request | response assembled, tool batch done | `UsageEvent`, `last_turn_rounds`, `MaxRoundsEvent`, `TruncatedEvent` |
| turn | `ChatAgent.run` appends the user message | a round with no tool calls (or a boundary) | session rows, `last_turn_usage` |
| session | first turn | process exit / session switch | store tables, transcript |

Loop mechanics: `agent/loop.py` (`run_chat_loop`); turn bookkeeping:
`agent/chat.py` (`ChatAgent.run` / `retry` / `_run_from_user_message`); retry and
turn-scoped flags: `cli/retry.py`, `cli/limits.py`.