opencode-headroom-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pietro partescano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# opencode-headroom-plugin
+
+A plugin for **OpenCode v2** that transparently compresses **large tool results** in a session via **Headroom**, without touching the provider configuration already set up in OpenCode and without any provider-specific limitations (it also works with **AWS Bedrock**).
+
+It doesn't modify `opencode.json`/`opencode.jsonc`, doesn't create fake providers, and doesn't route provider HTTP traffic through a proxy: it hooks into `session.hook("context", ...)`, the point where OpenCode assembles the session's messages **before** translating them into the provider's native format (Anthropic Messages, OpenAI Chat, Bedrock Converse, ...) and before signing the request. Only tool results (`role: "tool"`) are sent to Headroom for compression — never user/assistant text, never system messages.
+
+## Prerequisites
+
+- **Node.js 20.3+** (or Bun — OpenCode loads `.js` files directly; the plugin uses `AbortSignal.any`).
+- **Headroom** installed and **its proxy already running** before starting OpenCode:
+  ```bash
+  pip install "headroom-ai[proxy]"
+  headroom proxy            # defaults to http://127.0.0.1:8787
+  ```
+  The plugin **never** starts or manages the Headroom process, and doesn't route traffic through it: it only calls its stateless `POST /v1/compress` endpoint (compresses and nothing else, never contacts any provider itself) and, when needed, `GET /v1/retrieve/{hash}`.
+
+## Installation
+
+1. Clone/download this repository and install the dependency:
+   ```bash
+   npm install
+   ```
+2. Wire the plugin into OpenCode with one of the methods below.
+
+### A. Global, for every project (recommended)
+
+Create a symlink in OpenCode's global plugins directory — no `opencode.json` edit required:
+
+```bash
+npm run plugin:install
+# equivalent to: bash scripts/install.sh
+```
+
+To remove it:
+
+```bash
+npm run plugin:uninstall
+```
+
+The script links this folder to `~/.config/opencode/plugins/headroom-context-compression` (override with the `OPENCODE_CONFIG_DIR` variable). OpenCode automatically loads every plugin package found there.
+
+### B. Only for a specific project
+
+Copy or symlink the plugin folder into the project's `.opencode/plugins/`:
+
+```bash
+mkdir -p /path/to/project/.opencode/plugins
+ln -s /path/to/this/repo /path/to/project/.opencode/plugins/headroom-context-compression
+```
+
+### C. Via `opencode.json(c)` (if you prefer an explicit entry)
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "/absolute/path/to/this/repo",
+      "options": {
+        "proxyUrl": "http://127.0.0.1:8787"
+      }
+    }
+  ]
+}
+```
+
+After any of these methods, restart the OpenCode server (`opencode service restart`) or simply start a new session.
+
+## If the plugin doesn't show up as active
+
+1. **Restart the OpenCode server**, not just the client/TUI: `opencode service restart`. Plugins load at server startup.
+2. **Check `opencode plugin list`**: `headroom-context-compression` should appear. If it doesn't appear at all, the config file is probably not being read (wrong path, or a JSON syntax error — watch out for missing commas between properties).
+3. **Verify the plugin folder has an `index.js` at its root** (not only inside `src/`). OpenCode resolves plugins referenced by local path (both in `plugins` and via auto-discovery) by conventionally looking for `index.*`/`server.*` at the folder root, and **ignores `package.json`'s `exports`** in that case. This repository already ships a root `index.js` for exactly that reason.
+
+## Configuration
+
+No option is required: with no configuration the plugin points at `http://127.0.0.1:8787` (the `headroom proxy` default), only compresses tool results ≥ 2000 characters, and never compresses if the proxy isn't local (see "Security" below).
+
+| Plugin option (`options`) | Environment variable | Default | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `HEADROOM_ENABLED` | `true` | Fully disables compression. |
+| `proxyUrl` | `HEADROOM_PROXY_URL` | `http://127.0.0.1:8787` | Address of `headroom proxy`. |
+| `allowRemote` | `HEADROOM_ALLOW_REMOTE` | `false` | Allows a non-local `proxyUrl`. See "Security". |
+| `minContextTokens` | `HEADROOM_MIN_CONTEXT_TOKENS` | `10000` | Minimum estimated size (tokens) of the whole session context before attempting compression at all. |
+| `minMessageChars` | `HEADROOM_MIN_MESSAGE_CHARS` | `2000` | Minimum size (characters) a tool result must reach before it's sent to Headroom. |
+| `timeoutMs` | `HEADROOM_TIMEOUT_MS` | `40000` | Timeout for the `/v1/compress` call. Headroom gives itself an internal budget of 30s for the compression step (observed in its own startup log: `compression=30.0s`); on large contexts (hundreds of messages) compression can take 20-25s, so the default leaves margin above that budget. |
+| `renameToolCalls` | — | `true` | Renames tool calls in the payload sent to Headroom, so its `DEFAULT_EXCLUDE_TOOLS` list (which protects `read`/`grep` by name) doesn't block compression of large results from those tools **that aren't already protected** by the point below. |
+| `excludeProviders` | — | `[]` | List of `providerID`s (e.g. `"amazon-bedrock"`) to fully exclude from compression, in case it's ever needed. Empty by default: Bedrock works without any exceptions. |
+
+## Protected tools (never compressed)
+
+`read`, `write`, `edit`, `patch`, `skill`, and `headroom_retrieve` **never become compression candidates**, regardless of size — this isn't configurable. Reason: their output serves as an anchor for a later exact match (an `edit` operating on text read by `read`, for example) or is directive text meant to be followed literally (`skill`); compressing it would risk breaking that match or that directive. This rule is carried over from [`noheadroom`](https://github.com/raquezha/noheadroom) (a Headroom bridge for Pi-Agent), from which this plugin inherits the conservative setting. Other tools (`grep`, `glob`, `bash`, `webfetch`, ...) remain compressible.
+
+## Cross-turn compression and loop guards
+
+OpenCode doesn't persist the mutations made by the `context` hook into the session's history: on the next turn the same tool result comes back uncompressed. To avoid calling Headroom again from scratch on the same content every time, the plugin keeps, per session:
+
+- a **replay cache** (tool-call id + tool name + original text → already-compressed, validated text): if the exact same tool result shows up again, it's reapplied without contacting the proxy again;
+- some **loop guards** (already-seen content, request unchanged since the last attempt, a 3-second throttle between attempts) to avoid redundant calls when the `context` hook fires multiple times for the same turn.
+
+This mechanism is also carried over from `noheadroom`, which solves the same problem for Pi-Agent.
+
+## Security
+
+Compressing sends the tool results' content to the configured `proxyUrl`. Because of this, if `proxyUrl` doesn't point at `localhost`/`127.0.0.1`/`::1`, the plugin **disables itself automatically** until you explicitly set `allowRemote: true` — only do that if you trust that proxy.
+
+## Retrieving the original content
+
+When Headroom compresses a tool result, it leaves a marker shaped like `[N items compressed to M. Retrieve more: hash=...]` (or `<<ccr:hash...>>`). The plugin registers a **`headroom_retrieve(hash)`** tool that the model can call to fetch the full original from Headroom's CCR cache (TTL 1800s) — no need to install Headroom's official MCP server.
+
+## How it works
+
+### ❌ What doesn't work: a plain HTTP proxy
+
+The obvious approach — and the one the official `headroom-opencode` package uses for OpenCode v1 — is to rewrite the native HTTP request's URL so it goes through the Headroom proxy, leaving path/method/headers/body otherwise intact. That works for Anthropic/OpenAI/Google Vertex, but **breaks AWS Bedrock**: OpenCode's `amazon-bedrock` provider calls AWS's **Converse** API, and the request is signed with **AWS SigV4** *before* it reaches the proxy. If the proxy then compresses the body, the signature no longer matches the (now different) content, and AWS rejects the request outright.
+
+![Naive HTTP proxy rewrite -- breaks AWS Bedrock](assets/workflow-naive-proxy.svg)
+
+There's no clean fix within that approach: re-signing the request after compression would need a second, provider-aware hop (essentially a full SigV4-capable gateway) just for Bedrock — not transparent, not generalizable to whatever provider comes next.
+
+### ✅ Current implementation: compression at the message level
+
+Instead of touching HTTP traffic, the plugin hooks into `session.hook("context", ...)` — the point where OpenCode assembles the session's messages in its **provider-agnostic** shape, before "lowering" them to the provider's native protocol (Converse, Chat Completions, GenerateContent, ...) and, crucially, **before** that request is signed. Only `role: "tool"` parts are extracted, filtered (size, protected tools) and sent to Headroom's stateless `POST /v1/compress`; the compressed text is written back into the same `ToolResultPart` only after validating that role and `tool_call_id` didn't change. Everything downstream — provider lowering, SigV4 signing, transport — happens exactly as before, just on an already-compressed body.
+
+![Current implementation -- message-level compression via session.hook(context)](assets/workflow-current-implementation.svg)
+
+This works identically for every provider, Bedrock included, because it never touches the native HTTP body or its signature. Full architectural details and alternatives considered in `MEMORY.md`.
+
+## Sources
+
+The compression logic, protected tools, replay cache, and loop guards are carried over from two Headroom extensions for **Pi-Agent** (MIT license): [`@casualjim/pi-headroom`](https://github.com/casualjim/pi-mimir) and, especially for the protected tools and the replay cache, [`@raquezha/noheadroom`](https://github.com/raquezha/noheadroom) — both derive from `@ryan_nookpi/pi-extension-headroom` (Jonghakseo).
+
+## Tests
+
+```bash
+npm test
+```
+
+Suite built on `node --test`, no external framework:
+- `test/bridge.test.js`, `test/config.test.js` — pure logic, no dependency on `@opencode/plugin` or a running Headroom proxy.
+- `test/guard.test.js` — replay cache and loop guards, pure and testable without the plugin.
+- `test/plugin.test.js` — integration with the real `@opencode/plugin` library, `fetch` stubbed (no real network), including a test that reproduces the Bedrock scenario, one for protected tools, and one for the cross-turn replay cache.
+- `test/resolution.test.js` — verifies that OpenCode actually resolves the plugin from this folder (real `Host.resolve`/`Host.load`).

package/assets/workflow-current-implementation.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" data-diagram-type="SEQUENCE" height="614px" preserveAspectRatio="none" style="width:1295px;height:614px;background:#FFFFFF;" version="1.1" viewBox="0 0 1295 614" width="1295px" zoomAndPan="magnify"><?plantuml 1.2026.6?><defs/><g><g class="title" data-source-line="10"><text fill="#000000" font-family="sans-serif" font-size="14" font-weight="700" lengthAdjust="spacing" textLength="665.5469" x="311.4993" y="27.9951">OK Current implementation -- message-level compression via session.hook(context)</text></g><g class="participant-lifeline" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-lifeline"><g><title>OpenCode</title><rect fill="#000000" fill-opacity="0.00000" height="471.3906" width="8" x="44.6167" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="48" x2="48" y1="89.8906" y2="561.2813"/></g></g><g class="participant-lifeline" data-entity-uid="part2" data-qualified-name="Plugin" data-source-line="13" id="part2-lifeline"><g><title>Plugin</title><rect fill="#000000" fill-opacity="0.00000" height="471.3906" width="8" x="379.0615" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="383.0522" x2="383.0522" y1="89.8906" y2="561.2813"/></g></g><g class="participant-lifeline" data-entity-uid="part3" data-qualified-name="Headroom" data-source-line="14" id="part3-lifeline"><g><title>Headroom</title><rect fill="#000000" fill-opacity="0.00000" height="471.3906" width="8" x="701.7036" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="704.8433" x2="704.8433" y1="89.8906" y2="561.2813"/></g></g><g class="participant-lifeline" data-entity-uid="part4" data-qualified-name="Provider" data-source-line="15" id="part4-lifeline"><g><title>Provider adapter</title><rect fill="#000000" fill-opacity="0.00000" height="471.3906" width="8" x="903.4585" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="906.564" x2="906.564" y1="89.8906" y2="561.2813"/></g></g><g class="participant-lifeline" data-entity-uid="part5" data-qualified-name="API" data-source-line="16" id="part5-lifeline"><g><title>LLM API</title><rect fill="#000000" fill-opacity="0.00000" height="471.3906" width="8" x="1246.4067" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="1250.2681" x2="1250.2681" y1="89.8906" y2="561.2813"/></g></g><g class="participant participant-head" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-head"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="87.2334" x="5" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.2334" x="12" y="62.292">OpenCode</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="32.71" x="32.2617" y="78.5889">Core</text></g><g class="participant participant-tail" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-tail"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="87.2334" x="5" y="560.2813"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.2334" x="12" y="580.2764">OpenCode</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="32.71" x="32.2617" y="596.5732">Core</text></g><g class="participant participant-head" data-entity-uid="part2" data-qualified-name="Plugin" data-source-line="13" id="part2-head"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="176.0186" x="295.0522" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="42.8545" x="361.6343" y="62.292">Plugin</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="162.0186" x="302.0522" y="78.5889">session.hook('context')</text></g><g class="participant participant-tail" data-entity-uid="part2" data-qualified-name="Plugin" data-source-line="13" id="part2-tail"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="176.0186" x="295.0522" y="560.2813"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="42.8545" x="361.6343" y="580.2764">Plugin</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="162.0186" x="302.0522" y="596.5732">session.hook('context')</text></g><g class="participant participant-head" data-entity-uid="part3" data-qualified-name="Headroom" data-source-line="14" id="part3-head"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="149.7207" x="630.8433" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.1309" x="669.1382" y="62.292">Headroom</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="135.7207" x="637.8433" y="78.5889">POST /v1/compress</text></g><g class="participant participant-tail" data-entity-uid="part3" data-qualified-name="Headroom" data-source-line="14" id="part3-tail"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="149.7207" x="630.8433" y="560.2813"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.1309" x="669.1382" y="580.2764">Headroom</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="135.7207" x="637.8433" y="596.5732">POST /v1/compress</text></g><g class="participant participant-head" data-entity-uid="part4" data-qualified-name="Provider" data-source-line="15" id="part4-head"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="233.7891" x="790.564" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="117.4346" x="848.7412" y="62.292">Provider adapter</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="219.7891" x="797.564" y="78.5889">(Bedrock / Vertex / OpenAI / ...)</text></g><g class="participant participant-tail" data-entity-uid="part4" data-qualified-name="Provider" data-source-line="15" id="part4-tail"><rect fill="#F0FFF4" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="233.7891" x="790.564" y="560.2813"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="117.4346" x="848.7412" y="580.2764">Provider adapter</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="219.7891" x="797.564" y="596.5732">(Bedrock / Vertex / OpenAI / ...)</text></g><g class="participant participant-head" data-entity-uid="part5" data-qualified-name="API" data-source-line="16" id="part5-head"><rect fill="#F0FFF4" height="30.2969" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="68.2773" x="1216.2681" y="58.5938"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="54.2773" x="1223.2681" y="78.5889">LLM API</text></g><g class="participant participant-tail" data-entity-uid="part5" data-qualified-name="API" data-source-line="16" id="part5-tail"><rect fill="#F0FFF4" height="30.2969" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="68.2773" x="1216.2681" y="560.2813"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="54.2773" x="1223.2681" y="580.2764">LLM API</text></g><g class="message" data-entity-1="part1" data-entity-2="part2" data-source-line="18" id="msg1"><polygon fill="#444444" points="371.0615,132.1563,381.0615,136.1563,371.0615,140.1563,375.0615,136.1563" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="48.6167" x2="377.0615" y1="136.1563" y2="136.1563"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="117.4697" x="157.1042" y="115.9575">context hook fires</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="310.4448" x="60.6167" y="131.0903">event.messages: Message[] (provider-agnostic)</text></g><g class="message" data-entity-1="part2" data-entity-2="part2" data-source-line="19" id="msg2"><line style="stroke:#444444;stroke-width:1;" x1="383.0615" x2="425.0615" y1="195.5547" y2="195.5547"/><line style="stroke:#444444;stroke-width:1;" x1="425.0615" x2="425.0615" y1="195.5547" y2="208.5547"/><line style="stroke:#444444;stroke-width:1;" x1="384.0615" x2="425.0615" y1="208.5547" y2="208.5547"/><polygon fill="#444444" points="394.0615,204.5547,384.0615,208.5547,394.0615,212.5547,390.0615,208.5547" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="176.8013" x="402.5505" y="160.2231">keep only role='tool' parts,</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="133.0913" x="424.4055" y="175.356">skip protected tools,</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="201.7793" x="390.0615" y="190.4888">skip parts &lt; minMessageChars</text></g><g class="message" data-entity-1="part2" data-entity-2="part3" data-source-line="20" id="msg3"><polygon fill="#444444" points="693.7036,248.8203,703.7036,252.8203,693.7036,256.8203,697.7036,252.8203" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="383.0615" x2="699.7036" y1="252.8203" y2="252.8203"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="126.0264" x="481.3694" y="232.6216">POST /v1/compress</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="138.1631" x="475.301" y="247.7544">(only tool-result text)</text></g><g class="message" data-entity-1="part3" data-entity-2="part2" data-source-line="21" id="msg4"><polygon fill="#444444" points="394.0615,277.9531,384.0615,281.9531,394.0615,285.9531,390.0615,281.9531" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="388.0615" x2="704.7036" y1="281.9531" y2="281.9531"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="214.7666" x="436.9993" y="276.8872">compressed text + retrieve hash</text></g><g class="message" data-entity-1="part2" data-entity-2="part2" data-source-line="22" id="msg5"><line style="stroke:#444444;stroke-width:1;" x1="383.0615" x2="425.0615" y1="326.2188" y2="326.2188"/><line style="stroke:#444444;stroke-width:1;" x1="425.0615" x2="425.0615" y1="326.2188" y2="339.2188"/><line style="stroke:#444444;stroke-width:1;" x1="384.0615" x2="425.0615" y1="339.2188" y2="339.2188"/><polygon fill="#444444" points="394.0615,335.2188,384.0615,339.2188,394.0615,343.2188,390.0615,339.2188" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="252.2939" x="418.2356" y="306.02">validate role &amp; tool_call_id unchanged,</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="308.6421" x="390.0615" y="321.1528">write compressed text back into ToolResultPart</text></g><g class="message" data-entity-1="part2" data-entity-2="part1" data-source-line="23" id="msg6"><polygon fill="#444444" points="59.6167,379.4844,49.6167,383.4844,59.6167,387.4844,55.6167,383.4844" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="53.6167" x2="382.0615" y1="383.4844" y2="383.4844"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="126.5659" x="152.5562" y="363.2856">mutated Message[]</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="252.897" x="89.3906" y="378.4185">(still provider-agnostic, not yet signed)</text></g><g class="message" data-entity-1="part1" data-entity-2="part4" data-source-line="24" id="msg7"><polygon fill="#444444" points="895.4585,423.75,905.4585,427.75,895.4585,431.75,899.4585,427.75" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="48.6167" x2="901.4585" y1="427.75" y2="427.75"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="214.5254" x="370.7749" y="407.5513">lower messages to native format</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="251.7036" x="352.1858" y="422.6841">(Converse / Chat / GenerateContent...)</text></g><g class="message" data-entity-1="part4" data-entity-2="part4" data-source-line="25" id="msg8"><line style="stroke:#444444;stroke-width:1;" x1="907.4585" x2="949.4585" y1="472.0156" y2="472.0156"/><line style="stroke:#444444;stroke-width:1;" x1="949.4585" x2="949.4585" y1="472.0156" y2="485.0156"/><line style="stroke:#444444;stroke-width:1;" x1="908.4585" x2="949.4585" y1="485.0156" y2="485.0156"/><polygon fill="#444444" points="918.4585,481.0156,908.4585,485.0156,918.4585,489.0156,914.4585,485.0156" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="80.7104" x="1038.5774" y="451.8169">sign request</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="328.9482" x="914.4585" y="466.9497">(AWS SigV4 etc.) on the already-compressed body</text></g><g class="message" data-entity-1="part4" data-entity-2="part5" data-source-line="26" id="msg9"><polygon fill="#444444" points="1238.4067,510.1484,1248.4067,514.1484,1238.4067,518.1484,1242.4067,514.1484" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="907.4585" x2="1244.4067" y1="514.1484" y2="514.1484"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="85.0967" x="1036.3843" y="509.0825">send request</text></g><g class="message" data-entity-1="part5" data-entity-2="part4" data-source-line="27" id="msg10"><polygon fill="#444444" points="918.4585,539.2813,908.4585,543.2813,918.4585,547.2813,914.4585,543.2813" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="912.4585" x2="1249.4067" y1="543.2813" y2="543.2813"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="59.3315" x="1049.2668" y="538.2153">response</text></g><?plantuml-src ZLHXRzCm4FsUNt4Q4bt5qe4qWQW0gOi8J6oqOjFuGD7anRV4gkCBjjFIVyyvJRQa1ObyI2pVk_VkdiznAsKgOKK9hX2IDihay22qmyWzHV1NZIR3AtHEv3ZJAZUGeV5eUwYPjRH9I9E5PsVDqmzcdkmvMOdsNv25i5vbgXB6_pzGPAlSKcra2qvVfcdQ1tybZmUeZw_JDscwZ-gBlcsUAFBAQuIZ-HT8QckvPL1bfR7abV2A3CGnb3jROerhr91HMLdU2S6r4cnUivuKHAlZZDYqttvy54NLKnVCNw59IEAItnQFG3YO9qF8GjUvCaipu1krXADnaxF33FC-ev2Mg5oQnVpw1axNhqwx4fkSBhwdPccjs0uGKbHypajpV8wCorPm2hTeMPGNeUpP1IycaqbRGPitPBkyl8BPug91y3UAvWd47zfofz0s0Q4bU51SsjAmbyPFMclT5DhP-_4JZgjM8nQv8SSgusZ7rETS8LP0Hc_1aiRt8q-aHn2gSYTiuafLm3mUCuyIGl1fEs3W7PJAjA998QphQNIMJU70KlQf4GsCCM_KsaDpub6ND6nybnLA20Qy08lUAkuT2k6AlxIr5bf9uR7f2futEdUPqFfEIQXDLWYJe-HMDbOnQb_Wdcy2AEC9RZZnMrDVk4uzfNaoXRBcwUQSHzEvBJPQQpZm_WGCUTYY1yT_1PJZxcnRu1GqRNYEkfFaYi7mrU4M7yYMmZDrGcQDrY4F4blj-VC93Lek8GcJmNF0unKzZkI0FQYoQ_o3Se5gzlqQhbL-UmReiycO9m1yWI2qPVktSS-FUvBR0ISF9jEXaHrTn3j3CKwjY6_W7m00?></g></svg>

package/assets/workflow-naive-proxy.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" data-diagram-type="SEQUENCE" height="533px" preserveAspectRatio="none" style="width:853px;height:533px;background:#FFFFFF;" version="1.1" viewBox="0 0 853 533" width="853px" zoomAndPan="magnify"><?plantuml 1.2026.6?><defs/><g><g class="title" data-source-line="10"><text fill="#000000" font-family="sans-serif" font-size="14" font-weight="700" lengthAdjust="spacing" textLength="403.1836" x="221.7915" y="27.9951">X Naive HTTP proxy rewrite -- breaks AWS Bedrock</text></g><g class="participant-lifeline" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-lifeline"><g><title>OpenCode</title><rect fill="#000000" fill-opacity="0.00000" height="389.8594" width="8" x="44.6167" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="48" x2="48" y1="89.8906" y2="479.75"/></g></g><g class="participant-lifeline" data-entity-uid="part2" data-qualified-name="Provider" data-source-line="13" id="part2-lifeline"><g><title>amazon-bedrock</title><rect fill="#000000" fill-opacity="0.00000" height="389.8594" width="8" x="364.5063" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="367.998" x2="367.998" y1="89.8906" y2="479.75"/></g></g><g class="participant-lifeline" data-entity-uid="part3" data-qualified-name="Proxy" data-source-line="14" id="part3-lifeline"><g><title>Headroom</title><rect fill="#000000" fill-opacity="0.00000" height="389.8594" width="8" x="546.1885" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="549.2598" x2="549.2598" y1="89.8906" y2="479.75"/></g></g><g class="participant-lifeline" data-entity-uid="part4" data-qualified-name="AWS" data-source-line="15" id="part4-lifeline"><g><title>AWS Bedrock</title><rect fill="#000000" fill-opacity="0.00000" height="389.8594" width="8" x="757.311" y="89.8906"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5,5;" x1="760.3174" x2="760.3174" y1="89.8906" y2="479.75"/></g></g><g class="participant participant-head" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-head"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="87.2334" x="5" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.2334" x="12" y="62.292">OpenCode</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="32.71" x="32.2617" y="78.5889">Core</text></g><g class="participant participant-tail" data-entity-uid="part1" data-qualified-name="OC" data-source-line="12" id="part1-tail"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="87.2334" x="5" y="478.75"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.2334" x="12" y="498.7451">OpenCode</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="32.71" x="32.2617" y="515.042">Core</text></g><g class="participant participant-head" data-entity-uid="part2" data-qualified-name="Provider" data-source-line="13" id="part2-head"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="135.0166" x="300.998" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="117.1475" x="309.9326" y="62.292">amazon-bedrock</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="121.0166" x="307.998" y="78.5889">provider (AI SDK)</text></g><g class="participant participant-tail" data-entity-uid="part2" data-qualified-name="Provider" data-source-line="13" id="part2-tail"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="135.0166" x="300.998" y="478.75"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="117.1475" x="309.9326" y="498.7451">amazon-bedrock</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="121.0166" x="307.998" y="515.042">provider (AI SDK)</text></g><g class="participant participant-head" data-entity-uid="part3" data-qualified-name="Proxy" data-source-line="14" id="part3-head"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="93.8574" x="503.2598" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.1309" x="513.623" y="62.292">Headroom</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="79.8574" x="510.2598" y="78.5889">HTTP Proxy</text></g><g class="participant participant-tail" data-entity-uid="part3" data-qualified-name="Proxy" data-source-line="14" id="part3-tail"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="93.8574" x="503.2598" y="478.75"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="73.1309" x="513.623" y="498.7451">Headroom</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="79.8574" x="510.2598" y="515.042">HTTP Proxy</text></g><g class="participant participant-head" data-entity-uid="part4" data-qualified-name="AWS" data-source-line="15" id="part4-head"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="107.9873" x="707.3174" y="42.2969"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="93.9873" x="714.3174" y="62.292">AWS Bedrock</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="92.374" x="715.124" y="78.5889">Converse API</text></g><g class="participant participant-tail" data-entity-uid="part4" data-qualified-name="AWS" data-source-line="15" id="part4-tail"><rect fill="#FFF3F3" height="46.5938" rx="2.5" ry="2.5" style="stroke:#444444;stroke-width:0.5;" width="107.9873" x="707.3174" y="478.75"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="93.9873" x="714.3174" y="498.7451">AWS Bedrock</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="92.374" x="715.124" y="515.042">Converse API</text></g><g class="message" data-entity-1="part1" data-entity-2="part2" data-source-line="17" id="msg1"><polygon fill="#444444" points="356.5063,132.1563,366.5063,136.1563,356.5063,140.1563,360.5063,136.1563" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="48.6167" x2="362.5063" y1="136.1563" y2="136.1563"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="130.5396" x="143.2917" y="115.9575">build native request</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="295.8896" x="60.6167" y="131.0903">(Converse API, /model/{id}/converse-stream)</text></g><g class="message" data-entity-1="part2" data-entity-2="part2" data-source-line="18" id="msg2"><line style="stroke:#444444;stroke-width:1;" x1="368.5063" x2="410.5063" y1="180.4219" y2="180.4219"/><line style="stroke:#444444;stroke-width:1;" x1="410.5063" x2="410.5063" y1="180.4219" y2="193.4219"/><line style="stroke:#444444;stroke-width:1;" x1="369.5063" x2="410.5063" y1="193.4219" y2="193.4219"/><polygon fill="#444444" points="379.5063,189.4219,369.5063,193.4219,379.5063,197.4219,375.5063,193.4219" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="116.9937" x="375.5063" y="160.2231">sign request body</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="81.5547" x="393.2258" y="175.356">(AWS SigV4)</text></g><g class="message" data-entity-1="part2" data-entity-2="part3" data-source-line="19" id="msg3"><polygon fill="#444444" points="538.1885,233.6875,548.1885,237.6875,538.1885,241.6875,542.1885,237.6875" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="368.5063" x2="544.1885" y1="237.6875" y2="237.6875"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="132.355" x="393.1699" y="217.4888">send signed request</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="157.6821" x="380.5063" y="232.6216">(URL rewritten to proxy)</text></g><g class="message" data-entity-1="part3" data-entity-2="part3" data-source-line="20" id="msg4"><line style="stroke:#444444;stroke-width:1;" x1="550.1885" x2="592.1885" y1="281.9531" y2="281.9531"/><line style="stroke:#444444;stroke-width:1;" x1="592.1885" x2="592.1885" y1="281.9531" y2="294.9531"/><line style="stroke:#444444;stroke-width:1;" x1="551.1885" x2="592.1885" y1="294.9531" y2="294.9531"/><polygon fill="#444444" points="561.1885,290.9531,551.1885,294.9531,561.1885,298.9531,557.1885,294.9531" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="173.3545" x="557.1885" y="261.7544">compress tool-result bytes</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="154.0703" x="566.8306" y="276.8872">inside the request body</text></g><path d="M555,307.9531 L555,347.9531 L842,347.9531 L842,317.9531 L832,307.9531 L555,307.9531" fill="#FFF9E6" style="stroke:#999999;stroke-width:0.5;"/><path d="M832,307.9531 L832,317.9531 L842,317.9531 L832,307.9531" fill="#FFF9E6" style="stroke:#999999;stroke-width:0.5;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="92.3774" x="561" y="325.02">body changed</text><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="700" lengthAdjust="spacing" textLength="35.8706" x="657.5098" y="325.02">after</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="60.4932" x="697.5127" y="325.02">signing --</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="266.7666" x="561" y="340.1528">signature no longer matches the content</text><g class="message" data-entity-1="part3" data-entity-2="part4" data-source-line="22" id="msg5"><polygon fill="#444444" points="749.311,370.3516,759.311,374.3516,749.311,378.3516,753.311,374.3516" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="550.1885" x2="755.311" y1="374.3516" y2="374.3516"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="163.3506" x="574.0745" y="369.2856">forward mutated request</text></g><g class="message" data-entity-1="part4" data-entity-2="part3" data-source-line="23" id="msg6"><polygon fill="#444444" points="561.1885,399.4844,551.1885,403.4844,561.1885,407.4844,557.1885,403.4844" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="555.1885" x2="760.311" y1="403.4844" y2="403.4844"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="187.1226" x="562.1885" y="398.4185">403 SignatureDoesNotMatch</text></g><g class="message" data-entity-1="part3" data-entity-2="part2" data-source-line="24" id="msg7"><polygon fill="#444444" points="379.5063,428.6172,369.5063,432.6172,379.5063,436.6172,375.5063,432.6172" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="373.5063" x2="549.1885" y1="432.6172" y2="432.6172"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="95.4497" x="411.6226" y="427.5513">error response</text></g><g class="message" data-entity-1="part2" data-entity-2="part1" data-source-line="25" id="msg8"><polygon fill="#444444" points="59.6167,457.75,49.6167,461.75,59.6167,465.75,55.6167,461.75" style="stroke:#444444;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:10;"/><line style="stroke:#444444;stroke-width:1;" x1="53.6167" x2="367.5063" y1="461.75" y2="461.75"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="89.8511" x="163.636" y="456.6841">request failed</text></g><?plantuml-src ZLDDRzf04BtxLupe9K6rg0Ig50wL22bAr2QWaduSV5cyWrbXxxYp2uHK_U-TDIQs-o5r3zRAyzwRDxCpRcjigLWLu3PAqy7O3DOgTnYv9eBVTsXJl4VdL8QJt6GMKhGUkOMQCDDXIZanl1fLfnrCFV4riKR-5sIXs9lKbChw_mUgT9inxQokmRFPR3WRji0FvF5lgAltRtz7jPDULIUAlF4vGkyRF2YpHxXzV5n0oVHq1CO36uyGnx1YL5i7awzBk4RDb6vxKLGsBg4tBz5EIMCYNyOUA0VpQHUY2lLCDbwT118hMVP63C75v0wMDnykAzQY_jlbtg8I5XM9hGmkWi4p_EdOnRPS1ZTsZ-mG9ekxYY3HA9fF8NxtaceCgvt9DLZbGmiu38FpYRrear_3e93wyi4FetyEqZeIEo-jAIwZirPNruKvglLWHVeeei7UqcHVHd-Gdex2GAih6kgMaS-VFjRFuT62fzCBLGBoK0qxfQ9acM61K1xBRPTBtgD7brXZdUG2ly6EeyZAP02RREE1rcUX485qesmcFlfzjPPDwFShOs5_uZYnuQxyZX4iGKw2P2YKJpVegYJI8Z7h6uzI-1ZMn0V56egTLxwfCGfTQUeOlHc67ftqRmYTZEzzqEvKN3SPPIrPX5n9LhQwtTJvTFnIx5gP7FKl?></g></svg>

package/index.js

@@ -0,0 +1,12 @@
+/**
+ * Conventional root entrypoint.
+ *
+ * OpenCode resolves a plugin referenced by filesystem path (either via
+ * `plugins` in opencode.json or through `.opencode/plugins/` auto-discovery)
+ * by looking for `index.*`/`server.*` directly in this directory — it does
+ * NOT consult `package.json`'s `exports` field for local path references
+ * (that field only applies when the plugin is installed and referenced by
+ * npm package name). Keep the real implementation in src/ and re-export it
+ * here so both resolution paths work.
+ */
+export { default } from "./src/index.js"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "opencode-headroom-plugin",
+  "version": "1.0.0",
+  "description": "OpenCode v2 plugin that transparently compresses large tool results via Headroom at the message level — works with any provider, including AWS Bedrock.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "headroom",
+    "llm",
+    "context-compression",
+    "token-optimization",
+    "aws-bedrock"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "pietro partescano <goldfix@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goldfix/opencode-headroom-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/goldfix/opencode-headroom-plugin/issues"
+  },
+  "homepage": "https://github.com/goldfix/opencode-headroom-plugin#readme",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "scripts",
+    "assets"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "plugin:install": "bash scripts/install.sh",
+    "plugin:uninstall": "bash scripts/uninstall.sh"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.19"
+  },
+  "engines": {
+    "node": ">=20.3"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Installs this plugin for auto-discovery by every OpenCode project on this
+# machine, by symlinking it into OpenCode's global plugins directory.
+# No opencode.json / opencode.jsonc edit is required (see docs/plugins.md
+# "Discover": OpenCode loads immediate plugin package directories from
+# ~/.config/opencode/plugins automatically).
+#
+# Usage:
+#   bash scripts/install.sh [--force]
+#
+# Env overrides:
+#   OPENCODE_CONFIG_DIR   Root config directory (default: ~/.config/opencode)
+set -euo pipefail
+
+PLUGIN_NAME="headroom-context-compression"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+TARGET_DIR="$CONFIG_DIR/plugins/$PLUGIN_NAME"
+FORCE="${1:-}"
+
+if [ ! -d "$REPO_ROOT/node_modules/@opencode/plugin" ]; then
+  echo "--> @opencode/plugin is not installed here yet. Run 'npm install' in ${REPO_ROOT} first."
+  exit 1
+fi
+
+mkdir -p "$CONFIG_DIR/plugins"
+
+if [ -e "$TARGET_DIR" ] || [ -L "$TARGET_DIR" ]; then
+  if [ "$FORCE" != "--force" ]; then
+    echo "--> ${TARGET_DIR} already exists. Re-run with --force to replace it."
+    exit 1
+  fi
+  rm -rf "$TARGET_DIR"
+fi
+
+ln -s "$REPO_ROOT" "$TARGET_DIR"
+
+echo "--> Linked ${TARGET_DIR} -> ${REPO_ROOT}"
+echo "--> Make sure 'headroom proxy' is running before starting OpenCode."
+echo "--> Restart the OpenCode server (e.g. 'opencode service restart') to load the plugin."

package/scripts/uninstall.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Removes the global symlink created by scripts/install.sh.
+# Refuses to touch anything that is not a symlink, in case a user replaced
+# it with a real directory.
+#
+# Usage:
+#   bash scripts/uninstall.sh
+set -euo pipefail
+
+PLUGIN_NAME="headroom-context-compression"
+CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+TARGET_DIR="$CONFIG_DIR/plugins/$PLUGIN_NAME"
+
+if [ ! -e "$TARGET_DIR" ] && [ ! -L "$TARGET_DIR" ]; then
+  echo "--> Nothing installed at ${TARGET_DIR}."
+  exit 0
+fi
+
+if [ ! -L "$TARGET_DIR" ]; then
+  echo "--> ${TARGET_DIR} exists but is not a symlink; leaving it alone. Remove it manually if needed."
+  exit 1
+fi
+
+rm "$TARGET_DIR"
+echo "--> Removed ${TARGET_DIR}"
+echo "--> Restart the OpenCode server (e.g. 'opencode service restart') to unload the plugin."

package/src/bridge.js

@@ -0,0 +1,275 @@
+/**
+ * Pure message-compression logic: converts OpenCode's provider-agnostic
+ * `Message`/`ToolResultPart` shape (from `@opencode/ai`, seen in
+ * `session.hook("context", ...)`) into the plain "OpenAI-shape" messages
+ * Headroom's `POST /v1/compress` expects, and applies the compressed result
+ * back — touching only `tool` role messages.
+ *
+ * Ported from `@casualjim/pi-headroom` (pi-mimir) and, for the guard rules
+ * below, from its sibling fork `@raquezha/noheadroom` (both derive from
+ * `@ryan_nookpi/pi-extension-headroom`, MIT) — adapted to OpenCode's message
+ * model. Kept free of `@opencode/plugin` so it can be unit tested without a
+ * running OpenCode server.
+ */
+
+import { createHash } from "node:crypto"
+
+/** Only these roles ever get sent to Headroom; `system` never leaves this plugin. */
+const CONVERTIBLE_ROLES = new Set(["user", "assistant", "tool"])
+
+// File reads and structural edits (edit/patch) supply exact anchors for later
+// exact-match edits; compressing their output risks corrupting those anchors,
+// and `skill` output is directive text meant to be followed verbatim. Ported
+// from noheadroom's `PROTECTED_TOOLS`, renamed to OpenCode's built-in tool
+// names. These never become compression candidates, regardless of size —
+// unlike `renameToolCalls` below, which only concerns tools we DO allow to
+// compress but still want to shield from Headroom's own default exclusions.
+const PROTECTED_TOOLS = new Set(["read", "write", "edit", "patch", "skill", "headroom_retrieve"])
+
+/**
+ * @param {Array} messages - `event.messages` from the `context` hook.
+ * @param {number} minMessageChars - skip tool results shorter than this.
+ * @param {{ renameToolCalls?: boolean }} [options]
+ */
+export function buildCompressionPayload(messages, minMessageChars, options = {}) {
+  const renameToolCalls = options.renameToolCalls !== false
+  const mappings = []
+
+  for (let messageIndex = 0; messageIndex < messages.length; messageIndex++) {
+    const message = messages[messageIndex]
+    if (!CONVERTIBLE_ROLES.has(message.role)) continue
+
+    if (message.role === "tool") {
+      const parts = Array.isArray(message.content) ? message.content : []
+      for (let partIndex = 0; partIndex < parts.length; partIndex++) {
+        const part = parts[partIndex]
+        if (!part || part.type !== "tool-result") continue
+        const text = extractToolResultText(part)
+        // `null` means the result carries non-text content (files/images) or
+        // an error — never compressed, never even sent to Headroom.
+        if (text === null) continue
+        mappings.push({
+          messageIndex,
+          partIndex,
+          toolCallId: part.id,
+          toolName: part.name,
+          applyTo: !PROTECTED_TOOLS.has(part.name) && text.length >= minMessageChars,
+          originalText: text,
+          converted: { role: "tool", content: text, tool_call_id: part.id },
+        })
+      }
+      continue
+    }
+
+    const converted = message.role === "user" ? convertUser(message) : convertAssistant(message, renameToolCalls)
+    if (!converted) continue
+    mappings.push({
+      messageIndex,
+      partIndex: -1,
+      toolCallId: undefined,
+      toolName: undefined,
+      applyTo: false,
+      originalText: extractText(converted),
+      converted,
+    })
+  }
+
+  return {
+    messages: mappings.map((mapping) => mapping.converted),
+    mappings,
+    candidateCount: mappings.filter((mapping) => mapping.applyTo).length,
+  }
+}
+
+/**
+ * Applies Headroom's compressed messages back onto the original OpenCode
+ * messages, touching only entries marked `applyTo`. Anything Headroom
+ * changed outside those entries (it may rewrite context for its own
+ * cross-message analysis) is ignored — the original message is kept as is.
+ */
+export function applyCompressionResult(messages, mappings, compressedMessages) {
+  if (!Array.isArray(compressedMessages) || compressedMessages.length !== mappings.length) {
+    return { ok: false, reason: "message-count-changed" }
+  }
+
+  const next = messages.slice()
+  let appliedMessages = 0
+  let tokensBefore = 0
+  let tokensAfter = 0
+
+  for (let index = 0; index < mappings.length; index++) {
+    const mapping = mappings[index]
+    if (!mapping.applyTo) continue
+
+    const compressed = compressedMessages[index]
+    if (!compressed || compressed.role !== "tool") return { ok: false, reason: "role-changed" }
+    if (compressed.tool_call_id !== mapping.converted.tool_call_id) return { ok: false, reason: "tool-call-id-changed" }
+
+    const rawText = typeof compressed.content === "string" ? compressed.content : mapping.originalText
+    if (rawText === mapping.originalText) continue
+
+    const nextText = naturalizeHeadroomMarkers(rawText)
+    // Reject the whole batch on an empty result: it is never a legitimate
+    // compression outcome and likely signals a malformed proxy response.
+    if (!nextText.trim()) return { ok: false, reason: "empty-compressed-content" }
+    // A single candidate that didn't actually shrink is skipped on its own —
+    // it does not invalidate the other candidates in this batch.
+    if (estimateTokens(nextText) >= estimateTokens(mapping.originalText)) continue
+
+    const original = next[mapping.messageIndex]
+    const originalPart = Array.isArray(original.content) ? original.content[mapping.partIndex] : undefined
+    if (!originalPart || originalPart.type !== "tool-result") return { ok: false, reason: "target-unreplaceable" }
+
+    const nextContent = original.content.slice()
+    nextContent[mapping.partIndex] = { ...originalPart, result: { type: "text", value: nextText } }
+    next[mapping.messageIndex] = { ...original, content: nextContent }
+
+    tokensBefore += estimateTokens(mapping.originalText)
+    tokensAfter += estimateTokens(nextText)
+    appliedMessages++
+  }
+
+  if (appliedMessages === 0) return { ok: false, reason: "no-applicable-message-changed" }
+  const tokensSaved = Math.max(0, tokensBefore - tokensAfter)
+  if (tokensSaved === 0) return { ok: false, reason: "no-estimated-token-savings" }
+
+  return {
+    ok: true,
+    messages: next,
+    appliedMessages,
+    appliedTokensBefore: tokensBefore,
+    appliedTokensAfter: tokensAfter,
+    appliedTokensSaved: tokensSaved,
+    appliedCompressionRatio: tokensAfter / tokensBefore,
+  }
+}
+
+/**
+ * Headroom's bracket markers carry the CCR hash. Keep the hash and name the
+ * tool that redeems it, so the model doesn't need an MCP server to resolve
+ * "Retrieve more: hash=...]" — our own `headroom_retrieve` tool does it.
+ * Idempotent: running it on already-naturalized text is a no-op (the
+ * rewritten phrasing no longer matches the source markers), which matters
+ * because replayed/cached text has already passed through this once.
+ */
+export function naturalizeHeadroomMarkers(text) {
+  return text
+    .replace(
+      /\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve (?:more|original): hash=([a-f0-9]{12,24})\]/gi,
+      "[$1. Retrieve the full original with the `headroom_retrieve` tool using hash=$2.]",
+    )
+    .replace(
+      /Retrieve original: hash=([a-f0-9]{12,24})/gi,
+      "Retrieve the full original with the `headroom_retrieve` tool using hash=$1",
+    )
+}
+
+/**
+ * Deterministic per-message fingerprint of the whole `event.messages` array,
+ * used by `guard.js` to detect an unchanged or already-compressed context
+ * without re-running the (more expensive) compression payload build.
+ */
+export function fingerprintMessages(messages) {
+  return messages.map((message) => `${message.role}:${stableHash(fingerprintText(message)).slice(0, 16)}`).join(",")
+}
+
+/** Rough total context size, used to gate compression on small sessions where it isn't worth a proxy round trip. */
+export function estimateContextTokens(messages) {
+  return messages.reduce((total, message) => total + estimateTokens(fingerprintText(message)), 0)
+}
+
+export function stableHash(value) {
+  return createHash("sha256").update(value).digest("hex")
+}
+
+export function estimateTokens(text) {
+  // Cheap local estimate; an exact tokenizer would add a heavy dependency for a footer number.
+  return text.length === 0 ? 0 : Math.max(1, Math.ceil(text.length / 4))
+}
+
+function fingerprintText(message) {
+  if (message.role === "tool") {
+    const parts = Array.isArray(message.content) ? message.content : []
+    return parts
+      .map((part) => (part?.type === "tool-result" ? `${part.id}:${extractToolResultText(part) ?? ""}` : ""))
+      .join("|")
+  }
+  if (message.role === "user") return joinTextParts(message.content)
+  if (message.role === "assistant") {
+    const parts = Array.isArray(message.content) ? message.content : []
+    const toolCallIds = parts
+      .filter((part) => part?.type === "tool-call")
+      .map((part) => part.id)
+      .join(",")
+    return `${joinTextParts(parts)}#${toolCallIds}`
+  }
+  return ""
+}
+
+function extractToolResultText(part) {
+  const result = part.result
+  if (!result) return null
+  if (result.type === "text") return typeof result.value === "string" ? result.value : safeStringify(result.value)
+  if (result.type === "json") return safeStringify(result.value)
+  if (result.type === "content") {
+    const items = Array.isArray(result.value) ? result.value : []
+    // A file/image tool result loses meaning as text; leave it untouched
+    // rather than risk destroying an attachment.
+    if (items.some((item) => item?.type !== "text")) return null
+    return items.map((item) => item.text).join("\n")
+  }
+  return null // "error" results are left untouched
+}
+
+function convertUser(message) {
+  const text = joinTextParts(message.content)
+  if (text) return { role: "user", content: text }
+  const hasMedia = Array.isArray(message.content) && message.content.some((part) => part?.type === "media")
+  return hasMedia ? { role: "user", content: "[media omitted from Headroom compression payload]" } : null
+}
+
+function convertAssistant(message, renameToolCalls) {
+  const parts = Array.isArray(message.content) ? message.content : []
+  const text = joinTextParts(parts)
+  const toolCalls = parts.filter((part) => part?.type === "tool-call")
+  if (!text && toolCalls.length === 0) return null
+
+  const converted = { role: "assistant", content: text || null }
+  if (toolCalls.length > 0) {
+    converted.tool_calls = toolCalls.map((call) => ({
+      id: call.id,
+      type: "function",
+      function: {
+        // Headroom protects exact tool names (read, grep, ...) from compression
+        // via its DEFAULT_EXCLUDE_TOOLS; a neutral name keeps large results compressible
+        // for tools we allow to compress (PROTECTED_TOOLS above blocks the rest regardless).
+        name: renameToolCalls ? "opencode_tool_result" : call.name,
+        arguments: renameToolCalls ? JSON.stringify({ originalToolName: call.name }) : JSON.stringify(call.input ?? {}),
+      },
+    }))
+  }
+  return converted
+}
+
+function joinTextParts(content) {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return ""
+  return content
+    .filter((part) => part?.type === "text")
+    .map((part) => part.text)
+    .join("\n")
+}
+
+function extractText(converted) {
+  if (typeof converted.content === "string") return converted.content
+  return ""
+}
+
+function safeStringify(value) {
+  if (typeof value === "string") return value
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}

package/src/client.js

@@ -0,0 +1,73 @@
+/**
+ * Minimal HTTP client for the two Headroom proxy endpoints this plugin uses:
+ * `POST /v1/compress` (stateless compression, no upstream provider call) and
+ * `GET /v1/retrieve/{hash}` (CCR original-content lookup).
+ *
+ * Never calls anything else on the proxy, and never starts or manages the
+ * `headroom proxy` process itself.
+ */
+export class HeadroomClient {
+  #baseUrl
+  #timeoutMs
+
+  constructor({ baseUrl, timeoutMs }) {
+    this.#baseUrl = baseUrl.replace(/\/+$/, "")
+    this.#timeoutMs = timeoutMs
+  }
+
+  /**
+   * @param {Array} messages - OpenAI-shape messages from `buildCompressionPayload`.
+   * @param {string} [model] - drives Headroom's tokenizer/context-limit resolution.
+   */
+  async compress(messages, model, signal) {
+    const response = await fetch(`${this.#baseUrl}/v1/compress`, {
+      method: "POST",
+      // A redirect could forward full tool results to a non-local host, bypassing `allowRemote`.
+      redirect: "error",
+      headers: { "content-type": "application/json", "x-headroom-stack": "opencode-plugin" },
+      body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+      signal: this.#withTimeout(signal),
+    })
+    if (!response.ok) {
+      throw new Error(`Headroom /v1/compress failed with HTTP ${response.status}`)
+    }
+    const payload = await response.json()
+    return {
+      messages: payload.messages,
+      tokensBefore: payload.tokens_before,
+      tokensAfter: payload.tokens_after,
+      tokensSaved: payload.tokens_saved,
+    }
+  }
+
+  /** @returns {Promise<{ ok: true, content: string } | { ok: false, error: string }>} */
+  async retrieve(hash, signal) {
+    try {
+      const response = await fetch(`${this.#baseUrl}/v1/retrieve/${hash}`, {
+        redirect: "error",
+        signal: this.#withTimeout(signal),
+      })
+      if (!response.ok) {
+        return {
+          ok: false,
+          error:
+            response.status === 404
+              ? "Entry not found in Headroom's CCR store (TTL 1800s) — the compressed content expired."
+              : `Headroom /v1/retrieve failed with HTTP ${response.status}`,
+        }
+      }
+      const body = await response.json()
+      if (typeof body === "string") return { ok: true, content: body }
+      if (body && typeof body.original_content === "string") return { ok: true, content: body.original_content }
+      return { ok: true, content: JSON.stringify(body, null, 2) }
+    } catch (error) {
+      return { ok: false, error: `Headroom /v1/retrieve failed: ${error instanceof Error ? error.message : String(error)}` }
+    }
+  }
+
+  #withTimeout(signal) {
+    const timeout = AbortSignal.timeout(this.#timeoutMs)
+    if (!signal) return timeout
+    return AbortSignal.any([signal, timeout])
+  }
+}

package/src/config.js

@@ -0,0 +1,84 @@
+/**
+ * Plugin configuration: resolved once at `setup(ctx)` time from plugin
+ * options (`opencode.json` `plugins[].options`) layered over environment
+ * variables. No settings file, no persistence — keep it simple until a real
+ * need for `/headroom`-style runtime toggling shows up.
+ */
+
+export const DEFAULT_BASE_URL = "http://127.0.0.1:8787" // headroom proxy's own default
+export const DEFAULT_MIN_CONTEXT_TOKENS = 10_000
+export const DEFAULT_MIN_MESSAGE_CHARS = 2000
+// Headroom's own internal budget for the compression step is 30s (seen in its proxy startup
+// log, "Anthropic pre-upstream timeouts: ... compression=30.0s"); 40s leaves margin above that
+// for large contexts (observed: 23.4s for 183 messages / ~135k tokens) instead of aborting a
+// request Headroom would have finished successfully.
+export const DEFAULT_TIMEOUT_MS = 40_000
+
+/**
+ * @param {Record<string, unknown>} options - `ctx.options`
+ * @param {Record<string, string | undefined>} env
+ */
+export function resolveConfig(options = {}, env = {}) {
+  return {
+    enabled: parseBoolean(options.enabled, parseBoolean(env.HEADROOM_ENABLED, true)),
+    baseUrl: normalizeBaseUrl(parseString(options.proxyUrl, env.HEADROOM_PROXY_URL) || DEFAULT_BASE_URL),
+    allowRemote: parseBoolean(options.allowRemote, parseBoolean(env.HEADROOM_ALLOW_REMOTE, false)),
+    renameToolCalls: parseBoolean(options.renameToolCalls, true),
+    // Below this estimated total context size, compression isn't worth a proxy round trip.
+    minContextTokens: parseInteger(
+      options.minContextTokens,
+      parseInteger(env.HEADROOM_MIN_CONTEXT_TOKENS, DEFAULT_MIN_CONTEXT_TOKENS, 0),
+      0,
+    ),
+    minMessageChars: parseInteger(
+      options.minMessageChars,
+      parseInteger(env.HEADROOM_MIN_MESSAGE_CHARS, DEFAULT_MIN_MESSAGE_CHARS, 1),
+      1,
+    ),
+    timeoutMs: parseInteger(options.timeoutMs, parseInteger(env.HEADROOM_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100), 100),
+    // Provider IDs to skip entirely (e.g. a provider known to misbehave with Headroom).
+    // Compressing at the message level (this plugin) has no known need for this today —
+    // kept as an escape hatch, not a default exclusion.
+    excludeProviders: Array.isArray(options.excludeProviders) ? options.excludeProviders : [],
+  }
+}
+
+export function isLocalHeadroomUrl(rawUrl) {
+  try {
+    const url = new URL(rawUrl)
+    return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname)
+  } catch {
+    return false
+  }
+}
+
+/** Compressing sends full tool-result content to `baseUrl`; never do that to a non-local proxy silently. */
+export function isRemoteBlocked(config) {
+  return !config.allowRemote && !isLocalHeadroomUrl(config.baseUrl)
+}
+
+function normalizeBaseUrl(raw) {
+  return (raw || DEFAULT_BASE_URL).trim().replace(/\/+$/, "")
+}
+
+function parseString(raw, fallback) {
+  if (typeof raw === "string" && raw.trim()) return raw.trim()
+  return typeof fallback === "string" ? fallback : undefined
+}
+
+function parseBoolean(raw, fallback) {
+  if (raw === undefined) return fallback
+  if (typeof raw === "boolean") return raw
+  if (typeof raw !== "string") return fallback
+  const normalized = raw.trim().toLowerCase()
+  if (["1", "true", "yes", "on"].includes(normalized)) return true
+  if (["0", "false", "no", "off"].includes(normalized)) return false
+  return fallback
+}
+
+function parseInteger(raw, fallback, min) {
+  if (raw === undefined) return fallback
+  const parsed = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseInt(raw, 10) : Number.NaN
+  if (!Number.isFinite(parsed) || parsed < min) return fallback
+  return Math.trunc(parsed)
+}

package/src/guard.js

@@ -0,0 +1,134 @@
+/**
+ * Per-session guard state: cross-turn replay cache and loop-prevention
+ * fingerprints. Ported from `noheadroom` (source_app/noheadroom,
+ * extensions/headroom.ts), which solves the same problem for Pi: OpenCode,
+ * like Pi, does not persist a `context` hook's mutations back into session
+ * history, so every subsequent request resends the same large tool result
+ * uncompressed. Without this module the plugin would re-call Headroom's
+ * `/v1/compress` for identical content on every turn of a multi-step tool
+ * loop.
+ *
+ * Kept free of `@opencode/plugin` for unit testing. Unlike noheadroom (one
+ * process per Pi session), an OpenCode plugin instance can see multiple
+ * concurrent sessions, so `index.js` keys one state object per `sessionID`
+ * via `createSessionGuardState()` — this module has no concept of sessions
+ * itself.
+ */
+
+import { applyCompressionResult, stableHash } from "./bridge.js"
+
+// Bounded FIFO, not config: a safety valve, not a tunable. 512 hashes is far
+// beyond a realistic reread-loop case while keeping memory bounded for long
+// sessions. Mirrors noheadroom's MAX_SEEN_CANDIDATE_CONTENT_FINGERPRINTS.
+const MAX_TRACKED_FINGERPRINTS = 512
+// Kills rapid repeated compression attempts (e.g. several hook invocations
+// for the same turn) without needing to reason about their exact cause.
+const THROTTLE_MS = 3000
+
+export function createSessionGuardState() {
+  return {
+    lastCompressionTime: 0,
+    lastInputFingerprint: null,
+    lastOutputFingerprint: null,
+    lastGuardSkipCandidateFingerprint: null,
+    seenCandidateContentFingerprints: new Set(),
+    seenCandidateContentOrder: [],
+    compressedCandidates: new Map(),
+  }
+}
+
+export function shouldThrottle(state, now) {
+  return now - state.lastCompressionTime < THROTTLE_MS
+}
+
+/** Identifies a specific tool-result occurrence, independent of its position in the message list. */
+function candidateKey(mapping) {
+  return stableHash(JSON.stringify([mapping.toolCallId ?? null, mapping.toolName ?? null, stableHash(mapping.originalText)]))
+}
+
+/**
+ * Reapplies previously-validated compressed text for candidates whose exact
+ * (tool call id, tool name, original text) was compressed before in this
+ * session — without calling Headroom again.
+ *
+ * @returns {Array|undefined} the replayed messages, or `undefined` if nothing in the cache applies.
+ */
+export function replayCachedCandidates(state, messages, payload) {
+  if (state.compressedCandidates.size === 0) return undefined
+
+  const mappings = payload.mappings.map((mapping) => ({
+    ...mapping,
+    applyTo: mapping.applyTo && state.compressedCandidates.has(candidateKey(mapping)),
+  }))
+  const compressed = mappings.map((mapping) =>
+    mapping.applyTo ? { ...mapping.converted, content: state.compressedCandidates.get(candidateKey(mapping)) } : mapping.converted,
+  )
+
+  const applied = applyCompressionResult(messages, mappings, compressed)
+  return applied.ok ? applied.messages : undefined
+}
+
+/** Records validated compressions from a successful proxy round trip so later turns can replay them. */
+export function recordCachedCandidates(state, payload, appliedMessages) {
+  for (const mapping of payload.mappings) {
+    if (!mapping.applyTo) continue
+    const part = appliedMessages[mapping.messageIndex]?.content?.[mapping.partIndex]
+    if (!part || part.type !== "tool-result" || part.result?.type !== "text") continue
+    const text = part.result.value
+    if (text === mapping.originalText) continue
+
+    state.compressedCandidates.set(candidateKey(mapping), text)
+    if (state.compressedCandidates.size > MAX_TRACKED_FINGERPRINTS) {
+      state.compressedCandidates.delete(state.compressedCandidates.keys().next().value)
+    }
+  }
+}
+
+/** True once every current candidate's original text has already been seen (and rejected or replayed) before. */
+export function allCandidateContentSeen(state, payload) {
+  const seen = state.seenCandidateContentFingerprints
+  const hashes = payload.mappings.filter((mapping) => mapping.applyTo).map((mapping) => stableHash(mapping.originalText))
+  return hashes.length > 0 && hashes.every((hash) => seen.has(hash))
+}
+
+/** Mutates `payload.mappings` in place, excluding already-seen candidates from this round's proxy request. */
+export function ignoreSeenCandidateContent(state, payload) {
+  const seen = state.seenCandidateContentFingerprints
+  for (const mapping of payload.mappings) {
+    if (mapping.applyTo && seen.has(stableHash(mapping.originalText))) mapping.applyTo = false
+  }
+}
+
+export function recordSeenCandidateContent(state, payload, appliedMessages) {
+  for (const mapping of payload.mappings) {
+    if (!mapping.applyTo) continue
+    addSeenHash(state, stableHash(mapping.originalText))
+    const part = appliedMessages[mapping.messageIndex]?.content?.[mapping.partIndex]
+    if (part?.type === "tool-result" && part.result?.type === "text") addSeenHash(state, stableHash(part.result.value))
+  }
+}
+
+function addSeenHash(state, hash) {
+  if (state.seenCandidateContentFingerprints.has(hash)) return
+  state.seenCandidateContentFingerprints.add(hash)
+  state.seenCandidateContentOrder.push(hash)
+  while (state.seenCandidateContentOrder.length > MAX_TRACKED_FINGERPRINTS) {
+    const oldest = state.seenCandidateContentOrder.shift()
+    state.seenCandidateContentFingerprints.delete(oldest)
+  }
+}
+
+/** Fingerprints only the candidates eligible this round, so unrelated conversation growth doesn't defeat the guard below. */
+export function generateCandidateFingerprint(payload) {
+  const units = payload.mappings
+    .filter((mapping) => mapping.applyTo)
+    .map((mapping) => ({
+      messageIndex: mapping.messageIndex,
+      partIndex: mapping.partIndex,
+      toolCallId: mapping.toolCallId ?? null,
+      toolName: mapping.toolName ?? null,
+      textLength: mapping.originalText.length,
+      textHash: stableHash(mapping.originalText),
+    }))
+  return stableHash(JSON.stringify(units))
+}

package/src/index.js

@@ -0,0 +1,178 @@
+/**
+ * OpenCode v2 plugin: transparent Headroom context compression.
+ *
+ * Hooks `session.hook("context", ...)` — the provider-agnostic message list
+ * OpenCode assembles immediately before dispatching to the model, *before*
+ * any provider-specific lowering (Anthropic Messages, OpenAI Chat, Bedrock
+ * Converse, ...) or request signing happens. Only `tool` role messages are
+ * sent to Headroom's stateless `POST /v1/compress` for compression; user and
+ * assistant text are never touched, and PROTECTED_TOOLS (see bridge.js) are
+ * never candidates regardless of size. Because this runs above the wire
+ * protocol, it works identically for every provider OpenCode supports —
+ * including AWS Bedrock, whose native Converse API and SigV4-signed
+ * requests made an earlier `http.request`-based approach unworkable (see
+ * MEMORY.md).
+ *
+ * The guard/replay logic in guard.js follows `noheadroom`
+ * (source_app/noheadroom): a cross-turn cache avoids recompressing the same
+ * tool result on every step of a multi-step turn (OpenCode doesn't persist
+ * `context` mutations into history, so the uncompressed original reappears
+ * on the next call), and fingerprint guards throttle/skip redundant proxy
+ * calls when the eligible content hasn't changed.
+ *
+ * Prerequisite: `headroom proxy` must already be running and reachable.
+ * This plugin never starts, stops, or otherwise manages that process.
+ *
+ * @see https://docs.headroomlabs.ai/docs/proxy#post-v1compress
+ * @see https://opencode.ai/v2/docs/build/plugins
+ */
+import { Plugin } from "@opencode/plugin"
+import { applyCompressionResult, buildCompressionPayload, estimateContextTokens, fingerprintMessages } from "./bridge.js"
+import { HeadroomClient } from "./client.js"
+import { isRemoteBlocked, resolveConfig } from "./config.js"
+import {
+  allCandidateContentSeen,
+  createSessionGuardState,
+  generateCandidateFingerprint,
+  ignoreSeenCandidateContent,
+  recordCachedCandidates,
+  recordSeenCandidateContent,
+  replayCachedCandidates,
+  shouldThrottle,
+} from "./guard.js"
+
+// Bounds memory if a server process outlives many short-lived sessions; the least recently
+// used session is evicted first, well before this is ever reached in normal interactive use.
+const MAX_TRACKED_SESSIONS = 200
+
+export default Plugin.define({
+  id: "headroom-context-compression",
+  async setup(ctx) {
+    const config = resolveConfig(ctx.options, process.env)
+    const client = new HeadroomClient({ baseUrl: config.baseUrl, timeoutMs: config.timeoutMs })
+    const sessionStates = new Map()
+    let proxyWarningShown = false
+
+    if (config.enabled && isRemoteBlocked(config)) {
+      console.warn(
+        `[headroom] Compression disabled: ${config.baseUrl} is not local and "allowRemote" is not set. ` +
+          "Tool results would be sent to that proxy in full before compression. Set options.allowRemote to true only for a trusted proxy.",
+      )
+    }
+
+    await ctx.session.hook("context", async (event) => {
+      if (!config.enabled || isRemoteBlocked(config)) return
+      if (config.excludeProviders.includes(event.model.providerID)) return
+      if (estimateContextTokens(event.messages) < config.minContextTokens) return
+
+      const state = sessionStateFor(sessionStates, event.sessionID)
+      const payload = buildCompressionPayload(event.messages, config.minMessageChars, {
+        renameToolCalls: config.renameToolCalls,
+      })
+      const replayed = replayCachedCandidates(state, event.messages, payload)
+      const bypass = () => replaceMessages(event, replayed)
+
+      if (payload.candidateCount === 0) return bypass()
+
+      const now = Date.now()
+      if (shouldThrottle(state, now)) return bypass()
+
+      const inputFingerprint = fingerprintMessages(event.messages)
+      // Our own compressed output looping back as next-turn input: nothing new to do, and no replay needed.
+      if (state.lastOutputFingerprint === inputFingerprint) return
+      if (state.lastInputFingerprint === inputFingerprint) return bypass()
+
+      const candidateFingerprint = generateCandidateFingerprint(payload)
+      if (state.lastGuardSkipCandidateFingerprint === candidateFingerprint) return bypass()
+      if (allCandidateContentSeen(state, payload)) return bypass()
+      ignoreSeenCandidateContent(state, payload)
+
+      state.lastCompressionTime = now
+      let result
+      try {
+        result = await client.compress(payload.messages, event.model.id)
+      } catch (error) {
+        if (!proxyWarningShown) {
+          proxyWarningShown = true
+          console.warn(
+            `[headroom] compression skipped, proxy unavailable at ${config.baseUrl} (further failures are silent until it recovers): ` +
+              (error instanceof Error ? error.message : String(error)),
+          )
+        }
+        return bypass()
+      }
+      proxyWarningShown = false
+      if (!result.tokensSaved || result.tokensSaved <= 0) {
+        state.lastInputFingerprint = inputFingerprint
+        state.lastGuardSkipCandidateFingerprint = candidateFingerprint
+        return bypass()
+      }
+
+      // Apply on top of the replayed messages, not the originals: candidates excluded from this
+      // round by ignoreSeenCandidateContent are the ones already compressed (and cached) earlier,
+      // and must stay compressed. noheadroom stitches the same replayed values back in.
+      const applied = applyCompressionResult(replayed ?? event.messages, payload.mappings, result.messages)
+      if (!applied.ok) {
+        state.lastInputFingerprint = inputFingerprint
+        state.lastOutputFingerprint = null
+        state.lastGuardSkipCandidateFingerprint = candidateFingerprint
+        console.warn(`[headroom] compression not applied: ${applied.reason}`)
+        return bypass()
+      }
+
+      state.lastInputFingerprint = inputFingerprint
+      state.lastGuardSkipCandidateFingerprint = null
+      recordSeenCandidateContent(state, payload, applied.messages)
+      recordCachedCandidates(state, payload, applied.messages)
+      state.lastOutputFingerprint = fingerprintMessages(applied.messages)
+      replaceMessages(event, applied.messages)
+    })
+
+    await ctx.tool.transform((editor) => {
+      editor.add({
+        name: "headroom_retrieve",
+        description:
+          "Retrieve the full original content that Headroom compressed. Use the exact hash from a compression " +
+          "marker (e.g. `Retrieve more: hash=...`) in a tool result.",
+        input: {
+          type: "object",
+          properties: { hash: { type: "string", description: "The compression marker hash (12-24 hex characters)." } },
+          required: ["hash"],
+          additionalProperties: false,
+        },
+        execute: async ({ hash }, toolContext) => {
+          const normalized = String(hash ?? "").trim().toLowerCase()
+          if (!/^[a-f0-9]{12,24}$/.test(normalized)) {
+            return { content: JSON.stringify({ error: "Invalid hash format. Expected 12-24 hex characters." }) }
+          }
+          const result = await client.retrieve(normalized, toolContext?.signal)
+          return { content: result.ok ? result.content : JSON.stringify({ error: result.error, hash: normalized }) }
+        },
+      })
+    })
+  },
+})
+
+function sessionStateFor(sessionStates, sessionID) {
+  const existing = sessionStates.get(sessionID)
+  if (existing) {
+    // Re-insert to mark as most recently used, so eviction below drops idle sessions first.
+    sessionStates.delete(sessionID)
+    sessionStates.set(sessionID, existing)
+    return existing
+  }
+
+  if (sessionStates.size >= MAX_TRACKED_SESSIONS) {
+    sessionStates.delete(sessionStates.keys().next().value)
+  }
+  const state = createSessionGuardState()
+  sessionStates.set(sessionID, state)
+  return state
+}
+
+function replaceMessages(event, messages) {
+  if (!messages) return
+  messages.forEach((message, index) => {
+    event.messages[index] = message
+  })
+}