Commit Graph
20 Commits
Author SHA1 Message Date
24acbe8f32 fix(openclaw): record turn advancements as one marker file per key (#4212)
## Description

OpenClaw 2026.9.9 started calling the context engine's `commitTurn`
after every accepted turn. While a commit is pending, it runs every
later turn of that session on its legacy context path, which means no
Headroom compression. The plugin's turn-commit store (from #3442) has
three ways to leave a commit pending, and this PR removes all three.
Each committed key becomes one small marker file, created with exclusive
creation (`O_CREAT | O_EXCL`). There's no lock and no shared file to
rewrite, and only the key is stored.

**What we saw.** We run the plugin on Kubernetes with a read-only root
filesystem. After upgrading OpenClaw to 2026.9.9, every turn logged:

```
[context-engine] durable turn advancement remains queued: <key>: ENOENT: no such file or directory, mkdir '/home/openclaw/.headroom'
```

On the session's next turn, OpenClaw retries the pending commit before
assembling context. When the retry fails, it degrades that turn to the
legacy engine (`degradeBeforeStart("pending durable turn advancement
could not be completed before the next turn")` in OpenClaw's
`context-engine-turn-attempt`). A failed commit only increments
`attempt_count`, so the row stays pending and every later turn of the
session degrades too.

**The three problems in `advancement-key-store.ts`:**

1. **Read-only home.** The default
`~/.headroom/openclaw/commit-log.json` can't be created on a read-only
root. Node reports the failed `mkdir` as `ENOENT`, which reads like a
bug rather than a setting. `commitLogPath` exists on the engine but not
in the manifest's `configSchema` (`additionalProperties: false`), so
`HEADROOM_WORKSPACE_DIR` is the only way to move it.
2. **Unbounded growth.** Every accepted turn's `messages` (OpenClaw caps
a turn at 8 MiB) are kept forever in one JSON file. Each commit
re-reads, parses, copies and rewrites the whole file on the gateway's
event loop, so the file and each commit's latency grow with every turn
ever committed. Nothing reads the messages back (`get` is test-only),
and OpenClaw's transcript already holds them.
3. **A lock nothing reclaims.** By design, the lock is never
force-broken. A gateway killed mid-commit (an OOM kill, a node drain)
leaves `commit-log.json.lock` behind, and every later commit waits 60 s
and then fails until someone deletes it. With the retry above, every
turn then starts 60 s late before degrading.

## 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)
- [x] Documentation update
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- **One marker per committed key**, at
`commit-log.d/<sha256[0:2]>/<sha256(key)>` next to the old log path,
created with `open(path, "wx")`. The first creator in any process gets
`"committed"`; every later caller gets `EEXIST`, i.e. `"duplicate"`.
Only that exclusive create can mean `"duplicate"`, and only when what
exists at the path is a marker file. An `EEXIST` from creating the shard
directory (a file where the directory belongs), or anything but a file
at the marker's path, is a storage error. The marker holds
`{advancementKey, committedAt}`: 99 bytes for OpenClaw's UUID keys.
- **Only the key is recorded.** For this engine, the advancement *is*
the key: `assemble()` works from the messages OpenClaw passes in, and
the plugin keeps no turn state. The contract asks for "one atomic,
idempotent write keyed by `advancementKey`" (OpenClaw
`docs/concepts/context-engine.md`), and creating the marker is that
write.
- **Keys are still never evicted**, for the reason #3442 gives.
- **Migration.** Before every commit and lookup, a store checks for a
`commit-log.json` from an earlier version. With no log there, that check
is one failed `open()`. If a log is there and it's a version the store
hasn't migrated, the store moves its keys into markers and records which
version that was (size, mtime, inode) in
`commit-log.d/migrated-legacy-log.json`. That record only saves work, so
a store that can't write it carries on and reads the log again later.
The log's version and its contents come from one open handle. The log
itself is never moved or changed, so an older version still running
against the same workspace keeps its own record, and nothing has to
write to the log's directory (which may be read-only, with a writable
marker volume mounted beneath it). An unchanged log is skipped by its
metadata alone, even if it can no longer be read. A changed one is
migrated again, so a key an older version commits at any moment, even
while a store is migrating the log, is never accepted as new. Only keys
the store hasn't seen get markers, so a rewrite costs only the keys it
adds. Both the object and the older array format are read. Several
processes can migrate at once safely, since creating an existing marker
is a no-op. A corrupt log still fails loudly rather than being read as
empty, and the store recovers once it's fixed.
- **An actionable error.** When the marker directory can't be created,
the message says what to do: `Cannot record turn advancements under
<dir>: <error>. Point HEADROOM_WORKSPACE_DIR (or the plugin's
commitLogPath) at a writable directory.` A lookup in a store whose path
a file blocks fails the same way on every platform, although Windows
reports such a path as `ENOENT`, which is also what a missing marker
gives.
- **`commitLogPath` is settable.** It's declared in
`openclaw.plugin.json`, with a UI hint and a README row.
- **Tests.** The store suite is rewritten for the new design. It keeps
the existing guarantees: committed, then duplicate; survives a restart;
never evicts across 600 keys; exactly one winner in-process and across
two OS processes; a failed write is retried, not remembered. New tests
cover:
  - a commit stores one small marker holding only the key;
- committing more keys never rewrites an earlier marker (same inode and
mtime);
  - a leftover `.lock` from a crashed process doesn't block a commit;
- a file where the marker directory or a shard directory belongs, and a
directory where a marker belongs: each is an error, never `"duplicate"`,
and the same key commits once the path is cleared;
- a file blocking the store's directory or its marker directory,
reported the way Windows reports it (`ENOENT`, not `ENOTDIR`): a lookup
is a storage error, not an absent key;
  - both legacy formats, including two stores migrating concurrently;
- a legacy log in a read-only directory: commits go through; a restart
doesn't read the unchanged log again; a migrated log that can no longer
be read doesn't block commits; and once the directory is writable, a key
an older version commits the old way (temp file + rename) is migrated
before a running store's next commit;
- a key an older version commits while a store is migrating the log: the
store's next lookup finds it, and its next commit, like a new store's,
is `"duplicate"`;
- an older version rewriting the log: only the key it added gets a
marker;
- a migration record that can't be written: commits go through, in that
store and in one started later;
  - a corrupt legacy log.

In `engine.test.ts`, a commit carrying 1 MB of tool output stores under
1 KB. The lock-holder fixture is removed, since there is no lock.

## Testing

- [ ] Unit tests pass (`pytest`) (n/a, TypeScript plugin only)
- [ ] Linting passes (`ruff check .`) (n/a)
- [ ] Type checking passes (`mypy headroom`) (n/a; `npm run typecheck`
passes)
- [x] New tests added for new functionality
- [x] Manual testing performed (see Real Behavior Proof)

### Test Output

```text
$ cd plugins/openclaw && npm run typecheck        # exit 0
$ npx vitest run                                  # Node v24.21.0, macOS
 Test Files  9 passed (9)
      Tests  139 passed (139)
$ npx vitest run                                  # Node v22.22.0, GitHub Actions windows-latest
 Test Files  9 passed (9)
      Tests  137 passed | 2 skipped (139)
```

## Real Behavior Proof

- Environment: macOS, Node v24.21.0, for the benchmark below: "old" is
`advancement-key-store.ts` from `main`, "new" is this PR, and the same
script drives both. In production: OpenClaw 2026.9.9 on Kubernetes with
a read-only root filesystem and `HEADROOM_WORKSPACE_DIR` on a writable
volume, running the plugin at v0.40.0 from a fork tag, with
`advancement-key-store.ts` identical to a9e9ea6e.
- Exact command / steps: one script drives both stores through the first
three cases, and the last compares production logs:
- commit 300 accepted turns, each carrying 100 KB of tool output, and
time commits #1, #100 and #300;
- commit once with a `commit-log.json.lock` left behind, as a killed
process would leave it;
- commit with the workspace's parent directory not writable (mode 0555);
- in production, compare one gateway's OpenClaw logs over a 12-hour
night on v0.40.0's store with its first 3 hours on this store.
- Observed result: the new store stays small and fast and ignores a
leftover lock. In production, no commit failed and no turn fell back to
legacy.

  | | Old store | New store |
  |---|---|---|
  | Store on disk after 300 turns | 30.0 MB | 0.02 MB |
| Commit #1 / #100 / #300 | 3.3 / 14.3 / 40.4 ms | 2.6 / 0.1 / 0.2 ms |
| Leftover lock file from a crashed process | fails after 60.0 s |
committed immediately |
| Workspace not writable | `EACCES: permission denied, mkdir
'…/.headroom'` | same error, plus which setting fixes it |

In production, v0.40.0's store failed all 53 commits overnight with the
`remains queued` line above, and all 8 later turns of a session fell
back to legacy. On this store, the same gateway made 38 commits in its
first 3 hours, none failed, and no turn fell back. The 5 later turns we
could trace to their session all ran on headroom. The 38 markers take
296 KiB on disk, shard directories included.
- Not tested: the two permission-bit tests (a read-only directory, an
unwritable migration record) on Windows or as root, where they are
skipped, since permission bits don't restrict either. Our production
build predates the last three commits, which change only how a legacy
log is migrated and how a blocked path is reported, and that deployment
never had a legacy log.

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a.
- Stable/default behavior changed: the commit store's on-disk format (an
existing log is migrated on first use). The default location is
unchanged.
- Kill switch / disable path: none needed. Pointing `commitLogPath` or
`HEADROOM_WORKSPACE_DIR` elsewhere starts a fresh store.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert. The old log stays where it was, so an older
version still finds every key it wrote. Keys committed after the upgrade
live only in markers, so an older version could re-accept a turn that
was mid-retry during the downgrade.

## 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 (on Node
24; see Additional Notes)
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- A version older than this one, running at the same moment against the
same workspace, keeps writing the old file, and this store migrates
whatever it adds. The older version doesn't read markers, though, so it
could still accept a key only this version committed. That's the same
mixed-version caveat any format change has.
- Unrelated to this change: the cross-process tests run `node
--experimental-transform-types`, which Node 26 no longer accepts (`bad
option`). They pass on Node 24, which CI uses.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4212"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 22:46:13 -06:00
liuyongcheng0000andJerrett Davis 33f204406c fix(openclaw/release): ship responsive npm integrations (#1458)
## Description

Fixes #977 and #2353.

The v0.35.0 release built all three JavaScript packages successfully,
but npm rejected every publish with ENEEDAUTH. Because each publish step
used continue-on-error, the publish-npm job still concluded success. npm
therefore remains on headroom-ai 0.22.4 and headroom-openclaw 0.1.0,
while headroom-opencode is absent.

The checked-in OpenClaw source had already corrected the old
strict-schema mismatch and added a circuit breaker, but its assemble
hook still called compression for every tiny conversation and allowed a
30-second default wait. This PR completes both the runtime correction
and the delivery path instead of merely exposing one failure.

## Changes

### OpenClaw runtime

- Skip proxy compression below an 800-character context floor (roughly
200 tokens), avoiding synchronous HTTP work on short conversations that
cannot produce meaningful savings.
- Measure actual content, including tool-call arguments, so a single
large tool result remains eligible.
- Allow operators to disable the floor with minContextChars=0.
- Lower the interactive request ceiling from 30 seconds to 2 seconds.
- Pass that timeout into the SDK, whose AbortSignal cancels the HTTP
request, instead of racing a promise while the fetch continues in the
background.
- Preserve circuit-breaker fail-open behavior and document/schema the
new defaults.

### npm release integrity

- Authenticate with npm before publishing any package, so a missing or
invalid NPM_TOKEN fails before a partial release begins.
- Make SDK, OpenClaw, and OpenCode npm publish failures fatal when npm
publishing is enabled.
- Preserve NPM_SKIP=true as the explicit opt-out.
- Make retries safe after partial publication by skipping only the exact
package version already present, then continuing to missing packages.
- Remove the false-success notice path.

## Existing #977 corrections verified

- The current OpenClaw schema declares startupTimeoutMs,
routeCodexViaProxy, gatewayProviderIds, request timeout, and
circuit-breaker fields written/used by the installer and runtime.
- wrap defaults to the real published package name, headroom-openclaw.
- unwrap removes managed values while preserving unrelated user
configuration.
- The coding savings profile uses protect_recent=0 paired with
type-based recent-read protection, avoiding the old blanket
short-session protection without weakening tool-result fidelity.

## Testing

- 80 OpenClaw plugin tests pass.
- TypeScript typecheck and production build pass.
- 123 OpenClaw wrap/provider, savings-profile, compress endpoint, and
MCP contract tests pass.
- 47 release-workflow and MCP contract tests pass.
- The npm release asset builder installed/imported and verified the
actual 0.35.1 SDK and OpenClaw tarballs.
- Workflow YAML parses; Ruff, format, and git diff checks pass.

## Required repository action

A maintainer must replace or restore the npm publishing credential in
NPM_TOKEN, then rerun the v0.35.0 release workflow (or publish the next
version). This PR makes that failure visible and safely rerunnable;
repository code cannot provision the external npm credential.

Co-authored with @liuyongcheng0000, whose original PR identified the
masked npm failures.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/1458"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Jerrett Davis <mxjerrett@gmail.com>
2026-10-28 17:40:52 -05:00
f8851878a4 fix(plugins/openclaw): keep compression system-prompt notice cache-stable (#3811)
## Description

`HeadroomContextEngine.assemble()` in the OpenClaw plugin returns a
`systemPromptAddition` string that OpenClaw prepends to the system
prompt every turn. It interpolated the per-turn `tokensSaved` count, so
the system prompt — the start of the provider's cached prefix — changed
on every compressing turn, defeating prompt caching. Reported cost: a
turn saving 267 tokens caused a ~93K-token cache miss on Bedrock/Claude
Opus 5.5, roughly 4,000x the tokens the compression saved.

Refs #3809

## 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

- `plugins/openclaw/src/engine.ts`: replaced the interpolated
`${result.tokensSaved}` notice with a fixed constant
(`HEADROOM_COMPRESSION_NOTICE`), so any turn that includes it is
byte-identical to any other. Added a `hasAnnouncedCompression` instance
flag so the notice, once shown (tokensSaved > 100), stays present and
unchanged on later turns even when a given turn has nothing new to
compress
- `plugins/openclaw/src/engine.ts`: added `announceCompression`
(boolean, default `true`) to `HeadroomEngineConfig` to disable the
notice entirely.
- `plugins/openclaw/openclaw.plugin.json`: added `announceCompression`
to `configSchema.properties` (required — schema has
`additionalProperties: false`) and a matching `uiHints` entry.
- `plugins/openclaw/README.md`: documented the new option in the
configuration table.
- `plugins/openclaw/test/engine.test.ts`: 5 new tests, static notice
with no interpolated count, byte-identical notices across differing
`tokensSaved`, notice staying present on a turn with nothing to compress
(the flap-prevention regression case), `announceCompression: false`
opt-out, and the existing below-threshold no-op case.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ npx vitest run test/engine.test.ts
 RUN  v4.1.10 /Users/sarah_ling/Documents/GitHub/headroom/plugins/openclaw

 Test Files  1 passed (1)
      Tests  27 passed (27)
   Start at  18:17:43
   Duration  527ms

$ npx vitest run
 Test Files  1 failed | 6 passed (7)
      Tests  3 failed | 104 passed (107)

# The 3 failures are in test/advancement-key-store.test.ts, unrelated to this change
```

## Real Behavior Proof

- Environment: local vitest run against `plugins/openclaw` (mocked
`compress()`/proxy — no live OpenClaw host or real Bedrock/Anthropic
request).
- Exact command / steps: added a temporary test that mocks a 6-turn
session mirroring the reported scenario (tokensSaved: 0, 267, 0, 9000,
0, 50) and recorded `assemble()`'s `systemPromptAddition` per turn.
- Observed result: notice absent on turn 1, appears static and identical
on turns 2–6 (including turns 3/5 with nothing to compress, and turn 6's
below-threshold 50-token save) — 1 total transition across 6 turns,
versus the old behavior's distinct string on every compressing turn.
- Not tested: no live OpenClaw + real provider run to directly observe
the Bedrock cache-read/cache-write fields improve, as the original
issue's report did. The fix is verified at the unit level (the exact
value the plugin hands to OpenClaw), not against a real provider cache.

## Runtime Rollout Safety

- Rollout-managed feature(s): None
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes, the notice text changes (no
longer reports a live token count) and stays present for the rest of the
session instead of tracking that turn's compression state. Default
(`announceCompression` unset) still shows the notice, matching prior
default-on behavior.
- Kill switch / disable path: set `announceCompression: false` in the
plugin config to fully disable the notice.
- Unsafe override required: None
- Qualification impact: None
- Rollback path: Revert this PR

## 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)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3811"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-06 08:37:07 -05:00
6576ef639c fix(openclaw-plugin): circuit breaker + per-request timeout for proxy resilience (#639)
## Description

This change adds bounded timeout and circuit-breaker behavior so
OpenClaw can degrade safely when Headroom or the upstream stream stalls,
while returning structured proxy errors instead of hanging.

Closes #638 by improving OpenClaw/proxy resilience when the Headroom
proxy stalls or Anthropic resets a stream. The PR adds proxy-side
handling for `httpx.RemoteProtocolError`, returns structured 502
responses for otherwise unhandled proxy middleware errors, and adds
OpenClaw plugin timeout/circuit-breaker fallback behavior.

## Type of Change

- [x] Bug fix
- [ ] New feature
- [x] Documentation
- [ ] Refactor
- [x] Tests only

## Changes Made

- Added OpenClaw plugin per-request compression timeout and circuit
breaker fallback.
- Cleared timeout timers after successful or failed compression so
successful calls do not leave pending timers.
- Added a focused Vitest regression for timeout cleanup.
- Added `contracts.tools` for `headroom_retrieve` without whole-file
manifest reformatting.
- Added proxy handling for mid-stream `httpx.RemoteProtocolError` and
structured 502 fallback behavior.
- Documented the new OpenClaw resilience configuration fields.

## Testing

- [x] Unit tests
- [x] Integration-style proxy tests
- [x] Typecheck/build
- [ ] Manual testing

### Test Output

```text
cd plugins/openclaw && npm test
Test Files 6 passed (6), Tests 55 passed (55)

cd plugins/openclaw && npm run typecheck
passed

cd plugins/openclaw && npm run build
Build success

UV_SKIP_WHEEL_FILENAME_CHECK=1 uv run --with pytest --with pytest-asyncio --with fastapi --with httpx --with uvicorn --with h2 python -m pytest tests/test_proxy_streaming_resilience.py -q
24 passed in 2.16s
```

## Real Behavior Proof

- Environment: Windows 11, Node/npm from local plugin worktree, Python
3.13.3, focused local worktree for PR #639.
- Exact command / steps: Installed plugin dependencies, ran OpenClaw
plugin tests/typecheck/build, and ran the proxy streaming resilience
suite with required async/FastAPI/httpx extras.
- Observed result: Plugin tests, typecheck, build, and proxy resilience
tests all passed.
- Not tested: Live OpenClaw gateway session in this pass; original
reporter previously verified patched files in a container and OpenClaw
degraded/recovered cleanly.

## Review Readiness

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

---------

Co-authored-by: Sergei Baikin <sergei.baikin@fotograf.de>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
2026-08-13 11:52:01 -05:00
felixboenkost-droidandBjörn-Christian Bönkost 6d116b15f1 Harden OpenClaw plugin proxy routing (#1074)
## Description

Hardens the bundled OpenClaw plugin so configured proxy routing is
fail-closed and `autoStart` is opt-in.

Closes: N/A

This follow-up is intentionally separate from the ContentRouter cache
fix because it changes plugin/gateway behavior rather than core
compression routing.

The plugin should not mutate upstream provider routing unless a
configured proxy URL is reachable and looks like Headroom. It should
also avoid unhandled startup promise rejections when proxy startup is
fire-and-forget.

Why this shape:

- `autoStart: false` by default matches deployments where Headroom is
supervised externally, for example by systemd. The plugin should not
silently start or assume ownership of a proxy unless the operator opted
in.
- Provider routing is fail-closed: a configured URL must first respond
like Headroom, not merely expose a generic liveness endpoint. This
prevents accidentally routing model traffic through the wrong local
service.
- `/readyz` is treated as liveness, not identity. Identity comes from
Headroom-shaped stats endpoints (`/v1/retrieve/stats` or `/stats`)
because those are harder for unrelated services to satisfy by accident.
- Startup remains asynchronous, but errors are captured and exposed
instead of becoming unhandled promise rejections.
- This is a separate PR because the core cache fix is about compression
correctness, while this patch is about integration safety around
OpenClaw gateway routing.

## Type of Change

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

## Changes Made

- Make proxy `autoStart` opt-in (`default: false`).
- Probe configured `proxyUrl` before applying provider routing.
- Treat `/readyz` as liveness only; require Headroom-shaped
`/v1/retrieve/stats` or `/stats` for identity.
- Observe fire-and-forget startup promise rejection and expose startup
error for callers.
- Isolate proxy-ready listener failures.
- Keep provider routing deferred when no active/probed Headroom proxy
exists.
- Register retrieve tool with explicit `headroom_retrieve` name.
- Extend plugin/unit tests for configured proxy failures, generic
non-Headroom endpoints, path collisions, and routing behavior.

Changed files:

- `plugins/openclaw/README.md`
- `plugins/openclaw/openclaw.plugin.json`
- `plugins/openclaw/src/engine.ts`
- `plugins/openclaw/src/plugin/index.ts`
- `plugins/openclaw/src/proxy-manager.ts`
- `plugins/openclaw/test/engine.test.ts`
- `plugins/openclaw/test/gateway-config.test.ts`
- `plugins/openclaw/test/plugin-runtime-routing.test.ts`
- `plugins/openclaw/test/proxy-manager.test.ts`

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added new functionality
- [x] Manual testing performed

### Test Output

```text
$ npm test

Test Files  6 passed (6)
Tests  74 passed (74)

$ npm run typecheck
tsc --noEmit

$ npm run build
tsup && node prepare-dist.mjs
Build success
```

## Real Behavior Proof

- Environment: local OpenClaw plugin package in the Headroom repo.
- Exact command / steps:
  - Run plugin test suite.
  - Run TypeScript typecheck.
  - Run plugin build.
- Observed result:
  - Tests passed: `74/74`.
  - Typecheck passed.
  - Build passed.
- Not tested:
- Full OpenClaw Gateway integration as part of this standalone PR prep.

## Review Readiness

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

## Checklist

- [x] My code follows project's style guidelines
- [x] I performed self-review my code
- [ ] I commented my code, particularly in hard-to-understand areas
- [x] I made corresponding changes documentation
- [x] My changes generate no new warnings
- [x] I added tests prove fix is effective or feature works
- [x] New and existing unit tests pass locally my changes
- [ ] I updated CHANGELOG.md if applicable

## Screenshots (if applicable)

N/A.

## Additional Notes

Checklist items left unchecked intentionally:

- No CHANGELOG update included.
- No extra comments were needed beyond existing code structure.

Co-authored-by: Björn-Christian Bönkost <bjoern@v2202603344248440850.hotsrv.de>
2026-06-22 22:52:59 -05:00
Tim Poppe 7c8c909c85 fix(openclaw): declare headroom_retrieve tool contract (#947)
## Summary
- add `contracts.tools` to the OpenClaw plugin manifest
- declare `headroom_retrieve` so the manifest matches the tool
registered at runtime
- remove the OpenClaw `contracts.tools` warning during startup

## Testing
- npm test
- npm run typecheck


<!-- headroom-maintainer-template-completion:start -->

## Description

This PR prepares `fix(openclaw): declare headroom_retrieve tool
contract` for review by documenting the intended change, validation
evidence, and remaining merge-readiness context.

Linked issues: None declared.

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Refactor
- [ ] Tests only

## Changes Made

- Commit: fix(openclaw): declare headroom_retrieve tool contract
- Touches `plugins/openclaw/openclaw.plugin.json`

## Testing

- [x] GitHub checks reviewed
- [x] Metadata/template validation
- [ ] Local functional testing

### Test Output

```text
gh pr view 947 --repo chopratejas/headroom --json statusCheckRollup
- PR Governance / template: FAILURE
- PR Governance / label: SUCCESS
- external / GitGuardian Security Checks: SUCCESS
```

## Real Behavior Proof

- Environment: GitHub PR metadata and checks for `chopratejas/headroom`
PR #947.
- Exact command / steps: Reviewed PR title, commits, changed files,
linked issues, labels, and check rollup; appended this maintainer
template completion block without replacing the author's original
description.
- Observed result: PR body now contains all required governance
sections, checked readiness fields, and a non-placeholder validation
evidence block.
- Not tested: This pass updated PR metadata only; code validation
remains represented by the linked GitHub checks and any author-provided
evidence above.

## Review Readiness

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

<!-- headroom-maintainer-template-completion:end -->
2026-06-15 11:12:26 -05:00
JerrettDavisandCopilot 2f05705043 fix(openclaw): normalize provider proxy routing
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-08 22:28:17 -05:00
JerrettDavisandCopilot d4f6e3938f fix(proxy): add fast-fail launch settings
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-08 22:03:21 -05:00
JerrettDavis e0383675aa fix(openclaw): keep gateway routing runtime-only 2026-04-08 21:10:49 -05:00
JerrettDavis 6f500dfa9c feat(openclaw): support configurable gateway providers 2026-04-08 21:10:49 -05:00
JerrettDavis 92b7b09f70 fix(openclaw): route codex through headroom proxy 2026-04-08 21:10:49 -05:00
JerrettDavis 746a1737c1 Select Headroom context engine on install 2026-04-06 21:35:58 -05:00
JerrettDavis 89f3e5f01f fix(openclaw): proxyPort only applies to local URLs, consistency pass
- proxyPort default (8787) now only applied to local URLs; remote URLs
  use their protocol default (80/443) as expected
- Remove redundant localhost-only entries from network capabilities
  (covered by http://*:* and https://*:* wildcards)
- Sync package.json capabilities with openclaw.plugin.json
- Export isLocalProxyUrl from barrel index
- Fix JSDoc indentation in start() method
- Rename "Required Proxy Setup" to "Manual Proxy Setup" with accurate
  description for remote proxy users
- Clarify autoStart description: local-only, ignored for remote
- Add test: remote URL does not get proxyPort applied

Build: tsc clean, 30 tests passed
2026-04-03 10:30:10 -05:00
JerrettDavis 4c3d9c4e28 feat(openclaw): support remote Headroom proxy (connect-only)
Remove localhost-only restriction from proxyUrl validation. Remote URLs
are connect-only: the plugin probes and uses them but never attempts to
spawn a subprocess. Auto-start remains available for local addresses
(127.0.0.1/localhost) only.

- Accept http:// and https:// URLs for any hostname
- Add isLocalProxyUrl() helper to gate auto-start on local addresses
- Remote URLs that fail probe get a clear "Remote proxy not reachable"
  error instead of falling through to auto-start
- Update plugin.json schema, network capabilities, and UI hints
- Update plugin README with local vs remote proxy sections
- Add tests: remote connect, remote fail-fast, isLocalProxyUrl

Build: tsc --noEmit clean
Tests: 29 passed (0 skipped)
2026-04-03 10:30:09 -05:00
JerrettDavis fa99ba785e docs: add OpenClaw plugin section to main README
Add dedicated OpenClaw plugin section with install instructions,
explanation of --dangerously-force-unsafe-install requirement (proxy
subprocess spawning), and quick config example. Links to plugin README
for full details. Update integration tables to reference new section.

Also fix proxy port handling: apply default proxyPort when explicit
proxyUrl omits port, and allow trailing slash in proxyUrl validation
pattern. Add test coverage for port defaulting behavior.
2026-04-03 10:30:09 -05:00
JerrettDavis 593f1b7829 Restore pythonPath and proxyPort config support 2026-04-02 22:21:05 -05:00
JerrettDavis e4c7c47e34 Auto-detect proxyUrl by default and keep explicit override 2026-04-02 22:10:12 -05:00
JerrettDavis 777ffeb716 Add controlled proxy autostart and unsafe-install guidance 2026-04-02 21:47:27 -05:00
JerrettDavis 205ec54df2 Harden openclaw plugin proxy handling and metadata 2026-04-02 21:27:12 -05:00
chopratejas 053c4a06af feat: add OpenClaw ContextEngine plugin (@headroom-ai/openclaw)
- HeadroomContextEngine: implements ContextEngine interface (bootstrap, ingest,
  assemble, compact, afterTurn, prepareSubagentSpawn, dispose)
- ProxyManager: auto-detects running proxy or spawns one as child process,
  health checks, restart on crash, graceful shutdown
- AgentMessage ↔ OpenAI format conversion (user, assistant/tool_use, toolResult)
- headroom_retrieve CCR tool: agent can retrieve original uncompressed content
- Plugin manifest (openclaw.plugin.json) with config schema
- 11 tests (6 unit + 5 integration), all passing
- Integration tested: 100 servers compressed, 3,735 tokens saved (82%)
2026-03-28 13:43:40 -07:00