harness-turns

name	harness-turns
description	How turns and cycle budgets work in Retainer's current shape — what max_turns means, what the watchdog does, what max_consecutive_errors triggers. Read when planning a multi-step task or when a cycle ended unexpectedly.
agents	cognitive, researcher, observer

Turns + cycle budgets

A "turn" is one round of (LLM call → optional tool dispatches → back to LLM). Both the cog and every agent run a bounded react loop with a maximum number of turns.

Budgets in this workspace

Actor	max_turns	max_consecutive_errors	watchdog
Cog	10 default, hard cap 20 (extendable mid-cycle via request_more_turns)	n/a (errors handled per-tool)	per-cycle deadline
Researcher	8	3	90s default
Observer	6	3	90s default

The numbers above match Springdrift's defaults except where noted in internal/agent/agent.go.

What "max_turns exhausted" means

Your loop ran the configured number of LLM calls without producing a final text reply (every turn ended with another tool call). The agent returns an error: "max_turns exhausted without final reply".

What to do:

• As an agent: don't deepen on the next dispatch. If the work truly needs more steps, return a partial answer with a note ("partial result; would need more turns to verify X").
• As the cog: the agent's error is informational — pass it to the user or retry with a narrower brief.

What max_consecutive_errors does

Three LLM-call errors in a row (transport, decode, etc.) ends the react loop with a hard error. This protects against a wedged provider hammering the budget.

If you see this: there's likely a real upstream problem (provider down, key revoked, network partition). The retry middleware already handles transient errors; reaching the consecutive-errors ceiling means it's not transient.

What the watchdog does

The watchdog kills the cycle if it runs longer than its deadline. This bounds the worst-case latency the operator sees.

You don't see the watchdog firing from inside the LLM loop — your context terminates and the cog emits a watchdog_fire cycle-log event. From the operator's perspective, the cycle returns an error.

Reading turn state

In your reply, you can see the turn from your activity stream (if you read it) or implicitly from how many tool-result blocks have accumulated in the conversation. Don't rely on counting manually — focus on the work.

Extending the cog's budget mid-cycle

The cog has a tool — request_more_turns(additional, reason) — that extends its own tool-turn budget for the in-flight cycle up to a hard ceiling of 20. Use it when:

• you're walking a diagnostic across multiple agents and would hit the default cap before finishing
• a deep delegation chain (cog → agent → agent's-internal-work → summarise) genuinely needs more rounds than 10 allows
• a self-check loop ("verify with a tool, then act") is bumping the cap on what's normally a short flow

Don't reach for it on routine work. Routine work fits in 10 turns. Each call to request_more_turns lands in the cycle log so an operator can see when (and why) the cog needed headroom — too many bumps is itself a signal that something's wrong with the workflow shape.

Practical advice

• Plan in the first turn: when the task is non-trivial, your first turn should think about what needs to happen, not jump to the first tool call. A wasted first turn often saves three.
• Stop when the answer is good enough: max_turns is a cap, not a target. The cleanest replies often come at turn 2 or 3.
• Don't retry blindly when a tool errors: read the error message; it's there for a reason. See harness-errors.