Headroom: the tool path, measured; provider path documented as blocked

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

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