Skip to content

A limit is announced before it stops the agent, once, and a client can draw the gauge

Decision 655 · accepted · 2026-09-20

Troupe.Agent.Headroom is pure and read after every model response: five fractions — turns, input tokens, output tokens, wall clock, and the model's context window, which is the provider's ceiling rather than ours. A dimension that crosses budget_warn_at writes a budget_warning with the numbers and a sentence (input tokens 4.9M/6.0M (82%)), and is not warned about again by that agent; agent_state.budget.headroom carries all five fractions always, so a client draws a gauge without knowing how each limit is counted. The warning is durable, not ephemeral, although the numbers are in agent_state for whoever asks later: the contract lets an ephemeral be dropped under load, and a warning that may not arrive is not one. The agent's replay ignores it, so it moves no fixture. full_send: true turns the warnings off for a session that wants no nagging, and a client may set it at session.create. What happens at the ceiling is 660.

Governs: apps/troupe_core/lib/troupe/agent/headroom.ex, apps/troupe_core/lib/troupe/agent/state.ex, apps/troupe_core/lib/troupe/config.ex, apps/troupe_protocol/lib/troupe/protocol/schema.ex, clients/tui/lib/troupe/remote/translate.ex