Implement context compaction for long agent runs

[jrswab]

Summary

Long-running agent conversations can exhaust LLM context windows, causing errors or degraded performance. Pi (https://github.com/badlogic/pi-mono) has an excellent compaction system that summarizes older messages while keeping recent ones intact. We should implement a similar feature natively in axe.

Motivation

• Axe currently has a hard 50-turn conversation limit as a safety rail
• Agents with many tool calls or large outputs quickly fill context windows
• Users hit provider errors (context length exceeded) before the 50-turn limit
• No way to recover from context overflow mid-run

Proposed Behavior

Automatic Compaction

• Trigger when context usage approaches the model's limit (proactive)
• Trigger on context overflow errors (reactive recovery)
• Configurable threshold (e.g., 80% of context window)

Manual Compaction

• Axe does not have an interactive mode, so manual compaction could be:
  • A --compact CLI flag on axe run
  • A new axe compact <agent> command
  • Or triggered automatically when approaching limits

What Compaction Does

1. Summarize older messages (system prompt + early turns) into a condensed form
2. Preserve the most recent N turns in full
3. Maintain tool call details in the summary so the agent retains context
4. Keep the full history in a session log file (if we add session persistence)

Configuration

Add to agent TOML:

[compaction]
enabled = true          # default: false
threshold = 0.8         # trigger at 80% context usage (default: 0.8)
keep_turns = 5          # preserve last N turns in full (default: 5)

Inspiration

Pi's compaction:

• Automatic + manual /compact [custom instructions]
• Lossy but recoverable via /tree (full history in JSONL)
• Customizable via extensions

Acceptance Criteria

• Compaction triggered automatically when context threshold is reached
• Reactive compaction recovers from context overflow errors
• Summarized context preserves task intent and key tool results
• Configurable per-agent via TOML
• Works with all providers (Anthropic, OpenAI, Ollama, etc.)
• Tests for compaction logic
• Documentation update

Open Questions

1. Should we add optional session persistence (JSONL) to preserve full history?
2. Should compaction use the same LLM provider or allow a cheaper model (e.g., Haiku for summarizing)?
3. How do we estimate context usage when providers don't return it consistently?