Files
headroom/plugins/openclaw/README.md
Parideboy 1372f95524 fix(openclaw): let the circuit breaker open on proxy failures (#4755)
## Description

`assemble()` in the openclaw plugin passed `fallback: true` to the SDK's
`compress()`. In `sdk/typescript/src/client.ts`, that flag makes a
connection error, a timeout or a 5xx retry once and then **resolve** to
`makeFallbackResult(messages)` — `tokensBefore: 0`, `tokensSaved: 0`,
`compressed: false` — instead of throwing.

That result never reached the `catch` that calls `tripCircuit()`. Worse,
`assemble()` treated it as a successful no-op and called
`resetCircuit()`, so the error counter went back to zero on every turn.
Against a proxy that accepts connections but never answers, the circuit
breaker could never open: every `assemble()` paid up to `2 ×
requestTimeoutMs` and then bypassed compression anyway.

Closes #4738

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Pass `fallback: false` on the plugin's `compress()` call, so proxy
failures throw into the existing `catch` → `tripCircuit()`. Graceful
degradation is unchanged: that `catch` already returns the original
messages.
- Treat a zero `tokensBefore` on **nonempty** input as a failure too, so
a result that resolved empty cannot keep the breaker closed either.
Empty input is exempt, because the proxy legitimately answers
`tokens_before: 0` for an empty `messages` array — caught in review, see
the `minContextChars: 0` case below.
- `README.md`: the post-cool-down turn does not call `/health`; nothing
in the engine ever did. It re-probes by attempting a real compression.
Fixed, and the threshold row now says which failures count.

## Testing

- [ ] Unit tests pass (`pytest`) — N/A, this is the TypeScript plugin;
ran `vitest` instead
- [ ] Linting passes (`ruff check .`) — N/A, no Python changed
- [ ] Type checking passes (`mypy headroom`) — N/A, no Python changed
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ npx vitest run test/engine.test.ts
 Test Files  1 passed (1)
      Tests  41 passed (41)

$ npm run typecheck
> node node_modules/@typescript/native/bin/tsc --noEmit
(clean)

$ npm run build
ESM Build success in 18ms
DTS Build success in 515ms
```

The three new tests each fail on the unpatched tree (verified by
stashing only `src/engine.ts` and re-running):

```text
× passes fallback: false so proxy failures reach the circuit breaker
× opens the circuit on zero-token results, even if the SDK swallows the error
× does not count an empty context as a failure
```

Full suite: 158 passed, 2 failed — both pre-existing and unrelated, in
`test/advancement-key-store.test.ts`, caused by this machine's Node
rejecting `--experimental-transform-types` in the child-process fixture
(`node: bad option: --experimental-transform-types`). They fail
identically on `upstream/main` without this patch.

## Real Behavior Proof

- Environment: Windows 11, Node v26.10.0, `plugins/openclaw` built with
`npm run build`, in-tree `headroom-ai@0.42.0`. Stub proxy is a
`node:http` server that accepts the connection and never responds.
Engine constructed with `requestTimeoutMs: 500`,
`circuitBreakerThreshold: 3`, `circuitBreakerCooldownMs: 60000`,
`minContextChars: 0`, driven through five `assemble()` calls with a
2000-char message.
- Exact command / steps: `npm run build` in `plugins/openclaw`, then
`node proof-circuit.mjs`, which starts the hung proxy on an ephemeral
port, points the engine at it, and makes five sequential `assemble()`
calls. Run once on the unpatched build and once on the patched build.
- Observed result: before the patch the breaker never opened and every
call paid the full timeout. After the patch it opens after the third
failure and calls 4 and 5 skip the proxy entirely (0 ms, 0 requests).
Messages returned are the originals in every case, so model output is
unchanged; only the latency is removed.

Before the patch:

```text
call 1: ms=1004 requestsSeenByProxy=2 totalProxyRequests=2
call 2: ms=1001 requestsSeenByProxy=2 totalProxyRequests=4
call 3: ms=1003 requestsSeenByProxy=2 totalProxyRequests=6
call 4: ms=1001 requestsSeenByProxy=2 totalProxyRequests=8
call 5: ms=1002 requestsSeenByProxy=2 totalProxyRequests=10
circuit-opened=false
```

After the patch:

```text
call 1: ms=1004 requestsSeenByProxy=2 totalProxyRequests=2 messagesAreOriginal=true
call 2: ms=1002 requestsSeenByProxy=2 totalProxyRequests=4 messagesAreOriginal=true
call 3: ms=1002 requestsSeenByProxy=2 totalProxyRequests=6 messagesAreOriginal=true
call 4: ms=0 requestsSeenByProxy=0 totalProxyRequests=6 messagesAreOriginal=true
call 5: ms=0 requestsSeenByProxy=0 totalProxyRequests=6 messagesAreOriginal=true
circuit-opened=true
  warn: [headroom] Circuit breaker opened after 3 errors (last: HeadroomConnectionError: Failed to connect to Headroom at http://127.0.0.1:53545: TimeoutError: The operation was aborted due to timeout); bypassing compression for 60000ms
  warn: [headroom] Circuit open — using uncompressed messages
  warn: [headroom] Circuit open — using uncompressed messages
```

- Not tested: a live OpenClaw host with a real provider (the engine
needs a host to drive, so I drove `assemble()` directly against the
built plugin), and the published `headroom-ai` beyond `0.42.0`.
`fallback` has been in the SDK's `CompressOptions` since the first TS
release, so the flag resolves against the plugin's `^0.40.0` range too.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — this is a plugin-local circuit
breaker inside `headroom-openclaw`, with no rollout flag or channel
gating involved.
- Minimum rollout channel: N/A, no gating is introduced.
- Stable/default behavior changed: yes, deliberately. The circuit
breaker now opens on proxy failures instead of never opening, so an
unhealthy proxy causes compression to be skipped for
`circuitBreakerCooldownMs` (default 60 s) rather than being attempted on
every turn. Messages are returned unchanged either way, so model output
is unaffected; the change removes repeated timeout latency.
- Kill switch / disable path: `enabled: false` disables the plugin
entirely; `circuitBreakerThreshold` can be raised to make the breaker
effectively unreachable; `circuitBreakerCooldownMs` bounds how long each
bypass lasts.
- Unsafe override required: no.
- Qualification impact: none — no provider, transport or config surface
changes, and no new dependency.
- Rollback path: revert the commit. The prior behavior was a single-line
`fallback: true`, and nothing here migrates or persists state, so
reverting restores the old behavior exactly.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Review caught one defect in my first attempt, now fixed and covered by a
test: with `minContextChars: 0`, `assemble()` forwards empty `messages:
[]` to the proxy, which answers `200` with `tokens_before: 0`. Counting
that as a failure meant a handful of empty-context turns could open the
breaker and then skip compression for a healthy proxy. The zero-token
check is now scoped to nonempty input.

Found with AI assistance (opencode) operated by me.
2026-11-10 12:34:14 -06:00

234 lines
11 KiB
Markdown

# @headroom-ai/openclaw
Context compression plugin for [OpenClaw](https://github.com/openclaw/openclaw). Compresses tool outputs, code, logs, and structured data — 70-90% token savings with zero LLM calls.
Tool-call normalization preserves provider metadata, including thought signatures, when restoring assistant turns after compression.
## Install
Recommended one-command setup:
```bash
headroom wrap openclaw
```
Manual install:
```bash
pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
```
This plugin can auto-start a local `headroom proxy` when needed. OpenClaw treats process-launching plugins as unsafe by default, so `--dangerously-force-unsafe-install` is required even if you plan to use a remote proxy (the capability is declared at install time).
## Local Development Install (Detection-Friendly)
Building from source requires Node.js `^22.18.0 || ^24.11.0 || >=26.0.0` for the tsup 9 toolchain. Use a supported Node release before running `npm ci` and `npm run build`. This is a source-build requirement; the published plugin uses the Node runtime supported by your OpenClaw host and does not run tsup during plugin loading.
If you are testing from this repo, run npm install/build from the plugin directory so local launcher detection aligns with runtime paths. These linked installs are supported:
```bash
cd plugins/openclaw
npm install
npm run build
openclaw plugins install --dangerously-force-unsafe-install --link .
openclaw plugins install --dangerously-force-unsafe-install --link dist
```
From the repo root, install the plugin directory explicitly:
```bash
openclaw plugins install --dangerously-force-unsafe-install --link ./plugins/openclaw
```
Or, from inside `dist/`:
```bash
cd plugins/openclaw/dist
openclaw plugins install --dangerously-force-unsafe-install --link .
```
Why this matters:
- The plugin checks launchers in this order: PATH -> local npm bin -> global npm -> python.
- "local npm bin" means `plugins/openclaw/node_modules/.bin/headroom` relative to the source checkout.
- Using `--link dist` (or `--link .` from `dist/`) still keeps runtime code adjacent to the checkout, and launcher detection falls back to PATH/global/python if a local npm bin is not present under the installed root.
- `plugins/openclaw` also carries a no-op hook shim so OpenClaw's hook-pack fallback treats the path as valid instead of emitting a misleading `package.json missing openclaw.hooks` warning.
- If you install from a `.tgz`, local npm bin may not exist in the installed extension and detection will fall back to PATH/global/python.
## Configure
Install automatically selects the `contextEngine` slot for `headroom` on current OpenClaw releases. If you need to switch back manually, set `plugins.slots.contextEngine` to `"legacy"` or another engine id.
```json
{
"plugins": {
"entries": {
"headroom": {
"enabled": true,
"config": {
"proxyUrl": "http://127.0.0.1:8787"
}
}
},
"slots": {
"contextEngine": "headroom"
}
}
}
```
`proxyUrl` is optional. If omitted, the plugin auto-detects on localhost:
- `http://127.0.0.1:<proxyPort>`
- `http://localhost:<proxyPort>`
Default `proxyPort` is `8787`. Auto-start is opt-in; in production, prefer an externally
managed proxy such as systemd with `proxyUrl` set and `autoStart: false`.
### Upstream gateway routing
By default, the plugin also rewrites the built-in `openai-codex` provider base URL to a verified active Headroom proxy at runtime. That means Codex provider traffic flows through Headroom, so `/stats` can observe real upstream request and cache activity instead of only local context compression.
This does not replace Headroom's existing Codex routing rules. The proxy already decides between `api.openai.com` and `chatgpt.com/backend-api/codex/responses` based on ChatGPT auth. The plugin change only points OpenClaw's provider config at the active proxy in memory and preserves the rest of the provider config.
You can also route additional provider ids such as `anthropic`, `github-copilot`, `google`, or `openrouter` through the same proxy:
```json
{
"plugins": {
"entries": {
"headroom": {
"enabled": true,
"config": {
"gatewayProviderIds": ["openai-codex", "anthropic", "github-copilot", "google", "openrouter"]
}
}
}
}
}
```
When `gatewayProviderIds` is set, it becomes the exact list the plugin rewrites in memory for the current gateway process.
For convenience, the plugin also accepts family aliases:
- `codex` -> `openai-codex`
- `claude` -> `anthropic`
- `copilot` -> `github-copilot`
- `gemini` -> `google`
When OpenClaw has already resolved a provider's upstream `baseUrl`, the plugin preserves protocol-specific path segments while swapping only the origin. That keeps provider families on the right proxy route:
- Codex / ChatGPT backend: `/backend-api`
- OpenAI-compatible providers: `/v1` or `/api/v1`
- GitHub Copilot Claude-family models: `/anthropic`
- Gemini: `/v1beta`
GitHub Copilot is a special case because OpenClaw can route it through either OpenAI Responses or Anthropic Messages depending on the selected model. The plugin only rewrites Copilot when OpenClaw has already resolved the upstream `baseUrl`, so it can preserve the correct `/v1` or `/anthropic` path instead of guessing.
The routing is intentionally lightweight and reversible:
- the plugin does not persist provider `baseUrl` changes back to `openclaw.json`
- disabling the plugin, clearing `gatewayProviderIds`, or restarting without Headroom restores OpenClaw's normal provider resolution
- if you want durable provider rewrites, use `headroom wrap openclaw` instead of relying on plugin install side effects
If you need to disable that behavior:
```json
{
"plugins": {
"entries": {
"headroom": {
"enabled": true,
"config": {
"routeCodexViaProxy": false
}
}
}
}
}
```
### Local proxy (auto-start)
When `proxyUrl` points to localhost (or is omitted), the plugin will auto-start `headroom proxy` if no running proxy is detected. Launch order:
1. `headroom` from `PATH`
2. local npm bin (`node_modules/.bin/headroom`)
3. global npm bin
4. Python module (`python -m headroom.cli proxy ...`)
If `pythonPath` is set, it is tried first in the Python fallback step.
Docker-native Headroom installs intentionally leave `pythonPath` unset so this launcher order prefers the installed host `headroom` wrapper on `PATH`, which then runs Headroom in Docker.
### Remote proxy (connect-only)
Point `proxyUrl` to any reachable Headroom instance:
```json
{
"config": {
"proxyUrl": "https://headroom.example.com:8787"
}
}
```
Remote URLs are **connect-only** — the plugin probes the URL at startup and fails fast if the proxy is not reachable. No subprocess is spawned for remote addresses.
## Manual Proxy Setup
If you prefer to manage the proxy yourself (or are running a remote instance), start it before launching OpenClaw:
Python install:
```bash
pip install "headroom-ai[proxy]"
headroom proxy --host 127.0.0.1 --port 8787
```
NPM install:
```bash
npm install -g headroom-ai
headroom proxy --host 127.0.0.1 --port 8787
```
## How It Works
Every time OpenClaw assembles context for the model, the plugin compresses tool outputs and large messages:
- **JSON arrays** (tool outputs, search results) — statistical selection keeps anomalies, errors, boundaries
- **Code** — AST-aware compression via tree-sitter
- **Logs** — pattern deduplication, keeps errors and boundaries
- **Text** — ML-based token compression
Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored and the agent gets a `headroom_retrieve` tool to access full details when needed.
## Configuration Options
| Option | Default | Description |
|--------|---------|-------------|
| `proxyUrl` | auto-detected | Optional URL of a Headroom proxy. Configured URLs are probe-gated before provider routing. Remote URLs (`https://headroom.example.com`) are connect-only. |
| `proxyPort` | `8787` | Port used for default auto-detect and optional local auto-start when `proxyUrl` is not set. |
| `pythonPath` | auto-detected | Optional Python executable override for Python fallback launcher. |
| `autoStart` | `false` | Opt-in auto-start for a local `headroom proxy` if not already running (local URLs only; ignored for remote proxies). Keep `false` when systemd owns the proxy. |
| `startupTimeoutMs` | `20000` | Time to wait for auto-started proxy to become healthy |
| `requestTimeoutMs` | `2000` | Maximum milliseconds to wait for a single `compress()` call. The SDK aborts the request at this deadline and the original messages are used as a fallback. |
| `minContextChars` | `800` | Skip proxy compression below this approximate 200-token context floor. Large single tool results still qualify; set to `0` to disable the gate. |
| `circuitBreakerThreshold` | `3` | Number of consecutive `assemble()` failures before the circuit breaker opens and all requests bypass the proxy. Counts every way the proxy can fail a call — connection errors, timeouts, 5xx responses, and results that come back with no token count. Prevents cascading failures when the proxy is unhealthy. |
| `circuitBreakerCooldownMs` | `60000` | How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next `assemble()` call re-probes the proxy by attempting a real compression. |
| `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. |
| `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |
| `announceCompression` | `true` | Adds a static, cache-stable notice to the system prompt the first time a session compresses more than 100 tokens, then keeps it unchanged for the rest of the session. Set to `false` to guarantee Headroom never modifies the system prompt. |
| `commitLogPath` | `$HEADROOM_WORKSPACE_DIR/openclaw/commit-log.json`, else `~/.headroom/openclaw/commit-log.json` | Where the plugin records each turn OpenClaw has accepted (one small marker file per turn, in a sibling `commit-log.d/` directory), so a retried commit is answered as a duplicate even after a restart. Must be on a writable filesystem: on a read-only root (common in Kubernetes), point this or `HEADROOM_WORKSPACE_DIR` at a writable volume. While commits fail, OpenClaw 2026.9.9+ runs each later turn of the session on its legacy context path. |
## Comparison with lossless-claw
| | lossless-claw | headroom |
|---|---|---|
| Compaction method | LLM summarization (DAG) | OpenClaw native compaction (delegated) |
| Cost of compaction | Tokens (LLM calls) | OpenClaw configuration-dependent |
| Best for | Long conversations | Tool-heavy agents with large outputs |
| Retrieval | `lcm_grep`, `lcm_expand` | `headroom_retrieve` (instant) |
## License
Apache-2.0