Skip to content

The four ways a turn can stop are four different things, and the two that belong to the provider never end a branch silently

TUI decision 86 · accepted · 2026-09-17

Superseded in part

In part by 125.

Budget.exhausted?/3 was an or across turns, input, output and wall clock, so the agent could not say which ceiling it had reached; stop_reason was parsed, stored on the response, logged into assistant_message and read by nothing; and compaction_needed?/2 measured the provider's input_tokens, which excludes cache reads — so once Decision 84 put breakpoints on every request, a warm 200 k conversation reported a few hundred and compaction stopped firing in production entirely (the test stayed green because LLM.Fake hardcoded cache_read: 0). The fixes share one shape, the one Decision 85 already has: never silently lose work, always hand back the call that recovers it. Troupe.Agent.Headroom is a pure module computing all five fractions — the four budgets plus the model's context window, the last from Provider.total_input/1 — and is the single source for the compaction check, the warning and the question, so they cannot disagree. Past config.budget.warn_at (0.8) each dimension logs one budget_warning and the turn goes ahead: it is a notice, folded by the TUI model onto the window and into the transcript, and it is the only signal that arrives while there is still budget left to spend. At the ceiling, y now grants one more slice of the agent's own budget instead of making that agent's budget unlimited for the rest of the session — the grant is folded out of budget_ask_answered, so unlike the old in-memory session flag it survives a restart, and the checkpoint comes back at the end of every slice, which is what "don't let me lose work" actually needs; a keeps the old override, n still stops. stop_reason: :max_tokens no longer becomes finish(:finished, …) with half a sentence (or, when thinking ate the whole 8192, with nothing at all): with tool calls in the reply the turn continues but a call whose arguments were cut off mid-JSON is completed with an error naming the cause rather than run on a fragment — every tool_use still owes a tool_result or the next request is rejected — and with no tool call the model is told what happened and asked again once, then the branch fails as :output_truncated. :refusal finishes :refused. A 400 whose body names a context error is classified in Provider.classify/1 (beside stop_reason/1, so HTTP stays generic) as :context_overflow and compacts-and-retries once instead of wedging the branch — the wedge that lost a multi-million-token branch, because the only recovery the UI offered was typing more input, which rebuilds the same oversized prompt and fails identically. /compact is the hand escape hatch and goes through the Dispatcher rather than straight to the agent, because a branch that has come to rest has no agent process and that is exactly the branch that needs it. 429 is a wait, not a failure: retry-after is read and honoured and a rate limit gets eight attempts, where ~7.5 s of total backoff used to kill a three-hour branch over a one-minute org limit. Finally, max_wall_clock_ms counts working time — the sum of the gaps between an agent's own events, gaps longer than one stream's lifetime dropped — because measuring from the first event meant a session resumed the next day had already blown three hours and the first thing a resumed branch did was ask the budget question. The at-most-once guards for both recoveries live in Agent.Server's Data and never in the log, for the same reason cache_bp does: they are facts about the turn in flight, so a restart must come back willing to try each once more.

Governs: apps/troupe_core/lib/troupe/agent/headroom.ex, apps/troupe_core/lib/troupe/agent/server.ex, apps/troupe_core/lib/troupe/llm/providers/fake.ex, clients/tui/lib/troupe/remote/http.ex