clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 33
colibri/docs/HEADROOM-SIDECAR.md
Sam & Claude 34929a6a53
Some checks failed
CI / rust (pull_request) Has been cancelled
Details
CI / markdown (pull_request) Has been cancelled
Details
fix(headroom): harden sidecar protocol and timeout (Sam & Codex) 
Keep the Python sidecar connection open for multiple newline-delimited requests, add daemon-side request timeout/fallback tests, and document the opt-in Headroom sidecar contract.\n\nChecks: ./scripts/check-format.sh; cargo fmt --check; python3 -m py_compile scripts/headroom-sidecar.py; git diff --check; cargo test -p colibri-daemon cost -- --nocapture; cargo test -p colibri-daemon session:: -- --nocapture; cargo test -p colibri-daemon --all-targets; cargo check -p colibri-daemon; manual sidecar two-request smoke using a headroom-capable Python env.
2026-06-14 01:30:45 +02:00

2.1 KiB
Raw Blame History

Headroom sidecar for Colibri

Colibri can optionally ask a local headroom-ai sidecar to compress tool results before they are rendered through the session read path.

This is off by default. The daemon does not start or supervise Headroom; it only connects to an already-running Unix socket when explicitly enabled.

Configuration

COLIBRI_HEADROOM_ENABLED=1
COLIBRI_HEADROOM_SOCKET=/var/run/colibri/headroom.sock  # optional default

Start the sidecar with a Python environment that can import headroom:

python3 scripts/headroom-sidecar.py --socket /var/run/colibri/headroom.sock

Then start colibri-daemon with the environment above. Check connection state with colibri status; the status JSON includes:

{
  "headroom": {
    "enabled": true,
    "socket": "/var/run/colibri/headroom.sock",
    "connected": true
  }
}

Protocol

The daemon keeps one Unix-socket connection open and sends newline-delimited JSON requests. The sidecar must support multiple requests on that same accepted connection.

Request:

{"id":"tool-name","raw":"tool output text","role":"tool"}

Response:

{"id":"tool-name","compressed":"shorter text","tokens_before":100,"tokens_after":25}

If tokens_after >= tokens_before, Colibri keeps the original tool result. If the sidecar errors, disconnects, or times out, Colibri degrades to the original uncompressed content.

Current daemon timeout: 5 seconds per sidecar request.

Scope and caveats

  • Compression is opt-in and best-effort.
  • The sidecar currently affects session prompt/message rendering paths that pass a HeadroomSidecar; it is not a global daemon-wide replacement for existing cost-mode compaction.
  • Keep COLIBRI_HEADROOM_ENABLED=0 for ISO/live-USB defaults unless Headroom is staged and smoke-tested on the target image.
  • FreeBSD: upstream headroom-ai may require local packaging work because some ONNX/ORT-backed extras do not have FreeBSD prebuilt binaries. Use a known-good Python environment and validate scripts/headroom-sidecar.py directly before enabling the daemon flag.