From 00abedb66ba7d55b22c57b5f890b25f22893abd8 Mon Sep 17 00:00:00 2001 From: Sam Date: Wed, 11 Nov 2026 19:00:13 +1100 Subject: [PATCH] Headroom: the tool path, measured; provider path documented as blocked --- docs/NEXT.md | 9 ++++++++- docs/PLAN-INTERFACE.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/NEXT.md b/docs/NEXT.md index a8fe442..64783c5 100644 --- a/docs/NEXT.md +++ b/docs/NEXT.md @@ -113,7 +113,14 @@ The one place it would earn its keep here: a failed run in `Agents>agents` offer asks "what does this failure need" with four options and records the answer, the confidence and the options on the task. A person still decides, and it never decides a merge. -## Headroom: blocked, with a measured reason +## Headroom: a tool, not a provider + +The `headroom-bridge` extension gives an agent two tools (`compress_for_agent`, +`check_headroom`). The endpoint answers (`POST /v1/compress` → 200). It needs the `headroom-ai` +npm package for Pi to resolve, which is not installed; then the extensions picker can give it to +one agent. As a *provider* it does not work here: 502 on OpenAI requests, 401 on Anthropic ones. + +## Headroom: blocked as a provider A provider entry was added, tested and removed. Headroom answers `502 proxy_error` to OpenAI chat requests and `401 invalid x-api-key` to Anthropic ones: its backend is Anthropic and this diff --git a/docs/PLAN-INTERFACE.md b/docs/PLAN-INTERFACE.md index a27057a..4064554 100644 --- a/docs/PLAN-INTERFACE.md +++ b/docs/PLAN-INTERFACE.md @@ -664,6 +664,34 @@ To use it, one of these is needed: The provider entry was removed so no agent can be pointed at a failing endpoint by accident. +### The path that does work: headroom as a tool + +The `headroom-bridge` extension in `~/.agents/extensions` does something different from a +provider: it gives a Pi agent two tools, `compress_for_agent` and `check_headroom`. The first +calls headroom's compression endpoint; the second reports whether the service is up. That is the +integration that fits: headroom shortens text an agent is about to pass on, rather than standing +between the agent and its model. + +Measured directly, without the extension: + +``` +POST http://192.168.20.13:8787/v1/compress {"model": …, "messages":[…]} → 200 +{tokens_before: 4009, tokens_after: 4009, tokens_saved: 0, compression_ratio: 1.0, + transforms_applied: ["router:protected:user_message"]} +``` + +So the endpoint works and reports its effect honestly; a single long user message is protected +from compression, which is why it saved nothing in that test. To give one agent the tool: + +1. `~/.agents/extensions/headroom-bridge` needs the `headroom-ai` npm package resolvable by Pi; + it is **not** installed in `~/.pi/agent/npm`, so the extension will fail to import until it is. +2. Give the extension to one agent with the extensions picker in `Agents>agents` — `space` writes a + wrapper and points that agent's command at it. +3. Then that agent, and no other, has the compression tool. + +That is the honest position: compression is available as a tool, blocked on one npm package, and +it is per agent because the wrapper is per agent. + ## Mouse-1, measured The person supplied `docs/MOUSE-1-NOTES.md`, written from measurements on 2026-11-08/09. The