Compress the message history sent to the LLM — primarily large tool outputs, logs, and search results — at the model-call boundary using the optional headroom-ai package.

Design:

• Non-destructive: runs in wrap_model_call and only rewrites the request copy of the messages via request.override(...). Persisted ThreadState keeps full originals, so it is reversible. Complementary to (not a replacement for) SummarizationMiddleware.
• Structure-preserving: only string content is mapped back onto the original LangChain messages, so message IDs and tool_calls are intact. Any message-count change or error falls back to the originals (fail_open).
• Optional dependency: transparent no-op when headroom-ai is absent; middleware is only added to the chain when compaction.enabled.
• Event-loop safe: async hook offloads compression via asyncio.to_thread.

Wiring: lead agent (after summarization) + subagent runtime. Config: new compaction section in AppConfig / config.example.yaml (config_version 12 -> 13). New [compaction] extra (headroom-ai). Docs: backend/docs/compaction.md + CLAUDE.md.
Tests: test_compaction_config.py, test_compaction_middleware.py (use a compress_fn injection seam; never import the heavy ML stack).

Fixes #

Why

What changed

Surface area

• Frontend UI — page / component / setting / interaction under frontend/
• Backend API — endpoint / SSE event / request-response shape under backend/app
• Agents / LangGraph — agent node, graph wiring, langgraph.json, or prompt change
• Sandbox — docker/ or sandboxed execution
• Skills — change under skills/
• Dependencies — new/upgraded entry in backend/pyproject.toml or frontend/package.json (say what it buys us)
• Default behavior change — changes existing behavior without the user opting in (default model, default setting, data shape)
• Docs / tests / CI only — no runtime behavior change

Screenshots / Recording

Bug fix verification

Validation

AI assistance

Tool(s) used:

How you used it:

• I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.