hermes-agent/docs
Michael Jordan ac48add3a7 feat(agent): report context occupancy, not just tokens saved
Tokens saved is the wrong headline for this feature. Micro-compaction is
not an efficiency optimisation — the same summarization work happens either
way. What it buys is (a) that work amortized across turns instead of one
stall, and (b) a window kept low enough that a session runs much further
before needing a hard compaction at all.

Neither shows up in "net tokens saved". A session can save nothing on paper
and still be a clear win on both counts.

So the telemetry now carries occupancy: tokens_after as a share of the
compaction threshold, plus the threshold and resolved window it was
computed from. That is the number that says whether a session has headroom
left. The report leads with it, and cross-references the batch
`compression_attempt` lines already in the log so it can show how often the
long pause actually fired — ideally never.

Occupancy is read from the cached threshold only. The public
`threshold_tokens` property resolves lazily and can issue a synchronous
/models probe (#32221); telemetry must never be the thing that blocks a
turn, so an unresolved window reports null. In practice a pass has already
resolved it via the tail calculation, so the field is populated. A test
pins the no-forcing behaviour directly against the emitter.

The report is pure ASCII: `scripts/check_subprocess_stdin.py` currently
dies on a cp1252 console before printing its results, and a diagnostic tool
that crashes on the platform it is diagnosing is worse than no tool.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-31 17:44:19 +05:30
..
design docs(profile): update clone-from references 2026-06-13 07:33:58 -07:00
kanban feat(kanban): gate notifier watcher on dispatch_in_gateway 2026-06-01 20:30:24 -07:00
middleware fix(middleware): preserve translated downstream failures 2026-06-06 09:26:18 -07:00
observability Merge remote-tracking branch 'origin/main' into feat/gateway-health-diagnostics-monitoring 2026-07-29 15:37:14 +00:00
plans fix(gateway): recover partial Telegram overflow streams 2026-06-10 15:09:35 -07:00
security docs(security): add network egress isolation guide for Docker deployments (#26385) 2026-05-29 14:09:10 +10:00
billing-lifecycle.md feat(cli): plan catalog on Free + plan= deep link + top-up/auto-refill copy split (#68689) 2026-07-22 08:11:09 +05:30
chronos-managed-cron-contract.md docs(chronos): pin hop-1 auth to the hosted-agent bootstrap token 2026-06-24 20:57:43 +10:00
hermes-kanban-v1-spec.pdf feat(kanban): durable multi-profile collaboration board (#17805) 2026-04-30 13:36:47 -07:00
micro-compaction.md feat(agent): report context occupancy, not just tokens saved 2026-07-31 17:44:19 +05:30
profile-routing.md fix(gateway): gate profile routing on multiplex_profiles + widen batch-key routing to all adapters 2026-07-15 09:50:05 -07:00
rca-ssl-cacert-post-git-pull.md fix(ssl): align guard docs and escape hatch 2026-06-13 21:14:32 -07:00
relay-connector-contract.md fix(relay): coerce Slack behavior flags exactly as the native adapter does 2026-07-29 12:03:01 -07:00
session-lifecycle.md fix(config): shipped template no longer enables session auto-reset (#67772) 2026-07-19 23:33:53 -07:00
streaming-tts.md feat(tts): Gemini SSE + xAI WebSocket streaming providers, tts.streaming.provider knob, docs + E2E tests 2026-07-28 22:31:40 -07:00