ROADMAP-24 — P3 — Token-budgeted context management with compaction #116

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M17-T03 · Priority: P3 · Effort: large

Problem

Context management is message-count-only (SESSION_MAX_MESSAGES=40), applies only across runs, and ignores tokens entirely. Within a run, the whole messages list is re-sent every step (agentkit/core/agent.py:316): growth is bounded only indirectly by the 2,000-char tool-output truncation. Message counts are deceptive for parallel calls (1 message, many tokens) and Gemini thought_signature bytes. An oversized context surfaces as an opaque provider 400 → generic FAILED.

Acceptance criteria

• Per-run token ledger fed by real usage counts (not estimates) available on the LLMResponse
• SESSION_TOKEN_BUDGET setting; oldest tool outputs summarized or compacted instead of blanket tail truncation
• Budget exhaustion aborts with an explicit status/reason (e.g. MAX_STEPS_EXCEEDED-style dedicated reason), never a provider 400
• Compaction is provider-valid (the truncation cut-point logic in Redis store is the model to follow)
• Unit tests: budget breach, compaction validity for both providers' validators

Suggested branch / commit

feat/context-budget · feat(core): token-budgeted context management with compaction