docs(turn-loop): document hyperhive.autoCompact nix option

The compaction section already documented HIVE_COMPACT_WATERMARK_TOKENS
but didn't mention the per-agent nix option (hyperhive.autoCompact,
default true) that maps to it.

Add a short note after the watermark paragraph explaining that operators
can set autoCompact = false in agent.nix to disable proactive compaction,
and note the reactive path still applies. Useful for sonnet/opus agents
where the 75% heuristic fires before the session is actually full.
This commit is contained in:
iris 2026-06-05 18:26:40 +02:00 committed by mara
commit 83059a0fcb

View file

@ -199,6 +199,17 @@ or `/compact` is surfaced as a `Note` but never fails the turn that
already succeeded. The operator can also force a compaction any time
via `/api/compact`.
To disable proactive compaction for a specific agent, use the nix option:
```nix
hyperhive.autoCompact = false; # default true
```
Setting `autoCompact = false` is equivalent to `HIVE_COMPACT_WATERMARK_TOKENS=0`.
Useful for agents running large-context models (sonnet/opus) where the 75%
heuristic fires before the session is actually full — the reactive path
(compact-on-overflow when the session hits the hard limit) still applies.
- **Auto session-reset** — a third path that fires when both
conditions hold: context is ≥ a watermark (`HIVE_AUTO_RESET_WATERMARK_TOKENS`,
default **50% of `context_window_tokens(model)`**) AND the time since